Skip to content

The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.

feat: allow terminal stream opening for dormant agents to support retained runtime access

0xken151e07c4ccc3c1
diff --git a/cli/src/lib/terminalBackendCoordinator.spec.ts b/cli/src/lib/terminalBackendCoordinator.spec.ts
index ef0180df2..71d4baa5a 100644
--- a/cli/src/lib/terminalBackendCoordinator.spec.ts
+++ b/cli/src/lib/terminalBackendCoordinator.spec.ts
@@ -3,7 +3,7 @@ import type { RegisteredSession } from './registry.js'
import type { TerminalBackend } from './terminalBackend.js'
import { TerminalBackendCoordinator } from './terminalBackendCoordinator.js'
import { terminalRouteKey } from './terminalRuntime.js'
-import type { TerminalRuntimeRef } from './terminalTypes.js'
+import type { TerminalRuntimeRef, TerminalStreamHandle, TerminalStreamSink } from './terminalTypes.js'
const tmux: TerminalRuntimeRef = { backend: 'tmux', paneId: '%1' }
const herdr: TerminalRuntimeRef = {
@@ -30,7 +30,59 @@ function backend(instanceId: string, submit: TerminalBackend['submitText']): Ter
}
}
+function streamHandle(): TerminalStreamHandle {
+ return {
+ runtime: tmux,
+ beginSnapshot: vi.fn(),
+ snapshot: vi.fn(async () => ({
+ state: 'succeeded' as const,
+ value: { bytes: new Uint8Array(), cols: 80, rows: 24 },
+ })),
+ endSnapshot: vi.fn(),
+ writeRaw: vi.fn(),
+ resize: vi.fn(),
+ scroll: vi.fn(),
+ pauseOutput: vi.fn(),
+ resumeOutput: vi.fn(),
+ close: vi.fn(),
+ }
+}
+
describe('TerminalBackendCoordinator', () => {
+ it('opens a retained terminal runtime even when engine discovery marked the agent dormant', async () => {
+ const tmuxBackend = backend('tmux:default', vi.fn())
+ const handle = streamHandle()
+ tmuxBackend.openStream = vi.fn(async () => ({ state: 'succeeded' as const, value: handle }))
+ const coordinator = new TerminalBackendCoordinator([tmuxBackend], ['tmux'], ['default'])
+ const current = session()
+ current.active = false
+ const sink: TerminalStreamSink = { onData: vi.fn(), onClose: vi.fn() }
+
+ await expect(coordinator.openStream(current, { cols: 80, rows: 24 }, sink)).resolves.toEqual({
+ state: 'succeeded', value: handle,
+ })
+ expect(tmuxBackend.openStream).toHaveBeenCalledWith(
+ tmux,
+ { engine: 'claude', processIdentity: current.processIdentity },
+ { cols: 80, rows: 24 },
+ sink,
+ )
+ })
+
+ it('reports the backend failure when a dormant agent no longer has a terminal pane', async () => {
+ const tmuxBackend = backend('tmux:default', vi.fn())
+ tmuxBackend.openStream = vi.fn(async () => ({ state: 'failed' as const, reason: 'tmux pane is unavailable' }))
+ const coordinator = new TerminalBackendCoordinator([tmuxBackend], ['tmux'], ['default'])
+ const current = session()
+ current.active = false
+
+ await expect(coordinator.openStream(
+ current,
+ { cols: 80, rows: 24 },
+ { onData: vi.fn(), onClose: vi.fn() },
+ )).resolves.toEqual({ state: 'failed', reason: 'tmux pane is unavailable' })
+ })
+
it('merges backend-scoped title snapshots and prefers the primary runtime title', async () => {
const first = backend('tmux:default', vi.fn())
first.titles = vi.fn(async () => ({ state: 'succeeded' as const, value: new Map([[terminalRouteKey(tmux), 'tmux title']]) }))
diff --git a/cli/src/lib/terminalBackendCoordinator.ts b/cli/src/lib/terminalBackendCoordinator.ts
index a52299ed8..e3e787c52 100644
--- a/cli/src/lib/terminalBackendCoordinator.ts
+++ b/cli/src/lib/terminalBackendCoordinator.ts
@@ -190,7 +190,11 @@ export class TerminalBackendCoordinator {
size: TerminalStreamSize,
sink: TerminalStreamSink,
): Promise<TerminalReadResult<TerminalStreamHandle>> {
- if (!session.active) return { state: 'failed', reason: 'terminal agent is dormant' }
+ // `active` describes whether the engine process was discovered, not whether the retained
+ // terminal runtime is still viewable. A dormant agent can legitimately be waiting at setup,
+ // trust, or a shell prompt. Let each backend authoritatively check whether its pane still
+ // exists. Engine-targeted operations (capture, leases, and submit helpers) keep their active
+ // guards elsewhere in this coordinator; the opened stream may still carry raw terminal input.
let reason = 'TERMINAL_RUNTIME_UNAVAILABLE'
for (const runtime of this.orderedRuntimes(session)) {
const backend = this.backendFor(runtime)