@platless/axom-cli 0.3.13 → 0.5.9

package/dist/workstation/acp/initializeResponse.js

@@ -0,0 +1,285 @@
+/**
+ * The `initialize` handshake, as data: the params this client sends and what it reads out of the
+ * agent's reply.
+ *
+ * ## Why this is its own module
+ *
+ * Two readers must agree on every byte of this: `connectAgent` (the live SDK path) and the
+ * deterministic ACP processor (`processor/`, spec 2026-10-11 §5.4), which parses the same reply off
+ * the keeper's raw log inside `step`. `step`'s import graph may not reach anything that spawns a
+ * process, reads the clock or draws a random id (`processor/guard.test.ts`), and `acpClient.ts` does
+ * all three — so the pure half lives here and `acpClient.ts` re-exports every name it used to own.
+ * One implementation rather than two kept equal by a test: the equivalence test in
+ * `processor/initialize.test.ts` then guards the processor's *wiring* (the right line, the right
+ * result), not a second copy of these rules.
+ *
+ * The Qoder runtime profile in `_meta` is deliberately not read here: it belongs to the connection's
+ * runtime diagnostics, which the processor takes over in Task 17b/17c.
+ */
+import { PROTOCOL_VERSION } from '@agentclientprotocol/sdk';
+import { airCapabilityMeta, asSdkClientCapabilities, AIR_ASYNC_TASKS_CAPABILITY, AIR_NATIVE_SUBAGENT_SESSIONS_CAPABILITY, DRAFT_SUBAGENTS_CAPABILITY, } from './draftSubagents.js';
+import { metaTerminalAuthArgs, terminalLoginSpecOf } from './terminalLoginSpec.js';
+/** The `initialize` params this client sends — the same object on the live path and from the processor. */
+export function initializeRequestParams() {
+    return {
+        protocolVersion: PROTOCOL_VERSION,
+        // Three things are declared here, and they are not interchangeable — see
+        // `draftSubagents.ts` for the tier each one sits in.
+        //
+        // 1. `subagents: {}` is the **canonical** draft field from ACP RFD #1992. Both official
+        //    adapters gate native subagent sessions on it, and both answer with
+        //    `agentCapabilities.sessionCapabilities.subagents` (measured against each).
+        //
+        // 2. The AIR list is sent as well, for two separate reasons. It is the *only* channel for
+        //    `asyncTasks` — nothing canonical exists for background work — and it is the fallback
+        //    for `nativeSubagentSessions`, because a released SDK sitting between us and an agent
+        //    can strip a draft field it has no type for (upstream says so in #1017's compatibility
+        //    note). Declaring both is not belt-and-braces: they cover different failure modes.
+        //
+        // 3. `subagent-transcript: true` stays. It is claude-agent-acp's older vendor key
+        //    (`dist/acp-agent.js:155-158`), and it still governs the **fallback** path taken when
+        //    native subagent sessions are not negotiated — an older adapter, or a stripped
+        //    capability. Without it that path strips every subagent's text and thinking
+        //    (`stripSubagentTextAndThinking`, `:3926`), leaving nothing but tool-call wreckage.
+        //    Adapters that have never heard of any of these keys are required by the spec to
+        //    ignore them.
+        clientCapabilities: asSdkClientCapabilities({
+            [DRAFT_SUBAGENTS_CAPABILITY]: {},
+            // `ClientSessionCapabilities.configOptions` (`types.gen.d.ts:4306`), part of the schema
+            // proper — unlike `subagents` above, this survives the pinned SDK's `zInitializeRequest`
+            // stripping because it's a known field, not a draft one. `{}` for `boolean` tells the
+            // agent it may send `type: "boolean"` entries in `SessionConfigOption` and that this
+            // client will send `session/set_config_option` with a boolean `value`
+            // (`SessionConfigOptionsCapabilities`, `types.gen.d.ts:4333-4353`); without it an agent
+            // with a boolean toggle downgrades it to a two-value select.
+            session: { configOptions: { boolean: {} } },
+            // `ClientCapabilities.elicitation` (`types.gen.d.ts:4479`) is a known field of the schema
+            // proper, not a draft one, so it survives `zInitializeRequest` stripping as-is. `{}` for
+            // `url` (`ElicitationUrlCapabilities`, `:4616`) means the client can put a URL in front of
+            // the user; this is the precondition for the whole device-code login shape to exist at all
+            // — Codex's own `getCodexAuthMethods` gates its `chat-gpt-device-code` auth method on
+            // `clientCapabilities?.elicitation?.url != null`. Without declaring it, Codex never offers
+            // that method and `elicitation/create` with `mode: 'url'` never arrives to answer (see
+            // `permission.ts`'s `handleCreateElicitation`).
+            //
+            // `form` (`ElicitationFormCapabilities`, `types.gen.d.ts:4455`) is what keeps Claude's
+            // AskUserQuestion alive: without it the adapter puts the tool in `disallowedTools`
+            // (`claude-agent-acp/dist/acp-agent.js:5959`), so the model never has it at all — the
+            // symptom is prose questions, not an unrendered card. This is the trigger for the whole
+            // elicitation-standardization plan: everything through Task 17 built the machinery to
+            // answer `elicitation/create` once it arrives; this line is what makes it arrive at all.
+            elicitation: { url: {}, form: {} },
+            _meta: {
+                // The convention Zed introduced and the ACP adapters adopted: an agent may gate its terminal
+                // sign-in methods on this key — claude-agent-acp advertises `claude-ai-login` / `console-login`
+                // (each with a `_meta["terminal-auth"]` naming the pipe-friendly invocation) only when the
+                // client declares it; pi-acp always returns its method but attaches the same block only then.
+                // We DO host those invocations — `terminalLogin.ts` runs them with pipes, sniffs the OAuth URL
+                // out of the output and surfaces it as a login link (spec 2026-09-24 D6/D7/D9) — so declaring
+                // this is a statement of fact, not an aspiration. Same-machine only: a hosted login's
+                // localhost OAuth callback must reach the workstation's own listener, which a browser opened
+                // on another machine cannot do; the standard `authenticate` methods (device-code style) are
+                // unaffected and never needed this key.
+                'terminal-auth': true,
+                'subagent-transcript': true,
+                ...airCapabilityMeta(AIR_NATIVE_SUBAGENT_SESSIONS_CAPABILITY, AIR_ASYNC_TASKS_CAPABILITY),
+            },
+        }),
+    };
+}
+/**
+ * Whether a JSON-RPC error code is one a frame may carry: an integer inside the Kotlin twin's `Int`
+ * range. See `acpClient.ts` `jsonRpcErrorCode` for why a malformed code is reported as no code at
+ * all. Split out so the processor, which sees the peer's `{code}` as plain JSON rather than as the
+ * SDK's `RequestError`, applies the identical rule.
+ */
+export function jsonRpcErrorCodeOf(code) {
+    if (typeof code !== 'number' || !Number.isInteger(code))
+        return undefined;
+    return code >= -2_147_483_648 && code <= 2_147_483_647 ? code : undefined;
+}
+/**
+ * Read an `initialize` result exactly the way `connectAgent` always has.
+ *
+ * The protocol version is checked **first** and nothing else is read when it is wrong — Global
+ * Constraint 1 is v1-only and a reply for another version is not ours to interpret. Malformed input
+ * throws where it always threw (a non-array `authMethods`, a non-object result); callers that must
+ * not throw (the processor) catch it themselves, so the live path keeps its exact behaviour.
+ */
+export function parseInitializeResult(initResponse) {
+    if (initResponse.protocolVersion !== PROTOCOL_VERSION) {
+        return { protocolSupported: false, protocolVersion: initResponse.protocolVersion };
+    }
+    const sessionCapabilities = initResponse.agentCapabilities?.sessionCapabilities;
+    const capabilities = {
+        // Capability markers are empty objects (`{ _meta? }`); supplying `{}` means "supported", and
+        // omitting the field (or explicit `null`) means "not supported". A truthiness check reads `{}`
+        // correctly by accident but reads `null`/`undefined` correctly too, which hides the real bug:
+        // this must stay an explicit `!= null`, never `Boolean(...)` or a bare truthy test.
+        list: sessionCapabilities?.list != null,
+        delete: sessionCapabilities?.delete != null,
+        resume: sessionCapabilities?.resume != null,
+        loadSession: initResponse.agentCapabilities?.loadSession === true,
+        logout: initResponse.agentCapabilities?.auth?.logout != null,
+        /**
+         * ACP `PromptCapabilities.image` (`types.gen.d.ts:1601`): "Agent supports
+         * [`ContentBlock::Image`]". Every field of that type is optional, so an agent that says
+         * nothing supports text only -- `=== true` rather than `!== false`.
+         *
+         * Verified against codex-acp 1.7.0, which declares `{embeddedContext: true, image: true}`.
+         * `audio` is deliberately not read: no agent we target declares it, and an unread capability
+         * is a field nobody can act on.
+         */
+        promptImage: initResponse.agentCapabilities?.promptCapabilities?.image === true,
+        mcpHttp: initResponse.agentCapabilities?.mcpCapabilities?.http === true,
+    };
+    // Honour the advertised capability, not what the agent happens to route: some adapters (e.g.
+    // codex-acp routing `session/fork`) implement more than they declare in `agentCapabilities`.
+    // Reading `capabilities` above off `initResponse` — never probing the agent for what it accepts
+    // — is what keeps that distinction intact.
+    const advertisedAuthMethods = initResponse.authMethods ?? [];
+    const authMethods = advertisedAuthMethods
+        .map(toAuthMethodSnapshot)
+        .filter((method) => method !== null);
+    const terminalLogins = [];
+    for (const method of advertisedAuthMethods) {
+        const spec = terminalLoginSpecOf(method);
+        if (spec && typeof method.id === 'string') {
+            // A duplicate id keeps its first position and takes the later spec — exactly `Map.set`.
+            const existing = terminalLogins.findIndex(([id]) => id === method.id);
+            if (existing >= 0)
+                terminalLogins[existing] = [method.id, spec];
+            else
+                terminalLogins.push([method.id, spec]);
+        }
+    }
+    return {
+        protocolSupported: true,
+        capabilities,
+        authMethods,
+        droppedAuthMethods: advertisedAuthMethods.length - authMethods.length,
+        terminalLogins,
+        ...(initResponse.agentCapabilities?._meta?.['axom/accountRateLimits']?.read === true ? { supportsAccountLimits: true, accountLimitsVersion: initResponse.agentCapabilities?._meta?.['axom/accountRateLimits']?.version ?? 1 } : {}),
+        supportsSteering: steeringAdvertised(initResponse._meta),
+        steeringTimings: steeringTimings(initResponse._meta),
+        agentInfo: initResponse.agentInfo ?? undefined,
+    };
+}
+/**
+ * Whether an `InitializeResponse._meta` advertises the `_session/steering` extension.
+ *
+ * ## `_session/steering` is not ACP
+ *
+ * It is absent from the schema this client is pinned to (`grep steer
+ * node_modules/@agentclientprotocol/sdk/dist/schema/types.gen.d.ts` returns nothing). It is an
+ * extension `claude-agent-acp` implements: the method constant lives at its `acp-agent.js@0.76.0:164`
+ * and its 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.
+ *
+ * ## Why the top-level `_meta` specifically
+ *
+ * The adapter advertises it at `InitializeResponse._meta.steering.supported`, a **sibling of
+ * `agentCapabilities`** (`acp-agent.js@0.76.0:944-950`), not a key inside it. `_meta` is typed
+ * `{[key: string]: unknown} | null` (`types.gen.d.ts:1498-1500`), so every hop down has to be
+ * narrowed rather than indexed through a cast.
+ *
+ * Strictly `=== true`. An agent that sends `steering: {}` (the shape ACP uses for its *own*
+ * capability markers) has not said `supported`, and this extension does not define that spelling —
+ * reading it as a yes would be this client inventing a wire contract.
+ */
+export function steeringAdvertised(meta) {
+    if (typeof meta !== 'object' || meta === null)
+        return false;
+    const steering = meta.steering;
+    if (typeof steering !== 'object' || steering === null)
+        return false;
+    return steering.supported === true;
+}
+/**
+ * The delivery timings the `_session/steering` extension defines — when the agent hands an injected
+ * message to the model. `next` is the only lossless one: `now` aborts the running generation and
+ * discards whatever tool calls were still outstanding.
+ */
+export const STEER_TIMINGS = ['now', 'next', 'later'];
+/**
+ * Which delivery timings an `InitializeResponse._meta` says the agent accepts —
+ * `_meta.steering.timings`, the sibling of the `supported` flag {@link steeringAdvertised} reads,
+ * and read from the **top-level** `_meta` for exactly the same reason.
+ *
+ * ## Empty is the answer, not the absence of one
+ *
+ * An agent that declares no timings has told us we may not name one. That is not "assume the
+ * default" — the extension ignores an unrecognised `priority` **silently** (the measurement behind
+ * ruling N4: sending `next` to today's adapters lands as `now`, which throws away the user's
+ * in-flight work). So an empty result must reach the caller as "do not specify a timing at all",
+ * and today — before the upstream PR that makes adapters broadcast this — every agent in the wild
+ * produces exactly that. Steady state, not a bug.
+ *
+ * ## Unknown values are dropped, never rejected
+ *
+ * A timing this build has never heard of is skipped and the known ones beside it survive. This
+ * client is deployed on user machines and can be older than both the agent it launches and the
+ * server it reports to; throwing (or discarding the whole array) on a value from a future version
+ * of the extension would take steering away from an agent that does support it. Non-strings are
+ * dropped the same way: `_meta` is typed `{[key: string]: unknown}`, so nothing here is guaranteed.
+ *
+ * Duplicates collapse — the wire shape is a JSON array but the fact is a set.
+ */
+export function steeringTimings(meta) {
+    if (typeof meta !== 'object' || meta === null)
+        return [];
+    const steering = meta.steering;
+    if (typeof steering !== 'object' || steering === null)
+        return [];
+    const declared = steering.timings;
+    if (!Array.isArray(declared))
+        return [];
+    const known = [];
+    for (const entry of declared) {
+        if (typeof entry !== 'string')
+            continue;
+        if (!STEER_TIMINGS.includes(entry))
+            continue;
+        if (known.includes(entry))
+            continue;
+        known.push(entry);
+    }
+    return known;
+}
+/**
+ * One `initialize` auth method, or `null` when the agent did not advertise a usable one.
+ *
+ * `initResponse` is another process's JSON that arrived over a pipe; `AuthMethod` is what this
+ * client *asked* for, not what it was handed. Both variants of that union make `id` and `name`
+ * required (`@agentclientprotocol/sdk` `types.gen.d.ts:2241-2246` for `AuthMethodTerminal`,
+ * `:2281-2286` for `AuthMethodAgent`), so an agent that omits them is off-spec -- but nothing
+ * between its stdout and here checks, and the snapshot then carries `undefined` in two positions
+ * its own type declares non-optional. That lie does not stay local: `JSON.stringify` erases an
+ * `undefined` value entirely, so the object passes every `typeof x.id` check in this process and
+ * still reaches a peer with the keys missing.
+ *
+ * `agoragentic-acp` advertises exactly `{type: 'terminal', description: '…'}`. Observing it once
+ * put a malformed `AuthMethodInfo` in the roster, which rides in every subsequent
+ * `management_hello`, which the server then cannot decode -- and a hello the server cannot decode
+ * closes the socket with nothing said, so the workstation retried into a permanent OFFLINE.
+ *
+ * Dropping rather than repairing: `id` is the value `authenticate` is called with, so inventing
+ * one would trade a missing sign-in method for a broken one.
+ */
+export function toAuthMethodSnapshot(method) {
+    if (typeof method.id !== 'string' || typeof method.name !== 'string')
+        return null;
+    // Terminal by shape (spec 2026-09-24 D6): a top-level `type: "terminal"`, or a `_meta
+    // ["terminal-auth"]` object from an agent that advertises its terminal login only there.
+    const terminal = terminalLoginSpecOf(method) !== undefined;
+    const args = 'args' in method && Array.isArray(method.args) ? method.args : terminal ? metaTerminalAuthArgs(method) : undefined;
+    return {
+        id: method.id,
+        name: method.name,
+        ...(terminal ? { type: 'terminal' } : {}),
+        ...(method.description != null ? { description: method.description } : {}),
+        // `args` only exists on a terminal method — top-level, or under `_meta["terminal-auth"]` when
+        // that is the only place the agent put it. Never the `_meta` command: see `terminalLogins`.
+        ...(args ? { args } : {}),
+    };
+}

