@platless/axom-cli 0.1.0 → 0.5.9

package/dist/workstation/acp/test/fakeAgent.js

@@ -72,7 +72,7 @@
 //                                               // before `.connect()`, since it only works if the
 //                                               // handler exists in time to answer this call
 //     pingResultSink?: string,
-//     requestPermissionDuringPrompt?: { toolCall: ToolCallUpdate, options: PermissionOption[] },
+//     requestPermissionDuringPrompt?: { sessionId?: string, toolCall: ToolCallUpdate, options: PermissionOption[] },
 //                                               // if set, session/prompt calls the client's
 //                                               // session/request_permission with this payload
 //                                               // before returning, and writes the raw response to
@@ -85,6 +85,24 @@
 //                                               // before returning, and writes the raw response to
 //                                               // createElicitationResultSink.
 //     createElicitationResultSink?: string,
+//     createElicitationsDuringPrompt?: object[],
+//                                               // the plural of the above: session/prompt calls the
+//                                               // client's elicitation/create once per element, IN
+//                                               // ORDER and ONE AT A TIME — each call is awaited
+//                                               // before the next is sent, so exactly one card is
+//                                               // ever open. That sequencing is the point: it is how
+//                                               // a real agent asks a follow-up question, and it is
+//                                               // the only way to observe one property kind's answer
+//                                               // without the others' cards confusing the timeline.
+//                                               // Each raw response is appended to the JSON array at
+//                                               // createElicitationResultsSink, which is REWRITTEN
+//                                               // after every answer rather than once at the end —
+//                                               // a driver (a test, or a human clicking through a
+//                                               // browser) has to be able to read the answer to card
+//                                               // N while card N+1 is still open, and a single
+//                                               // write at the end of the turn would only be
+//                                               // readable after the last card was answered.
+//     createElicitationResultsSink?: string,
 //     authenticateSink?: string,               // if set, a file this process writes (the raw JSON
 //                                               // `authenticate` params, i.e. `{ methodId }`) the
 //                                               // moment it receives that request — lets a test
@@ -124,6 +142,8 @@
 //                                               // stderr-only login shape (antigravity), and it
 //                                               // starts at spawn on purpose, which is exactly the
 //                                               // window `ConnectAgentOptions.present` warns about.
+//     newSessionDelayMs?: number,              // delays the session/new response
+//     hangOnSessionLoad?: boolean,             // session/load never resolves, for startup cleanup tests
 //     hangOnSessionNew?: boolean,              // if true, session/new never resolves — the agent
 //                                               // answered initialize and then went quiet on the
 //                                               // very next request. Distinct from hangOnInitialize:
@@ -145,14 +165,41 @@
 //                                               // 这么干的:setTimeout 0,见 acp-agent.js:756)。
 //                                               // 用数组的数组是因为「推几次」本身就是被测行为:
 //                                               // claude 会推两次(70 → 68),codex 只推一次。
+//     rejectLaterSessionNew?: string,           // p3-fix7c 3: a marker path; the first session/new (across
+//                                               // processes) succeeds and creates it, every later one throws —
+//                                               // a probe retry that fails.
+//     commandsBeforeLaterSessionReply?: { commands: AvailableCommand[], markerPath: string }, // p3-fix7b M-4:
+//                                               // like commandsBeforeNewSessionReply, but only from the second
+//                                               // session/new on (counted across processes through markerPath) —
+//                                               // a first probe that saw nothing, then a retry the table races.
+//     commandsBeforeNewSessionReply?: AvailableCommand[], // p3-fix7 N9: one available_commands_update
+//                                               // sent INSIDE the session/new handler, before its reply —
+//                                               // the order a fast Claude adapter produced in run 5, which
+//                                               // reached the client before it knew its own session id.
 //     newSessionCommandsDelayMs?: number,       // 每次推送之间的间隔,默认 0。让测试能把一条晚到的
 //                                               // 推送放在 settle 窗口的里面或外面。
