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
fix(chat): honest empty-state copy, presence on the tri-state locate
reviewc87797b5abe9
diff --git a/CLAUDE.md b/CLAUDE.mdindex 2f60fca48..e2a683be8 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -2466,6 +2466,8 @@ command-bearing opens; this does not add a human-confirm dialog or change mobile`locatedTranscriptSessions` so a dead one can be dropped on an empty read (the panel's Retrywould otherwise replay it forever) — a HOOK-fed ref is never dropped that way, since an emptyread there is usually a transient master hiccup and forgetting it sends the next read local.+ It is generated shell, so `remote-transcript-locate.test.ts` runs it for real under `/bin/sh`+ against a fake host tree — keep it that way.**A remote node never falls through to this machine** (2026-09-28): the handler decidesremoteness from the SHELL's records (`isRemoteNode` dep — live remote pty or`workspaceStore.sshProjectIdForNode`, never a renderer flag) and applies `remoteOnly` to the@@ -2473,9 +2475,10 @@ command-bearing opens; this does not add a human-confirm dialog or change mobileThe host locate is tri-state (`locateRemoteTranscriptRef`): a CLEAN MISS is `found:false`, afailure to ask is `unreadable` ("Couldn't read the transcript.") — the phone's `chat.page` sharesthe same deps and the same distinction. Before this, a mounted SSH node whose locate missed (or- whose master was down) read THIS machine's resolver, cwd-newest fallback included.- It is generated shell, so `remote-transcript-locate.test.ts` runs it for real under `/bin/sh`- against a fake host tree — keep it that way. (2) **The cwd fallback keeps `accountId`** in BOTH+ whose master was down) read THIS machine's resolver, cwd-newest fallback included. `transcriptExists` shares the same locate+ (`remotePresenceFromLocate`: ref/absent/unreadable → present/absent/unknown, a malformed id+ `unknown`), so it also works for a node with no live pty. A remote grok node (no remote reader)+ shows "not supported yet", not the retryable error. (2) **The cwd fallback keeps `accountId`** in BOTH`resolveTranscript` and `contextEnsure`; without it a managed-account node fell back to thesystem root and could adopt an unrelated session's newest transcript. (3) **Relay tabs** staylocal-only (a transcript read over the relay would read the GUEST's disk) and reject withdiff --git a/docs/mobile-chat-view.md b/docs/mobile-chat-view.mdindex 3ebdf06c8..75032497b 100644--- a/docs/mobile-chat-view.md+++ b/docs/mobile-chat-view.md@@ -103,7 +103,7 @@ 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, and custom agents whose base harness is one of them); 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. The desktop ⌘M panel reads through the SAME deps and the same rule: 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`), and shows `unreadable` as "Couldn't read the transcript." 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.page` | `{nodeId, before?, maxBytes?}` | `{page: ChatPage}` | Only for agents with a chat view — `canChat(capabilityAgentId(agent))` (claude, grok, and custom agents whose base harness is one of them); 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, which has no remote reader, 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`. || `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. |diff --git a/src/main/index.ts b/src/main/index.tsindex 35244a77c..b4e129a2a 100644--- a/src/main/index.ts+++ b/src/main/index.ts@@ -226,7 +226,6 @@ import {} from '../core/transcript-reader'import {locateRemoteTranscriptCommand,- parseLocatedTranscript,remoteTranscriptRoots} from '../core/remote-transcript-locate'import { readChatTranscript, registerTranscriptIpc, resolveTranscript, type TranscriptIpcDeps } from '../core/transcript-ipc'@@ -235,6 +234,7 @@ import type { ChatSendOutcome, HostChatReply, RendererChatStatus } from '../sharimport {createReadRemotePage,locateRemoteTranscriptRef,+ remotePresenceFromLocate,remoteTargetForNode,forgetLocatedRef,rememberHookRef,@@ -2588,65 +2588,17 @@ app.whenReady().then(async () => {return typeof r === 'object' ? r : undefined}- /**- * Does a remote node's transcript still exist ON THE HOST — `present` / `absent` / `unknown` —- * or `null` when this is not a remote session at all (take the local path).- *- * `remoteTranscriptRefFor` above cannot answer this: it collapses "not a remote session", "no- * resolved home", "the ssh call failed" and "the host looked and there is nothing" into one- * `undefined`, which is correct for a READER (they all fall back) and wrong for the caller that- * acts on absence. `locateRemoteTranscriptCommand` was already written for exactly this- * distinction — it exits 0 on a clean miss, "so no transcript is an ANSWER, not a failed ssh"- * — and that is the property this reads.- *- * Every step that cannot decide answers `unknown`, never `absent`. The one caller drops a- * `--resume <id>` on `absent`, and a momentarily dead ControlMaster must not be able to look- * like a deleted conversation.- */- const remoteTranscriptPresence = async (+ // Presence over the SAME tri-state locate (see `remotePresenceFromLocate`): a node with no live+ // pty resolves through its SSH project's master instead of reading as "not remote". sessionId+ // only (no cwd): presence is about THIS id, never the cwd's newest transcript.+ const remoteTranscriptPresence = (sessionId: string,accountId: string | undefined,nodeId: string | undefined- ): Promise<TranscriptPresence | null> => {- if (!nodeId) return null- const rt = ptyManager.sshRemoteForNode(nodeId)- // Not a remote session — the caller takes the LOCAL path, which is the right disk to read.- if (!rt) return null- // From here on the session IS remote, so every failure is `unknown`: falling back to the- // local resolver would search this machine for a file that only lives on the host.- if (remoteTranscriptBySession.has(sessionId)) return 'present'- if (!sshProjectManager) return 'unknown'- const remoteHome = sshProjectManager.remoteHomeForControlPath(rt.controlPath)- if (!remoteHome) return 'unknown'- let accountDir: string | undefined- if (accountId) {- // A hand-edited project.json can carry any string; the helper validates and throws.- try {- accountDir = remoteAccountConfigDirAbs(remoteHome, accountId)- } catch {- accountDir = undefined- }- }- const cmd = locateRemoteTranscriptCommand(- remoteTranscriptRoots(remoteHome, accountDir),- undefined,- sessionId+ ): Promise<TranscriptPresence | null> =>+ remotePresenceFromLocate(sessionId, () =>+ locateRemoteRef({ sessionId, cwd: undefined, accountId, nodeId }, sshTargetForNode))- if (!cmd) return 'unknown'- try {- const { code, stdout } = await sshProjectManager.sshRun(- childArgs(rt.conn, rt.controlPath, cmd)- )- if (code !== 0) return 'unknown'- const located = parseLocatedTranscript(stdout)- // Jailed exactly like a hook-supplied path: a located path we would refuse to READ must not- // be reported as a transcript that exists either.- if (located && isSafeRemoteTranscriptPath(located, remoteHome)) return 'present'- return located ? 'unknown' : 'absent'- } catch {- return 'unknown'- }- }/*** Read a remote transcript through a ref, forgetting refs WE located once they stop reading.diff --git a/src/main/remote-transcript-page.test.ts b/src/main/remote-transcript-page.test.tsindex bff5c023c..a9b723e9b 100644--- a/src/main/remote-transcript-page.test.ts+++ b/src/main/remote-transcript-page.test.ts@@ -1,5 +1,5 @@import { describe, expect, it, vi } from 'vitest'-import { createReadRemotePage, forgetLocatedRef, locateRemoteTranscriptRef, rememberHookRef, remoteTargetForNode, type RemoteTranscriptRefCache } from './remote-transcript-page'+import { createReadRemotePage, forgetLocatedRef, locateRemoteTranscriptRef, remotePresenceFromLocate, rememberHookRef, remoteTargetForNode, type RemoteTranscriptRefCache } from './remote-transcript-page'import type { RemoteFileRef } from './remote-ssh/remote-file'const ref = (path: string): RemoteFileRef => ({@@ -156,3 +156,38 @@ describe('locateRemoteTranscriptRef (the host-side locate, tri-state)', () => {expect(await locateRemoteTranscriptRef(q, base({ isSafePath: () => false }))).toBe('unreadable')})})++describe('remotePresenceFromLocate (transcriptExists on a remote node)', () => {+ const SID = '46b36ce2-dd77-4f5e-a89e-4a0e831e83df'+ it('ref → present, clean miss → absent, could not ask → unknown, not remote → null', async () => {+ expect(await remotePresenceFromLocate(SID, async () => ref('/t.jsonl'))).toBe('present')+ expect(await remotePresenceFromLocate(SID, async () => 'absent')).toBe('absent')+ expect(await remotePresenceFromLocate(SID, async () => 'unreadable')).toBe('unknown')+ expect(await remotePresenceFromLocate(SID, async () => undefined)).toBeNull()+ })+ it('a malformed id is unknown, never absent (absent drops a --resume)', async () => {+ expect(await remotePresenceFromLocate('not-an-id', async () => 'absent')).toBe('unknown')+ })+ it('works without a live pty: an SSH-project node resolves over its project master', async () => {+ const run = vi.fn(async () => ({ code: 0, stdout: '' }))+ const project = { conn: { host: 'proj' } as RemoteFileRef['conn'], controlPath: '/proj' }+ const target = (id: string) =>+ remoteTargetForNode(id, { live: () => undefined, projectIdFor: () => 'p', refForProject: () => project })+ const r = await remotePresenceFromLocate(SID, () =>+ locateRemoteTranscriptRef(+ { sessionId: SID, cwd: undefined, accountId: undefined, nodeId: 'nt-idle' },+ {+ cache: cache(),+ isRemote: () => true,+ target,+ remoteHome: () => '/home/u',+ command: () => 'locate',+ run,+ isSafePath: () => true+ }+ )+ )+ expect(r).toBe('absent')+ expect(run).toHaveBeenCalledWith(project, 'locate')+ })+})diff --git a/src/main/remote-transcript-page.ts b/src/main/remote-transcript-page.tsindex 2cc2600e5..6e4d16b93 100644--- a/src/main/remote-transcript-page.ts+++ b/src/main/remote-transcript-page.ts@@ -8,6 +8,8 @@ import type { ChatTranscriptPage } from '../shared/chat-page'import type { TranscriptPage } from '../core/remote-ssh/transcript-window'import type { RemoteFileRef } from './remote-ssh/remote-file'import { parseLocatedTranscript } from '../core/remote-transcript-locate'+import { SESSION_ID_RE } from '../core/transcript-reader'+import type { TranscriptPresence } from '../shared/types'/** Remote transcript refs by sessionId, and which of them we located ourselves (vs hook-fed). */export interface RemoteTranscriptRefCache {@@ -92,6 +94,27 @@ export async function locateRemoteTranscriptRef<T extends { conn: RemoteFileRef[return ref}+/**+ * Does a remote node's transcript still exist ON THE HOST — from the same tri-state locate the+ * readers use, so it works for a node with no live pty too (its SSH project's master). `null` =+ * not a remote session (take the local path).+ *+ * Every lookup that cannot decide is `unknown`, never `absent`: the one caller drops a+ * `--resume <id>` on `absent`, and a dead master must not look like a deleted conversation. A+ * malformed id is `unknown` as well — the locate calls it a clean miss (no file can carry it), but+ * the local probe answers `unknown` for one, and the two legs must not disagree on what drops a+ * resume.+ */+export async function remotePresenceFromLocate(+ sessionId: string,+ locate: () => Promise<RemoteRefLookup>+): Promise<TranscriptPresence | null> {+ const r = await locate()+ if (r === undefined) return null+ if (typeof r === 'object') return 'present'+ return r === 'absent' && SESSION_ID_RE.test(sessionId) ? 'absent' : 'unknown'+}+export function createReadRemotePage(deps: {cache: RemoteTranscriptRefCache/** The session's remote ref (cached, or located on the host), or why there is none — seediff --git a/src/renderer/nodes/ChatPanel.tsx b/src/renderer/nodes/ChatPanel.tsxindex 462002bef..9bf2281cd 100644--- a/src/renderer/nodes/ChatPanel.tsx+++ b/src/renderer/nodes/ChatPanel.tsx@@ -82,27 +82,42 @@ interface ChatPanelProps {* initial `[]` because nothing caught the rejection, and a failed resolution was indistinguishable* from a session nobody has spoken to. They need different words — and two of them are retryable.*/-type LoadState = 'loading' | 'ok' | 'missing' | 'unsupported' | 'error'+type LoadState = 'loading' | 'ok' | 'missing' | 'unsupported' | 'remoteUnsupported' | 'error'++/**+ * An `unreadable` read of a GROK node can only be the remote case: core's grok leg is local-only+ * and answers a remote grok node (`remoteOnly`) with `unreadable` before touching anything, while+ * its local reader never sets the flag. So the agent alone names it — no renderer-side remoteness+ * guess, and no new field on the wire (the phone contract keeps `unreadable`). `=== 'grok'`+ * exactly, mirroring core's routing (`readChatTranscript` routes only the builtin id to grok's+ * reader). Retry cannot heal it, so it must not read as a transient failure.+ */+const remoteGrokUnreadable = (agentId: string | undefined): boolean => agentId === 'grok'const isUnsupported = (e: unknown): boolean =>!!e && typeof e === 'object' && (e as { code?: string }).code === E_UNSUPPORTED/** One line each, in the user's terms: what is on screen and whether waiting will fix it.- * `missing` names the two causes that actually produce it — a transcript Claude has cleaned up- * (30 days by default), and a remote session whose host hasn't been reached yet — because the- * second one heals by itself the moment the session speaks, and the first one never will. */+ * `missing` is a CLEAN miss — the (local or remote) host looked and there is no file: a transcript+ * Claude has cleaned up (30 days by default), or a session that has not written one yet (the+ * second heals the moment it speaks). A host that could not be ASKED is `error`, which Retry can+ * fix; `remoteUnsupported` is a remote node whose agent has no remote reader, which it never can. */const EMPTY_TEXT: Record<LoadState, { title: string; detail?: string }> = {loading: { title: 'Loading conversation…' },ok: { title: 'No conversation yet.' },missing: {title: 'No transcript found for this session.',- detail: "It may have been cleaned up, or the agent's host isn't reachable yet."+ detail: "It may have been cleaned up, or the session hasn't written one yet."},unsupported: {title: "Transcripts can't be read on this surface.",detail: 'Open this session on the desktop app to read its conversation.'},- error: { title: "Couldn't read the transcript." }+ remoteUnsupported: { title: "Reading a remote Grok session's transcript isn't supported yet." },+ error: {+ title: "Couldn't read the transcript.",+ detail: "The agent's host may not be reachable — Retry once it is."+ }}/**@@ -264,7 +279,7 @@ export function ChatPanel({setThread(emptyThread(identity))// A read that FAILED (the host did not answer, a remote node with no reachable master)// is not "no transcript": it gets the error copy, and ↻ is the way out.- setLoadState(res.unreadable ? 'error' : 'missing')+ setLoadState(!res.unreadable ? 'missing' : remoteGrokUnreadable(agentId) ? 'remoteUnsupported' : 'error')return}setThread((t) => applyTail(t, identity, res, { carryUnconfirmed: live }))@@ -352,7 +367,7 @@ export function ChatPanel({attemptLiveRef.current = () => {if (!livePendingRef.current) return// This surface cannot read transcripts at all (relay tab): every live read would be refused.- if (loadStateRef.current === 'unsupported') {+ if (loadStateRef.current === 'unsupported' || loadStateRef.current === 'remoteUnsupported') {livePendingRef.current = falsereturn}@@ -614,7 +629,7 @@ export function ChatPanel({{EMPTY_TEXT[loadState].detail && (<div className="term-chat__empty-detail">{EMPTY_TEXT[loadState].detail}</div>)}- {loadState !== 'unsupported' && loadState !== 'ok' && (+ {loadState !== 'unsupported' && loadState !== 'remoteUnsupported' && loadState !== 'ok' && (<button className="term-chat__retry" onClick={() => load()}>Retry</button>diff --git a/src/renderer/nodes/ChatPanel.ux.test.tsx b/src/renderer/nodes/ChatPanel.ux.test.tsxindex 1f82175d1..34aad4a52 100644--- a/src/renderer/nodes/ChatPanel.ux.test.tsx+++ b/src/renderer/nodes/ChatPanel.ux.test.tsx@@ -235,7 +235,19 @@ describe('ChatPanel empty states', () => {pending[0].resolve({ messages: [], found: false, olderCursor: null, unmatchedResults: [], unreadable: true })})expect(msgs().textContent).toContain("Couldn't read the transcript.")+ expect(msgs().textContent).toContain("The agent's host may not be reachable")expect(msgs().textContent).not.toContain('No transcript found')+ expect(host.querySelector('.term-chat__retry')).not.toBeNull()+ })++ it('an unreadable REMOTE grok read says it is unsupported, with no Retry (Retry can never fix it)', async () => {+ await render({ agentId: 'grok' })+ await act(async () => {+ pending[0].resolve({ messages: [], found: false, olderCursor: null, unmatchedResults: [], unreadable: true })+ })+ expect(msgs().textContent).toContain("Reading a remote Grok session's transcript isn't supported yet.")+ expect(msgs().textContent).not.toContain("Couldn't read")+ expect(host.querySelector('.term-chat__retry')).toBeNull()})it('a clean miss still says no transcript was found', async () => {@@ -244,6 +256,7 @@ describe('ChatPanel empty states', () => {pending[0].resolve({ messages: [], found: false, olderCursor: null, unmatchedResults: [] })})expect(msgs().textContent).toContain('No transcript found for this session.')+ expect(msgs().textContent).toContain("hasn't written one yet")})})