Node-based terminal manager for AI coding agents — tmux-backed terminals and parallel agent sessions as draggable nodes on an infinite pan/zoom canvas. macOS, Linux, and a browser Server Edition.
TypeScript adhdagent-orchestrationai-agentscanvasclaude-codecodexcoding-agentsdeveloper-toolselectrongeminilinuxmacosmultiplexeropencodeparallel-agentsterminalterminal-emulatorterminal-multiplexertmuxworkspace-manager
docs(relay): Share with team — the real SAS-skip rule, the full two-writer gap, --json and bridge precision
review373fe403661a
diff --git a/CLAUDE.md b/CLAUDE.mdindex 66b12b471..51320eaad 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -8455,12 +8455,18 @@ come from the cached, validated probe, never from the renderer), and every commarestarts (threaded through every `fileToProject` base; a file field of that name is ignored).Every reopen path (Recently closed, ⇧⌘T, `openSshProject`'s endpoint reuse) warns first, and only"Open here anyway" clears it.-- **The SAS skip is ONE bookmark shape**: `approvedAt` + `source:'ssh'`, seeded by- `shareTeam.seedBookmark` from the code `team bootstrap` just returned over the project's own ssh- channel (host key authenticated by `known_hosts`; `decodeJoinCode` checks hostId = hash(key) and- `wss:`/loopback `ws:`). It rides the existing client bookmark auto-confirm, so it is NOT a seventh- confirm site. Feed `seedBookmark` nothing but a code a bootstrap returned over that channel; a- pasted code always compares the SAS. A failed seed degrades to the SAS prompt, never to a skip.+- **The SAS skip lives in ONE writer of `approvedAt`, and `source` gates nothing.** The client+ auto-confirm is `autoApprove: approvedAt !== null` (`hosted-join.ts`, for the bookmark recorded+ with the code's exact host key); `relay-bookmarks.ts` only validates `source`, it is a label.+ Normally `approvedAt` is set by a human's OK after a SAS comparison. `shareTeam.seedBookmark`+ (`main/remote-ssh/share-team.ts`) is the one writer that sets it WITHOUT one: a new bookmark+ labelled `source:'ssh'`, or, for an existing bookmark with the same hostId and host key,+ `approvedAt` set on it while it keeps its token and its `source` (often `'code'`). It rides the+ existing client bookmark auto-confirm, so it is NOT a seventh confirm site. That is sound only for+ its input: the join code `team bootstrap` returned over the project's own ssh channel (host key+ authenticated by `known_hosts`; `decodeJoinCode` checks hostId = hash(key) and `wss:`/loopback+ `ws:`). Feed it nothing else; the code does NOT yet enforce "only the last bootstrap's code". A+ failed seed degrades to the SAS prompt, never to a skip; any pasted code compares the SAS.- **Hosted tabs are one per shared project, and the tab id IS the host project id.** relay-apitranslates no ids, so a tab under any other id asks the host about a project it does not know: aclosed relay copy under that id is replaced, anything else holding it (an open tab, a local@@ -8473,10 +8479,12 @@ come from the cached, validated probe, never from the renderer), and every comma- **Admin errors are stable codes, and a `--json` refusal goes to STDOUT.** `E_BAD_KEY`,`E_BAD_CWD`, `E_HOSTING_OFF`, `E_ADOPT_FAILED`, `E_BAD_REQUEST`, `E_UNSUPPORTED`(`core/relay/admin-error.ts`); a remote caller branches on the code, never the sentence, and- Node's own errno codes never pass as one (`adminErrorCode`). `team <verb> --json` prints- `{"ok":false,"code","error"}` on stdout (exit 1) beside the human line on stderr, because the+ Node's own errno codes never pass as one (`adminErrorCode`). Under `team <verb> --json` a server+ failure (exit 1: a refusal, or no server reachable) prints `{"ok":false,"error","code"?}` on+ stdout beside the human line on stderr (`code` only when the server sent one), because thedesktop's ssh exec reads stdout only: a refusal on stderr alone arrives as an empty, unparseable- reply. Bootstrap starts hosting and waits up to 15 s for the relay's first verdict BEFORE it+ reply. The CLI's own argv/stdin refusals (`parseTeamArgv`, the resume stdin parse) exit 2 on+ stderr only. Bootstrap starts hosting and waits up to 15 s for the relay's first verdict BEFORE itwrites an owner, a project or a share: a refusal (`E_HOSTING_OFF`) writes none of them, and noverdict yet (`hosting:'starting'`) is still a success.- **`curl | bash` is a trap: download to a temp file first** (`SHARE_INSTALL_SCRIPT`). With no@@ -8487,16 +8495,28 @@ come from the cached, validated probe, never from the renderer), and every commadata dir. And a value with `'` or `\` is refused, never nested-quoted: fish's single quotes treatboth as escapes, so no nesting survives every login shell.-**Known gap: one hook script, two writers.** The server core's local install and the desktop's-`RemoteHooks` write the same `~/.nodeterm/agent-hooks/<agent>.sh` (same command, same event lists;-the script reads `$NODETERM_HOOK_ENDPOINT` per session, so one copy serves both cores), but not the-same bytes: only the server bakes the Codex thread-identity prelude (`REMOTE_IDENTITY_ROOT` is-null). Last writer wins, so after a desktop connect a server-run shared-identity Codex node reports-no status until the server restarts.--**Surfaces (Share with team):** Desktop is full (any desktop OS; the host must be Linux). Server-Edition runs `team bootstrap`/`team resume` from a shell, and its `shareTeam` answers-`E_UNSUPPORTED` (it has no SSH projects). Mobile is N/A.+**Known gap (accepted for v1): two writers of the same agent files on a shared host.** The server+core and the desktop's `RemoteHooks` (for any SSH project still on that host) write the same files+under one `$HOME`, with different bytes; the last writer wins.+- **What collides.** The hook script `~/.nodeterm/agent-hooks/<agent>.sh` (same path, command and+ event lists; `mergeManagedHook` strips our entries first, so a config never doubles, and under a+ version skew the last writer's event set stays): only the server's copy carries the Codex+ thread-identity prelude (`REMOTE_IDENTITY_ROOT` is null). And the discovery files: by default the+ server writes the `get-linked-context` skill and the context-link blocks in `~/.codex/AGENTS.md`,+ `~/.gemini/GEMINI.md` and opencode's `AGENTS.md` (`src/server/index.ts` `initServerContextLink`),+ and with server canvas control on the `manage-nodeterm-canvas` skill and blocks+ (`src/server/canvas-control.ts`), all naming its own shims under `<dataDir>`, which bake the+ prelude; `RemoteHooks` writes the same files naming the neutral `~/.nodeterm/context.sh` /+ `nodeterm.sh`.+- **When each re-asserts.** The server at every start (the daily auto-update restarts it). The+ desktop: the hook script on connect and on every hook-tunnel repair (the reuse branch re-runs+ `setup()`); the discovery files through the agent-tools freshness check, which rewrites any that+ differ on connect, on every tunnel repair, and hourly while a project on that host is connected.+- **Who is affected.** Only shared-identity Codex tool shells on the server: they carry no+ `NODETERM_*` env and need the prelude to find their node, so against the desktop's copies their+ hooks report nothing. Every other pane carries its own endpoint env and works with either copy+ (and when a session's endpoint is dead, the script's failover can deliver its event to the other+ core's endpoint).**Known limitations** (full list in the doc): non-editors still receive cross-project presence and`context:update` metadata (deploy one core per team); a viewer's socket backlog over 1 MB still@@ -8505,10 +8525,12 @@ non-content fields stay last writer wins between tabs, the share-time window, ovedits to another core, load-time repairs that are never cast, the card modal's comments on a relaytab) are under "Known limits" in the doc.-**Surfaces:** Desktop is full (joiner, plus approval and invite code in an owner's hosted tab).-Server Edition is the host (the `team` CLI; its browser clients cannot approve and are not hosted-peers). Mobile is N/A for v1: the phone still speaks the legacy dialect, and the host it would join-now exists in core. The iOS follow-up is the tunnel-dialect migration.+**Surfaces:** Desktop is full (joiner, plus approval and invite code in an owner's hosted tab, plus+Share with team from any desktop OS onto a Linux host). Server Edition is the host (the `team` CLI,+`team bootstrap`/`team resume` included; its browser clients cannot approve and are not hosted+peers, and its `shareTeam` rejects with `E_UNSUPPORTED`, having no SSH projects). Mobile is N/A for+v1: the phone still speaks the legacy dialect, and the host it would join now exists in core. The+iOS follow-up is the tunnel-dialect migration.## Speech / dictation (desktop + server)diff --git a/docs/SERVER.md b/docs/SERVER.mdindex f186a4697..d295e3c48 100644--- a/docs/SERVER.md+++ b/docs/SERVER.md@@ -233,10 +233,11 @@ hosting, makes the key an owner, adopts the folder into this core's workspace (dpath; an existing `.nodeterm/project.json` keeps its nodes) and shares it, then prints the joincode. `team resume --project <id>` restarts, on this core's own tmux socket, the agent sessions adesktop handed over, each with its conversation resumed; it reads its session list as JSON on-**stdin**, never from the command line. Under `--json` both print a refusal as one JSON line on-stdout with a stable code (`E_BAD_KEY`, `E_BAD_CWD`, `E_HOSTING_OFF`, `E_ADOPT_FAILED`,-`E_BAD_REQUEST`, `E_UNSUPPORTED`). The browser build itself cannot start Share with team (it has no-SSH projects; its `shareTeam` answers `E_UNSUPPORTED`).+**stdin**, never from the command line. Under `--json`, a server failure (exit 1) prints one JSON+line on stdout, with a stable code when the server sent one (`E_BAD_KEY`, `E_BAD_CWD`,+`E_HOSTING_OFF`, `E_ADOPT_FAILED`, `E_BAD_REQUEST`, `E_UNSUPPORTED`); a command line the CLI itself+refuses exits 2 on stderr only. The browser build cannot start Share with team: it has no SSH+projects, and its `shareTeam` rejects with `E_UNSUPPORTED`.## Security modeldiff --git a/docs/hosted-team-relay.md b/docs/hosted-team-relay.mdindex c4c5c54f2..30f834efc 100644--- a/docs/hosted-team-relay.md+++ b/docs/hosted-team-relay.md@@ -1,8 +1,8 @@# Hosted team relay (a Server Edition as the relay host)-**Status:** sub-project 1 of "team on an SSH host", built on `feat/hosted-team-relay` (2026-09).-Everything below was checked against the code on that branch. Where the design spec says something-else, the code wins; the spec is a local planning file and is not the reference.+**Status:** built from 2026-09 on: the relay host, the shared canvas authority, host key proof of+possession and Share with team. Everything below was checked against the code. Where a design spec+says something else, the code wins; the specs are local planning files and are not the reference.**Builds on:** `docs/remote-sessions.md` (relay tabs, the trust gate, Team Access) and`docs/team-presence.md` (presence, co-attach, canvas sync).@@ -111,10 +111,13 @@ answer is false) and prints the same join code. Sharing a second folder is the sanother `--adopt`: the same team and the same join code, and teammates who are connected get its tabat once (see [Hosted tabs](#hosted-tabs)).-`--json` prints `{hostId, projectId, projectName, joinCode, hosting, created}`. A refusal under-`--json` is one JSON line on **stdout**, `{"ok":false,"code":"E_…","error":"…"}` (exit 1), beside-the human sentence on stderr, because a caller reading over an ssh exec channel (the desktop) reads-stdout only. The codes are stable; branch on them, never on the sentence:+`--json` prints `{hostId, projectId, projectName, joinCode, hosting, created}`. Under `--json`, a+failure from the server (a refusal, or a server that cannot be reached; exit 1) is one JSON+line on **stdout**, `{"ok":false,"error":"…","code":"E_…"}`, beside the human sentence on stderr,+because a caller reading over an ssh exec channel (the desktop) reads stdout only. `code` is there+only when the server sent one. A command line (or, for `team resume`, a stdin) that the CLI itself+refuses exits 2 and prints to stderr only. The codes are stable; branch on them, never on the+sentence:| Code | Meaning ||---|---|@@ -123,7 +126,7 @@ stdout only. The codes are stable; branch on them, never on the sentence:| `E_HOSTING_OFF` | Hosting could not start (the scheduler's reason follows), or it stopped before a join code could be issued. || `E_ADOPT_FAILED` | The folder's `.nodeterm/project.json`, or this core's own workspace index, is there but cannot be read. Nothing is set aside; fix the file and run it again. || `E_BAD_REQUEST` | A malformed request: a bad label, project id or resume list. |-| `E_UNSUPPORTED` | This server cannot adopt folders or resume sessions. The desktop's `shareTeam` verbs answer it too, on the Server Edition and in relay tabs. |+| `E_UNSUPPORTED` | This server cannot adopt folders or resume sessions. (Separately, the renderer's `shareTeam` verbs REJECT with an error coded `E_UNSUPPORTED` in the Server Edition's browser and in relay tabs; that is the bridge refusing, not a JSON reply from a server.) |### `team resume`@@ -158,15 +161,15 @@ ls ~/Library/Application\ Support/*/remote-peer-key.jsonShare with team reads this key for you; nothing else in the UI shows it in v1.The file is created the first time the desktop hosts a Team Access invite, connects to another-desktop's pairing code (New Remote Connection) or joins a hosted team. Pairing a **phone** does not-create it; that uses a different key file (`remote-host-key.json`). Only if the file is really not-there, run `team init` and `team info` for a join code and paste it once (see+desktop's pairing code (New Remote Connection), joins a hosted team or runs Share with team. Pairing+a **phone** does not create it; that uses a different key file (`remote-host-key.json`). Only if the+file is really not there, run `team init` and `team info` for a join code and paste it once (see[The first connect](#the-first-connect)); that join spends one of the team's shared device mints.While your desktop asks you to read a code to an owner, `team status --json` lists your device under-`pending` with its `peerKeyB64` and `sas`. Take the key whose `sas` matches your prompt, press Cancel-on the prompt (that ends the request), run `team bootstrap` (or `team add-owner`) with that key, and-paste the code again. A request that is still pending when its key becomes an owner is not upgraded;-it would wait out its 10 minutes.+`pending` with its `peerKeyB64` and `sas`. Take the key whose `sas` matches your prompt, press+Cancel on the prompt (that ends the request), run `team bootstrap` (or `team add-owner`) with that+key, and paste the code again. A request that is still pending when its key becomes an owner is not+upgraded; it would wait out its 10 minutes.### The first connect@@ -196,7 +199,8 @@ grants the chosen role once the joiner has pressed OK too.**Share with team…** turns a desktop **SSH project** into a hosted team on the same host, with thisdesktop as an owner. It is in the project tab's ⌄ menu and in the sessions sidebar's project menu(SSH projects only), and in ⌘K as "Share <name> with team" for the active one. While the project's-SSH connection is down it is disabled: "Connect this project first (its SSH connection is down)."+SSH connection is down the two menu items are disabled with the reason "Connect this project first+(its SSH connection is down).", and the ⌘K row shows that reason and does nothing when run.The code: `src/renderer/lib/shareSshTeam.ts` (the order, pure), `components/ShareTeamDialog.tsx`,`src/main/remote-ssh/share-team.ts` (the `shareTeam` IPC verbs),@@ -296,7 +300,7 @@ again.12. **`team resume`** for the resumable agents whose sessions are gone, with the list on stdin.13. **Join**, and show the invite code.-Any failure after step 6 and before `team bootstrap` succeeds takes the mark back, and reopens the+Any failure from step 6 on, before `team bootstrap` succeeds, takes the mark back, and reopens theSSH project if step 8 had closed it: "The SSH project was reopened; nothing was changed." If thatundo itself fails, the result says so instead: the project may still be closed and still carry themark that stops its mirror, and reopening it from "Recently closed" (which warns, see below) clears@@ -343,13 +347,20 @@ again.### The owner's own join skips the SASA pasted code makes you read a SAS to an owner ([The first connect](#the-first-connect)). Share with-team does not, and it is the only join that does not. The join code came back from `team bootstrap`-over the project's own SSH channel, whose host key `known_hosts` already authenticated, and the code-names the relay key it was minted for (`decodeJoinCode` checks that the host id is the hash of that-key). That is the assurance comparing six digits by eye gives. So before joining, the desktop seeds-the team's bookmark with `approvedAt` and `source: 'ssh'`, and the bookmark's auto-confirm opens the-connection; the host approves its own half because your key is an owner in `team.json`. A bookmark-already held for the same team and key keeps its device token. Every other join, a pasted code or a+team does not. The client's auto-confirm reads one thing, the bookmark's `approvedAt` (for the host+key the bookmark was recorded with; `hosted-join.ts`), and normally only a human's OK after a SAS+comparison sets it. `shareTeam.seedBookmark` is the one writer that sets it without one: it writes a+new bookmark with `approvedAt` (labelled `source: 'ssh'`), or, when a bookmark for the same host id+and host key already exists, sets `approvedAt` on it and keeps its device token and its label+(`source: 'code'` stays `code`). `source` is a label only; nothing reads it to decide.++That is safe only because of what `seedBookmark` is given: the join code `team bootstrap` just+returned over the project's own SSH channel, whose host key `known_hosts` already authenticated. The+code names the relay key it was minted for (`decodeJoinCode` checks that the host id is the hash of+that key), which is the assurance comparing six digits by eye gives. Its input must be such a code+and nothing else; the desktop does not yet check that the code it is handed is the one the last+bootstrap returned. The host approves its own half because your key is an owner in `team.json`. If+the seed fails, the join asks for the SAS like a pasted code. Every other join, a pasted code or ateammate's, still compares the SAS.### Refusals@@ -374,32 +385,51 @@ desktop instead, remove the system install first (its service, its update timerunder `/etc/systemd/system/`) and share again, which installs a per-user server; nothing of root'steam or data is carried over.-### Agent hooks on a shared host--The server core's own hook install (`src/core/agents/hooks/install-helper.ts`-`managedHookScriptPath`, and `codex.ts`'s `scriptPath`) and the desktop's install over SSH-(`RemoteHooks`, `src/main/remote-ssh/remote-hooks.ts`) point each agent's config-(`~/.claude/settings.json`, `~/.gemini/settings.json`, `~/.codex/hooks.json`, …) at the same-machine-wide script, `~/.nodeterm/agent-hooks/<agent>.sh`, with the same command and the same event-lists (`@shared/agents/hook-events.ts`), so a config never gains a second entry. Both run as the-same user (the server runs as your SSH login), so it is one file. The script reads-`$NODETERM_HOOK_ENDPOINT` when it runs, and every session carries its own: the SSH project's-sessions name the desktop's reverse-tunnel endpoint-(`~/.nodeterm/hook-endpoint-<projectId>-<owner>.env`), the server core's name-`<dataDir>/hook-endpoint.env`. One copy therefore serves both sets of sessions, and each reports to-its own core.--**The bytes are not identical**, and the last writer wins. The server bakes a Codex thread-identity-prelude into every script, pointing at its own data directory; `RemoteHooks` writes none-(`REMOTE_IDENTITY_ROOT = null`). The server rewrites the scripts each time it starts, the desktop-each time an SSH project on that host connects. The prelude does nothing for the desktop's sessions-(it runs only when `NODETERM_NODE_ID` is empty). Without it, though, the hooks of a Codex node the-server core runs in shared-identity mode cannot find their node (they run from Codex's shared-app-server, which carries only `CODEX_THREAD_ID`), so that node reports nothing. That is the state-right after sharing to a server that was already running (the desktop connected after the server-last started), and after any later connect of another SSH project on that host, until the server-restarts (the daily auto-update restarts it, unless it was turned off). Likewise, when the desktop-and the server run different nodeterm versions, the last writer's script serves both.+### Agent hooks and discovery files on a shared host (a known gap)++After a share, two nodeterm writers keep the same files under the same `$HOME`: the server core (it+runs as your SSH login) and this desktop's `RemoteHooks` (`src/main/remote-ssh/remote-hooks.ts`)+for any SSH project it still has on that host. This is accepted for v1 and stated in full here.++**What they share.** Both point each agent's hook config (`~/.claude/settings.json`,+`~/.gemini/settings.json`, `~/.codex/hooks.json`, …) at the same machine-wide script,+`~/.nodeterm/agent-hooks/<agent>.sh` (`src/core/agents/hooks/install-helper.ts`+`managedHookScriptPath`, `codex.ts`'s `scriptPath`). A config does not gain a second entry because+`mergeManagedHook` strips every entry carrying our marker before it adds its own; under a version+skew between the two, the last writer's event set is the one left. The script reads+`$NODETERM_HOOK_ENDPOINT` when it runs, and every pane carries its own: the SSH project's sessions+name the desktop's reverse-tunnel endpoint (`~/.nodeterm/hook-endpoint-<projectId>-<owner>.env`),+the server core's name `<dataDir>/hook-endpoint.env`. Normally each session reports to its own+core; when a session's endpoint is dead, the script's failover walks the other endpoint files on the+host, so a desktop session whose tunnel is down can have its event delivered to the server's+endpoint instead.++**What collides.** The two writers do not write the same bytes:++- **The hook script.** The server bakes a Codex thread-identity prelude into it, pointing at its own+ data directory; `RemoteHooks` writes none (`REMOTE_IDENTITY_ROOT = null`).+- **The discovery files.** At boot, by default, the server writes the context-link skill+ (`~/.claude/skills/get-linked-context/SKILL.md`) and its marker blocks in `~/.codex/AGENTS.md`,+ `~/.gemini/GEMINI.md` and opencode's `AGENTS.md`, all naming its own shim under+ `<dataDir>/context-links/`; with server canvas control on, also the `manage-nodeterm-canvas` skill+ (system and managed-account dirs) and its blocks, naming `<dataDir>/canvas-control/nodeterm.sh`.+ Those shims bake in the same prelude. `RemoteHooks` writes the same files naming its neutral+ `~/.nodeterm/context.sh` and `~/.nodeterm/nodeterm.sh`, which carry none.++**When each one writes.** The server, each time it starts (the daily auto-update restarts it, unless+that was turned off). The desktop rewrites the hook script whenever it sets up an SSH project on+that host, which is on connect and again on every hook-tunnel repair; its agent-tools freshness+check rewrites any discovery file that differs from its own on connect, on every tunnel repair, and+hourly while a project on that host stays connected. The last writer wins.++**Who is affected.** Only Codex nodes the server core runs in shared-identity mode, and only their+tool shells: those run from Codex's shared app-server, carry `CODEX_THREAD_ID` and none of the+`NODETERM_*` environment, and need the prelude to find their node. Against the desktop's copies,+such a node's hooks report nothing (the script exits at its `NODETERM_NODE_ID` gate) and its shell+calls to the canvas and context shims cannot say which node they come from. That is the state right+after sharing to a server that was already running (the desktop connected after the server last+started), and whenever the desktop re-asserts its copies later, until the server's next start. Every+other pane, on either core, carries its own endpoint in its environment and works with either copy.## Roles@@ -1159,7 +1189,7 @@ are unchanged.not hosted peers; the access policy never applies to them, and they cannot call `relay:hosted:*`(those verbs are intercepted inside the relay session and never registered on the platform). Ajoin code pasted into a browser tab gets one "not supported in the browser build" notice. Share- with team does not apply (the Server Edition has no SSH projects, and its `shareTeam` answers+ with team does not apply (the Server Edition has no SSH projects, and its `shareTeam` rejects with`E_UNSUPPORTED`), but `team bootstrap` and `team resume` work from a shell on the host.- **Mobile:** N/A for v1. The phone still speaks the legacy relay dialect. The host it would joinnow exists in core (a standing listener on the tunnel dialect); the phone side needs thediff --git a/src/core/relay/relay-trust.ts b/src/core/relay/relay-trust.tsindex 2b8b99546..af93b85c1 100644--- a/src/core/relay/relay-trust.ts+++ b/src/core/relay/relay-trust.ts@@ -33,9 +33,10 @@// link's own secret, read from the host's own link record (src/core/watch-link/link-host.ts; any// other key is denied at once, never asked). Client side: the joining human's// `relay:client:confirm`, and the client's `autoApprove` for a hosted team's approved bookmark-// (src/main/remote/hosted-join.ts). That auto-confirm also covers a bookmark Share with team seeds-// with `source: 'ssh'`, which is not a new confirm site: its code came over an authenticated ssh-// channel. A seventh is a design change.+// (src/main/remote/hosted-join.ts). That auto-confirm reads the bookmark's `approvedAt` alone+// (`source` is a label). Share with team's `seedBookmark` sets it without a SAS comparison; that is+// not a new confirm site, because the code it is given came back from `team bootstrap` over an+// authenticated ssh channel. A seventh is a design change.import {confirmLocal,confirmRemote,