+//     newSessionSink?: string,                  // if set, a file this process writes (the raw JSON
+//                                               // session/new params, including `_meta`) the moment
+//                                               // it receives that request — Task 5's proof that
+//                                               // `AcpSession.open` actually sent
+//                                               // `_meta.claudeCode.emitRawSDKMessages` (or did not,
+//                                               // for an agent that is not claude)
+//     extNotifications?: { method: string, params: unknown }[], // sent, in order, as raw
+//                                               // extNotification calls after session/new answers —
+//                                               // same "after the reply" timing as
+//                                               // `newSessionCommands` above. Task 5 uses this to
+//                                               // model claude-agent-acp's
+//                                               // `extNotification("_claude/sdkMessage", …)`.
+//     extNotificationDelayMs?: number,          // delay between each of the above; default 0.
 //     sessions?: SessionInfo[],                 // session/list's response `sessions` array; default []
 //     nextCursor?: string,                      // session/list's response `nextCursor`
 //     sessionListSink?: string,                 // if set, a file this process writes (the raw JSON
 //                                                // session/list params, i.e. `{cwd, cursor}`) the
 //                                                // moment it receives that request — Task 7's proof
 //                                                // that listNativeSessions really sent cwd/cursor
+//     deleteSessionSink?: string,               // if set, a file each session/delete request's params
+//                                                // are appended to as a JSON line
+//     deleteSessionFailures?: string[],         // session ids whose session/delete throws internalError
 //     loadUpdates?: SessionUpdate[],            // Task 7 (adoption.ts): sent as session/update
 //                                                // notifications during session/load, before it
 //                                                // returns — this is the replay mechanism ACP v1
@@ -172,6 +219,9 @@
 //                                                // the shape credentials expiring mid-conversation
 //                                                // actually takes, and the only failure the login
 //                                                // card may be drawn for
+//     exitOnPrompt?: boolean,                  // simulate transport loss after accepting a prompt
+//     promptRpcError?: { code: number, message: string }, // explicit remote JSON-RPC failure
+//     promptCallsSink?: string,                 // append-only request log for no-replay assertions
 //     promptSink?: string,                       // if set, a file this process overwrites with the raw
 //                                                // JSON session/prompt params on every prompt — the
 //                                                // only way to observe WHICH sessionId a prompt was
@@ -179,12 +229,18 @@
 //                                                // to a loaded session rather than opening a new one
 //     loadSessionResponse?: LoadSessionResponse, // session/load's response; default {}
 //     loadSessionSink?: string,                 // if set, a file this process writes (the raw JSON
-//                                                // session/load params) the moment it receives that
-//                                                // request — lets a test prove the right
-//                                                // sessionId/cwd were sent, and (by NOT configuring
-//                                                // this and asserting the file never appears) that
-//                                                // adoption.ts never calls session/load when the
-//                                                // capability isn't advertised
+//                                                // session/load params, including `_meta`) the
+//                                                // moment it receives that request — lets a test
+//                                                // prove the right sessionId/cwd/`_meta` were sent,
+//                                                // and (by NOT configuring this and asserting the
+//                                                // file never appears) that adoption.ts never calls
+//                                                // session/load when the capability isn't advertised
+//     loadExtNotifications?: { method: string, params: unknown }[], // Task 9's equivalent of
+//                                                // `extNotifications` above, but pushed after
+//                                                // session/load answers instead of session/new — the
+//                                                // shape claude-agent-acp's activity push actually
+//                                                // takes on the adoption/reconnect path, where no
+//                                                // session/new is ever sent
 //     resumeSessionResponse?: ResumeSessionResponse, // session/resume's response; default {}
 //     resumeSessionSink?: string,                // same idea as loadSessionSink, for session/resume
 //                                                // — Task 7's proof that adoption.ts NEVER calls
@@ -206,6 +262,16 @@
 //                                                // `promptRequired`, so seeing it back means the
 //                                                // agent ignored the opt-in we always send
 //     steerRejectsWith?: string,                 // if set, the handler throws with this message
+//     asyncTaskStopSink?: string,                // if set, a file this process writes (the raw JSON
+//                                                // `_session/async_task/stop` params) the moment it
+//                                                // receives that request. Also an EXTENSION, not ACP
+//                                                // (`claude-agent-acp` `acp-agent.js@0.79.0:165`),
+//                                                // routed by its literal method name for the same
+//                                                // reason `_session/steering` is
+//     asyncTaskStopStopped?: boolean,            // what `{ stopped }` the handler answers with;
+//                                                // default true. `false` is what the adapter answers
+//                                                // for an id it has no live task under
+//                                                // (`acp-agent.js@0.79.0:1788`)
 //     newSessionConfigOptions?: SessionConfigOption[], // returned verbatim on session/new (types.gen.d.ts:2546)
 //     newSessionModes?: SessionModeState,              // returned verbatim on session/new (:2542)
 //     setConfigOptionSink?: string,                    // file receiving the JSON params of each session/set_config_option