package/dist/workstation/acp/installErrors.js

@@ -16,13 +16,13 @@
  * built.
  *
  * Three shapes, matching the three things a failed install can mean (see `acpClient.ts`'s
- * `isMissingPackageVersion`/`stderrShowsMissingPackageVersion` — the one predicate every ETARGET
+ * `stderrShowsMissingPackageVersion` — the one predicate every ETARGET
  * check in this codebase reuses rather than re-deriving):
  *
  * 1. An ordinary failure with no ETARGET in sight: a network hiccup, a full disk, a missing archive
  *    tool, a timeout. {@link friendlyOrdinaryInstallError}.
  * 2. The registry pins a version that is not published upstream, and the unpinned retry
- *    (`unpinnedFallbackFor`, `registry/launch.ts`) that tries to work around it fails too.
+ *    (`AcpAgents.installPristineWithFallback`) that tries to work around it fails too.
  *    {@link friendlyPinnedVersionUnavailableAndFallbackFailed}.
  * 3. The same missing pin, but the unpinned retry succeeds — not a failure at all, so it produces no
  *    message here. It produces a {@link PinnedVersionUnavailable} fact instead, which
@@ -87,3 +87,13 @@ export function friendlyPinnedVersionUnavailableAndFallbackFailed(agentId, pinne
     return (`The registry pins '${agentId}' to version ${pinned}, which is not published. Installing the ` +
         `latest available version instead failed too: ${shortDetail(fallbackDetail)}.${reassurance(existingVersion)}`);
 }
