Browser-based graphical shell and control plane for a Linux server you own — real terminal, file manager, live metrics and BYOK AI in one mobile-first workspace. Next.js 16 · React 19 · node-pty · Tailwind v4 · shadcn/ui. Public alpha, self-hosted.
TypeScript browser-shellcontrol-planefile-managerhomelabmobile-firstnextjsptyreactself-hostedserver-managementshadcn-uisysadmintailwindcssterminaltypescriptvpsweb-desktopweb-terminal
docs(mcp): document service tokens and update reconciliation
rahmanef632426885f9d3d
diff --git a/README.md b/README.mdindex 839dd411..4017532c 100644--- a/README.md+++ b/README.md@@ -61,7 +61,7 @@ For a real deployment, put MSO behind **Tailscale, a VPN, or a TLS reverse proxy- **Inspect system health** — view live CPU, memory, disk, network, process, and uptime signals.- **Operate services safely** — inventory system and user `systemd` units, read bounded journal output, and expose start/stop/restart only for exact owner-configured allowlist entries.- **See pending package updates** — read the package manager’s existing local cache without refreshing repositories or applying an upgrade.-- **Update itself** — Settings → About shows what is on `origin/main`, lists the incoming commits, and runs the whole deploy (pull → verify the build out-of-tree → build → restart) from a button. The verification runs first on purpose: a commit that does not compile becomes a refusal, not an outage. The updater runs in the owner's systemd user manager and does not require passwordless sudo. Same thing from a shell: `mso update` (`mso update run` remains a compatibility alias). The CLI update path is Git-based and still works when the web runtime is down.+- **Update itself** — Settings → About shows what is on `origin/main`, lists the incoming commits, and runs the whole deploy (pull → verify the build out-of-tree → build → restart) from a button. The verification runs first on purpose: a commit that does not compile becomes a refusal, not an outage. A clean local `main` that is ahead of or diverged from `origin/main` is reported explicitly and refused until its commits are pushed/reconciled; MSO never treats that state as a remote-connectivity failure or silently deploys unpushed history. The updater runs in the owner's systemd user manager and does not require passwordless sudo. Same thing from a shell: `mso update` (`mso update run` remains a compatibility alias). The CLI update path is Git-based and still works when the web runtime is down.- **Manage other apps on the box** — detect, start/stop/restart, health, version, logs, and state backups for separate applications you already run (Hermes, OpenClaw, 9Router), driven through their own systemd/Docker/CLI contracts. 9Router uses its configured application domain or split-origin host as the in-shell dashboard; its Docker port is loopback-only unless public exposure is explicitly enabled. See [docs/MANAGED-APPS.md](./docs/MANAGED-APPS.md).**Work** — code/text editor, browser, and media tools in the same workspace.diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.mdindex 7d770d97..9a752ebb 100644--- a/docs/CHANGELOG.md+++ b/docs/CHANGELOG.md@@ -4,6 +4,20 @@Newest first. `docs/PROGRESS.md` is the source of truth for *why* a change was made;this is the *what*, and it is what Settings → About shows as “What's new”.+## 2026-09-05++**Added**++- `mcp` preserve restricted project service bridge++**Fixed**++- `update` handle diverged checkout explicitly++**Docs**++- `mcp` document service tokens and update reconciliation+## 2026-09-04**Added**diff --git a/docs/MCP.md b/docs/MCP.mdindex 03dd8cae..0544ee79 100644--- a/docs/MCP.md+++ b/docs/MCP.md@@ -112,6 +112,36 @@ client that calls a tool it was never shown still gets refused.`workflow_id`: it correlates steps, it never gates a capability. `lib/mcp/global-tools.test.ts`pins all of this, including that a token's visible list matches its callable set exactly.+## Restricted service tokens for trusted automation++Interactive/browser MCP clients should use the OAuth flow above. For a **trusted local operator** that needs a narrowly scoped server-to-server bearer, MSO also has an owner-CLI-only mint path. There is deliberately no HTTP endpoint that mints these tokens.++The current policy is intentionally small: service tokens may expose only `project_capabilities` and `project_function_call`. Every allowlisted tool must have all of its policy-defined top-level string arguments constrained to exact allowed values; including `project_function_call` therefore requires `exec` scope and pins both `project` and `name`. The function's declared `inputSchema` remains the authority for its JSON `input`; the service-token layer does not invent a second nested schema.++Example for one declared project function:++```bash+mso mcp service-token \+ --label visual-worker \+ --client-id visual-worker \+ --scope exec \+ --tools project_capabilities,project_function_call \+ --constraints-json '{"project_capabilities":{"project":["example-project"]},"project_function_call":{"project":["example-project"],"name":["capture_snapshot"]}}'+```++The command prints the raw bearer **once**. Treat that output as a secret: do not commit it, paste it into logs/chat, or put it in a world-readable file. The MCP store keeps only the bearer hash under the existing owner-only `~/.mso` permissions. Service tokens use the normal 90-day bearer lifetime as a backstop; rotate/revoke them when the consumer no longer needs access.++```bash+mso mcp list # metadata/id only; never returns raw bearers+mso mcp revoke <id>+```++At runtime the restriction is fail-closed in both discovery and execution: `initialize` / `tools/list` expose only the token's allowlist, and `tools/call` independently rejects a hidden tool, wrong project, or wrong function name and records the denial in the MCP audit trail. The token's scope is still a ceiling, not a substitute for the allowlist, project-function manifest, filesystem/host guards, or normal tool checks.++### Bounded visual output from project functions++Declared project functions normally return their `{ code, stdout, stderr }` process envelope. A successful function may opt into direct MCP visual output by writing one JSON document with protocol `mso.project-function-content.v1`. Promotion is deliberately strict: exit code must be zero, stderr must be empty, there may be at most four content rows and exactly one image, the image must be PNG/JPEG/WebP with a matching file signature, decoded image size is capped at 620 KiB, and text is bounded. Anything malformed or unsupported is not promoted into trusted image content. This keeps visual debugging behind the same fixed-argv project-function boundary rather than creating arbitrary binary/file transport.+## Toolset version, hash and action refreshThe catalog has a stable server version plus a schema-derived toolset signature. It is returned by public `GET /mcp`, MCP `initialize`, scoped `tools/list`, and the authenticated Settings → MCP endpoint. The signature changes when a name, description, input schema, scope, annotation or per-operation limit changes—not only when the tool count changes.diff --git a/docs/PROGRESS.md b/docs/PROGRESS.mdindex 4dd03a72..7364599e 100644--- a/docs/PROGRESS.md+++ b/docs/PROGRESS.md@@ -1,4 +1,11 @@# mso — Progress Log++## 2026-09-05 — Restricted MCP service tokens + truthful diverged self-update++- **Machine automation gets least-privilege MCP bearers instead of a generic exec token.** A trusted local operator can mint a service token only from the owner CLI; there is no HTTP mint endpoint. The current service-token policy permits only `project_capabilities` and `project_function_call`, requires an exact top-level string constraint for every allowlisted tool, filters `initialize` / `tools/list`, and re-checks both the tool allowlist and argument constraints at `tools/call`. OAuth/browser tokens keep their existing behavior. Raw bearers are emitted once and the existing owner-only MCP store persists only their SHA-256 hash; normal token expiry/revocation still applies.+- **Project-function visuals stay bounded rather than becoming arbitrary binary passthrough.** A successful declared project function may opt into `mso.project-function-content.v1`; MSO accepts at most one PNG/JPEG/WebP image with matching magic bytes plus bounded text/content, under the existing runner output cap. Non-zero exits, stderr, malformed envelopes, unsupported MIME types, oversized payloads, and invalid image signatures remain ordinary process output or failures rather than trusted MCP image content. Project functions still execute fixed argv and validate caller JSON against their declared schema.+- **Self-update now models both sides of Git history.** Status uses `git rev-list --left-right --count HEAD...origin/main` and reports `ahead` and `behind` separately. A normal update is refused when local `main` is ahead or diverged, so unpushed work cannot be silently deployed or overwritten; `--rebuild` remains an explicit rebuild of the already-selected clean checkout and does not mutate Git history. Settings → About suppresses the Update action for local-ahead/diverged state and explains the real reconciliation requirement instead of mislabeling it as a remote-connectivity failure.+- **Verification:** the two implementation commits remain independently reviewable; targeted MCP/updater tests pass 65/65, TypeScript passes, `git diff --check` is clean, the safe out-of-tree production build passed on the same implementation head, and GitHub dependency/security/CodeQL/ShellCheck/Verify checks were green before this documentation follow-up.- **Rahmanef-aligned MCP widget palette / Block + Page v2 (2026-09-04):** MCP server `1.10.0` / toolset `2026.09.04.7` moves the two canonical ChatGPT resources to `ui://mso/block-v2.html` and `ui://mso/page-v2.html` so hosts do not reuse the old purple CSS cache key. Block and Page now share one visual-token source aligned with `rahmanef.com`: light `#f4f4f7` / `#1c1c1f`, dark `#1b1b20` / `#f2f2f5`, accent `#1f6df0`, Plus Jakarta Sans display copy, Inter body copy, fine separators, and editorial foreground/background primary-action inversion. ChatGPT theme changes propagate through `window.openai.theme` with a color-scheme fallback. Block/Page v1 and the earlier workflow/surface URIs remain readable but unlisted compatibility aliases; the headless workflow and two-surface/security contracts are unchanged.- **Headless workflows + two-surface MCP UI contract (2026-09-04):** MCP server `1.10.0` / toolset `2026.09.04.6` removes the automatic UI binding from `workflow_start`: orchestration, collision checks, tracing, evidence, and learning continue in the background without consuming the answer with a progress card. ChatGPT now has exactly two canonical MCP App resources: `ui://mso/block-v1.html` through `render_mso_block` for compact validation/action/CRUD input-output, and `ui://mso/page-v1.html` through `render_mso_page` for native operator views plus reviewed development/preview/production embeds. Block buttons send a user-approved follow-up and never execute mutations inside the widget, preserving normal scope, approval, audit, and workflow boundaries. The prior workflow/surface URIs remain non-advertised read aliases, while `workflow_status` and `render_mso_surface` remain app-only compatibility shims for cached clients. The ChatGPT transport profile is 66 tools: 64 model-visible actions (35 read / 17 write / 12 exec) plus two app-only shims; the full catalog is 90. Only Block and Page advertise a resource URI.- **Local release audit timeout hardening (2026-09-04):** the tolerant pre-push dependency audit now caps `bun audit --json` at 15 seconds. A registry timeout is reported and skipped only in the local gate, matching its existing network-tolerant policy; CI remains the fail-closed dependency-audit authority. This prevents a slow registry request from holding GitHub's pre-push SSH session open for minutes and failing the otherwise-green release with a transport/SIGPIPE-style exit.