@@ -225,7 +291,7 @@
 // fixture that can prove "honour the advertised capability, not the router" end to end, not just
 // assert a boolean.
 async function main() {
-    const { writeFileSync } = require('node:fs');
+    const { writeFileSync, appendFileSync, existsSync } = require('node:fs');
     // Parsed and wired up before the (slow, cold-start) dynamic import below, so a caller that kills
     // this process almost immediately after spawning it (exercising connectAgent's initialize
     // timeout with a short deadline) still gets a SIGTERM handler in place. Registering this only
@@ -307,16 +373,56 @@ async function main() {
         return {};
     })
         .onRequest(methods.agent.session.new, async (ctx) => {
+        if (config.echoMcpAuthorizationToStderr) {
+            const authorization = ctx.params.mcpServers.find((server) => server.name === 'axom-delegation')?.headers?.[0]?.value;
+            process.stderr.write('adapter diagnostic: started\n');
+            process.stderr.write(`configured Authorization: ${authorization?.slice(0, 9) ?? ''}`);
+            await new Promise((resolve) => setTimeout(resolve, 20));
+            process.stderr.write(`${authorization?.slice(9) ?? ''}\n`);
+            process.stderr.write(`configured token: ${authorization?.slice(7) ?? ''}\n`);
+            process.stderr.write(`Open https://auth.example.test/device?token=${authorization?.slice(7) ?? ''} to continue\n`);
+            process.stderr.write('adapter diagnostic: finished\n');
+        }
         if (config.newSessionRejectsWith)
             throw new Error(config.newSessionRejectsWith);
         // Checked after the rejection so the two flags stay independently exercisable; a promise that
         // never settles is the only faithful way to model an agent that simply stops answering.
         if (config.hangOnSessionNew)
             return new Promise(() => { });
+        if (config.newSessionDelayMs)
+            await new Promise((resolve) => setTimeout(resolve, config.newSessionDelayMs));
+        if (config.newSessionSink)
+            writeFileSync(config.newSessionSink, JSON.stringify(ctx.params));
+        for (const { method, params } of config.beforeSessionReplyNotifications ?? []) {
+            await ctx.client.notify(method, params);
+        }
         // Pushed AFTER this handler returns, not before: the real adapter schedules its first
         // `available_commands_update` on a `setTimeout(…, 0)` that runs once `session/new` has been
         // answered (`acp-agent.js:752-757`). Sending them inline would let a client that only reads
         // updates *before* the reply still pass, which is the bug this fixture exists to catch.
+        if (config.rejectLaterSessionNew) {
+            if (existsSync(config.rejectLaterSessionNew))
+                throw new Error('second session refused');
+            writeFileSync(config.rejectLaterSessionNew, 'seen');
+        }
+        if (config.commandsBeforeLaterSessionReply) {
+            const { commands, markerPath } = config.commandsBeforeLaterSessionReply;
+            if (existsSync(markerPath)) {
+                await ctx.client.notify(methods.client.session.update, {
+                    sessionId,
+                    update: { sessionUpdate: 'available_commands_update', availableCommands: commands },
+                });
+            }
+            else {
+                writeFileSync(markerPath, 'seen');
+            }
+        }
+        if (config.commandsBeforeNewSessionReply) {
+            await ctx.client.notify(methods.client.session.update, {
+                sessionId,
+                update: { sessionUpdate: 'available_commands_update', availableCommands: config.commandsBeforeNewSessionReply },
+            });
+        }
         const pushes = config.newSessionCommands ?? [];
         if (pushes.length > 0) {
             void (async () => {
@@ -329,6 +435,18 @@ async function main() {
                 }
             })();
         }
+        // Same "after the reply, not before" reasoning as `newSessionCommands` above — Task 5
+        // (agent-reported activity) uses this to model claude-agent-acp's
+        // `extNotification("_claude/sdkMessage", …)`, which only ever arrives once a session exists.
+        const extNotifications = config.extNotifications ?? [];
+        if (extNotifications.length > 0) {
+            void (async () => {
+                for (const { method, params } of extNotifications) {
+                    await new Promise((r) => setTimeout(r, config.extNotificationDelayMs ?? 0));
+                    await ctx.client.notify(method, params);
+                }
+            })();
+        }
         return {
             sessionId,
             ...(config.newSessionConfigOptions ? { configOptions: config.newSessionConfigOptions } : {}),
@@ -339,20 +457,49 @@ async function main() {
         if (config.sessionListSink)
             writeFileSync(config.sessionListSink, JSON.stringify(ctx.params));
         return { sessions: config.sessions ?? [], ...(config.nextCursor ? { nextCursor: config.nextCursor } : {}) };
+    })
+        .onRequest(methods.agent.session.delete, (ctx) => {
+        if (config.deleteSessionSink)
+            appendFileSync(config.deleteSessionSink, JSON.stringify(ctx.params) + '\n');
+        if (config.deleteSessionFailures?.includes(ctx.params.sessionId))
+            throw RequestError.internalError(undefined, 'boom');
+        return {};
     })
         .onRequest(methods.agent.session.load, async (ctx) => {
         if (config.loadSessionSink)
             writeFileSync(config.loadSessionSink, JSON.stringify(ctx.params));
         if (config.loadSessionRejectsWith)
             throw new Error(config.loadSessionRejectsWith);
+        if (config.hangOnSessionLoad)
+            return new Promise(() => { });
+        for (const { method, params } of config.beforeSessionReplyNotifications ?? []) {
+            await ctx.client.notify(method, params);
+        }
+        for (const notification of config.scopedLoadUpdates ?? []) {
+            await ctx.client.notify(methods.client.session.update, notification);
+        }
         for (const update of config.loadUpdates ?? []) {
             await ctx.client.notify(methods.client.session.update, { sessionId: ctx.params.sessionId, update });
         }
+        // Same "after the reply, not before" reasoning as `extNotifications` on session/new above —
+        // Task 9 uses this to model claude-agent-acp's `extNotification("_claude/sdkMessage", …)`
+        // arriving on the session/load (adoption/reconnect) path, where no session/new is ever sent.
+        const loadExtNotifications = config.loadExtNotifications ?? [];
+        if (loadExtNotifications.length > 0) {
+            void (async () => {
+                for (const { method, params } of loadExtNotifications) {
+                    await new Promise((r) => setTimeout(r, config.extNotificationDelayMs ?? 0));
+                    await ctx.client.notify(method, params);
+                }
+            })();
+        }
         return config.loadSessionResponse ?? {};
     })
         .onRequest(methods.agent.session.resume, async (ctx) => {
         if (config.resumeSessionSink)
             writeFileSync(config.resumeSessionSink, JSON.stringify(ctx.params));
+        if (config.resumeSessionRejectsWith)
+            throw new Error(config.resumeSessionRejectsWith);
         return config.resumeSessionResponse ?? {};
     })
         .onRequest(methods.agent.session.setConfigOption, (ctx) => {
@@ -384,10 +531,21 @@ async function main() {
             throw new Error(config.steerRejectsWith);
         const outcome = config.steerOutcome ?? 'injected';
         return outcome === 'promptRequired' ? { outcome, reason: 'noRunningTurn' } : { outcome };
+    })
+        .onRequest('_session/async_task/stop', (params) => params, (ctx) => {
+        if (config.asyncTaskStopSink)
+            writeFileSync(config.asyncTaskStopSink, JSON.stringify(ctx.params));
+        return { stopped: config.asyncTaskStopStopped ?? true };
     })
         .onRequest(methods.agent.session.prompt, async (ctx) => {
+        if (config.promptCallsSink)
+            appendFileSync(config.promptCallsSink, JSON.stringify(ctx.params) + '\n');
         if (config.promptSink)
             writeFileSync(config.promptSink, JSON.stringify(ctx.params));
+        if (config.exitOnPrompt)
+            process.exit(1);
+        if (config.promptRpcError)
+            throw new RequestError(config.promptRpcError.code, config.promptRpcError.message);
         // A plain Error is masked by the SDK as JSON-RPC -32603; `RequestError.authRequired()` is
         // the real thing an agent whose credentials expired answers with (-32000). The two shapes are
         // what the login card has to tell apart, and only a real agent process on a real wire proves
@@ -396,6 +554,11 @@ async function main() {
             throw RequestError.authRequired();
         if (config.promptRejectsWith)
             throw new Error(config.promptRejectsWith);
+        if (config.foregroundWriteSink && ctx.params.prompt.some(block => block.type === 'text' && block.text === 'partial-write')) {
+            appendFileSync(config.foregroundWriteSink, 'partial\n');
+            await cancelled;
+            return { stopReason: 'cancelled' };
+        }
         for (const update of updates) {
             await ctx.client.notify(methods.client.session.update, { sessionId: ctx.params.sessionId, update });
         }
@@ -405,7 +568,7 @@ async function main() {
         // OS process speaking real ACP, not just callable in-process.
         if (config.requestPermissionDuringPrompt) {
             const result = await ctx.client.request(methods.client.session.requestPermission, {
-                sessionId: ctx.params.sessionId,
+                sessionId: config.requestPermissionDuringPrompt.sessionId ?? ctx.params.sessionId,
                 toolCall: config.requestPermissionDuringPrompt.toolCall,
                 options: config.requestPermissionDuringPrompt.options,
             });
@@ -416,6 +579,19 @@ async function main() {
             const result = await ctx.client.request(methods.client.elicitation.create, config.createElicitationDuringPrompt);
             writeFileSync(config.createElicitationResultSink, JSON.stringify(result));
         }
+        // The plural form. `await` inside the loop is load-bearing, not incidental: the whole point is
+        // that card N is answered before card N+1 is raised. The sink is rewritten on every iteration
+        // so the answer to card N is readable while card N+1 is still open.
+        if (Array.isArray(config.createElicitationsDuringPrompt)) {
+            const results = [];
+            for (const payload of config.createElicitationsDuringPrompt) {
+                const result = await ctx.client.request(methods.client.elicitation.create, payload);
+                results.push(result);
+                if (config.createElicitationResultsSink) {
+                    writeFileSync(config.createElicitationResultsSink, JSON.stringify(results));
+                }
+            }
+        }
         if (config.hangUntilCancel) {
             await cancelled;
             return { stopReason: config.stopReasonAfterCancel ?? 'end_turn' };

package/dist/workstation/acp/test/keeperWorld.js

@@ -0,0 +1,267 @@
+/**
+ * The shared world of the keeper-acp end-to-end tests (Task 21's adoption tests, Task 23's fault-injection gate): a temp config dir
+ * with a real keeper-acp (the built bundle in `dist/keepers`), a real adapter process (`scriptAgent.ts`, driven by marker files), and
+ * the server's half played by {@link FakeServer} (frames applied once per seq — the server's de-duplication — plus the answers it
+ * recorded). A daemon life is either in-process ({@link KeeperWorld.life}: its own keeper connection, AcpAgents, manager and
+ * TaskRegistry; "killing" it drops the connection without any goodbye) or a real process ({@link KeeperWorld.daemonProcess}:
+ * `daemonLife.ts` under vite-node, killed with SIGKILL). {@link KeeperWorld.dispose} kills every keeper, adapter and daemon process it
+ * started, by pid.
+ */
+import { spawn } from 'node:child_process';
+import { appendFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { rm } from 'node:fs/promises';
+import path, { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { expect, vi } from 'vitest';
+import { killKeepersUnder, tempDir } from '../../../test/keeperKit.js';
+import { AcpKeeperClient } from '../../keepers/acp/client.js';
+import { computeBuildVersion } from '../../keepers/kit/buildVersion.js';
+import { keeperGen } from '../../keepers/kit/identity.js';
+import { KeeperLauncher } from '../../keepers/kit/launcher.js';
+import { AgentSessionManager } from '../../agentSessions.js';
+import { AGENT_WIRE_VERSION } from '../../protocol/agent.js';
+import { TaskRegistry } from '../../update/taskRegistry.js';
+import { AcpAgents } from '../acpAgents.js';
+import { keeperGenerations } from '../processor/transport/generations.js';
+import { KeeperTransport } from '../processor/transport/keeper.js';
+import { LocalTransport } from '../processor/transport/local.js';
+const here = path.dirname(fileURLToPath(import.meta.url));
+export const packageRoot = path.join(here, '..', '..', '..', '..');
+export const realDist = path.join(packageRoot, 'dist', 'keepers');
+export const SCRIPT_AGENT = join(here, 'scriptAgent.ts');
+export const DAEMON_LIFE = join(here, 'daemonLife.ts');
+export const BOOTSTRAP = "eval(require('node:fs').readFileSync(process.argv[1], 'utf8'))";
+export const touch = (dir, name) => writeFileSync(join(dir, name), '');
+export const agentPid = (dir) => Number(readFileSync(join(dir, 'pid'), 'utf8'));
+export const stdinLines = (dir) => existsSync(join(dir, 'stdin.jsonl')) ? readFileSync(join(dir, 'stdin.jsonl'), 'utf8').split('\n').filter(Boolean).map((l) => JSON.parse(l)) : [];
+export const downMethods = (records) => records.filter((r) => r.kind === 'down').map((r) => JSON.parse(r.line).method);
+/** The server's half: applies each seq once, in order (bridge_seq), per ref; remembers the answers it gave (spec §5.5.4). */
+export class FakeServer {
+    applied = new Map();
+    lastSeen = new Map();
+    received = [];
+    /** ref → requestId → outcome: what the user answered (the card's `answer`). */
+    answers = new Map();
+    apply = (frame) => {
+        this.received.push(frame);
+        if ((frame.t === 'agent_event' || frame.t === 'agent_turn_done') && typeof frame.seq === 'number') {
+            const last = this.lastSeen.get(frame.sessionRef) ?? 0;
+            if (frame.seq <= last)
+                return; // the server's de-duplication
+            this.lastSeen.set(frame.sessionRef, frame.seq);
+            const list = this.applied.get(frame.sessionRef) ?? [];
+            list.push(frame);
+            this.applied.set(frame.sessionRef, list);
+        }
+    };
+    timeline(ref) { return this.applied.get(ref) ?? []; }
+    seqs(ref) { return this.timeline(ref).map((frame) => frame.seq); }
+    turnDones(ref) { return this.timeline(ref).filter((frame) => frame.t === 'agent_turn_done'); }
+    texts(ref) {
+        return this.timeline(ref).filter((f) => f.t === 'agent_event' && f.eventName === 'agent_message_chunk')
+            .map((f) => (f.payload.content?.text ?? ''));
+    }
+    cards(ref) {
+        return this.timeline(ref).filter((f) => f.eventName === 'permission_request').map((f) => f.payload.requestId);
+    }
+    /** The user answers a card: recorded first (the server's item), then sent if a daemon is there. */
+    answer(ref, requestId, outcome) {
+        const answered = this.answers.get(ref) ?? new Map();
+        answered.set(requestId, outcome);
+        this.answers.set(ref, answered);
+        return { t: 'agent_answer', sessionRef: ref, requestId, outcome };
+    }
+    /** Task 22's resend: the answers this side recorded for cards a durable reopen still reports pending. */
+    resends(ref, opened) {
+        const answered = this.answers.get(ref);
+        return (opened.pendingRequestIds ?? []).filter((id) => answered?.has(id))
+            .map((id) => ({ t: 'agent_answer', sessionRef: ref, requestId: id, outcome: answered.get(id) }));
+    }
+}
+/** What the server's timeline says, without the ref: compared between two runs. */
+export const comparable = (frames) => frames.map(({ sessionRef: _ref, ...rest }) => rest);
+/** Seqs 1..n, no duplicate, no gap. */
+export function expectContiguous(seqs) {
+    expect(seqs).toEqual(Array.from({ length: seqs.length }, (_, k) => k + 1));
+}
+export class KeeperWorld {
+    configDir;
+    agentDir;
+    launcher;
+    lives = [];
+    processes = [];
+    extraDists = [];
+    agentDirs = [];
+    constructor(prefix) {
+        this.configDir = tempDir(prefix);
+        this.agentDir = this.newAgentDir(`${prefix}agent-`);
+        this.launcher = this.launcherFor(realDist);
+    }
+    launcherFor(distDir) {
+        return new KeeperLauncher({ configDir: this.configDir, workstationId: 'ws-t21', server: 'http://test.invalid', distDir, useSystemd: false,
+            startTimeoutMs: 20_000, umask: 0o022 });
+    }
+    /** Another adapter's marker directory (its pid is killed on dispose). */
+    newAgentDir(prefix = 'axom-t23-agent-') {
+        const dir = tempDir(prefix);
+        this.agentDirs.push(dir);
+        return dir;
+    }
+    scriptArgs(config, dir = this.agentDir) {
+        return ['-e', BOOTSTRAP, SCRIPT_AGENT, JSON.stringify({ dir, ...config })];
+    }
+    /** One daemon life: its own keeper-acp connection, AcpAgents (with the generations), manager and TaskRegistry, bound to `server`. */
+    life(server, over = {}) {
+        const use = over.launcher ?? this.launcher;
+        const real = new KeeperTransport(new AcpKeeperClient({ launcher: use }));
+        const keeper = (over.wrapKeeper ? over.wrapKeeper(real) : real);
+        const generations = keeperGenerations({ launcher: use, current: keeper, log: () => { } });
+        const local = new LocalTransport({ configDir: this.configDir });
+        const acp = new AcpAgents({ cacheDir: this.configDir, registry: { load: async () => [] }, transports: { keeper, local }, keeperGenerations: generations,
+            sessionStartTimeoutMs: 15_000, ...over.acp });
+        const tasks = new TaskRegistry();
+        const sent = [];
+        const manager = new AgentSessionManager(acp, null, join(this.configDir, 'agents'), tasks);
+        manager.bindSend((frame) => { sent.push(frame); server.apply(frame); }, AGENT_WIRE_VERSION);
+        let killed = false;
+        const result = {
+            keeper, generations, acp, tasks, manager, sent,
+            // kill -9 as keeper-acp sees it: the connection drops, nothing is detached, nothing is said.
+            kill() { if (killed)
+                return; killed = true; keeper.close(); generations.close(); void local.dispose(0); },
+        };
+        this.lives.push(result);
+        return result;
+    }
+    openFrame(ref, config, over = {}) {
+        return {
+            t: 'agent_open', id: `open-${ref}-${Math.random().toString(36).slice(2, 8)}`, sessionRef: ref, agentKey: 'script', bridge: 'script-acp',
+            cwd: this.configDir, shell: '/bin/sh', command: process.execPath, args: this.scriptArgs(config), ...over,
+        };
+    }
+    /** Opens `ref` on life `l` and waits for the reply. */
+    async openOn(l, ref, config, over = {}) {
+        const frame = this.openFrame(ref, config, over);
+        await l.manager.handleFrame(frame);
+        const reply = opened(l, frame.id)[0];
+        expect(reply, `no agent_opened for ${ref}`).toBeDefined();
+        expect(reply.ok, reply.error ?? '').toBe(true);
+        return reply;
+    }
+    /** The server reopens `ref` on life `l` after a reconnect: `agent_open` with its watermark, then Task 22's answer resend. */
+    async reopenOn(l, server, ref, config, over = {}) {
+        const reply = await this.openOn(l, ref, config, { resumeFromSeq: server.lastSeen.get(ref) ?? 0, ...over });
+        for (const frame of server.resends(ref, reply))
+            await l.manager.handleFrame(frame);
+        return reply;
+    }
+    /** Every raw record of `ref`, read over a connection of its own. */
+    async rawOf(ref, launcher = this.launcher) {
+        const reader = new KeeperTransport(new AcpKeeperClient({ launcher }));
+        try {
+            await reader.attach(ref);
+            const records = [];
+            const summary = (await reader.list()).find((s) => s.sessionKey === ref);
+            for (let at = summary.raw.first;;) {
+                const page = await reader.readRaw(ref, at);
+                if (page.length === 0)
+                    break;
+                records.push(...page);
+                at = page[page.length - 1].o + 1;
+            }
+            return records;
+        }
+        finally {
+            reader.close();
+        }
+    }
+    /** keeper-acp's listing of `ref`, over a connection of its own. */
+    async summaryOf(ref) {
+        const reader = new KeeperTransport(new AcpKeeperClient({ launcher: this.launcher }));
+        try {
+            return (await reader.list()).find((s) => s.sessionKey === ref);
+        }
+        finally {
+            reader.close();
+        }
+    }
+    /**
+     * A daemon life in a process of its own (`daemonLife.ts` under vite-node): it adopts what keeper-acp holds, then handles the frames
+     * it is given on stdin (one JSON per line; `{cmd:'forceBegin'}` runs a force update's `TaskRegistry.stopAll()`, `{cmd:'forceStop'}`
+     * also the restart path's detach, and exits). Every
+     * frame it sends lands in a file; its stderr is kept in `<configDir>/daemon-<n>.stderr` (the sentinel grep reads it).
+     */
+    daemonProcess(faults = {}) {
+        const n = this.processes.length + 1;
+        const framesOut = join(this.configDir, `frames-daemon-${n}.jsonl`);
+        const stderrFile = join(this.configDir, `daemon-${n}.stderr`);
+        const child = spawn(join(packageRoot, 'node_modules', '.bin', 'vite-node'), [DAEMON_LIFE,
+            JSON.stringify({ configDir: this.configDir, distDir: realDist, framesOut, faults })], { cwd: packageRoot, stdio: ['pipe', 'ignore', 'pipe'] });
+        let stderr = '';
+        child.stderr.on('data', (chunk) => { stderr += chunk.toString('utf8'); appendFileSync(stderrFile, chunk); });
+        const exited = new Promise((resolve) => child.once('exit', () => resolve()));
+        const result = {
+            child,
+            frames: () => existsSync(framesOut) ? readFileSync(framesOut, 'utf8').split('\n').filter(Boolean).map((line) => JSON.parse(line)) : [],
+            send: (frame) => { child.stdin.write(`${JSON.stringify(frame)}\n`); },
+            stderr: () => stderr,
+            kill: async () => { if (child.exitCode === null && child.signalCode === null)
+                child.kill('SIGKILL'); await exited; },
+            exited,
+        };
+        this.processes.push(result);
+        return result;
+    }
+    /** Opens `ref` in a daemon process and waits for its `agent_opened{ok}` (the server never prompts before it). */
+    async openIn(proc, frame) {
+        proc.send(frame);
+        let reply;
+        await vi.waitFor(() => {
+            expect(proc.child.exitCode, proc.stderr()).toBeNull();
+            reply = proc.frames().find((f) => f.t === 'agent_opened' && f.id === frame.id);
+            expect(reply).toBeDefined();
+        }, { timeout: 45_000, interval: 100 });
+        expect(reply.ok, reply.error ?? '').toBe(true);
+        return reply;
+    }
+    /** An "older build" of keeper-acp: the same bundle with one byte more (its own buildVersion, so its own generation). */
+    olderGeneration() {
+        const oldDist = tempDir('axom-t21-old-dist-');
+        this.extraDists.push(oldDist);
+        mkdirSync(join(oldDist, 'acp'), { recursive: true });
+        writeFileSync(join(oldDist, 'acp', 'keeper.mjs'), `${readFileSync(join(realDist, 'acp', 'keeper.mjs'), 'utf8')}\n// an older generation\n`);
+        const manifest = JSON.parse(readFileSync(join(realDist, 'acp', 'manifest.json'), 'utf8'));
+        const oldBuild = computeBuildVersion(join(oldDist, 'acp'));
+        writeFileSync(join(oldDist, 'acp', 'manifest.json'), JSON.stringify({ ...manifest, buildVersion: oldBuild }));
+        return { oldLauncher: this.launcherFor(oldDist), oldGen: keeperGen(oldBuild) };
+    }
+    /** Kills every daemon process, life, keeper-acp generation and adapter this world started (by pid); the directories stay. */
+    async stop() {
+        for (const proc of this.processes.splice(0))
+            await proc.kill().catch(() => { });
+        for (const life of this.lives.splice(0))
+            life.kill();
+        for (const gen of await this.launcher.liveGenerations('acp').catch(() => []))
+            await this.launcher.stop('acp', gen, 'force').catch(() => { });
+        for (const dir of this.agentDirs) {
+            const pidFile = join(dir, 'pid');
+            if (existsSync(pidFile)) {
+                try {
+                    process.kill(Number(readFileSync(pidFile, 'utf8')), 'SIGKILL');
+                }
+                catch { /* gone */ }
+            }
+        }
+    }
+    /** {@link stop}, then removes every directory (killing any keeper whose pid manifest is still under the config dir). */
+    async dispose() {
+        await this.stop();
+        for (const dist of this.extraDists.splice(0))
+            await rm(dist, { recursive: true, force: true });
+        for (const dir of this.agentDirs.splice(0))
+            await rm(dir, { recursive: true, force: true });
+        killKeepersUnder(this.configDir);
+    }
+}
+export const opened = (l, id) => l.sent.filter((frame) => frame.t === 'agent_opened' && (id === undefined || frame.id === id));
+export const liveSessionOf = (l, ref) => l.manager.sessions.get(ref)?.session;