@platless/axom-cli 0.3.13 → 0.5.9

package/dist/workstation/acp/switching.js

@@ -0,0 +1,114 @@
+import { activityIsBusy } from './activityBusy.js';
+/** Spec §14: a session must be quiet this long before it is switched. */
+export const SWITCH_QUIET_MS = 30_000;
+/** How long a switch waits for the session's record loop to reach a record boundary before it gives up (and retries later). */
+export const SWITCH_SUSPEND_TIMEOUT_MS = 10_000;
+/** A reopen request the server did not answer (busy, an older open won, …) is asked again after this long. */
+export const REOPEN_REQUEST_RETRY_MS = 60_000;
+/** The note a switch writes into a successor it gives up on (rollback): discovery never picks such a key (fix round 1). */
+export const SWITCH_ABANDONED_NOTE = 'switch_abandoned';
+/** A reopen for an adapter keeper-acp lost is asked at most this many times per lost spawn (60 s, 120 s, 240 s apart). */
+export const ADAPTER_LOST_REOPEN_ATTEMPTS = 3;
+/** The prefix of a switched key's suffix: `<sessionRef>#s<n>`. */
+export const SWITCHED_KEY_MARK = '#s';
+/** The transport key of the `keyGen`th life of `sessionRef` (0: the ref itself). */
+export function sessionKeyFor(sessionRef, keyGen) {
+    return keyGen <= 0 ? sessionRef : `${sessionRef}${SWITCHED_KEY_MARK}${keyGen}`;
+}
+/** The key generation a spawn label records (`label.keyGen`; absent or invalid: 0). */
+export function keyGenOf(label) {
+    const value = label?.keyGen;
+    return typeof value === 'number' && Number.isSafeInteger(value) && value > 0 ? value : 0;
+}
+/**
+ * The session ref a keeper-acp session belongs to: its label's `sessionRef`, provided the key is the one the label's `keyGen` derives
+ * from it (a key nothing could have spawned under that ref names none).
+ */
+export function refOfSession(summary) {
+    const ref = summary.label.sessionRef;
+    if (typeof ref !== 'string' || ref === '')
+        return undefined;
+    return sessionKeyFor(ref, keyGenOf(summary.label)) === summary.sessionKey ? ref : undefined;
+}
+/**
+ * Several keeper-acp sessions of one ref (a switch a crash interrupted — the only way two exist): which one is the ref's session and
+ * which go. The newest key whose open completed wins (its import of the predecessor's outbox had landed: the import precedes the
+ * load); every other one is superseded. When no newer key completed its open, the switch never finished: the newer keys go and the
+ * oldest one stays the ref's session. `openCompleted(key)` reads the session's head checkpoint.
+ */
+export async function resolveSuperseded(sessions, openCompleted) {
+    const byGen = [...sessions].sort((a, b) => keyGenOf(b.label) - keyGenOf(a.label));
+    for (const candidate of byGen.slice(0, -1)) {
+        if (await openCompleted(candidate))
+            return { winner: candidate, superseded: byGen.filter((s) => s !== candidate) };
+    }
+    const oldest = byGen[byGen.length - 1];
+    return { winner: oldest, superseded: byGen.filter((s) => s !== oldest) };
+}
+/**
+ * The scan card's wording of each {@link switchBlockers} sentence (Task 25, spec §6.4): those sentences stay as they are for the
+ * log; a reader looking at "why can't this session move now" gets these. Unknown input (none today) passes through unchanged.
+ */
+export function plainSwitchBlocker(blocker) {
+    const quiet = /^not quiet for (\d+) s$/.exec(blocker);
+    if (quiet)
+        return `it was active less than ${quiet[1]} seconds ago`;
+    return PLAIN_BLOCKERS[blocker] ?? blocker;
+}
+const PLAIN_BLOCKERS = {
+    'opening, retiring or switching': 'it is being opened or moved',
+    'its adapter is not running': 'its agent process is not running right now',
+    'a turn is in flight': 'it is working on a reply',
+    'a permission or elicitation is unanswered': 'it is waiting for an answer',
+    'the agent reports it is active': 'the agent says it is still working',
+    'an async task or background terminal is still running': 'it has a background task or terminal still running',
+    'a delegation refresh is pending': 'its delegated access is being renewed',
+};
+/** Why a session may not be switched now (spec §6.3 step 2); empty = strictly idle. */
+export function switchBlockers(input) {
+    const { session } = input;
+    const blockers = [];
+    if (input.busyRef)
+        blockers.push('opening, retiring or switching');
+    const liveness = session.liveness;
+    if (!liveness.agentAlive)
+        blockers.push('its adapter is not running');
+    if (liveness.turnRunning)
+        blockers.push('a turn is in flight');
+    if ((session.pendingRequestIds?.length ?? 0) > 0)
+        blockers.push('a permission or elicitation is unanswered');
+    const raw = session.activityRaw;
+    // `activityIsBusy` calls Codex "only waiting on an approval" idle (correct for the heartbeat); a switch must not kill that wait.
+    if (activityIsBusy(raw) || raw?.type === 'active')
+        blockers.push('the agent reports it is active');
+    if ((session.liveBackgroundWork ?? 0) > 0)
+        blockers.push('an async task or background terminal is still running');
+    if (session.delegation?.refreshPending)
+        blockers.push('a delegation refresh is pending');
+    const quiet = input.quietMs ?? SWITCH_QUIET_MS;
+    const last = Math.max(input.lastActivityAt, session.lastFoldAt ?? 0);
+    if (input.now - last < quiet)
+        blockers.push(`not quiet for ${Math.round(quiet / 1000)} s`);
+    return blockers;
+}
+/**
+ * Spec §6.3 step 4 / analysis D §5.2 step 7: a load answers with the adapter's own idea of the session's config (most adapters do
+ * not persist a model or mode choice into the session file); every option whose value differs from what the session had before the
+ * switch is set back. Options the new process does not offer, or values it refuses, are reported and left as they are.
+ */
+export async function restoreConfigOptions(session, before, idFor, log) {
+    const restored = [];
+    for (const option of before) {
+        const now = session.configOptions.find((candidate) => candidate.id === option.id);
+        if (!now || now.type !== option.type || now.currentValue === option.currentValue)
+            continue;
+        try {
+            await session.setConfigOption(option.id, option.currentValue, idFor(option.id));
+            restored.push(option.id);
+        }
+        catch (error) {
+            log(`[acp] switch: config option '${option.id}' could not be set back to its value before the switch: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    return restored;
+}

package/dist/workstation/acp/terminalLogin.js

@@ -32,6 +32,21 @@
 import { spawn } from 'node:child_process';
 import { randomUUID } from 'node:crypto';
 import { createAuthUrlScanner } from './authUrlSniffer.js';
+import { withPathPrefix } from './registry/launch.js';
+export { metaTerminalAuthArgs, terminalLoginSpecOf } from './terminalLoginSpec.js';
+/**
+ * The launch a terminal sign-in runs under. A `_meta["terminal-auth"]` names its own command and
+ * args — but **not its own environment**: the resolved launch's env (and PATH prefix) still apply,
+ * because the launchEnv layer must reach the login child exactly as it reaches a session. Claude's
+ * `CLAUDE_SECURESTORAGE_CONFIG_DIR` decides which credential slot `--cli auth login` writes into;
+ * a meta login launched over an empty env would seed the shared slot and strand the isolated one —
+ * and every session on it — logged out. The append shape is the launch itself, unchanged.
+ */
+export function launchForTerminalLogin(terminal, resolved) {
+    return terminal.kind === 'meta'
+        ? { command: terminal.command, args: [], env: resolved.env, ...(resolved.pathPrefix ? { pathPrefix: resolved.pathPrefix } : {}) }
+        : resolved;
+}
 export class TerminalLoginFailedError extends Error {
 }
 export class TerminalLoginTimeoutError extends Error {
@@ -41,54 +56,13 @@ export class TerminalLoginCancelledError extends Error {
 /** How many of the process's last output lines a failure quotes. */
 const FAILURE_TAIL_LINES = 20;
 const DEFAULT_KILL_GRACE_MS = 2_000;
-function isRecord(value) {
-    return typeof value === 'object' && value !== null && !Array.isArray(value);
-}
-function stringArray(value) {
-    return Array.isArray(value) && value.every((item) => typeof item === 'string') ? [...value] : undefined;
-}
-function stringRecord(value) {
-    if (!isRecord(value))
-        return {};
-    return Object.fromEntries(Object.entries(value).filter((entry) => typeof entry[1] === 'string'));
-}
-function metaTerminalAuth(method) {
-    if (!isRecord(method) || !isRecord(method._meta))
-        return undefined;
-    const entry = method._meta['terminal-auth'];
-    return isRecord(entry) ? entry : undefined;
-}
-/** The `args` a `_meta["terminal-auth"]` entry carries, for display where the top-level `args` is absent. */
-export function metaTerminalAuthArgs(method) {
-    return stringArray(metaTerminalAuth(method)?.args);
-}
-/**
- * How to run this advertised method as a terminal login, or `undefined` when it is not one (spec
- * D6: top-level `type: "terminal"`, or a `_meta["terminal-auth"]` object).
- */
-export function terminalLoginSpecOf(method) {
-    if (!isRecord(method))
-        return undefined;
-    const meta = metaTerminalAuth(method);
-    if (meta && typeof meta.command === 'string' && meta.command.trim() !== '') {
-        return { kind: 'meta', command: meta.command, args: stringArray(meta.args) ?? [], env: stringRecord(meta.env) };
-    }
-    if (meta || method.type === 'terminal') {
-        return {
-            kind: 'append',
-            args: stringArray(method.args) ?? stringArray(meta?.args) ?? [],
-            env: { ...stringRecord(meta?.env), ...stringRecord(method.env) },
-        };
-    }
-    return undefined;
-}
 /**
  * The concrete command line. `baseEnv` is the workstation's and the agent's configured environment
  * (`AcpListSpec.env` then `.agentEnv`), layered the way `connectAgent` layers a session's; the
  * method's own `env` goes last because ACP says it overrides the base launch configuration.
  */
 export function terminalInvocationFor(spec, launch, baseEnv) {
-    const env = { ...launch.env, ...baseEnv, ...spec.env };
+    const env = withPathPrefix({ ...launch.env, ...baseEnv, ...spec.env }, launch.pathPrefix);
     if (spec.kind === 'meta')
         return { command: spec.command, args: [...spec.args], env };
     return { command: launch.command, args: [...launch.args, ...spec.args], env };

package/dist/workstation/acp/terminalLoginSpec.js

@@ -0,0 +1,41 @@
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function stringArray(value) {
+    return Array.isArray(value) && value.every((item) => typeof item === 'string') ? [...value] : undefined;
+}
+function stringRecord(value) {
+    if (!isRecord(value))
+        return {};
+    return Object.fromEntries(Object.entries(value).filter((entry) => typeof entry[1] === 'string'));
+}
+function metaTerminalAuth(method) {
+    if (!isRecord(method) || !isRecord(method._meta))
+        return undefined;
+    const entry = method._meta['terminal-auth'];
+    return isRecord(entry) ? entry : undefined;
+}
+/** The `args` a `_meta["terminal-auth"]` entry carries, for display where the top-level `args` is absent. */
+export function metaTerminalAuthArgs(method) {
+    return stringArray(metaTerminalAuth(method)?.args);
+}
+/**
+ * How to run this advertised method as a terminal login, or `undefined` when it is not one (spec
+ * D6: top-level `type: "terminal"`, or a `_meta["terminal-auth"]` object).
+ */
+export function terminalLoginSpecOf(method) {
+    if (!isRecord(method))
+        return undefined;
+    const meta = metaTerminalAuth(method);
+    if (meta && typeof meta.command === 'string' && meta.command.trim() !== '') {
+        return { kind: 'meta', command: meta.command, args: stringArray(meta.args) ?? [], env: stringRecord(meta.env) };
+    }
+    if (meta || method.type === 'terminal') {
+        return {
+            kind: 'append',
+            args: stringArray(method.args) ?? stringArray(meta?.args) ?? [],
+            env: { ...stringRecord(meta?.env), ...stringRecord(method.env) },
+        };
+    }
+    return undefined;
+}

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

@@ -0,0 +1,256 @@
+/**
+ * Local, network-free adapter fixtures for the build tests (spec 2026-10-11 §6): npm package
+ * tarballs, a fake `npm` that installs them with the **real** npm (offline), and binary archives.
+ *
+ * The adapter in every fixture keeps lazily loading its own modules for as long as it runs — a
+ * fresh `require` of `lib/mod-<n>.js` every few milliseconds, printed to stdout — which is exactly
+ * the access pattern a later install must never disturb.
+ */
+import { execFileSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { chmodSync, existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, readlinkSync, symlinkSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+export const LAZY_MODULES = 4;
+/** The adapter program: every 15 ms, drop and re-require one of its own modules and print what it says. */
+export function lazyAdapterSource(version, shebang = '#!/usr/bin/env node') {
+    return `${shebang}
+const path = require('node:path');
+let i = 0;
+setInterval(() => {
+  const file = path.join(__dirname, 'lib', 'mod-' + (i++ % ${LAZY_MODULES}) + '.js');
+  try {
+    delete require.cache[require.resolve(file)];
+    process.stdout.write(require(file) + '\\n');
+  } catch (error) {
+    process.stdout.write('LOAD-FAILED ' + error.message + '\\n');
+  }
+}, 15);
+process.stdout.write('started ${version}\\n');
+`;
+}
+function lazyModules(version) {
+    return Object.fromEntries(Array.from({ length: LAZY_MODULES }, (_, n) => [
+        `lib/mod-${n}.js`, `module.exports = ${JSON.stringify(`${version}:mod-${n}`)};\n`,
+    ]));
+}
+function writeTree(root, files) {
+    for (const [relative, content] of Object.entries(files)) {
+        const file = path.join(root, relative);
+        mkdirSync(path.dirname(file), { recursive: true });
+        writeFileSync(file, content);
+    }
+}
+/** An npm tarball (`package/` root, as `npm pack` writes) for `name@version` whose bin is the lazy adapter. */
+export function npmTarball(directory, name, version, options = {}) {
+    const tag = options.tag ? `-${options.tag}` : '';
+    const source = path.join(directory, `src-${name.replace(/[@/]/g, '_')}-${version}${tag}`, 'package');
+    writeTree(source, {
+        'package.json': JSON.stringify({ name, version, bin: { [name.split('/').pop()]: 'bin/adapter.js' }, ...(options.engines ? { engines: options.engines } : {}) }),
+        'bin/adapter.js': options.binSource ?? lazyAdapterSource(version).replace("path.join(__dirname, 'lib'", "path.join(__dirname, '..', 'lib'"),
+        ...lazyModules(version),
+    });
+    const tarball = path.join(directory, `${name.replace(/[@/]/g, '_')}-${version}${tag}.tgz`);
+    execFileSync('tar', ['-czf', tarball, '-C', path.dirname(source), 'package']);
+    return tarball;
+}
+/** A `.tar.gz` binary archive: `./adapter` (an executable script) and its lazily loaded `lib/`. */
+export function binaryArchive(directory, version) {
+    const source = path.join(directory, `bin-src-${version}`);
+    writeTree(source, { adapter: lazyAdapterSource(version, `#!${process.execPath}`), ...lazyModules(version) });
+    chmodSync(path.join(source, 'adapter'), 0o755);
+    const archive = path.join(directory, `bin-${version}.tar.gz`);
+    execFileSync('tar', ['-czf', archive, '-C', source, '.']);
+    return readFileSync(archive);
+}
+/** The real npm this machine has, run offline by the fake below. */
+export function realNpm() {
+    const sibling = path.join(path.dirname(process.execPath), 'npm');
+    return existsSync(sibling) ? sibling : 'npm';
+}
+/**
+ * A stand-in `npm` that only understands `install --prefix <dir> … <spec>`: records every spec it is
+ * asked for, then either fails the way npm would or installs the mapped local tarball with the real
+ * npm, `--offline` — never the network.
+ */
+export function fakeNpm(directory, options) {
+    mkdirSync(directory, { recursive: true });
+    const log = path.join(directory, 'calls.txt');
+    const pidLog = path.join(directory, 'pids.txt');
+    const config = path.join(directory, 'fake-npm.json');
+    writeFileSync(config, JSON.stringify({ ...options, realNpm: realNpm(), log, pidLog, cache: path.join(directory, 'npm-cache') }));
+    const script = path.join(directory, 'npm');
+    writeFileSync(script, `#!${process.execPath}
+const fs = require('node:fs'); const path = require('node:path'); const { spawnSync } = require('node:child_process');
+const cfg = JSON.parse(fs.readFileSync(${JSON.stringify(config)}, 'utf8'));
+const argv = process.argv.slice(2);
+if (argv[0] === 'view') {
+  // \`npm view <name> version --json\`: what \`latest\` names, from the same map an unpinned install uses.
+  fs.appendFileSync(cfg.log, 'view ' + argv[1] + '\\n');
+  const latest = cfg.latest && cfg.latest[argv[1]];
+  if (!latest || cfg.noView) { process.stderr.write('npm error code E404\\n'); process.exit(1); }
+  process.stdout.write(JSON.stringify(latest.slice(latest.lastIndexOf('@') + 1)) + '\\n');
+  process.exit(0);
+}
+const spec = argv[argv.length - 1];
+const prefix = argv[argv.indexOf('--prefix') + 1];
+fs.appendFileSync(cfg.log, spec + '\\n');
+const sleep = (ms) => Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+if (cfg.delayMs) sleep(cfg.delayMs);
+if ((cfg.etarget || []).includes(spec)) {
+  process.stderr.write('npm error code ETARGET\\nnpm error notarget No matching version found for ' + spec + '.\\n');
+  process.exit(1);
+}
+if (cfg.fail && cfg.fail[spec] !== undefined) { process.stderr.write(cfg.fail[spec]); process.exit(1); }
+if ((cfg.hang || []).includes(spec)) {
+  fs.appendFileSync(cfg.pidLog, process.pid + '\\n');
+  const name = spec.slice(0, spec.lastIndexOf('@') > 0 ? spec.lastIndexOf('@') : spec.length);
+  const dir = path.join(prefix, 'node_modules', name);
+  fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(path.join(dir, 'package.json'), JSON.stringify({ name, version: spec.split('@').pop() }));
+  for (;;) sleep(1000);
+}
+const pinned = cfg.tarballs[spec] ? spec : cfg.latest && cfg.latest[spec];
+const tarball = pinned && cfg.tarballs[pinned];
+if (!tarball) { process.stderr.write('npm error code E404\\nnpm error 404 Not Found - ' + spec + '\\n'); process.exit(1); }
+const real = spawnSync(cfg.realNpm, [...argv.slice(0, -1), '--offline', tarball], {
+  stdio: 'inherit', env: { ...process.env, npm_config_cache: cfg.cache },
+});
+process.exit(real.status === null ? 1 : real.status);
+`);
+    chmodSync(script, 0o755);
+    const lines = (file) => (existsSync(file) ? readFileSync(file, 'utf8').split('\n').filter(Boolean) : []);
+    return { command: script, calls: () => lines(log), pids: () => lines(pidLog).map(Number) };
+}
+/** Every file, directory and symlink under `root` with its content hash / link target — byte-identity of a tree. */
+export function treeDigest(root) {
+    const out = {};
+    const walk = (relative) => {
+        const full = path.join(root, relative);
+        const stat = lstatSync(full);
+        if (stat.isSymbolicLink())
+            out[relative] = `link:${readlinkSync(full)}`;
+        else if (stat.isDirectory()) {
+            out[relative || '.'] = `dir:${stat.mode.toString(8)}`;
+            for (const name of readdirSync(full).sort())
+                walk(relative ? path.join(relative, name) : name);
+        }
+        else
+            out[relative] = `file:${stat.mode.toString(8)}:${createHash('sha256').update(readFileSync(full)).digest('hex')}`;
+    };
+    walk('');
+    return out;
+}
+/**
+ * A `RunUv` that never spawns anything: `tool install` lays out what `uv tool install` really lays out
+ * (measured, `uvxInstall.ts`) under the `UV_TOOL_DIR`/`UV_TOOL_BIN_DIR` it is given — including the
+ * absolute paths, so a renamed tree really breaks — and `tool list --show-paths` reports it. Each
+ * executable is a shell script that prints `<name> <version> <exe> <args>`, and with `--wait` stays up.
+ */
+export function fakeUv(options) {
+    const calls = [];
+    const run = async (args, _timeoutMs, env = {}) => {
+        calls.push({ args: [...args], env: { ...env } });
+        const toolDir = env.UV_TOOL_DIR;
+        const binDir = env.UV_TOOL_BIN_DIR;
+        if (!toolDir || !binDir)
+            return { ok: false, stdout: '', error: 'fake uv refuses to touch the user tool dir' };
+        if (args[0] === 'tool' && args[1] === 'list') {
+            if (!existsSync(toolDir))
+                return { ok: true, stdout: 'No tools installed\n' };
+            let out = '';
+            for (const name of readdirSync(toolDir).sort()) {
+                const receipt = path.join(toolDir, name, 'receipt.json');
+                if (!existsSync(receipt))
+                    continue;
+                const { version, executables } = JSON.parse(readFileSync(receipt, 'utf8'));
+                out += `${name} v${version} (${path.join(toolDir, name)})\n`;
+                for (const exe of executables)
+                    out += `- ${exe} (${path.join(binDir, exe)})\n`;
+            }
+            return { ok: true, stdout: out || 'No tools installed\n' };
+        }
+        if (args[0] !== 'tool' || args[1] !== 'install')
+            return { ok: false, stdout: '', error: `fake uv: unexpected ${args.join(' ')}` };
+        const requirement = args[args.length - 1];
+        const pinned = requirement.includes('==') ? requirement : options.latest?.[requirement];
+        const executables = pinned ? options.packages[pinned] : undefined;
+        if (!pinned || !executables)
+            return { ok: false, stdout: '', error: `uv: no solution for ${requirement}` };
+        const [name, version] = pinned.split('==');
+        const venv = path.join(toolDir, name);
+        mkdirSync(path.join(venv, 'bin'), { recursive: true });
+        mkdirSync(binDir, { recursive: true });
+        writeFileSync(path.join(venv, 'VERSION'), version);
+        if (options.hang?.includes(requirement))
+            return new Promise(() => { });
+        if (options.fail?.[requirement] !== undefined)
+            return { ok: false, stdout: '', error: options.fail[requirement] };
+        for (const exe of executables) {
+            const script = path.join(venv, 'bin', exe);
+            // Like a real console script: an absolute path to its own environment baked in.
+            writeFileSync(script, `#!/bin/sh\necho "${name} $(cat '${path.join(venv, 'VERSION')}') ${exe} $*"\n[ "$1" = --wait ] && exec sleep 30\nexit 0\n`);
+            chmodSync(script, 0o755);
+            symlinkSync(script, path.join(binDir, exe));
+        }
+        writeFileSync(path.join(venv, 'receipt.json'), JSON.stringify({ version, executables }));
+        return { ok: true, stdout: '' };
+    };
+    return { run, calls };
+}
+/**
+ * A pure-Python wheel `name-version-py3-none-any.whl` in `directory`, written with the machine's
+ * `python3` (stdlib `zipfile`, no network). Its console script `name` prints `<name> <version>
+ * <sys.executable>`, and with `--wait` keeps re-importing its own module (printing what it says) — the
+ * lazy-loading pattern a later install must not disturb.
+ */
+export function pythonWheel(python, directory, name, version) {
+    mkdirSync(directory, { recursive: true });
+    const builder = path.join(directory, `make-wheel-${version}.py`);
+    writeFileSync(builder, String.raw `
+import base64, hashlib, sys, zipfile
+name, version, out = sys.argv[1], sys.argv[2], sys.argv[3]
+mod = name.replace('-', '_')
+files = {
+    mod + '/__init__.py': (
+        "import importlib, sys, time\n"
+        "def main():\n"
+        "    print('%s', '%s', sys.executable, flush=True)\n"
+        "    if '--wait' in sys.argv:\n"
+        "        from . import lazy\n"
+        "        for _ in range(3000):\n"
+        "            importlib.reload(lazy)\n"
+        "            print(lazy.VALUE, flush=True)\n"
+        "            time.sleep(0.02)\n"
+    ) % (name, version),
+    mod + '/lazy.py': "VALUE = '%s:lazy'\n" % version,
+    '%s-%s.dist-info/METADATA' % (mod, version): 'Metadata-Version: 2.1\nName: %s\nVersion: %s\n' % (name, version),
+    '%s-%s.dist-info/WHEEL' % (mod, version): 'Wheel-Version: 1.0\nGenerator: axom-test\nRoot-Is-Purelib: true\nTag: py3-none-any\n',
+    '%s-%s.dist-info/entry_points.txt' % (mod, version): '[console_scripts]\n%s = %s:main\n' % (name, mod),
+}
+record = '%s-%s.dist-info/RECORD' % (mod, version)
+lines = []
+for path, text in files.items():
+    digest = base64.urlsafe_b64encode(hashlib.sha256(text.encode()).digest()).rstrip(b'=').decode()
+    lines.append('%s,sha256=%s,%d' % (path, digest, len(text.encode())))
+lines.append(record + ',,')
+files[record] = '\n'.join(lines) + '\n'
+wheel = '%s/%s-%s-py3-none-any.whl' % (out, mod, version)
+with zipfile.ZipFile(wheel, 'w') as archive:
+    for path, text in files.items():
+        archive.writestr(path, text)
+print(wheel)
+`);
+    return execFileSync(python, ['-I', builder, name, version, directory], { encoding: 'utf8' }).trim();
+}
+/**
+ * What `npx --yes <name>@<version>` leaves in npm's cache: `<npmCache>/_npx/<hash>/node_modules/…`
+ * (with npm's hidden lockfile), made by the real npm, offline, from a local tarball.
+ */
+export function npxCacheEntry(npmCache, hash, tarball) {
+    const prefix = path.join(npmCache, '_npx', hash);
+    mkdirSync(prefix, { recursive: true });
+    execFileSync(realNpm(), ['install', '--prefix', prefix, '--no-save', '--no-audit', '--no-fund', '--offline', tarball], {
+        env: { ...process.env, npm_config_cache: path.join(npmCache, '..', `npx-fixture-cache-${hash}`) }, stdio: 'ignore',
+    });
+    return path.join(prefix, 'node_modules');
+}

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

@@ -0,0 +1,106 @@
+/**
+ * One daemon life in its own process (Task 21's kill -9 test, Task 23's fault gate): AcpAgents + AgentSessionManager over keeper-acp,
+ * the way `runDaemon` wires them — adoption at boot, then the server's frames, one JSON per stdin line, handed to the manager in order.
+ * Every frame it sends is appended to `framesOut` (one JSON line each): the server's view of what this daemon sent. It never exits on
+ * its own: the test kills it with SIGKILL — `{cmd:'offer'}` appends the reconnect offer it would send now — or sends `{cmd:'forceStop'}`, a force update's
+ * `TaskRegistry.stopAll()` followed by the restart path's `detachDurableSessions()` (keeper-hosted sessions detach), after which it exits 0.
+ * `{cmd:'forceBegin'}` is only the start of a force update (`stopAll()`, before the download): the daemon keeps running.
+ *
+ * Fault seams (`faults`, Task 23), both hang forever so a SIGKILL lands exactly there:
+ * - `holdOutboxEvent` / `holdOutboxText`: `acp.outbox.append` of entries holding a frame with this `eventName` / whose JSON contains
+ *   this text — the record's commands are already in raw (the driver writes before it records), its frames never reach the outbox
+ *   ("written into keeper, not recorded in the outbox");
+ * - `holdNoteType`: `acp.note` of this type — the daemon took the server's frame, nothing reached keeper-acp.
+ * Reaching a seam writes `<configDir>/held-<seam>`.
+ *
+ * Run with vite-node: `vite-node daemonLife.ts <config JSON>`; config `{configDir, distDir, framesOut, faults?}`.
+ */
+import { appendFileSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { createInterface } from 'node:readline';
+import { AcpKeeperClient } from '../../keepers/acp/client.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';
+const never = new Promise(() => { });
+/** The transport with the configured seams: every other call goes straight through. */
+function withFaults(inner, configDir, faults) {
+    if (!faults.holdOutboxEvent && !faults.holdOutboxText && !faults.holdNoteType)
+        return inner;
+    return new Proxy(inner, {
+        get(target, prop) {
+            const value = target[prop];
+            if (prop === 'appendOutbox' && (faults.holdOutboxEvent || faults.holdOutboxText)) {
+                return async (...args) => {
+                    if (args[1].some((entry) => entry.frame.eventName === faults.holdOutboxEvent) ||
+                        (faults.holdOutboxText !== undefined && JSON.stringify(args[1]).includes(faults.holdOutboxText))) {
+                        writeFileSync(path.join(configDir, 'held-outbox'), JSON.stringify(args[1]));
+                        return never;
+                    }
+                    return target.appendOutbox(...args);
+                };
+            }
+            if (prop === 'note' && faults.holdNoteType) {
+                return async (...args) => {
+                    if (args[1].type === faults.holdNoteType) {
+                        writeFileSync(path.join(configDir, 'held-note'), JSON.stringify(args[1]));
+                        return never;
+                    }
+                    return target.note(...args);
+                };
+            }
+            return typeof value === 'function' ? value.bind(target) : value;
+        },
+    });
+}
+async function main() {
+    const config = JSON.parse(process.argv[process.argv.length - 1]);
+    const launcher = new KeeperLauncher({ configDir: config.configDir, workstationId: 'ws-t21', server: 'http://test.invalid', distDir: config.distDir,
+        useSystemd: false, startTimeoutMs: 20_000, umask: 0o022 });
+    const keeper = withFaults(new KeeperTransport(new AcpKeeperClient({ launcher })), config.configDir, config.faults ?? {});
+    const acp = new AcpAgents({ cacheDir: config.configDir, registry: { load: async () => [] }, transports: { keeper },
+        keeperGenerations: keeperGenerations({ launcher, current: keeper, log: () => { } }) });
+    const tasks = new TaskRegistry();
+    const manager = new AgentSessionManager(acp, null, path.join(config.configDir, 'agents'), tasks);
+    manager.bindSend((frame) => appendFileSync(config.framesOut, `${JSON.stringify(frame)}\n`), AGENT_WIRE_VERSION);
+    await manager.adoptSessions();
+    // Frames in wire order, handled without waiting for each other (as the agent channel's dispatcher does).
+    for await (const line of createInterface({ input: process.stdin, crlfDelay: Infinity })) {
+        if (!line.trim())
+            continue;
+        const message = JSON.parse(line);
+        if ('cmd' in message) {
+            if (message.cmd === 'offer') {
+                // What this daemon would put in a connection's reconnect offer now (`resumeOfferSessions`), as a frame.
+                appendFileSync(config.framesOut, `${JSON.stringify({ t: 'agent_resume_offer', sessions: await manager.resumeOfferSessions() })}\n`);
+                continue;
+            }
+            if (message.cmd === 'forceBegin') {
+                // A forced update starts (UpdateCoordinator: `stopAll()` before DOWNLOADING); this daemon keeps running while it downloads.
+                await tasks.stopAll();
+                appendFileSync(config.framesOut, `${JSON.stringify({ t: '__force_begun__' })}\n`);
+                continue;
+            }
+            if (message.cmd === 'forceStop') {
+                // The whole forced update as the sessions see it: `stopAll()`, then the restart path's detach right before the hand-off.
+                await tasks.stopAll();
+                await tasks.detachDurableSessions();
+                appendFileSync(config.framesOut, `${JSON.stringify({ t: '__force_stopped__' })}\n`);
+                process.exit(0);
+            }
+            continue;
+        }
+        void manager.handleFrame(message).catch((error) => {
+            process.stderr.write(`handling ${message.t} failed: ${error instanceof Error ? error.stack ?? error.message : String(error)}\n`);
+        });
+    }
+    setInterval(() => { }, 1_000);
+}
+main().catch((error) => {
+    process.stderr.write(`daemon life failed: ${error instanceof Error ? error.stack ?? error.message : String(error)}\n`);
+    process.exit(1);
+});