+/**
+ * A uv-distributed adapter, and `uv` itself is not on this workstation (the spawn failed `ENOENT`). Not a
+ * transient failure, so not "try again in a moment": the reader has to install uv first. Raised only by
+ * an Install that tried to run `uv` — scanning never checks for it.
+ */
+export function friendlyUvMissingError(agentId, existingVersion) {
+    return (`Could not install '${agentId}': uv is not installed on this workstation, and this agent is distributed ` +
+        `as a Python tool installed with uv. Install uv (https://docs.astral.sh/uv/getting-started/installation/) ` +
+        `so the workstation's service can find it on its PATH, then install the agent again.${reassurance(existingVersion)}`);
+}

package/dist/workstation/acp/installProbe.js

@@ -312,7 +312,7 @@ export function installNpxPackage(spec, options = {}) {
     // 都没有时 `npxCacheVersion` 同样是 `undefined` —— 两个 `undefined` 相等,若不单独守住这一条,
     // 一个从未被任何 npx 调用装过的包名,只要没剥版本前先被查过缓存,就会在这里被判定成"已经装好",
     // 一次 npx 都不用起。registry 自己从不发不钉版本的 spec(见 `registry/launch.ts` 的说明),这条分支
-    // 过去因此从没被真正走到过;`unpinnedFallbackFor` 的回退——`AcpAgents.installNpxWithFallback`——
+    // 过去因此从没被真正走到过;旧的 npx 安装期回退——
     // 是第一个会把不带版本的 spec 递进来的调用方,伪装成功比真的失败更糟:界面会说"已安装",磁盘上
     // 其实什么都没有。
     const pinnedVersion = npmPackageVersion(spec);

package/dist/workstation/acp/managedPatches.js

@@ -1,11 +1,15 @@
-/** Automatic adapter patches, owned by Axom, never written into npm's shared cache. */
-import { createHash, randomUUID } from 'node:crypto';
-import { cp, mkdir, readFile, readdir, rename, rm, stat, writeFile } from 'node:fs/promises';
+/**
+ * Automatic adapter patches, owned by Axom, applied only at **install** time to a copy of the
+ * daemon-owned pristine tree (spec §6.2/§3.3). The pristine tree is never patched in place, and
+ * nothing here ever runs at launch except {@link verifyPatchedFiles}, the tamper check.
+ */
+import { createHash } from 'node:crypto';
+import { constants } from 'node:fs';
+import { cp, readFile, writeFile } from 'node:fs/promises';
 import path from 'node:path';
-import { installNpxPackage, npmCacheDir, npmPackageName, npmPackageVersion } from './installProbe.js';
+import { inside } from './builds/model.js';
 import { packagePatchMatch, packagePatches } from './patchAssets.js';
 const sha = (content) => createHash('sha256').update(content).digest('hex');
-const pending = new Map();
 const warned = new Set();
 function warnOnce(key, message) {
     if (warned.has(key))
@@ -13,7 +17,7 @@ function warnOnce(key, message) {
     warned.add(key);
     console.warn(message);
 }
-function inside(root, relative) {
+function within(root, relative) {
     const target = path.resolve(root, relative);
     if (!target.startsWith(path.resolve(root) + path.sep))
         throw new Error('Axom patch path escapes its package');
@@ -28,7 +32,7 @@ export async function applyPackagePatches(packageDir, recipes) {
             throw new Error(`Axom patch '${recipe.id}' does not support ${metadata.name}@${metadata.version}`);
         }
         for (const edit of recipe.edits) {
-            const filename = inside(packageDir, edit.file);
+            const filename = within(packageDir, edit.file);
             const original = await readFile(filename, 'utf8');
             if (sha(original) !== edit.before_sha256 || !edit.before || original.split(edit.before).length !== 2) {
                 throw new Error(`Axom patch '${recipe.id}': original bytes changed in ${edit.file}`);
@@ -49,7 +53,7 @@ async function originalsFit(packageDir, recipe) {
         let content = files.get(edit.file);
         if (content === undefined) {
             try {
-                content = await readFile(inside(packageDir, edit.file), 'utf8');
+                content = await readFile(within(packageDir, edit.file), 'utf8');
             }
             catch {
                 return false;
@@ -61,168 +65,80 @@ async function originalsFit(packageDir, recipe) {
     }
     return true;
 }
-async function cachedModules(name, version, probe) {
-    const root = path.join(npmCacheDir(probe), '_npx');
-    let entries;
-    try {
-        entries = await readdir(root, { withFileTypes: true });
-    }
-    catch {
-        return undefined;
-    }
-    for (const entry of entries) {
-        if (!entry.isDirectory())
-            continue;
-        const modules = path.join(root, entry.name, 'node_modules');
-        try {
-            const metadata = JSON.parse(await readFile(inside(modules, name + '/package.json'), 'utf8'));
-            if (metadata.name === name && metadata.version === version)
-                return modules;
-        }
-        catch { /* Interrupted/other version of npm's cache. */ }
-    }
-    return undefined;
-}
-/** Called by Install/Update and every real launch, including adapters installed before this CLI. */
-export async function preparePatchedLaunch(agent, launch, adapterRoot, probe, options = {}) {
-    const distribution = agent.distribution.npx;
-    if (!distribution)
-        return launch;
-    const name = npmPackageName(distribution.package);
-    const version = npmPackageVersion(distribution.package);
-    const candidates = (options.recipes ?? packagePatches).filter((patch) => patch.package === name);
+/**
+ * The recipes this CLI applies to `name@version`, read against the **pristine** package at
+ * `pristinePackageDir`: exact-version recipes always (their bytes are a promise — a mismatch fails the
+ * patch step loudly), range recipes only when the pristine bytes fit (otherwise upstream runs, with a
+ * warning). An empty answer means the build is the pristine tree itself.
+ */
+export async function selectPackagePatches(name, version, pristinePackageDir, recipes = packagePatches) {
+    const candidates = recipes.filter((patch) => patch.package === name);
     const matched = candidates.flatMap((recipe) => {
-        const match = version ? packagePatchMatch(recipe, version) : undefined;
+        const match = packagePatchMatch(recipe, version);
         return match ? [{ recipe, match }] : [];
     });
-    if (matched.length && (!/^(?:@[a-z0-9._-]+\/)?[a-z0-9._-]+$/i.test(name) || !version || !/^[0-9a-z.+-]+$/i.test(version))) {
+    if (matched.length && (!/^(?:@[a-z0-9._-]+\/)?[a-z0-9._-]+$/i.test(name) || !/^[0-9a-z.+-]+$/i.test(version))) {
         throw new Error('Invalid package identity for Axom adapter patch');
     }
-    // A range only says a recipe may fit; the pristine package's bytes decide.
-    const fitting = new Set();
-    if (matched.some(({ match }) => match === 'range')) {
-        const modules = await pristineModules();
-        for (const { recipe, match } of matched) {
-            if (match !== 'range')
-                continue;
-            if (await originalsFit(inside(modules, name), recipe))
-                fitting.add(recipe);
-            else
-                warnOnce(`${recipe.id}@${distribution.package}`, `[axom-patch] ${recipe.id} does not fit ${distribution.package}; using the upstream package. Review the patch inventory.`);
-        }
-    }
-    const recipes = matched.filter(({ recipe, match }) => match === 'exact' || fitting.has(recipe)).map(({ recipe }) => recipe);
-    if (!recipes.length) {
-        if (candidates.length && !matched.length) {
-            warnOnce(distribution.package, `[axom-patch] No verified patch for ${distribution.package}; using the upstream package. Review the patch inventory.`);
+    const selected = [];
+    for (const { recipe, match } of matched) {
+        if (match === 'exact') {
+            selected.push(recipe);
+            continue;
         }
-        return launch;
-    }
-    const digest = sha(JSON.stringify(recipes));
-    const target = path.join(adapterRoot, 'patched-npm', sha(name).slice(0, 16), version, digest);
-    const existing = pending.get(target);
-    if (existing) {
-        await existing;
-        return makeLaunch();
-    }
-    const preparation = prepare();
-    pending.set(target, preparation);
-    try {
-        await preparation;
-        return await makeLaunch();
+        if (await originalsFit(pristinePackageDir, recipe))
+            selected.push(recipe);
+        else
+            warnOnce(`${recipe.id}@${name}@${version}`, `[axom-patch] ${recipe.id} does not fit ${name}@${version}; using the upstream package. Review the patch inventory.`);
     }
-    finally {
-        pending.delete(target);
+    if (!selected.length && candidates.length && !matched.length) {
+        warnOnce(`${name}@${version}`, `[axom-patch] No verified patch for ${name}@${version}; using the upstream package. Review the patch inventory.`);
     }
-    async function prepare() {
-        const packageDir = inside(path.join(target, 'node_modules'), name);
-        const receiptFile = path.join(target, 'axom-patches.json');
-        let receipt;
+    return selected;
+}
+/** The identity of a recipe set: any recipe change is a new digest, hence a new build. */
+export function patchDigest(recipes) {
+    return sha(JSON.stringify(recipes));
+}
+/**
+ * Copy the pristine `node_modules` (reflink where the filesystem supports it — `COPYFILE_FICLONE`
+ * falls back to an ordinary copy by itself; relative symlinks such as `.bin/*` are kept relative so
+ * the copy never points back into pristine) into `stagedRoot`, patch the copy, and write a receipt.
+ * Returns the sha256 of every patched file, relative to the package directory.
+ */
+export async function createPatchedTree(pristineRoot, stagedRoot, name, version, recipes) {
+    await cp(path.join(pristineRoot, 'node_modules'), path.join(stagedRoot, 'node_modules'), {
+        recursive: true, verbatimSymlinks: true, mode: constants.COPYFILE_FICLONE,
+    });
+    const packageDir = inside(path.join(stagedRoot, 'node_modules'), name);
+    const files = await applyPackagePatches(packageDir, recipes);
+    const expected = expectedPatchedFiles(recipes);
+    if (JSON.stringify(sortKeys(files)) !== JSON.stringify(sortKeys(expected)))
+        throw new Error('Incomplete Axom adapter patch');
+    await writeFile(path.join(stagedRoot, 'axom-patches.json'), JSON.stringify({
+        digest: patchDigest(recipes), package: name, version, patches: recipes.map((recipe) => recipe.id), files,
+    }) + '\n');
+    console.info(`[axom-patch] Applied ${recipes.map((recipe) => recipe.id).join(', ')} to ${name}@${version}`);
+    return files;
+}
+/** The files a recipe set rewrites and their expected sha256, derived from the shipped recipes. */
+export function expectedPatchedFiles(recipes) {
+    return Object.fromEntries(recipes.flatMap((recipe) => recipe.edits.map((edit) => [edit.file, edit.after_sha256])));
+}
+function sortKeys(record) {
+    return Object.fromEntries(Object.entries(record).sort(([a], [b]) => a.localeCompare(b)));
+}
+/** The launch-time tamper check: every patched file still hashes to what was recorded at install. */
+export async function verifyPatchedFiles(packageDir, files) {
+    for (const [file, hash] of Object.entries(files)) {
+        let content;
         try {
-            receipt = JSON.parse(await readFile(receiptFile, 'utf8'));
+            content = await readFile(within(packageDir, file));
         }
-        catch (error) {
-            if (error.code !== 'ENOENT')
-                throw error;
-        }
-        if (receipt) {
-            if (receipt.digest !== digest)
-                throw new Error('Axom adapter patch receipt does not match this CLI');
-            // Derive expected files from the shipped recipe, never from a writable receipt alone.
-            const expected = Object.fromEntries(recipes.flatMap((recipe) => recipe.edits.map((edit) => [edit.file, edit.after_sha256])));
-            if (JSON.stringify(receipt.files) !== JSON.stringify(expected))
-                throw new Error('Incomplete Axom adapter patch receipt');
-            for (const [file, hash] of Object.entries(expected)) {
-                if (sha(await readFile(inside(packageDir, file))) !== hash)
-                    throw new Error(`Axom patched adapter was modified: ${file}`);
-            }
+        catch {
+            throw new Error(`Axom patched adapter is missing ${file}`);
         }
-        else {
-            try {
-                await stat(target);
-                throw new Error('Incomplete Axom patched adapter directory; refusing to use it');
-            }
-            catch (error) {
-                if (error.code !== 'ENOENT')
-                    throw error;
-            }
-            const modules = await pristineModules();
-            await mkdir(path.dirname(target), { recursive: true });
-            const temporary = target + '.staging-' + randomUUID();
-            try {
-                // Dependencies and .bin are part of the adapter environment; clone them as well.
-                await cp(modules, path.join(temporary, 'node_modules'), { recursive: true, dereference: true });
-                const files = await applyPackagePatches(inside(path.join(temporary, 'node_modules'), name), recipes);
-                await writeFile(path.join(temporary, 'axom-patches.json'), JSON.stringify({
-                    digest, package: name, version, patches: recipes.map((recipe) => recipe.id), files,
-                }) + '\n');
-                try {
-                    await rename(temporary, target);
-                }
-                catch (error) {
-                    // A second daemon may have published the same immutable copy while we built ours.
-                    if (!['EEXIST', 'ENOTEMPTY'].includes(error.code ?? ''))
-                        throw error;
-                    return prepare();
-                }
-                console.info(`[axom-patch] Applied ${recipes.map((recipe) => recipe.id).join(', ')} to ${name}@${version}`);
-            }
-            finally {
-                await rm(temporary, { recursive: true, force: true });
-            }
-        }
-    }
-    async function pristineModules() {
-        let modules = await cachedModules(name, version, probe);
-        if (!modules) {
-            const installed = await installNpxPackage(distribution.package, {
-                env: probe, timeoutMs: options.timeoutMs, npxCommand: options.npxCommand,
-            });
-            if (!installed.ok)
-                throw new Error(installed.error);
-            modules = await cachedModules(name, version, probe);
-        }
-        if (!modules)
-            throw new Error(`Installed package ${distribution.package} is absent from npm's cache`);
-        return modules;
-    }
-    async function makeLaunch() {
-        const packageDir = inside(path.join(target, 'node_modules'), name);
-        const metadata = JSON.parse(await readFile(path.join(packageDir, 'package.json'), 'utf8'));
-        if (metadata.name !== name || metadata.version !== version)
-            throw new Error('Patched adapter package identity changed');
-        const selectedBins = [...new Set(recipes.map(recipe => recipe.bin).filter((bin) => bin !== undefined))];
-        if (selectedBins.length > 1)
-            throw new Error('Axom patches disagree about the adapter executable');
-        const binaries = selectedBins.length ? [metadata.bin?.[selectedBins[0]]] :
-            typeof metadata.bin === 'string' ? [metadata.bin] : Object.values(metadata.bin ?? {});
-        if (binaries.length !== 1 || typeof binaries[0] !== 'string')
-            throw new Error('Patched adapter has no unambiguous executable');
-        const entry = inside(packageDir, binaries[0]);
-        if (!(await stat(entry)).isFile())
-            throw new Error('Patched adapter executable is missing');
-        const env = { ...launch.env };
-        env.PATH = path.join(target, 'node_modules', '.bin') + path.delimiter + (env.PATH ?? probe.path ?? process.env.PATH ?? '');
-        return { command: process.execPath, args: [entry, ...(distribution.args ?? [])], env };
+        if (sha(content) !== hash)
+            throw new Error(`Axom patched adapter was modified: ${file}`);
     }
 }