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(ssh): Share with team orchestrator — report a failed restore, guard every step after the bootstrap
reviewd2f37b1c98b7
diff --git a/src/renderer/lib/shareSshTeam.test.ts b/src/renderer/lib/shareSshTeam.test.tsindex 250196515..996b3cb2e 100644--- a/src/renderer/lib/shareSshTeam.test.ts+++ b/src/renderer/lib/shareSshTeam.test.ts@@ -35,6 +35,9 @@ const INPUT: ShareInput = {{ nodeId: 'term-x', title: 'Work account', agentId: 'claude', sessionId: 's-2', accountId: 'acct' }]}+/** A second resumable agent, for the cases that need more than one node in the resume request. */+const TERM_B: ShareInput['terminals'][number] = { nodeId: 'term-b', title: 'Codex', agentId: 'codex', sessionId: 's-3', state: 'done' }+const FLUSH_WITH_B = { ok: true, nodeIds: ['term-a', 'term-p', 'term-x', 'term-b'] }describe('runShare', () => {it('the whole flow, in order: no kill before bootstrap, no resume before the kill', async () => {@@ -59,6 +62,16 @@ describe('runShare', () => {expect(out).toMatchObject({ kind: 'refused', busy: [{ nodeId: 'term-a' }] })expect(log).toEqual([])})+ it('refuses a blocked agent too', async () => {+ const { deps, log } = setup()+ const out = await runShare(deps, { ...INPUT, terminals: [{ ...INPUT.terminals[0], state: 'blocked' }, INPUT.terminals[1]] })+ expect(out).toEqual({+ kind: 'refused',+ reason: 'Wait for these agents to finish (or stop them), then share again.',+ busy: [{ ...INPUT.terminals[0], state: 'blocked' }]+ })+ expect(log).toEqual([])+ })it('refuses more terminals than one share handles, before touching the host', async () => {const { deps, log } = setup()const terminals = Array.from({ length: 201 }, (_, i) => ({ nodeId: `t-${i}`, title: `T${i}` }))@@ -122,18 +135,111 @@ describe('runShare', () => {it('a bootstrap failure reopens the SSH project and kills nothing', async () => {const { deps, log } = setup({ bootstrap: { ok: false, code: 'E_HOSTING_OFF', error: 'refused (403)' } })const out = await runShare(deps, INPUT)- expect(out).toMatchObject({ kind: 'failed', step: 'bootstrapping', reopened: true, error: expect.stringContaining('refused (403)') })+ expect(out).toEqual({ kind: 'failed', step: 'bootstrapping', reopened: true, error: 'Hosting could not start on the host: refused (403)' })expect(log).toContain('restore')expect(log.some((l) => l.startsWith('kill:'))).toBe(false)})- it('a bootstrap failure still reports the failure when restore itself throws', async () => {- const { deps, log } = setup({ bootstrap: { ok: false, error: 'boom' } })+ it('a restore that throws is reported: never "reopened", always restoreFailed, the original error kept', async () => {+ const { deps, log } = setup({ bootstrap: { ok: false, code: 'E_ADOPT_FAILED', error: 'boom' } })deps.restore = async () => {throw new Error('restore failed')}- expect(await runShare(deps, INPUT)).toEqual({ kind: 'failed', step: 'bootstrapping', error: 'boom', reopened: true })+ expect(await runShare(deps, INPUT)).toEqual({ kind: 'failed', step: 'bootstrapping', error: 'boom', reopened: false, restoreFailed: true })expect(log.some((l) => l.startsWith('kill:'))).toBe(false)})+ it('a release and a restore that both throw report neither a reopen nor the release as undone', async () => {+ const { deps } = setup()+ deps.release = async () => {+ throw new Error('close failed')+ }+ deps.restore = async () => {+ throw new Error('restore failed')+ }+ expect(await runShare(deps, INPUT)).toEqual({ kind: 'failed', step: 'releasing', error: 'close failed', reopened: false, restoreFailed: true })+ })+ it('a missing canvas whose restore throws does not claim nothing was changed', async () => {+ const { deps } = setup({ flush: { ok: true, nodeIds: ['term-a', 'term-p'] } })+ deps.restore = async () => {+ throw new Error('restore failed')+ }+ expect(await runShare(deps, INPUT)).toEqual({+ kind: 'failed',+ step: 'releasing',+ error: 'The canvas on the host is not up to date (1 terminal missing). Try again in a moment.',+ reopened: false,+ restoreFailed: true+ })+ })+ it('a bootstrap failure without a server code says the host may have finished; a throw counts as one', async () => {+ const uncoded = setup({ bootstrap: { ok: false, error: 'timed out' } })+ expect(await runShare(uncoded.deps, INPUT)).toEqual({+ kind: 'failed',+ step: 'bootstrapping',+ error: 'timed out The host may have finished setting up anyway; run Share with team again to complete it.',+ reopened: true+ })+ expect(uncoded.log).toContain('restore')+ const thrown = setup()+ thrown.deps.api.bootstrap = async () => {+ throw new Error('socket hang up')+ }+ expect(await runShare(thrown.deps, INPUT)).toMatchObject({+ kind: 'failed',+ step: 'bootstrapping',+ error: 'socket hang up The host may have finished setting up anyway; run Share with team again to complete it.',+ reopened: true+ })+ })+ it('a coded bootstrap failure other than hosting-off keeps its error as is', async () => {+ const { deps } = setup({ bootstrap: { ok: false, code: 'E_BAD_CWD', error: 'not a folder' } })+ expect(await runShare(deps, INPUT)).toEqual({ kind: 'failed', step: 'bootstrapping', error: 'not a folder', reopened: true })+ })+ it('markHandedOff is retried once, then given up without failing the share', async () => {+ const once = setup()+ let calls = 0+ once.deps.markHandedOff = async (to) => {+ calls+++ if (calls === 1) throw new Error('disk busy')+ once.log.push(`handed:${to.hostId}:${to.projectId}`)+ }+ expect(await runShare(once.deps, INPUT)).toMatchObject({ kind: 'shared' })+ expect(calls).toBe(2)+ expect(once.log).toContain('handed:H:project-9')+ const never = setup()+ let tries = 0+ never.deps.markHandedOff = async () => {+ tries+++ throw new Error('disk full')+ }+ expect(await runShare(never.deps, INPUT)).toMatchObject({ kind: 'shared', resumed: [{ nodeId: 'term-a' }] })+ expect(tries).toBe(2)+ expect(never.log).not.toContain('restore')+ })+ it('after a successful bootstrap a throwing phase or join never rejects, skips no step, and still answers shared', async () => {+ const { deps, log } = setup()+ deps.phase = (p) => {+ log.push(`phase:${p}`)+ if (p === 'handing-over' || p === 'joining') throw new Error('ui gone')+ }+ deps.join = () => {+ throw new Error('ui gone')+ }+ const out = await runShare(deps, INPUT)+ expect(out).toMatchObject({ kind: 'shared', joinCode: 'nodeterm://join/CODE', resumed: [{ nodeId: 'term-a' }] })+ expect(log.some((l) => l.startsWith('kill:'))).toBe(true)+ expect(log).toContain('resume:project-9:term-a')+ expect(log).toContain('seed')+ expect(log).not.toContain('restore')+ })+ it('a throwing phase before the bootstrap does not strand the project closed', async () => {+ const { deps, log } = setup()+ deps.phase = (p) => {+ log.push(`phase:${p}`)+ if (p === 'bootstrapping') throw new Error('ui gone')+ }+ expect(await runShare(deps, INPUT)).toMatchObject({ kind: 'shared' })+ expect(log).toContain('bootstrap')+ })it('after a successful bootstrap nothing ever reopens: a failed kill resumes nothing and reports every node still on SSH', async () => {const { deps, log } = setup({ kill: { ok: false, error: 'ssh died' } })const out = await runShare(deps, INPUT)@@ -142,12 +248,54 @@ describe('runShare', () => {expect(log).not.toContain('restore')expect(log.some((l) => l.startsWith('resume:'))).toBe(false)})+ it('a kill verdict of unknown is not gone: nothing is resumed and the node stays on SSH', async () => {+ const { deps, log } = setup({ kill: { ok: true, results: [{ nodeId: 'term-a', state: 'unknown' }, { nodeId: 'term-p', state: 'gone' }, { nodeId: 'term-x', state: 'gone' }] } })+ const out = await runShare(deps, INPUT)+ expect(log.some((l) => l.startsWith('resume:'))).toBe(false)+ expect(out).toMatchObject({ kind: 'shared', resumed: [], stillOnSsh: [{ nodeId: 'term-a' }] })+ expect((out as { notResumed: Array<{ node: { nodeId: string }; reason: string }> }).notResumed).toContainEqual({+ node: expect.objectContaining({ nodeId: 'term-a' }),+ reason: 'still running on SSH'+ })+ })+ it('a node the kill reply leaves out is not gone: nothing is resumed and the node stays on SSH', async () => {+ const { deps, log } = setup({ kill: { ok: true, results: [{ nodeId: 'term-p', state: 'gone' }, { nodeId: 'term-x', state: 'gone' }] } })+ const out = await runShare(deps, INPUT)+ expect(log.some((l) => l.startsWith('resume:'))).toBe(false)+ expect(out).toMatchObject({ kind: 'shared', resumed: [], stillOnSsh: [{ nodeId: 'term-a' }] })+ })it('only verified-gone agents are resumed; an alive one is reported, not resumed', async () => {const { deps, log } = setup({ kill: { ok: true, results: [{ nodeId: 'term-a', state: 'alive' }, { nodeId: 'term-p', state: 'gone' }, { nodeId: 'term-x', state: 'gone' }] } })const out = await runShare(deps, INPUT)expect(log.some((l) => l.startsWith('resume:'))).toBe(false)expect(out).toMatchObject({ kind: 'shared', stillOnSsh: [{ nodeId: 'term-a' }] })})+ it('already-running counts as resumed', async () => {+ const { deps } = setup({ resume: { ok: true, results: [{ nodeId: 'term-a', status: 'already-running' }] } })+ expect(await runShare(deps, INPUT)).toMatchObject({ kind: 'shared', resumed: [{ nodeId: 'term-a' }] })+ })+ it('a failed resume reply puts every sent node in notResumed with that error', async () => {+ const { deps } = setup({ flush: FLUSH_WITH_B, resume: { ok: false, error: 'server busy' } })+ const out = await runShare(deps, { ...INPUT, terminals: [...INPUT.terminals, TERM_B] })+ expect(out).toMatchObject({+ kind: 'shared',+ resumed: [],+ notResumed: [+ { node: { nodeId: 'term-a' }, reason: 'server busy' },+ { node: { nodeId: 'term-b' }, reason: 'server busy' },+ { node: { nodeId: 'term-x' }, reason: 'runs under a managed account' }+ ]+ })+ })+ it('a node the resume reply leaves out is reported as unanswered, not resumed', async () => {+ const { deps } = setup({ flush: FLUSH_WITH_B, resume: { ok: true, results: [{ nodeId: 'term-a', status: 'resumed' }] } })+ const out = await runShare(deps, { ...INPUT, terminals: [...INPUT.terminals, TERM_B] })+ expect(out).toMatchObject({ kind: 'shared', resumed: [{ nodeId: 'term-a' }] })+ expect((out as { notResumed: unknown[] }).notResumed).toContainEqual({+ node: expect.objectContaining({ nodeId: 'term-b' }),+ reason: 'the server did not answer for it'+ })+ })it('a refused resume is reported with its reason, beside the manual agents', async () => {const { deps } = setup({ resume: { ok: true, results: [{ nodeId: 'term-a', status: 'refused', reason: 'unknown agent' }] } })const out = await runShare(deps, INPUT)@@ -182,6 +330,24 @@ describe('runShare', () => {await runShare(deps, INPUT)expect(seen).toEqual(['/srv/proj'])})+ it('says a shared install and re-probe failure once', async () => {+ const { deps } = setup()+ let n = 0+ deps.api.probe = async () => (n++ === 0 ? { ...READY, plan: { kind: 'install', reason: 'missing' } } : { ok: false, error: 'not connected' }) as never+ deps.api.install = async () => ({ ok: false, error: 'not connected' })+ expect(await runShare(deps, INPUT)).toEqual({ kind: 'failed', step: 'checking-install', error: 'not connected', reopened: false })+ })+ it('joins a re-probe failure that differs from the install message', async () => {+ const { deps } = setup()+ let n = 0+ deps.api.probe = async () => (n++ === 0 ? { ...READY, plan: { kind: 'install', reason: 'missing' } } : { ok: false, error: 'ssh died' }) as never+ expect(await runShare(deps, INPUT)).toEqual({+ kind: 'failed',+ step: 'checking-install',+ error: 'The install finished (exit 0) but nodeterm-server is not ready on the host. ssh died',+ reopened: false+ })+ })it('an install that does not leave a ready server fails without releasing anything', async () => {const { deps, log } = setup()deps.api.probe = async () => ({ ...READY, plan: { kind: 'install', reason: 'missing' } }) as neverdiff --git a/src/renderer/lib/shareSshTeam.ts b/src/renderer/lib/shareSshTeam.tsindex c3935c9d6..80d43abc6 100644--- a/src/renderer/lib/shareSshTeam.ts+++ b/src/renderer/lib/shareSshTeam.ts@@ -13,7 +13,8 @@// 3. After a successful bootstrap the SSH project is never reopened: the server is now the only// writer of the project file, and a desktop mirror write would race it. Every failure before// that point leaves the project as it was: once the share has marked (or closed) it, the-// failure clears the mark and reopens it before it is reported.+// failure clears the mark and reopens it before it is reported, and says so when that undo+// itself fails.//// The in-progress mark is set BEFORE the mirror is flushed, not with the close: a desktop save// between the flush and the close could otherwise queue a throttled mirror write that lands on the@@ -72,7 +73,17 @@ export interface ShareConfirmSummary {export type ShareOutcome =| { kind: 'refused'; reason: string; busy?: ShareNode[] }| { kind: 'cancelled' }- | { kind: 'failed'; step: SharePhase; error: string; reopened: boolean; log?: string }+ | {+ kind: 'failed'+ step: SharePhase+ error: string+ /** The share had closed the project and reopened it again. */+ reopened: boolean+ /** Undoing the share's own changes threw: the project may still be closed and still carry the+ * in-progress mark that stops its mirror, so the UI must not say nothing changed. */+ restoreFailed?: boolean+ log?: string+ }| {kind: 'shared'joinCode: string@@ -144,15 +155,31 @@ export function classifyTerminals(return { resumable, manual, stopping }}+/** Said after a bootstrap that failed without a server error code: a transport failure or a timeout+ * says nothing about whether the server finished, and a second run of the idempotent bootstrap+ * completes whatever it did. */+const BOOTSTRAP_MAY_HAVE_FINISHED =+ ' The host may have finished setting up anyway; run Share with team again to complete it.'+export async function runShare(deps: ShareDeps, input: ShareInput): Promise<ShareOutcome> {const { api } = depsconst { projectId, terminals, host, user } = input- const failed = (step: SharePhase, error: string, reopened: boolean): ShareOutcome => ({+ const failed = (step: SharePhase, error: string, reopened: boolean, restoreFailed = false): ShareOutcome => ({kind: 'failed',step,error,- reopened+ reopened,+ ...(restoreFailed ? { restoreFailed: true } : {})})+ // A phase report only updates the UI; a throw there must never stop a step, least of all one that+ // leaves the project closed and marked with nothing left to undo it.+ const phase = (p: SharePhase): void => {+ try {+ deps.phase(p)+ } catch {+ /* display only */+ }+ }// Refusals that need no host: checked before anything is asked of it.const busy = terminals.filter((n) => n.agentId && n.state && BUSY_STATES.has(n.state))@@ -167,7 +194,7 @@ export async function runShare(deps: ShareDeps, input: ShareInput): Promise<Shar}const ids = terminals.map((n) => n.nodeId)- deps.phase('probing')+ phase('probing')let probed = await call(() => api.probe(projectId, ids))if (!probed.ok) return failed('probing', probed.error, false)const plan = probed.plan@@ -185,18 +212,19 @@ export async function runShare(deps: ShareDeps, input: ShareInput): Promise<Sharif (!agreed) return { kind: 'cancelled' }if (plan.kind === 'install') {- deps.phase('installing')+ phase('installing')const installed = await call(() => api.install(projectId))// Probe again whatever the install answered: only a ready server lets the share go on, and a// failed reply (a dropped stream, say) does not by itself mean the server is not ready.- deps.phase('checking-install')+ phase('checking-install')const again = await call(() => api.probe(projectId, ids))if (!again.ok || again.plan.kind !== 'ready') {const base = installed.ok? `The install finished (exit ${installed.exitCode}) but nodeterm-server is not ready on the host.`: installed.error- const why = !again.ok ? ` ${again.error}` : again.plan.kind === 'refuse' ? ` ${again.plan.reason}` : ''- return failed('checking-install', base + why, false)+ const why = !again.ok ? again.error : again.plan.kind === 'refuse' ? again.plan.reason : ''+ // A dead connection fails the install and the re-probe with the same message: say it once.+ return failed('checking-install', why && why !== base ? `${base} ${why}` : base, false)}probed = again}@@ -205,40 +233,44 @@ export async function runShare(deps: ShareDeps, input: ShareInput): Promise<Sharconst adoptCwd = probed.probe.adoptCwdif (adoptCwd === null) return { kind: 'refused', reason: SHARE_REFUSAL.noFolder }- deps.phase('releasing')+ phase('releasing')try {await deps.prepare()} catch (e) {return failed('releasing', errorText(e), false)}// From the mark until a successful bootstrap, every failure clears the mark (and reopens the- // project if it was closed) before it is reported. Restore's own failure is swallowed: the- // original failure is the one the user must see.- const undo = async (): Promise<void> => {+ // project if it was closed) before it is reported. The original failure stays the reported error;+ // whether restore worked is reported beside it, because a mark left behind stops the project's+ // mirror for good and a project left closed is not "reopened".+ const undo = async (): Promise<boolean> => {try {await deps.restore()+ return true} catch {- /* best effort */+ return false}}+ /** Undo, then report `error`; `released` says whether the project had been closed by now. */+ const failAndUndo = async (step: SharePhase, error: string | ((restored: boolean) => string), released: boolean) => {+ const restored = await undo()+ return failed(step, typeof error === 'string' ? error : error(restored), released && restored, !restored)+ }try {await deps.markPending()} catch (e) {- await undo()- return failed('releasing', errorText(e), false)+ return failAndUndo('releasing', errorText(e), false)}const flushed = await call(() => api.flushMirror(projectId))- if (!flushed.ok) {- await undo()- return failed('releasing', flushed.error, false)- }+ if (!flushed.ok) return failAndUndo('releasing', flushed.error, false)const onHost = new Set(flushed.nodeIds)const missing = terminals.filter((n) => !onHost.has(n.nodeId))if (missing.length) {- await undo()- return failed(+ const stale = `The canvas on the host is not up to date (${missing.length} terminal${missing.length === 1 ? '' : 's'} missing).`+ // "Nothing was changed" holds only when the mark was cleared again.+ return failAndUndo('releasing',- `The canvas on the host is not up to date (${missing.length} terminal${missing.length === 1 ? '' : 's'} missing). Nothing was changed; try again in a moment.`,+ (restored) => (restored ? `${stale} Nothing was changed; try again in a moment.` : `${stale} Try again in a moment.`),false)}@@ -246,28 +278,38 @@ export async function runShare(deps: ShareDeps, input: ShareInput): Promise<Sharawait deps.release()} catch (e) {// A close can throw part-way, so restore reopens it whatever state it was left in.- await undo()- return failed('releasing', errorText(e), true)+ return failAndUndo('releasing', errorText(e), true)}- deps.phase('bootstrapping')+ phase('bootstrapping')const booted = await call(() => api.bootstrap(projectId, adoptCwd))if (!booted.ok) {- await undo()- const error = booted.code === 'E_HOSTING_OFF' ? `Hosting could not start on the host: ${booted.error}` : booted.error- return failed('bootstrapping', error, true)+ // Any bootstrap failure reopens the project, even one without a server code that may have+ // left the server set up: the desktop must never stay closed on an unconfirmed handover.+ const error =+ booted.code === 'E_HOSTING_OFF'+ ? `Hosting could not start on the host: ${booted.error}`+ : booted.code+ ? booted.error+ : booted.error + BOOTSTRAP_MAY_HAVE_FINISHED+ return failAndUndo('bootstrapping', error, true)}const result = booted.result- // Best effort: the server already owns the project, and the in-progress mark keeps the desktop- // from writing it even if this store write fails.- try {- await deps.markHandedOff({ hostId: result.hostId, projectId: result.projectId })- } catch {- /* best effort */+ // From here on the server owns the project: nothing below may reject or reopen it, so every dep+ // call is guarded and the shared outcome is always returned.+ // The store write is retried once, then given up: the in-progress mark already keeps the desktop+ // from writing the project, so a failure costs only the host binding.+ for (let attempt = 0; attempt < 2; attempt++) {+ try {+ await deps.markHandedOff({ hostId: result.hostId, projectId: result.projectId })+ break+ } catch {+ /* retried once, then best effort */+ }}- deps.phase('handing-over')+ phase('handing-over')const resumed: ShareNode[] = []const notResumed: Array<{ node: ShareNode; reason: string }> = []let stillOnSsh: ShareNode[]@@ -305,10 +347,14 @@ export async function runShare(deps: ShareDeps, input: ShareInput): Promise<Shar}notResumed.push(...classified.manual)- deps.phase('joining')+ phase('joining')// A failed seed only means the join shows the verification code instead of a pinned bookmark.await call(() => api.seedBookmark(result.joinCode))- deps.join(result.joinCode, result.projectId)+ try {+ deps.join(result.joinCode, result.projectId)+ } catch {+ /* the outcome carries the join code, so the team can still be joined from it */+ }return {kind: 'shared',