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.

Super Tabs: say why a terminal can't be recorded, and name an engine replaced while it runs (#1477)

0xdiego258c616abd189d
diff --git a/cli/src/engines/kit/identityScan.ts b/cli/src/engines/kit/identityScan.ts
index 2cdf07713..0bd45529d 100644
--- a/cli/src/engines/kit/identityScan.ts
+++ b/cli/src/engines/kit/identityScan.ts
@@ -6,6 +6,9 @@ export class IdentityReadUnavailable extends Error {
readonly code = 'IDENTITY_UNAVAILABLE'
constructor(reason: string, message = `Conversation identity is held: ${reason}.`) { super(message) }
}
+/** The engine's executable was replaced on disk (a package manager updated it) while the process kept
+ * running, so the kernel no longer reports its image and no native read can succeed until it restarts. */
+export const REPLACED_PROGRAM = 'the agent\u2019s program was replaced on disk while it was running; restart the agent'
/** A conversation was seen and then could not be read: never a reason to stop its process without it
* (lib/stopAgentService.ts `withoutConversation`). */
export class ObservedConversationUnavailable extends IdentityReadUnavailable {
diff --git a/cli/src/lib/nativeProcessControl.spec.ts b/cli/src/lib/nativeProcessControl.spec.ts
index 351e631bd..4069ff331 100644
--- a/cli/src/lib/nativeProcessControl.spec.ts
+++ b/cli/src/lib/nativeProcessControl.spec.ts
@@ -110,6 +110,20 @@ describe('strict Darwin control protocol', () => {
await expect(nativeProcessControl([42], 0, budget())).rejects.toThrow('probe did not complete')
}
})
+ it('names a live process whose program was replaced on disk, and only that, when the probe fails', async () => {
+ const live = process.pid, gone = 2_000_000_000
+ const paths = (pid: number) => `${JSON.stringify({ schema: 1, mode: 'paths' })}\n${JSON.stringify({ pid, unavailable: true })}\n`
+ for (const [pid, expected] of [[live, 'replaced on disk'], [gone, 'probe did not complete']] as const) {
+ host.exec.mockImplementation((_path, args, _options, callback) => args[0] === '--paths'
+ ? callback(null, paths(pid), '')
+ : callback(Object.assign(Error('exit 75'), { code: 75 }), Buffer.alloc(0), Buffer.alloc(0)))
+ await expect(nativeProcessControl([pid], 0, budget())).rejects.toThrow(expected)
+ expect(host.exec.mock.calls.at(-1)?.[1]).toEqual(['--paths', String(pid)])
+ }
+ host.exec.mockClear().mockImplementation((_path, _args, _options, callback) => callback(null, Buffer.from(output({ ...record(), imageHex: 'zz' })), Buffer.alloc(0)))
+ await expect(nativeProcessControl([42], 0, budget())).rejects.toThrow()
+ expect(host.exec.mock.calls.map(call => call[1][0])).toEqual(['--control']) // A parse failure is not a failed probe.
+ })
it('uses the remaining deadline and stops a missing, late or failed helper without accepting an empty pool', async () => {
await expect(nativeProcessControl([42], 0, budget())).resolves.toMatchObject({ parent: 0 })
expect(host.exec.mock.calls[0][1]).toEqual(['--control', expect.any(String), '0', '42'])
diff --git a/cli/src/lib/nativeProcessControl.ts b/cli/src/lib/nativeProcessControl.ts
index c88fa66e7..550f84b42 100644
--- a/cli/src/lib/nativeProcessControl.ts
+++ b/cli/src/lib/nativeProcessControl.ts
@@ -1,10 +1,10 @@
/** Joined, bounded kernel evidence for control. Discovery's partial image reader is not authority. */
import { execFile } from 'node:child_process'
import { constants, closeSync, fstatSync, openSync, opendirSync, readlinkSync, readSync, statSync } from 'node:fs'
-import { IdentityReadUnavailable } from '../engines/kit/identityScan.js'
+import { IdentityReadUnavailable, REPLACED_PROGRAM } from '../engines/kit/identityScan.js'
import type { NativeDescriptor } from '../engines/kit/nativeDescriptors.js'
import { NativeEvidenceBudget, nativeText, nativeUnavailable } from '../engines/kit/nativeEvidence.js'
-import { bundledProcessImageHelper, invalidateProcessImageHelper } from './nativeProcessImages.js'
+import { bundledProcessImageHelper, invalidateProcessImageHelper, parseNativeProcessImages } from './nativeProcessImages.js'
import { psEnv } from './childLocale.js'
export interface NativeControlRow {
@@ -207,6 +207,19 @@ function linuxControl(pids: readonly number[], parent: number, budget: NativeEvi
}
}
+/** A live process with no kernel image path cannot show control evidence until it restarts. */
+async function replacedImage(path: string, pids: readonly number[], budget: NativeEvidenceBudget): Promise<boolean> {
+ try {
+ const timeout = Math.min(budget.probe(), 1000)
+ const stdout = await new Promise<string>(resolve => {
+ execFile(path, ['--paths', ...pids.map(String)], { encoding: 'utf8', timeout, maxBuffer: 1024 * 1024, killSignal: 'SIGKILL', env: psEnv() },
+ (_error, out) => resolve(typeof out === 'string' ? out : ''))
+ })
+ const { unavailable } = parseNativeProcessImages(stdout, new Set(pids))
+ return [...unavailable].some(pid => { try { process.kill(pid, 0); return true } catch { return false } })
+ } catch { return false }
+}
+
/** No ps/lsof wait separates the last process and descriptor observations. This does not
* freeze an external process; immutable core ownership is still checked by every caller. */
export async function nativeProcessControl(pids: readonly number[], parent: number, budget: NativeEvidenceBudget): Promise<NativeControlSnapshot> {
@@ -215,6 +228,7 @@ export async function nativeProcessControl(pids: readonly number[], parent: numb
if (process.platform === 'linux') return linuxControl(pids, parent, budget)
if (process.platform !== 'darwin') return nativeUnavailable('native control evidence is unavailable on this platform')
let timer: ReturnType<typeof setTimeout> | undefined
+ let probeFailed: string | undefined
try {
const helper = await Promise.race([bundledProcessImageHelper({ retryUnavailable: true }), new Promise<null>(resolve => {
timer = setTimeout(() => resolve(null), budget.remaining())
@@ -226,13 +240,19 @@ export async function nativeProcessControl(pids: readonly number[], parent: numb
{ encoding: 'buffer', timeout, maxBuffer: 5 * 1024 * 1024, killSignal: 'SIGKILL', env: psEnv() },
(error, stdout, stderr) => {
if (error && ['ENOENT', 'ENOTDIR', 'EACCES', 'ENOEXEC'].includes(String(error.code))) invalidateProcessImageHelper(helper.key)
- if (error || stderr.length) reject(new IdentityReadUnavailable('the native control probe did not complete'))
+ if (error || stderr.length) {
+ probeFailed = helper.path
+ reject(new IdentityReadUnavailable('the native control probe did not complete'))
+ }
else resolve(stdout)
})
})
budget.step(bytes.length)
return parseNativeProcessControl(nativeText(bytes), pids, parent, budget)
} catch (error) {
+ if (probeFailed && await replacedImage(probeFailed, pids, budget)) {
+ throw new IdentityReadUnavailable(REPLACED_PROGRAM)
+ }
if (error instanceof IdentityReadUnavailable) throw error
return nativeUnavailable('the native control probe could not start')
} finally { if (timer) clearTimeout(timer) }
diff --git a/cli/src/superTabs/native.spec.ts b/cli/src/superTabs/native.spec.ts
index edc8c047c..503338464 100644
--- a/cli/src/superTabs/native.spec.ts
+++ b/cli/src/superTabs/native.spec.ts
@@ -1,9 +1,10 @@
import { createHash } from 'node:crypto'
-import { mkdtempSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs'
+import { existsSync, mkdtempSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs'
import { tmpdir } from 'node:os'
import { join } from 'node:path'
import { afterEach, describe, expect, it, vi } from 'vitest'
import { fakeCore } from '../testing/fakeCore.js'
+import { REPLACED_PROGRAM } from '../engines/kit/identityScan.js'
import { createNativeTurnObservations } from '../lib/nativeTurnObservations.js'
import { NativeRecorder, nativeJournalFile } from './native.js'
@@ -46,6 +47,17 @@ function setup() {
}
describe('durable native conversation recording', () => {
+ it('says why an unidentified terminal cannot be recorded instead of asking for an update', async () => {
+ const t = setup()
+ const transcripts = t.core.transcripts as { nativeTurns?: unknown }
+ transcripts.nativeTurns = vi.fn(async () => null)
+ await expect(t.open().prepare('tab', alpha)).rejects.toThrow('Harness hasn’t identified this terminal’s conversation yet. Retry in a moment, or restart the agent.')
+ vi.mocked(t.core.agents.byAgent).mockReturnValue({ agentId: 'harness', identityHold: `Conversation identity is held: ${REPLACED_PROGRAM}.` } as never)
+ await expect(t.open().prepare('tab', alpha)).rejects.toThrow('This agent’s program was updated while it was running. Restart the agent, then retry.')
+ delete transcripts.nativeTurns
+ await expect(t.open().prepare('tab', alpha)).rejects.toThrow('Update this machine’s Harness to record native terminal conversations.')
+ expect(existsSync(t.file)).toBe(false)
+ })
it('starts at the current boundary and records only the prepared conversation, without writing native input', async () => {
const t = setup(), host = t.open()
t.observer.read('harness'); t.prompt('Private history'); t.answer('Private answer')
@@ -204,7 +216,7 @@ describe('durable native conversation recording', () => {
t.backend.mockResolvedValueOnce({ status: 200, body: { data: { contextId: alpha, machineId: 'elsewhere' } } } as never)
await expect(host.prepare('tab', alpha)).rejects.toThrow('exact contributed terminal')
vi.mocked(t.core.transcripts.nativeTurns!).mockResolvedValueOnce(null)
- await expect(host.prepare('tab', alpha)).rejects.toThrow('Update')
+ await expect(host.prepare('tab', alpha)).rejects.toThrow('identified')
await host.prepare('tab', alpha)
t.time(80_000); await host.prepare('tab', alpha, true); t.time(100_000)
t.prompt('Still open'); t.answer('Recorded'); await host.capture(); await host.flush()
diff --git a/cli/src/superTabs/native.ts b/cli/src/superTabs/native.ts
index 9b5c4ed07..35fc49693 100644
--- a/cli/src/superTabs/native.ts
+++ b/cli/src/superTabs/native.ts
@@ -3,6 +3,7 @@ import { existsSync, lstatSync, mkdirSync, readFileSync, renameSync, writeFileSy
import { dirname, join } from 'node:path'
import type { CoreApi } from '../core/api.js'
import { nativeTurnCursorIn, type NativeTurnCursor, type NativeTurnObservation } from '../lib/nativeTurnObservations.js'
+import { REPLACED_PROGRAM } from '../engines/kit/identityScan.js'
import { backend, SuperTabHostError } from './host.js'
import { identifier, object } from './wire.js'
@@ -28,6 +29,13 @@ const copyEvent = (event: NativeTurnObservation): Omit<Event, 'contextId' | 'pre
turnId: event.turnId, kind: event.kind, text: event.text, truncated: event.truncated, interrupted: event.interrupted,
})
+/** The core reads no turns for an agent whose conversation it has not identified. Say why, so the person
+ * restarts the agent instead of updating a Harness that is already current. */
+function unidentified(hold: string | undefined): string {
+ if (hold?.includes(REPLACED_PROGRAM)) return 'This agent’s program was updated while it was running. Restart the agent, then retry.'
+ return 'Harness hasn’t identified this terminal’s conversation yet. Retry in a moment, or restart the agent.'
+}
+
/** Durable conversation recording stays outside the core. Capturing a bounded
* page never waits for the backend; flushing the outbox never writes into an agent. */
export class NativeRecorder {
@@ -127,9 +135,12 @@ export class NativeRecorder {
const existing = this.journal.agents[harnessId]?.contexts[contextId]
if (existing?.blocked) throw new Error(existing.blocked)
if (renew && (!existing || existing.until <= this.now())) throw new Error('Terminal recording expired. Reopen the terminal from this conversation.')
- const page = await this.core.transcripts.nativeTurns?.(harnessId)
+ const read = this.core.transcripts.nativeTurns
+ if (!read) throw new Error('Update this machine’s Harness to record native terminal conversations.')
+ const page = await read(harnessId)
this.available()
- if (!page || closed?.aborted) throw new Error('Update this machine’s Harness to record native terminal conversations.')
+ if (closed?.aborted) throw new Error('This terminal request is no longer available.')
+ if (!page) throw new Error(unidentified(this.core.agents.byAgent(harnessId)?.identityHold))
if (!existing && !this.journal.agents[harnessId] && Object.keys(this.journal.agents).length >= 128) throw new Error('Too many recorded terminals are active.')
if (!existing && Object.keys(this.journal.agents[harnessId]?.contexts ?? {}).length >= 256) throw new Error('Too many terminal contexts are active.')
this.commit(next => {