@platless/axom-cli 0.1.0 → 0.5.9

package/dist/workstation/acp/envSecrets.js

@@ -0,0 +1,27 @@
+/**
+ * The environment values the server's `agent_open` (and every other agent frame that launches an adapter) overlays — the workspace's
+ * `env` and the agent's `agentEnv`, where API keys and tokens are configured — are secrets for stderr purposes (spec 2026-10-11 §13,
+ * Task 23's sentinel gate): an adapter that prints its environment would otherwise leave the key in keeper-acp's `stderr.log`, the
+ * `err` records and the exit tail, or — for the daemon's short-lived connections (`connectAgent`: verify, native session listing,
+ * logins) — in daemon.log. Not redacted, because they are no credential and blanking them would garble every line they appear in
+ * (stack traces print paths): the overlay's `PATH` (the daemon computes it from `pathPrepend`), values shorter than
+ * {@link ENV_SECRET_MIN_LENGTH} ("1", "debug"), absolute paths, booleans and plain numbers.
+ */
+export const ENV_SECRET_MIN_LENGTH = 8;
+/** A value that is plainly not a secret (see the file comment). */
+export function isPlainEnvValue(value) {
+    return value.length < ENV_SECRET_MIN_LENGTH
+        || /^(?:\/|~\/|[A-Za-z]:[\\/])/.test(value)
+        || /^(?:true|false|yes|no|on|off)$/i.test(value)
+        || /^[-+]?\d+(?:\.\d+)?$/.test(value);
+}
+export function overlayEnvSecrets(overlays) {
+    const values = new Set();
+    for (const overlay of [overlays.env, overlays.agentEnv]) {
+        for (const [key, value] of Object.entries(overlay ?? {})) {
+            if (key !== 'PATH' && typeof value === 'string' && !isPlainEnvValue(value))
+                values.add(value);
+        }
+    }
+    return [...values];
+}

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

@@ -0,0 +1,144 @@
+/**
+ * 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 { inside } from './builds/model.js';
+import { packagePatchMatch, packagePatches } from './patchAssets.js';
+const sha = (content) => createHash('sha256').update(content).digest('hex');
+const warned = new Set();
+function warnOnce(key, message) {
+    if (warned.has(key))
+        return;
+    warned.add(key);
+    console.warn(message);
+}
+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');
+    return target;
+}
+/** A matching version and exact original bytes; already-patched or changed originals are rejected. */
+export async function applyPackagePatches(packageDir, recipes) {
+    const output = {};
+    for (const recipe of recipes) {
+        const metadata = JSON.parse(await readFile(path.join(packageDir, 'package.json'), 'utf8'));
+        if (metadata.name !== recipe.package || !packagePatchMatch(recipe, metadata.version)) {
+            throw new Error(`Axom patch '${recipe.id}' does not support ${metadata.name}@${metadata.version}`);
+        }
+        for (const edit of recipe.edits) {
+            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}`);
+            }
+            const patched = original.replace(edit.before, edit.after);
+            if (sha(patched) !== edit.after_sha256)
+                throw new Error(`Axom patch '${recipe.id}': invalid expected output`);
+            await writeFile(filename, patched, 'utf8');
+            output[edit.file] = sha(patched);
+        }
+    }
+    return output;
+}
+/** Whether every edit of `recipe` finds the bytes it was written against, edits on one file applied in order. */
+async function originalsFit(packageDir, recipe) {
+    const files = new Map();
+    for (const edit of recipe.edits) {
+        let content = files.get(edit.file);
+        if (content === undefined) {
+            try {
+                content = await readFile(within(packageDir, edit.file), 'utf8');
+            }
+            catch {
+                return false;
+            }
+        }
+        if (sha(content) !== edit.before_sha256 || !edit.before || content.split(edit.before).length !== 2)
+            return false;
+        files.set(edit.file, content.replace(edit.before, edit.after));
+    }
+    return true;
+}
+/**
+ * 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 = packagePatchMatch(recipe, version);
+        return match ? [{ recipe, match }] : [];
+    });
+    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');
+    }
+    const selected = [];
+    for (const { recipe, match } of matched) {
+        if (match === 'exact') {
+            selected.push(recipe);
+            continue;
+        }
+        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.`);
+    }
+    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.`);
+    }
+    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 {
+            content = await readFile(within(packageDir, file));
+        }
+        catch {
+            throw new Error(`Axom patched adapter is missing ${file}`);
+        }
+        if (sha(content) !== hash)
+            throw new Error(`Axom patched adapter was modified: ${file}`);
+    }
+}