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.

fix(cli): stop a guest's harness by closing its pane (#1547)

lingrd5eff3a6bfb9f
diff --git a/cli/src/lib/stopAgentService.spec.ts b/cli/src/lib/stopAgentService.spec.ts
index 5a468c5cc..767e680e1 100644
--- a/cli/src/lib/stopAgentService.spec.ts
+++ b/cli/src/lib/stopAgentService.spec.ts
@@ -104,6 +104,45 @@ it('preserves an unexpected evidence failure without signalling or hiding its ca
expect(terminateDeletedAgent).not.toHaveBeenCalled()
expect(deps.forgetSession).not.toHaveBeenCalled()
})
+// A guest's harness runs as the guest's own OS user: the owner's daemon can neither read its process's descriptors
+// (the native control probe) nor signal it (EPERM). Measured on a Mac sharing with a guest, 2026-10-22: closing the
+// owner's tmux pane ended the guest's process.
+it('stops a guest harness by closing its pane, without the native probe or a signal, once its process has left', async () => {
+ Object.assign(row, { guest: '[email protected]' })
+ vi.mocked(captureResumeIdentity).mockRejectedValue(new IdentityReadUnavailable('the native control probe did not complete'))
+ vi.mocked(checkPidRuntime).mockResolvedValueOnce({ state: 'alive' }).mockResolvedValue({ state: 'gone', reason: 'saved process identity is no longer running' })
+ deps.wait = vi.fn(async () => {})
+ await createStopAgentService(deps)(row.agentId)
+ expect(captureResumeIdentity).not.toHaveBeenCalled()
+ expect(deps.stopNative).not.toHaveBeenCalled()
+ expect(terminateDeletedAgent).not.toHaveBeenCalled()
+ expect(tmuxKill).toHaveBeenCalledOnce()
+ expect(checkPidRuntime).toHaveBeenCalledTimes(2)
+ expect(stoppedAgents.get(row.agentId)).toMatchObject({ active: false, sessionId: 'saved' })
+ expect(registry.byAgent(row.agentId)).toBeUndefined()
+})
+it('keeps a guest harness whose process is still running after its pane closed', async () => {
+ Object.assign(row, { guest: '[email protected]' })
+ vi.mocked(checkPidRuntime).mockResolvedValue({ state: 'alive' })
+ deps.wait = vi.fn(async () => {})
+ await expect(createStopAgentService(deps)(row.agentId)).rejects.toThrow('Could not confirm that the harness stopped')
+ expect(tmuxKill).toHaveBeenCalledOnce()
+ expect(deps.forgetSession).not.toHaveBeenCalled()
+ expect(registry.byAgent(row.agentId)).toBe(row)
+})
+it('waits for the process a starting guest harness gained while it was saved', async () => {
+ // Stopped before its engine was seen, which the pane's watcher binds while the screen is saved: an older copy of the
+ // row has no process, which reads as gone at once.
+ Object.assign(row, { guest: '[email protected]', processIdentity: undefined })
+ const engine = { pid: 91, executable: 'claude', startMarker: 'guest' }
+ vi.mocked(checkPidRuntime).mockImplementation(async s => s.processIdentity ? { state: 'alive' } : { state: 'gone', reason: 'none' })
+ deps.wait = vi.fn(async () => {})
+ await expect(createStopAgentService(deps)(row.agentId, { checkpoint: async (_s, phase) => {
+ if (phase === 'before') row.processIdentity = engine
+ } })).rejects.toThrow('Could not confirm that the harness stopped')
+ expect(vi.mocked(checkPidRuntime).mock.calls.every(([s]) => s.processIdentity?.pid === 91)).toBe(true)
+ expect(registry.byAgent(row.agentId)).toBe(row)
+})
// A close of a harness still starting that waited in vain for its first conversation (closeAgentService.ts).
it('stops a harness that never bound a conversation without one, only when its close asks', async () => {
Object.assign(row, { sessionId: '', transcriptPath: null, boundAt: null })
diff --git a/cli/src/lib/stopAgentService.ts b/cli/src/lib/stopAgentService.ts
index f4d2644e0..33d8a5825 100644
--- a/cli/src/lib/stopAgentService.ts
+++ b/cli/src/lib/stopAgentService.ts
@@ -37,7 +37,12 @@ export interface StopAgentServiceDeps {
* signalled: core/engines/nativeControls.ts, the engine's worker speaking its protocol under a grant.
*/
stopNative(session: RegisteredSession, current: () => boolean, confirmUnusedConversation?: (session: RegisteredSession) => Promise<boolean>): Promise<void>
+ /** The pause between reads of a guest's process while it leaves (tests pass one that returns at once). */
+ wait?(ms: number): Promise<void>
}
+/** How long a guest's engine has to leave once its pane closed, read every GUEST_EXIT_STEP_MS. */
+const GUEST_EXIT_WAIT_MS = 5_000
+const GUEST_EXIT_STEP_MS = 250
export class AgentStopError extends Error {
readonly code = 'STOP_UNCONFIRMED'
}
@@ -73,6 +78,18 @@ const bindingIdentity = (entry: RegisteredSession) => JSON.stringify([
export function createStopAgentService(deps: StopAgentServiceDeps) {
const { registry, stoppedAgents, restartJobs, stopJobs, backendFor, agentReconciler,
forgetSession, markDeleted, clearDeleted, stopNative } = deps
+ const wait = deps.wait ?? (ms => new Promise<void>(resolve => { const timer = setTimeout(resolve, ms); timer.unref?.() }))
+ /** A guest's engine, its pane closed, has left: read from the process table, which shows every user's processes. An
+ * unreadable table is not proof that it left. The process is the row's latest: one still starting gains it while its
+ * screen is saved, and an older copy without one would read as gone at once. */
+ const guestLeft = async (agentId: string, s: RegisteredSession): Promise<boolean> => {
+ const processIdentity = registry.resolve(agentId)?.processIdentity ?? s.processIdentity
+ for (let waited = 0; ; waited += GUEST_EXIT_STEP_MS) {
+ if ((await checkPidRuntime({ engine: s.engine, processIdentity })).state === 'gone') return true
+ if (waited >= GUEST_EXIT_WAIT_MS) return false
+ await wait(GUEST_EXIT_STEP_MS)
+ }
+ }
return (target: string, options: StopAgentOptions = {}) => {
const sessionId = registry.resolve(target)?.agentId ?? target
const existing = stopJobs.get(sessionId)
@@ -101,7 +118,15 @@ export function createStopAgentService(deps: StopAgentServiceDeps) {
return runtimeIdentity(current, !starting) === identity && (!conversation || current!.sessionId === conversation)
&& (binding === undefined || bindingIdentity(current!) === binding)
}
- const captured = await captureResumeIdentity({ ...live }).catch((error: unknown) => {
+ // A guest's harness runs as the guest's own OS user (docs/plans/2026-10-19-guest-machine-sharing-plan.md). This
+ // daemon can neither read that process's descriptors (the native control probe exits 75: macOS refuses
+ // proc_pidinfo for another user's process) nor signal it (EPERM), so every Stop of one was refused, "Conversation
+ // identity is held", and the guest could not close it (measured on a Mac sharing with a guest, 2026-10-22). It is
+ // never relaunched (GUEST_HARNESS_REFUSAL), so no native resume identity is kept for it: its screen is saved, and its
+ // pane, which is this daemon's, is closed. sudo hands the hangup to the guest's engine, as closing any terminal
+ // does, and the stop is confirmed only once that process has left.
+ const guest = !!live.guest
+ const captured = guest ? { ...live } : await captureResumeIdentity({ ...live }).catch((error: unknown) => {
if (!options.withoutConversation || conversation || live.transcriptPath || live.boundAt != null
|| !(error instanceof IdentityReadUnavailable) || error instanceof ObservedConversationUnavailable) throw error
options.withoutConversation()
@@ -116,7 +141,7 @@ export function createStopAgentService(deps: StopAgentServiceDeps) {
const s = current.sessionId && current.sessionId !== captured.sessionId ? { ...current } : { ...current, sessionId: captured.sessionId,
transcriptPath: captured.transcriptPath, hermesHome: captured.hermesHome, boundAt: captured.boundAt, source: captured.source }
binding = bindingIdentity(current)
- const transcript = s.sessionId && s.transcriptPath && engineKeepsTranscriptFile(s.engine)
+ const transcript = !guest && s.sessionId && s.transcriptPath && engineKeepsTranscriptFile(s.engine)
? controlTranscriptEvidence(s.engine, s.sessionId, s.transcriptPath, s.codexHome ?? undefined, s.cwd) : undefined
let nativeIdentityError: IdentityReadUnavailable | undefined
const verifyTranscript = () => {
@@ -139,15 +164,18 @@ export function createStopAgentService(deps: StopAgentServiceDeps) {
try {
markDeleted(sessionId)
if (s.sessionId) markDeleted(s.sessionId)
- await stopNative(s, () => {
- verifyTranscript()
- return sameTarget() && options.current?.() !== false
- }, options.confirmUnusedConversation).catch(error => { throw nativeIdentityError ?? error })
+ // (A guest's engine is its own, not this daemon's shared server's.)
+ if (!guest) {
+ await stopNative(s, () => {
+ verifyTranscript()
+ return sameTarget() && options.current?.() !== false
+ }, options.confirmUnusedConversation).catch(error => { throw nativeIdentityError ?? error })
+ }
if (nativeIdentityError) throw nativeIdentityError
verifyTranscript()
// Keep the terminal alive while the engine handles SIGTERM and flushes
// its native store. Killing tmux in parallel can deliver SIGHUP first.
- const termination = await (isTerminalEngine(s.engine) ? Promise.resolve('gone' as const)
+ const termination = await (isTerminalEngine(s.engine) || guest ? Promise.resolve('gone' as const)
: terminateDeletedAgent(s, {
checkRuntime: checkPidRuntime,
kill: (pid, signal) => {
@@ -187,7 +215,10 @@ export function createStopAgentService(deps: StopAgentServiceDeps) {
}))
if (nativeIdentityError) throw nativeIdentityError
if (panes.some(result => result.status !== 'fulfilled' || result.value.state !== 'succeeded')
- || (isTerminalEngine(s.engine) && !panes.length)) {
+ || ((isTerminalEngine(s.engine) || guest) && !panes.length)) {
+ throw new AgentStopError('Could not confirm that the harness stopped. Its saved conversation is safe. Try stopping again.')
+ }
+ if (guest && !await guestLeft(sessionId, s)) {
throw new AgentStopError('Could not confirm that the harness stopped. Its saved conversation is safe. Try stopping again.')
}
verifyTranscript()