@platless/axom-cli 0.1.0 → 0.5.9

package/dist/workstation/acp/registry/launch.js

@@ -1,128 +1,70 @@
+import { existsSync } from 'node:fs';
+import { homedir } from 'node:os';
 import path from 'node:path';
-import { binaryTargetFor, installedBinaryVersion, platformTriple } from '../binaryInstall.js';
-import { npmPackageName } from '../installProbe.js';
-import { uvPackageName, uvToolEntrypoint, uvToolEntrypointFrom } from '../uvxInstall.js';
-export class UnsupportedDistributionError extends Error {
-}
-/** `npx --yes <specifier> [dist args]`,两个调用方共用的一处构造:钉版本的和不钉版本的。 */
-function npxLaunch(specifier, npx, platform) {
-    return {
-        command: platform === 'win32' ? 'npx.cmd' : 'npx',
-        // `--yes` 让首次拉包不停在交互确认上。
-        args: ['--yes', specifier, ...(npx.args ?? [])],
-        env: { ...(npx.env ?? {}) },
-    };
-}
+import { fileURLToPath } from 'node:url';
+import { nativeExtensionFor } from '../patchAssets.js';
+import { verifyPatchedFiles } from '../managedPatches.js';
+import { AdapterNotInstalledError, inside, labelFor } from '../builds/model.js';
+import { assertBuildRunsOn } from '../builds/nodeGate.js';
 /**
- * registry 只给原料,不给命令行 —— 没有 `command` 字段,启动方式要从 `distribution` 推导。
- *
- * 三种分发方式现在都支持:`npx`/`uvx` 走各自安装侧维护的缓存/工具目录(见 `installProbe.ts`、
- * `uvxInstall.ts`),`binary` 走 `binaryInstall.ts`(Task 8)—— 按六个平台三元组挑一个目标、
- * 从 `adapterRoot` 找已经装好的版本。三条路径共同的规则是:**从不猜**,找不到就抛
- * `UnsupportedDistributionError`,理由写清楚是"这个平台没有发行版"还是"这台机器还没装",而不是
- * 笼统的一句"不支持"。
+ * `env` with `prefix` first on its `PATH` — unless `PATH` already starts with exactly that prefix (the
+ * spec's own env survived the merge), so applying it twice is harmless.
  */
