Skip to content

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.

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.ts
index 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 never
diff --git a/src/renderer/lib/shareSshTeam.ts b/src/renderer/lib/shareSshTeam.ts
index 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 } = deps
const { 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<Shar
if (!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<Shar
const adoptCwd = probed.probe.adoptCwd
if (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<Shar
await 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',