@platless/axom-cli 0.1.0 → 0.5.9

package/dist/workstation/acp/terminalLogin.js

@@ -0,0 +1,171 @@
+/**
+ * Hosting an ACP `terminal` sign-in on the workstation, so the reader gets a link instead of an
+ * instruction to go find a terminal (spec 2026-09-24 D6, D7, D9).
+ *
+ * ## Which command
+ *
+ * `AuthMethodTerminal` (`@agentclientprotocol/sdk` 1.4.0, `types.gen.d.ts:2237`) says its `args`
+ * are appended to "the configured agent invocation". That is wrong for at least one agent in the
+ * wild: measured, appending `login` to a binary agent's `acp` launch fails with "unexpected extra
+ * argument", while the same agent's `_meta["terminal-auth"]` names the invocation that works. So a
+ * `_meta["terminal-auth"]` that carries a `command` is taken as the whole invocation, and only
+ * without one does the standard append rule apply. That key appears nowhere in the SDK; it is a
+ * convention agents use, and it is matched by **shape**, never by which agent sent it.
+ *
+ * Trusting the agent's own command adds nothing it could not already do: it is a program this
+ * daemon already runs, as the same user, on the same machine. Nothing here composes, quotes or
+ * guesses a command, and nothing goes through a shell.
+ *
+ * ## How it runs
+ *
+ * Pipes, not a terminal: this client cannot reproduce an interactive terminal, which is also why it
+ * does not declare `clientCapabilities.auth.terminal` (`:4399`). What it can host is the common
+ * shape — print a link, wait for the reader to approve it somewhere, exit 0 — and that is every
+ * device-code login. `PYTHONUNBUFFERED=1` is set because a Python-built CLI block-buffers a pipe
+ * and was measured holding its link back for over 40 seconds; it names no agent and is inert for
+ * everything else.
+ *
+ * Every exit ends the **process group**, not just the child. A single-file bundle runs its real work
+ * in a grandchild; killing only the bundle's bootstrap was measured leaving that grandchild alive
+ * for 23 minutes.
+ */
+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 {
+}
+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;
+/**
+ * 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 = 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 };
+}
+function signalGroup(child, signal) {
+    if (child.pid === undefined)
+        return;
+    try {
+        // A negative pid addresses the whole group `detached: true` created. Windows has no process
+        // groups; there this reaches the direct child only.
+        process.kill(process.platform === 'win32' ? child.pid : -child.pid, signal);
+    }
+    catch {
+        // Best effort, and it must stay that way: this runs inside child-process event handlers, where
+        // a throw is an uncaught exception that takes the whole daemon down. ESRCH (the group is already
+        // gone) is the common case; anything else (EPERM) still leaves nothing this code could do.
+    }
+}
+/**
+ * Run one terminal sign-in to completion. Resolves on exit 0; rejects with
+ * {@link TerminalLoginFailedError} (non-zero exit, signal, or spawn failure — quoting the process's
+ * own last lines), {@link TerminalLoginTimeoutError} or {@link TerminalLoginCancelledError}. Every
+ * exit ends the process group first.
+ */
+export function runTerminalLogin(invocation, options) {
+    return new Promise((resolve, reject) => {
+        const killGraceMs = options.killGraceMs ?? DEFAULT_KILL_GRACE_MS;
+        if (options.signal?.aborted) {
+            reject(new TerminalLoginCancelledError('Sign-in was cancelled before it started.'));
+            return;
+        }
+        const child = spawn(invocation.command, invocation.args, {
+            stdio: ['ignore', 'pipe', 'pipe'],
+            detached: process.platform !== 'win32',
+            env: { ...process.env, ...invocation.env, PYTHONUNBUFFERED: '1' },
+        });
+        const scan = createAuthUrlScanner();
+        const presented = new Set();
+        const tail = [];
+        let ending;
+        let killTimer;
+        const onLine = (raw) => {
+            const line = raw.replace(/\r$/, '');
+            if (line.trim() !== '') {
+                // eslint-disable-next-line no-control-regex -- stripping the literal ESC (0x1b) is the point
+                tail.push(line.replace(/\x1b\[[0-9;]*[A-Za-z]/g, ''));
+                if (tail.length > FAILURE_TAIL_LINES)
+                    tail.shift();
+            }
+            const url = scan(line);
+            if (url && !presented.has(url)) {
+                presented.add(url);
+                options.present?.(`terminal-auth-url-${randomUUID()}`, url);
+            }
+        };
+        for (const stream of [child.stdout, child.stderr]) {
+            let buffer = '';
+            stream?.setEncoding('utf8');
+            stream?.on('data', (chunk) => {
+                buffer += chunk;
+                const lines = buffer.split('\n');
+                buffer = lines.pop() ?? '';
+                lines.forEach(onLine);
+            });
+            stream?.on('end', () => { if (buffer !== '')
+                onLine(buffer); buffer = ''; });
+        }
+        const end = (reason) => {
+            if (ending)
+                return;
+            ending = reason;
+            signalGroup(child, 'SIGTERM');
+            killTimer = setTimeout(() => signalGroup(child, 'SIGKILL'), killGraceMs);
+            killTimer.unref();
+        };
+        const deadline = setTimeout(() => end(new TerminalLoginTimeoutError(`Sign-in did not finish within ${Math.round(options.deadlineMs / 1000)} seconds.`)), options.deadlineMs);
+        const onAbort = () => end(new TerminalLoginCancelledError('Sign-in was cancelled.'));
+        options.signal?.addEventListener('abort', onAbort, { once: true });
+        const settle = (outcome) => {
+            clearTimeout(deadline);
+            if (killTimer)
+                clearTimeout(killTimer);
+            options.signal?.removeEventListener('abort', onAbort);
+            if (outcome)
+                reject(outcome);
+            else
+                resolve();
+        };
+        child.once('error', (error) => {
+            settle(new TerminalLoginFailedError(`Could not start the sign-in command: ${error.message}`));
+        });
+        child.once('exit', () => {
+            // Whatever the login left behind in its group must not outlive it — see the file comment.
+            signalGroup(child, 'SIGKILL');
+        });
+        child.once('close', (code, signal) => {
+            if (ending)
+                return settle(ending);
+            if (code === 0)
+                return settle(undefined);
+            const how = code !== null ? `exited with code ${code}` : `was ended by ${signal}`;
+            const said = tail.length > 0 ? `: ${tail.join('\n')}` : '';
+            return settle(new TerminalLoginFailedError(`The sign-in command ${how}${said}`));
+        });
+    });
+}

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);
+});