-export async function resolveLaunch(agent, platform, 
-// 六个平台三元组里的一半;只有 binary 分支用到。
-arch, 
-// `<workstation config dir>/acp-adapters` —— `binaryInstall.ts` 解包落地的根目录,只有 binary
-// 分支用到。npx 走 npm 自己的 `_npx` 缓存,uvx 走 `uv tool dir`,都不需要这个根目录。
-adapterRoot, 
-// 仅测试注入:真实调用永远走 `uvxInstall.ts` 的默认 `uv` 实现。签名上留成可选,两个真实调用点
-// (`acpAgents.ts`)不用跟着改。下面的 `uvTools` 给出时,这个参数被忽略 —— 见它的说明。
-run, 
-// 已经读好的 `uv tool list` 快照(`listUvTools`)。给了就直接查表,不再自己起 `uv` 子进程 ——
-// `AcpAgents.roster` 为整份 39 条 registry 只读一次,把结果传进这里,而不是让每个 uvx agent
-// 在这条路径上各自再起一次 `uv`。真正的启动路径(`resolveLaunchFor`)不传这个参数,继续用
-// `run`/默认实现现读一次,这里的现读对它而言正是期望行为。
-//
-// 这个函数整体是 async 的唯一原因:`uv` 现在是非阻塞调用(`RunUv` 返回 `Promise`,见
-// `uvxInstall.ts`),没有预取快照时这里必须 `await` 它。给了 `uvTools` 的那条路径
-// (`AcpAgents.resolvable`)完全同步、不等待任何东西,包成 `async` 只是让两条路径共用同一个
-// 签名——`Promise.resolve` 包一层同步返回值的开销,跟每次 roster 扫描本来就要付的成本比可以
-// 忽略不计。
-uvTools) {
-    const { npx, uvx, binary } = agent.distribution;
-    // specifier 里已内联精确版本,不会追 latest —— 除非 registry 钉的那个版本 npm 根本没有,
-    // 见 {@link unpinnedFallbackFor}。
-    if (npx)
-        return npxLaunch(npx.package, npx, platform);
-    if (uvx) {
-        // 不走 `uvx <pkg>`:那条路用 uv 自己的临时环境缓存,目录名带哈希,"装没装"读不可靠。
-        // 改成我们自己 `uv tool install`、启动时直接跑装出来的入口点 —— 与 binary 一样,
-        // 落到"我们装的、我们知道装在哪"这一条统一规则上。
-        const outcome = uvTools
-            ? uvToolEntrypointFrom(uvPackageName(uvx.package), uvTools)
-            : await uvToolEntrypoint(uvPackageName(uvx.package), run);
-        if (outcome.ok) {
-            return { command: outcome.path, args: [...(uvx.args ?? [])], env: { ...(uvx.env ?? {}) } };
-        }
-        if (outcome.reason === 'ambiguous') {
-            // 装了,但不敢猜:多个可执行文件里没有一个跟包名同名,uv 的列出顺序又不是文档化契约——
-            // 静默启动错的那个,换来的是一次没人能追回这里的 ACP 握手挂死或失败,比拒绝启动更糟。
-            throw new UnsupportedDistributionError(`Agent '${agent.id}' is distributed through uvx and its tool is installed, but this build ` +
-                `cannot tell which of its executables is the ACP adapter: ${outcome.candidates.join(', ')}.`);
-        }
-        throw new UnsupportedDistributionError(`Agent '${agent.id}' is distributed through uvx but its tool is not installed on this machine.`);
-    }
-    if (binary) {
-        // 六个平台三元组里挑一个;`windows-aarch64` 在实测的 registry 快照上只有 9/18 的覆盖,
-        // "这个平台没有发行版"是常态,不是异常——`installBinary`（`binaryInstall.ts`）在下载前就
-        // 用同一个函数做同一个判断,这里只是启动路径上再问一次同一件事,答案必须一致。
-        const triple = platformTriple(platform, arch);
-        const target = triple ? binaryTargetFor(agent, triple) : undefined;
-        if (!target) {
-            throw new UnsupportedDistributionError(`Agent '${agent.id}' publishes no archive for ${triple ?? `${platform}-${arch}`}.`);
-        }
-        // 装没装是这台机器磁盘上的事实,不是 registry 条目的属性 —— 跟 npx/uvx 分支一样,没装就说
-        // "没装",不是"不支持"。
-        //
-        // `agent.version` 必须传:同一个 agent 的多个版本可以并存(`<root>/<agent>/<version>/`,
-        // 就是为此设计的),`pickInstalledVersion` 的规则是"钉的版本在就取它,否则取最大"。
-        // `AcpAgents.roster` 报告 `adapterVersion` 时传了它,这里不传就会在两个版本并存时报告一个、
-        // 启动另一个 —— 名册说 0.75.0、跑起来是 0.74.0,而且没有任何一处会说出这件事。
-        const version = installedBinaryVersion(agent.id, adapterRoot, agent.version);
-        if (!version) {
-            throw new UnsupportedDistributionError(`Agent '${agent.id}' has no installed adapter on this machine.`);
-        }
-        return {
-            command: path.join(adapterRoot, agent.id, version, target.cmd),
-            args: [...(target.args ?? [])],
-            env: { ...(target.env ?? {}) },
-        };
-    }
-    throw new UnsupportedDistributionError(`Agent '${agent.id}' declares no launchable distribution.`);
+export function withPathPrefix(env, prefix) {
+    if (!prefix?.length)
+        return env;
+    const head = prefix.join(path.delimiter);
+    const current = env.PATH ?? '';
+    if (current === head || current.startsWith(head + path.delimiter))
+        return env;
+    return { ...env, PATH: current ? head + path.delimiter + current : head };
 }
 /**
- * 同一个 agent,但把 registry 钉的版本从 specifier 上剥掉 —— 上游钉了一个 npm 上并不存在的版本时,
- * 唯一还能把这个 agent 救回来的启动方式。
- *
- * ## 为什么需要它
- *
- * 2026-09-04 实测:registry 的 `codex-acp` 条目声明
- * `@agentclientprotocol/codex-acp@1.10.0`,而 npm 上这个包的版本停在 `1.9.0`
- * (`dist-tags.latest` 也是 `1.9.0`)。于是每一次 codex 启动都是 `npm error code ETARGET`,npx 退出,
- * 子进程死掉 —— 两台真实工作站同时失去了 codex。这是上游的缺陷;这里能做的是不让它把 agent 砖掉。
- *
- * ## 代价,以及为什么仍然值得
+ * The spawn spec for an installed build — **no npx, no registry read, no network**: the build's own
+ * entry, run with a fixed absolute Node (`nodePath`, the daemon's `process.execPath`) when it is
+ * JavaScript, or executed directly when it is native.
  *
- * 不钉版本装回来的,是 npm 此刻叫 `latest` 的那一个 —— **registry 从来没有指定过它**。它可能比钉的
- * 版本新(常见,上游多半正是发版发歪了),也可能是一个协议行为不同、甚至跟这个客户端谈不拢
- * `initialize` 的版本。所以这条路只在 ETARGET 上走(见 `acpClient.ts` 的 `isMissingPackageVersion`),
- * 只走一次,而且两条 warn 日志会把「跑的不是 registry 要的那个版本」说穿。
- *
- * ## 三种「没有回退可言」的情况,都返回 undefined
+ * `launchEnv` is the running CLI's catalog/runtime.json launch environment for this agent, evaluated
+ * at the registry version the build was installed from. It goes underneath the build's own
+ * (distribution-declared) env, the same order `registry/catalog.ts`'s `withLaunchEnv` always used.
+ * A patched build's files are re-hashed first (the tamper check that used to run on every launch), and
+ * a JavaScript build must pass the Node gate (`builds/nodeGate.ts`) against `nodePath`.
+ */
+/**
+ * Expand a leading `~` / `~/` in every env value against the user's home directory.
  *
- * 没有 npx 分发(`uvx` 走的是 uv 自己的缓存,`binary` 这个版本压根不支持)、specifier 本来就不带版本
- * (剥无可剥,npm 已经在追 latest 了)。剥版本用 `npmPackageName`,它按最后一个 `@` 切,所以
- * `@scope/name@1.10.0` → `@scope/name`,而前导的 `@` 不会被当成版本分隔符。
+ * Why here and nowhere else: the CLI-owned `launchEnv` (catalog / runtime.json) ships as a static
+ * file, so it cannot spell the per-machine absolute path some consumers need — Claude's
+ * `CLAUDE_SECURESTORAGE_CONFIG_DIR` is used as a literal path and never expands `~` itself. And the
+ * final merged env is the only point that covers both sources: a build's own distribution env
+ * overwrites same-key `launchEnv` values, so expanding the `launchEnv` alone would let an unexpanded
+ * build value win. Only a leading `~` is touched; a `~` elsewhere in a value is data, not a path.
  */
-export function unpinnedFallbackFor(agent, platform) {
-    const npx = agent.distribution.npx;
-    if (!npx)
-        return undefined;
-    const unpinned = npmPackageName(npx.package);
-    if (unpinned === npx.package)
-        return undefined;
-    return { pinned: npx.package, unpinned, launch: npxLaunch(unpinned, npx, platform) };
+function expandHomeInEnv(env) {
+    const home = homedir();
+    return Object.fromEntries(Object.entries(env).map(([key, value]) => [key, value === '~' ? home : value.startsWith('~/') ? path.join(home, value.slice(2)) : value]));
+}
+export async function launchForBuild(build, root, options) {
+    const dir = inside(root, build.dir);
+    const entry = inside(dir, build.launch.entry);
+    if (build.kind === 'npm-patched' && build.package && build.patchedFiles) {
+        await verifyPatchedFiles(inside(path.join(dir, 'node_modules'), build.package), build.patchedFiles);
+    }
+    if (!existsSync(entry))
+        throw new AdapterNotInstalledError(build.agentId, `build ${build.buildId} is missing its executable`);
+    // Every build launch passes the Node gate — patched and pristine alike, whatever the args look like.
+    await assertBuildRunsOn(build, root, options.nodePath);
+    const env = expandHomeInEnv({ ...options.launchEnv, ...build.launch.env });
+    const pathPrefix = build.launch.pathDirs?.map((relative) => inside(dir, relative));
+    if (pathPrefix?.length) {
+        env.PATH = pathPrefix.join(path.delimiter) + path.delimiter + (env.PATH ?? options.basePath ?? process.env.PATH ?? '');
+    }
+    const extra = pathPrefix?.length ? { pathPrefix } : {};
+    const extension = build.launch.runtime !== 'node' ? nativeExtensionFor(build.agentId, build.version) : undefined;
+    if (extension) {
+        return { command: options.nodePath, args: [fileURLToPath(extension), entry, ...build.launch.args], env, label: labelFor(build), ...extra };
+    }
+    return build.launch.runtime === 'node'
+        ? { command: options.nodePath, args: [entry, ...build.launch.args], env, label: labelFor(build), ...extra }
+        : { command: entry, args: [...build.launch.args], env, label: labelFor(build), ...extra };
 }

package/dist/workstation/acp/sessionUpdateMapper.js

@@ -1,3 +1,7 @@
+import { codexActivityRaw } from './activityReporting.js';
+export function newMapperScopeData() {
+    return { byId: {}, lastReportedQueueDepth: 0 };
+}
 /**
  * One session's memory, and the reason this file is no longer stateless: **what this session has
  * already been told**, for the two branches that cannot answer a frame from the frame alone.
@@ -30,7 +34,25 @@
  * already (every call's `rawInput`/`rawOutput` is journaled), so there is no eviction here.
  */
 export class SessionMapperState {
-    byId = new Map();
+    onActivityReported;
+    data;
+    /**
+     * Where an agent-reported activity-state push (today, only `codexActivityRaw`'s extraction of
+     * `session_info_update._meta.codex.threadStatus`) actually goes once {@link reportActivity} is
+     * called — `agentSessions.ts`'s job, not this file's: this module stays "zero IO" (see the file
+     * doc comment) by taking the effect as a constructor dependency rather than reaching for a
+     * socket itself.
+     *
+     * Defaults to a no-op so every existing `new SessionMapperState()` — the tests, `adoption.ts`'s
+     * replay path, which has no live connection to report anything on — keeps compiling and keeps
+     * doing nothing, exactly as it always has.
+     */
+    constructor(onActivityReported = () => { }, 
+    /** The memory itself, mutated in place — the processor passes the checkpointed copy it owns. */
+    data = newMapperScopeData()) {
+        this.onActivityReported = onActivityReported;
+        this.data = data;
+    }
     /**
      * The agent queue depth this session has already reported to the server.
      *
@@ -39,7 +61,9 @@ export class SessionMapperState {
      * reader already assumes. Seeding it to `-1` (or `null`) would let the very first frame through,
      * which on `pi-acp` is `startTurn`'s, i.e. the defect this field exists to prevent.
      */
-    lastReportedQueueDepth = 0;
+    get lastReportedQueueDepth() {
+        return this.data.lastReportedQueueDepth;
+    }
     /**
      * Is `depth` news? Records it if so. **This is the whole fix for a defect that shipped in the
      * previous commit**, so the reasoning is written out rather than summarised.
@@ -94,13 +118,26 @@ export class SessionMapperState {
     reportsQueueDepth(depth) {
         if (depth === this.lastReportedQueueDepth)
             return false;
-        this.lastReportedQueueDepth = depth;
+        this.data.lastReportedQueueDepth = depth;
         return true;
     }
+    /**
+     * One agent-reported activity-state push, vendor-verbatim. Not a `WireEvent` and never routed
+     * through {@link mapSessionUpdate}'s return value — activity is a level, not an edge (see the
+     * `agent_session_state` frame's own doc comment in `protocol/agent.ts`), so it must not become a
+     * durable item, must not be journaled and must not advance any seq. Forwarded to whatever
+     * {@link onActivityReported} this instance was constructed with.
+     */
+    reportActivity(raw) {
+        this.onActivityReported(raw);
+    }
     /** Remember what this call is called. Later updates that carry no `name` fall back to it. */
     record(toolCallId, name) {
         if (name)
-            this.byId.set(toolCallId, name);
+            this.remember(toolCallId, name);
+    }
+    remember(toolCallId, name) {
+        Object.defineProperty(this.data.byId, toolCallId, { value: name, enumerable: true, writable: true, configurable: true });
     }
     /**
      * The name to report for one update, in ACP's own order of authority: an explicit `name` on the
@@ -112,10 +149,10 @@ export class SessionMapperState {
      */
     resolve(toolCallId, name, title) {
         if (name) {
-            this.byId.set(toolCallId, name);
+            this.remember(toolCallId, name);
             return name;
         }
-        return this.byId.get(toolCallId) ?? title ?? 'unknown';
+        return (Object.hasOwn(this.data.byId, toolCallId) ? this.data.byId[toolCallId] : undefined) ?? title ?? 'unknown';
     }
 }
 /**
@@ -136,7 +173,7 @@ function compact(value) {
     return Object.fromEntries(Object.entries(value).filter(([, v]) => v !== undefined));
 }
 /**
- * `ToolCall.locations` → the wire `tool_call.locations` shape; omitted entirely when there are none.
+ * `ToolCall.locations` → the wire `tool_call.locations` shape; [] explicitly clears a snapshot.
  *
  * An identity copy of ACP's `ToolCallLocation` (`types.gen.d.ts:581`), which is `{path, line?}` —
  * `line` is `number | null | undefined` (`:586-589`) and used to be dropped here, which cost the
@@ -145,7 +182,7 @@ function compact(value) {
  * enclosing payload.
  */
 function mapLocations(locations) {
-    if (!locations || locations.length === 0)
+    if (locations == null)
         return undefined;
     return locations.map((location) => compact({ path: location.path, line: location.line ?? undefined }));
 }
@@ -166,7 +203,7 @@ function toolCallCreatedEvent(update, state) {
             // only field guaranteed to give the card a name.
             name: update.name ?? update.title,
             toolCallId: update.toolCallId,
-            rawInput: update.rawInput,
+            rawInput: update.rawInput ?? undefined,
             kind: mapToolKind(update.kind),
             title: update.title,
             locations: mapLocations(update.locations),
@@ -239,16 +276,10 @@ function toolCallUpdateEvent(update, state) {
             title: update.title ?? undefined,
             kind: update.kind ?? undefined,
             status: update.status ?? undefined,
-            // An empty array is omitted rather than sent, and the behaviour is deliberate now that the
-            // card's fold *does* honour ACP's "replace the content collection": `applyChunks` treats an
-            // empty chunk list as "unchanged" at every call site, never as a clear. So an empty array
-            // carries nothing either way — and the server drops it on the way back out anyway
-            // (`TimelineEvent.ToolCallUpdated.payload` only writes `content` when it is non-empty), which
-            // is why sending one could not express a clear even if a consumer wanted to act on it.
-            content: update.content && update.content.length > 0 ? update.content : undefined,
+            content: update.content == null ? undefined : update.content,
             locations: mapLocations(update.locations),
-            rawInput: update.rawInput,
-            rawOutput: update.rawOutput,
+            rawInput: update.rawInput ?? undefined,
+            rawOutput: update.rawOutput ?? undefined,
             // See the doc comment above: ACP's extension slot, copied verbatim and read by nothing *here*
             // (the server's `decodeToolUpdate` does read it, also verbatim).
             _meta: update._meta ?? undefined,
@@ -257,16 +288,11 @@ function toolCallUpdateEvent(update, state) {
 }
 function mapToolCallEvents(update, state) {
     const events = [toolCallCreatedEvent(update, state)];
-    // ACP permits a `tool_call` to arrive already finished — the agent reporting a call it both
-    // started and completed in one notification, with no separate `tool_call_update` at all. A card
-    // only ever leaves "Running" on an update reporting a non-pending status
-    // (`WorkTimelineTools.foldToolUpdate`'s outcome branch), and the creation event carries no status,
-    // so without this second event an already-terminal call would render as permanently "Running".
-    //
+    // Creation carries initial update fields too. Emit them immediately under the same id so pending
+    // content and status, as well as an already-terminal result, survive a missing later update.
     // `ToolCall` is structurally a `ToolCallUpdate` (every field of the latter, with `title` and `kind`
-    // merely narrower), so the same function emits both — the two cannot drift into disagreeing about
-    // what a terminal update looks like.
-    if (update.status === 'completed' || update.status === 'failed') {
+    // merely narrower), so the same function emits both.
+    if (update.status != null || update.content != null || update.rawOutput != null) {
         events.push(toolCallUpdateEvent(update, state));
     }
     return events;
@@ -476,6 +502,9 @@ export function mapSessionUpdate(update, state) {
             const queueNotice = agentQueueNotice(update._meta, state);
             if (queueNotice)
                 events.push(queueNotice);
+            const activityRaw = codexActivityRaw(update._meta);
+            if (activityRaw)
+                state.reportActivity(activityRaw);
             return events;
         }
         case 'usage_update':

package/dist/workstation/acp/steering.js

@@ -0,0 +1,58 @@
+/**
+ * The `_session/steering` and `_session/async_task/stop` extension vocabulary of the deterministic processor
+ * (`processor/control.ts`; the old live session that also used it was deleted in Task 29). Pure: no I/O,
+ * no clock — the processor's import guard walks this file.
+ */
+/**
+ * The steering extension's JSON-RPC method. **Not an ACP method** — `grep steer` over the pinned
+ * SDK's `dist/schema/types.gen.d.ts` returns nothing. It is implemented by `claude-agent-acp`
+ * (`acp-agent.js@0.76.0:164`), whose own comment calls it a *"Custom (extension) request method ...
+ * Named `_session/steering` per the agreed ACP steering wire protocol"*; the leading underscore is
+ * ACP's extension namespace. It is therefore reached through the untyped `request<Response, Params>
+ * (method: string, …)` overload rather than `methods.agent.*`, and every caller must check
+ * {@link AcpConnection.supportsSteering} first.
+ */
+export const STEER_METHOD = '_session/steering';
+/**
+ * The adapter's *stop one background task* extension method. **Not an ACP method** either — it is
+ * `claude-agent-acp`'s own `ASYNC_TASK_STOP_METHOD` (`acp-agent.js@0.79.0:165`), whose own comment
+ * reads *"Stops one Claude background task without cancelling the parent prompt turn."*
+ * `codex-acp@1.12.0` registers the same literal name with the same params
+ * (`dist/index.js:31608`, `:35126-35129`, `:32395-32406`). Reached through the untyped `request`
+ * overload, for the reason {@link STEER_METHOD} documents.
+ */
+export const ASYNC_TASK_STOP_METHOD = '_session/async_task/stop';
+/**
+ * Narrow a `_session/steering` response onto {@link SteerOutcome}, or throw.
+ *
+ * The extension answers with one of three outcomes (`acp-agent.js@0.76.0:1737`, `:1751`, `:1779`):
+ *
+ * - `injected` — a turn was running and the message went into it.
+ * - `promptRequired` (with `reason: "noRunningTurn"`) — no turn was running and we opted in, so the
+ *   agent did nothing at all and the content stays host-owned.
+ * - `startedNewTurn` — no turn was running and the client did *not* opt in, so the agent detached a
+ *   `prompt()` of its own.
+ *
+ * **`startedNewTurn` throws rather than mapping to anything** (decision D13). We always send
+ * `idleBehavior: "promptRequired"` ({@link AcpSession.steer}), so receiving it means the agent
+ * ignored the opt-in — and what it handed back is a turn nobody awaits: it never enters our queue,
+ * never lands an item, and never produces a `turn_done`, in a system that accounts by turn.
+ * Absorbing it as "injected" would mark a message delivered to a turn we are not tracking;
+ * absorbing it as "promptRequired" would submit the same message a second time. Neither is a
+ * recovery, so this fails where the contract broke, loudly enough to name.
+ *
+ * An outcome nobody recognises throws for the same reason: silently reading it as `injected` would
+ * record a delivery that may never have happened.
+ */
+export function mapSteerOutcome(result) {
+    const outcome = result?.outcome;
+    if (outcome === 'injected')
+        return 'injected';
+    if (outcome === 'promptRequired')
+        return 'promptRequired';
+    if (outcome === 'startedNewTurn') {
+        throw new Error(`[acp] the agent answered ${STEER_METHOD} with 'startedNewTurn', a turn this client never ` +
+            "opted into and does not track: we always send _meta.steering.idleBehavior = 'promptRequired'.");
+    }
+    throw new Error(`[acp] unrecognised ${STEER_METHOD} outcome: ${JSON.stringify(outcome)}`);
+}

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