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.
Mobile chat view — design (2026-09-27)
Bring the desktop ⌘M chat view (#943–#957) to nodeterm mobile (nodeterm-ios), with a Claude-mobile
feel: the session transcript rendered as markdown, a composer, a live "working" indicator, and Plan /
Question cards that answer the agent's prompts — over both transports (direct SSH and the E2EE
relay), in one delivery.
1. Context (measured, 2026-09-27)
- iOS today (
nodeterm-iosorigin/main 43bcf5c): no markdown and no transcript view anywhere; a session opens only as a SwiftTerm terminal (Features/Session/SessionView.swift). A Claude-style composer already exists (Terminal/DictationComposer.swift:+attach via PhotosPicker/fileImporter, mic viaServices/SpeechDictation.swift+ Whisper/Parakeet/Apple engines, ▲ send). SPM deps: SwiftTerm, Citadel, Sodium, WhisperKit, FluidAudio. - Transports:
SSHTransport(Citadel) withServices/HostCommands.swift(run/stream, reused session) — exec, file reads, tmux send-keys, SFTP uploads to~/.nodeterm/uploads/, answer-file writes.RelayTransport(E2EE NaCl) calls a fixed RPC set served by desktopsrc/main/remote/host-service.tsonRpc(pty., fs. jailed to shared roots, git., projects., node.*). No transcript, chat-send or permission-answer RPC exists. Server Edition has no relay host service (SSH-only for the phone). - Status to the phone: the agent-status mirror (
core/agent-status-mirror.ts→agent-status.json/ per-SSH-project~/.nodeterm/agent-status-<projectId>.json), polled every 4 s over SSH (Services/AgentStatusMonitor.swift), relayprojects.listevery 30 s off-LAN, plus APNs/Live Activities. The mirror carries state/sessionId/account/hibernated and inbox events; no transcript path, noheld(plan vs question), no model/effort. - Approvals today (
Services/InboxApproval.swift): allow/deny via the plain-word answer file (~/.nodeterm/pending/<id>.answer) when a pendingId exists, else tmux send-keys (digits/Escape/Enter). No structured answers (plan mode / revise / question answers / free text); SSH only. - Build reality: SwiftUI cannot be compiled on this Linux server; a Linux Swift 6.1.2 toolchain
(
/root/.cache/swift/swift-6.1.2-RELEASE-ubuntu24.04) compiles and tests pure logic in a scratch SwiftPM harness. iOS CI (.github/workflows/ios-build.yml) has been billing-blocked since 2026-09-14. - Reusable desktop core:
core/transcript-reader.ts(parseChatWindow, pagedChatTranscriptResultwitholderCursor/key/unmatchedResults/at, grow-on-no-complete-line),core/chat-tool-body.ts(plan/question bodies),core/remote-ssh/transcript-window.ts(transcriptPageCommand, POSIX sh, one round trip, size in the same reply),core/remote-transcript-locate.ts,core/agents/permission-decision.ts(buildPermissionDecision,answerHeldPermission, revision-5 gate),transcript-ipc.tsreadChatPage.
2. Decision: one wire format, two producers
Rejected: (2) phone parses on both transports (relay ships raw JSONL; still needs a desktop answer RPC; the TS parser must stay for desktop ⌘M anyway, so drift risk just moves); (3) a host-side helper parses for SSH (POSIX sh can't parse JSON; node is not guaranteed on hosts — Claude ships as a standalone binary).
Chosen: the phone always consumes the same ChatPage JSON. The desktop produces it for relay
hosts (reusing core unchanged); the phone produces it itself on SSH hosts (Swift port of the parser),
so SSH works with no desktop running. Golden fixtures generated by the TS implementation lock the
Swift port to byte-identical output.
3. Data & transport
3.1 Wire format
ChatPage {
version: 1
messages: ChatMessage[] // desktop shape: role, parts (text | thinking | tool{name,arg,result,
// summary,body,questions,id}), key (byte offset), at (ms)
found: boolean
olderCursor: number | null
unmatchedResults: {id, result}[]
model?: string // from the latest assistant record
effort?: string // from the latest assistant record (`effort` field)
sessionId?: string // the session id the host READ this page with; absent = none resolved
}
ChatStatus {
version: 1
state: 'working' | 'waiting' | 'blocked' | 'done' | null // the desktop WINDOW's hook state; null = unknown
held: {pendingId, toolName, questions?} | null
hibernated, paused, dropped, sessionEnded: boolean
structuredAnswers: boolean // held ticket accepts structured answers (else "answer in the terminal")
hostRefuses: boolean // the HOST's agent-status mirror refuses sends right now
refusal?: 'working' | 'dialog' // why, when hostRefuses
}
ChatSendOutcome { // chat.send reply body
result: 'sent' | 'refused' | 'pasted-not-submitted' | 'unconfirmed'
reason?: 'working' | 'dialog' | 'asleep' | 'paused' | 'dropped' | 'exited'
| 'busy' | 'late' | 'unavailable' | 'failed' // only with 'refused'
}
version lets the phone refuse a newer shape honestly: a ChatPage or ChatStatus whose version
it does not know is not rendered / treated as locked. Composer rule: unlocked only when
hostRefuses is false, held is null and state is done or null; any other value — including a
state string the phone does not recognize — is locked. hostRefuses exists because after a desktop
restart the window knows nothing (state: null) while the host mirror can still hold a live dialog,
and chat.send refuses on the mirror; the status must show the same lock the send applies. The
desktop re-gates every send regardless of what the phone showed. An unknown reason value is shown
as a generic "not sent".
3.2 Relay producer (desktop, this repo) — implemented
Four verbs in host-service.ts onRpc (handleChat), served to an approved phone only (the
session's approval gate refuses every RPC before approval). They are NOT reachable from a Team-access
relay guest: relay-host.ts serves no phone dialect at all (its onRpc is inert), so the
project-scope jail in relay-project-scope.ts never sees them and they widen nothing. The phone
sends only nodeId (plus paging / text / answer payload) — cwd, account, agent, session id,
transcript path and remote routing are resolved host-side from the desktop's own registry
(WorkspaceStore.getNodeResolved + the agent-status mirror; node ids are attacker-controllable, so
a phone-supplied path is never trusted). Ops: main/remote/host-chat.ts (createHostChat, wired
as hostBridge.chat in main/index.ts, forwarded by both phone hosts).
| verb | params | reply | does |
|---|---|---|---|
chat.page |
{nodeId, before?, maxBytes?} |
{page: ChatPage} |
Only for agents with a chat view — canChat(capabilityAgentId(agent)) (claude, grok, gemini, codex, copilot, opencode, cursor (its SQLite chat store, src/core/cursor-chat.ts; local only), and custom agents whose base harness is one of them; codex is read by its own reader, src/core/codex-chat.ts, locally and on an SSH host — fixtures and the record rules in src/shared/chat-fixtures/codex/); anything else is refused before any read. readChatTranscript with the ⌘M panel's own deps (paged ALWAYS — an absent page is the default 256 KB tail; grok unpaged) + model/effort, version: 1. Session id: the RENDERER's agent-status id first (what ⌘M reads — after a desktop restart a hook-fed id lives only there), then the mirror's, then the node's minted id; the fallbacks apply only when the renderer does not answer within 3 s or knows none. Remote (SSH-project) nodes are read REMOTE-ONLY (remoteOnly): over the live pty's ControlMaster, else the node's PROJECT's master (an idle tab / any node after a restart has no pty), and never from this machine's disk — a remote node with no reachable master, or a host that did not answer, is Could not read the transcript., not an empty page. The host-side locate is TRI-STATE (locateRemoteTranscriptRef, src/main/remote-transcript-page.ts): a CLEAN MISS (the host looked and has no such file, or there is no session id to look for) is found:false, and only a failure to ask (no master, no resolved home, a failed ssh, a path outside the jail, a failed ranged read) is the error. For REMOTE nodes the desktop ⌘M panel follows the same remote-only rule and the same absent-vs-unreadable split (same deps): its IPC handler decides remoteness from the shell's own records (isRemoteNode — live remote pty or workspaceStore.sshProjectIdForNode, never a renderer flag) and applies remoteOnly to the paged read, the legacy unpaged read, the find-bar index and the presence probe (unknown); it shows unreadable as "Couldn't read the transcript." (a remote grok node is read on its host too — core/remote-grok-chat.ts, whole-file and unpaged, with the same absent-vs-unreadable split; a remote node of an agent with no remote reader — CHAT_LOCAL_ONLY — as "not supported yet"). LOCAL nodes on ⌘M are unchanged — the renderer still sends the cwd, so claude's cwd fallback still applies there; the cwd-only-when-remote rule below is the phone path's. The cwd rides ONLY for a remote node with a known id (the host-side locate needs it); locally a known-but-dead id must not fall back to the cwd's newest transcript (another node's), and with no id at all ⇒ found:false. found:false therefore always means "looked, and there is no transcript". The reply's page.sessionId is exactly the id that read used (absent when none was resolved); the phone should PREFER it over the mirror's sessionId as the page's thread identity — the mirror lags — every 4 s on SSH, up to ~30 s on relay (projects.list off-LAN) — so right after /clear or a resume it still names the old session while the page already comes from the new transcript, and merging by byte key across the two would splice threads. sessionId is present on a found:false page too (an id was resolved, its transcript is missing — e.g. a fresh session that has not written yet): a new id on such a page alone is NOT a confirmed thread switch, so the phone must not clear the thread on it. Additive field: version stays 1, and an older desktop simply omits it (fall back to the mirror). |
chat.status |
{nodeId} |
{status: ChatStatus} |
the renderer's agent-status entry (state null = unknown, held, hibernated/paused/dropped/sessionEnded) + structuredAnswers = the held ticket is in main's structured-ticket ledger (script revision ≥ 5) + the host mirror's hostRefuses/refusal + version: 1. With {nodeId, catalog: true} (a literal true; opt-in, so an older phone sees the old shape) the status also carries catalog: ChatCatalog (src/shared/chat-catalog.ts) — the composer's / list for the node: measured built-ins, custom commands and skills, read on the node's host for an SSH node. Absent when the host could not build it (never an error on the status). Names pass catalogName, descriptions are one sanitized line; render them as text. partial: true = a root could not be read. The host waits at most 4 s for it (an SSH node's catalog is an ssh round trip) and then answers WITHOUT it — so a client asks with catalog: true ONCE per composer open (and again only when the user opens the menu after a while), never on every status poll. An entry with interactive: true is a built-in that opens a dialog in the agent's TUI: a client that cannot show the terminal after sending it must not offer it (the dialog would be invisible and the next send would answer it). Adopting it in nodeterm mobile is an iOS follow-up. |
chat.send |
{nodeId, text} |
ChatSendOutcome = {result, reason?} |
text capped at 64000 UTF-16 units RAW, then ESC + C0/C1 stripped (\n, \t kept; sanitizeChatText); refused FIRST (reason working/dialog) when the host's mirror says the agent is working / waiting / blocked or holds a question or approval ticket (renderer state is transient after a reload); refused busy while another send to the same node is still in flight (held until that send SETTLES, capped at 30 s); then the renderer runs the ⌘M composer's gate at send time (chatSendRefusal = agentProcessInPane + state ∈ {done, unknown} → its own kind as reason) plus "no held request" (dialog), then pty.sendText. 'sent' only for sendText === true; a paste the pane refused is refused/failed. |
agent.answer |
{nodeId, pendingId, answer} |
{ok: boolean} |
answerHeldPermission with the node's own I/O (local fs, or the SSH project's ControlMaster — the same heldPermissionIoFor the desktop answer path uses): validated against the pending request file, structured-ticket gated, no setMode auto. The pendingId must belong to THIS node — one of the mirror's approval tickets for it, or the renderer's held.pendingId (plans / questions) — else {ok:false} with no I/O and no answered event. Success emits the same optimistic "answered" event. |
Refusals are respond(id, false, {message}), with these exact strings:
| message | when |
|---|---|
<verb> is not served on this host. |
a desktop without the ops (pre-feature, or an unwired context) |
Invalid node id. |
nodeId missing / not a string / over REF_MAX_LEN / contains a C0/C1 control char |
Unknown node. |
the host has no such node (chat.page, chat.status, chat.send) |
Chat is not available for this agent. |
chat.page for a node whose agent has no chat view (codex, gemini, a plain terminal, …) |
Invalid page. |
before / maxBytes rejected by normalizeChatPage (checked before any read) |
Could not read the transcript. |
the page read FAILED: a remote host that did not answer, a remote node with no reachable master, a failed re-read — never an empty page standing in for it |
The desktop window is not available. |
chat.status: the renderer did not answer within 3 s (or there is no window) — never a guessed state |
Text too long. |
chat.send raw text over 64000 UTF-16 units |
chat.send requires non-empty text. |
nothing left after stripping control chars and whitespace |
Invalid pending id. |
agent.answer pendingId fails isValidPendingId |
Fail-closed rules: 'refused' means nothing was typed — no window (unavailable), a mirror or
renderer gate refused (its kind), another send in flight (busy), or the renderer received the query
after its startBy (late, 3 s; a late renderer refuses rather than typing). 'unconfirmed' means
the desktop could not confirm the outcome: a dispatched send that gets no report within 15 s, or a
sendText that REJECTED after starting. The text may have landed — or nothing may have been typed
at all (e.g. the window was reloading and never received the query) — the host cannot tell which.
The phone must never auto-resend on 'unconfirmed' (that risks a duplicate prompt): keep the
draft visible as "may not have been sent", re-read the page, and let the user decide. A chat.send
whose ops throw before dispatch is refused/unavailable; a throwing answer is {ok:false}.
agent.answer for an unknown node is {ok:false} (no I/O touched). Limits: page ≤ 5 MB (existing
clamp), chat text ≤ 64000, answer text ≤ 8000 (ANSWER_TEXT_MAX_CHARS, applied by
buildPermissionDecision). Unknown verb on an older desktop → Unknown method: chat.page → the phone
shows "Update nodeterm on your computer". The renderer round-trip resolves the main window at SEND
time (getMainWindow()), so a macOS window closed and re-created keeps answering. Server Edition:
N/A (it serves no phone relay; its bridge subscription is inert).
3.3 SSH producer (phone, nodeterm-ios)
- Locate: run the desktop's
remote-transcript-locatecommand string (ported verbatim as a builder), validate the path with a Swift port ofisSafeRemoteTranscriptPath. - Read: run
transcriptPageCommandverbatim; parse the framed reply (strict: size/start/end consistency, newline present) and the byte window with the SwiftparseChatWindow(1-byte lookbehind, partial-line drop, grow-on-no-complete-line up to 5 MB, tool-result carry, plan/question bodies,at, model/effort). - Held: list
~/.nodeterm/pending/*.jsonover SSH (bounded read), map by the payload'ssession_idto the node,tool_name→ plan/question; hook-script revision read from the installed script's marker; revision < 5 → no answer controls. - Send: the desktop tmux paste plan —
load-buffer -b nt -(text on stdin), copy-mode cancel guard,paste-buffer -d -p -r,send-keys Enter— on thenode-terminalsocket the session lives on (one socket per host since 2026-11). ESC bytes stripped. - Answer: Swift port of
buildPermissionDecision(validates against the pending request file), written atomically (umask 077, tmp + mv) from stdin;pendingIdregex-validated before any path.
3.3a Custom agents (mirror settings.customAgents, desktop side implemented)
A custom agent's node carries agentId: "custom:<uuid>". On SSH the phone can neither know its base
harness (the chat capability follows it) nor name its binary (the pane-owner check before a send) on
its own, so the agent-status mirror's settings block advertises them:
"settings": {
"customAgents": [
{ "id": "custom:3f2a…", "label": "Proxy Claude", "baseAgent": "claude", "binaries": ["claude"] },
{ "id": "custom:9b1c…", "label": "My agent", "binaries": ["my-agent"] },
{ "id": "custom:77de…", "label": "Wrapped", "baseAgent": "codex", "binaries": [] }
]
}
- Present in every mirror the phone reads: the local
agent-status.json(desktop and Server Edition; the relay'sprojects.listserves this same file) and each SSH project's pushed slice (agent-status-<projectId>.json, viasettingsFor). Absent on older desktops ⇒ refuse every custom node, as before. binariesis the desktop predicate'sbinariesFor(id, settings.customAgents), published only when every name matches^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$— the BUILDER enforces this alphabet, because a derived "name" can be a slice of a secret (oauth2:ghp_…from a git URL, a quoted env value, a${env:…}template). Empty = cannot be named honestly (e.g.bash -lc …, or a name outside the alphabet): refuse, never guess.- Residual the alphabet cannot catch: the launch-command tokenizer cannot tell a runner option's
VALUE from the program, so
npx --registry-token ghp_… my-agentwould "name" the token. The builder therefore also publishes[]for a name with a known credential prefix (ghp_,gho_,ghu_,ghs_,ghr_,github_pat_,AIza,sk-,xai-,glpat-) or a high-entropy shape (≥ 32 chars, ≥ 80% alphanumeric, letters AND digits). A heuristic: an unprefixed short secret can still pass, and a real binary it catches is simply refused ([]). The phone still validates each name (isPlainBinaryName) and refuses otherwise. baseAgentis present only when it is a builtin id. Chat on SSH: only when it isclaude(the only harness the Swift parser reads); on relay the desktop decides (canChat(capabilityAgentId(…))).- Never contains the raw launch command, args or env — they routinely hold API keys and proxy URLs,
and the slice is a file on the SSH host.
labelis display text (≤200 chars).
3.4 Live updates & paging (both transports)
- First open: 256 KB tail; scroll near top → 512 KB older pages; merge by
key; carried tool results; unconfirmed optimistic sends kept until the transcript has them; "Beginning of conversation" atolderCursor == null. - While the Chat screen is visible and the agent is working: tail re-read every 2 s, single-flight,
skipped when the size is unchanged; none when the screen is hidden or the app is backgrounded.
Status comes from the existing 4 s mirror poll (SSH) /
chat.status(relay).
4. Screen & interaction (iOS)
- Entry: a Chat | Terminal switch in the session screen's top bar; default Chat for
chat-capable agents (
CHAT_CAPABLE), last choice remembered per node. Tapping an Inbox question / approval opens that session in Chat. - Thread: user messages right-aligned in a neutral bubble; assistant unbubbled full-width. Markdown
via MarkdownUI (
gonzalezreal/swift-markdown-ui, the one new dependency —AttributedString (markdown:)has no block elements): code blocks horizontally scrollable with Copy; links open in Safari; relative/file links ignored. Tool calls as compact chips (tap → result sheet); thinking collapsed. Under each assistant response: Copy + relative time; long-press → Copy / Share. Scroll-to-bottom button when away from the bottom. - Plan card: full plan markdown + Approve · previous mode / Approve · accept edits / Approve · ask before edits / Revise… (inline text field). Question card: options (single / multi), Other field, Submit. Large touch targets; haptic on send. No controls when structured answers are unsupported → an "Answer in Terminal" banner with a button to switch tabs.
- Composer: reuse
DictationComposer(+ attach, mic, ▲). A model · effort chip above it; tap →/modelvia the send path, then switch to Terminal. Locked (with the reason) while working, while a prompt is held, or when the pane is shell-owned. Attach: SFTP on SSH; disabled with a reason on relay (no upload RPC — out of scope). - Working row: the existing mascot animation + "Claude is working…", shown optimistically on send.
- iPad: same view, readable max line width.
5. Safety & failure handling
- Never type blindly into a pane: send and
/modelonly when the state isdoneor unknown and no held request exists and an agent process owns the pane; the gate is re-asked at send time. Relay: the desktop decides. Text only via stdin; ESC stripped. - iOS consumer of
chat.send:'refused'→ keep the draft, say it was not sent (usereasonfor the sentence;busy= wait for the previous message), allow a resend;'unconfirmed'→ NEVER auto-resend (it may or may not have been typed); keep the draft marked "may not have been sent", reload the page, and leave the decision to the user. Unknown futureresultvalues are treated as'unconfirmed'(the safe side). Older desktops never return it, norreason. AChatStatuswith noversioncomes from a desktop older than this contract (nohostRefuses): treat it asversion 1withhostRefuses: false; any other unknownversion⇒ locked. - Answers validated against the host's pending request file; Swift and TS builders locked by golden
fixtures;
setMode autounrepresentable; expired ticket / old hook → "Couldn't send — answer in the terminal", never a false "sent". - Distinct states: transcript not found / unreadable / unsupported on this connection / desktop too old; network loss keeps the thread with a "Reconnecting" banner and pauses live reads; failed older page → retry row, thread kept.
- Cost: live reads only on a visible Chat screen while working; nothing in the background.
6. Testing & verification
- Golden fixtures: a desktop script cuts anonymized slices from real transcripts on this server
(huge image lines, multi-byte chars at window edges, cross-page tool results, plan/question,
model/effort), runs them through the TS parser/pager/tool-body/decision builder, and writes
fixtures/chat/*.json. A desktop test fails if the fixtures drift from the current TS output. The same fixtures are copied intonodeterm-ios; the Swift parser and decision builder must match them exactly in the Linux Swift harness. - Desktop: unit tests for the four relay verbs (scope jail, limits, nodeId resolution, send gate, revision gate).
- iOS pure logic (Linux harness): parser, paging/merge, send gate, decision builder, held derivation,
SSH command builders (run under a real
/bin/sh). - Not verifiable here: SwiftUI compile, layout, device behavior. Owed on a Mac (
xcodebuild+ device checklist in the iOS PR); no "tests green" claim for UI.
7. Delivery
- Desktop PR (
nodeterm, branchfeat/mobile-chat): relay verbs, golden-fixture generator + drift test, this doc, CLAUDE.md. Safe to merge first — no existing phone calls these verbs. - iOS PR (
nodeterm-ios): Swift parser + decision builder +ChatPagemodel, SSH & relay data sources, Chat screen, cards, composer integration, MarkdownUI. Mac build + device checklist in the PR.
8. Out of scope (YAGNI)
Voice conversation, thumbs/retry/read-aloud, relay file upload, Codex/Gemini chat view (no desktop chat view either), Android.