superpowers-manager 0.6.0 → 0.7.0

package/dist/commands/prepare.js

@@ -78,10 +78,9 @@ function validStagingLeaf(value) {
         !value.includes("\\"));
 }
 async function gatherPrepare(ctx) {
+    // Collect outcomes without writing so output failures cannot be classified as
+    // inspection failures. Replay collected outcomes after gathering completes.
     const env = ctx.env;
-    // `git show ad56569a4c161e7b122967442e2b026eeb6395f6:scripts/prepare:16::invocation_root=` — captured before the two case statements below.
-    // getcwd(3) returns the physical path, so this matches `pwd -P` without a
-    // realpath call.
     const cwd = process.cwd();
     const cache = upstreamCacheRoot(ctx.root, env, cwd);
     const cacheParent = dirname(cache);
@@ -102,34 +101,39 @@ async function gatherPrepare(ctx) {
     const pluginRoot = location.destinationRoot;
     const executableValidator = env.SUPERPOWERS_VALIDATOR_EXECUTABLE || "";
     const tmpParent = dirname(pluginRoot);
+    const outcomes = [];
+    const failed = (message) => ({
+        kind: "failed",
+        outcomes,
+        validator: NO_VALIDATOR_OUTPUT,
+        message,
+    });
+    const selection = ctx.selection ?? (await computeEffectiveSelection(ctx.root, env));
+    let prefetch;
+    try {
+        prefetch = await ctx.adapter.validatePreparationBeforeFetch(adapterContext);
+    }
+    catch {
+        return {
+            outcome: failed(ctx.adapter.presentation.callFailure("prepare", adapterContext)
+                .unexpected),
+            cleanupWarning: null,
+        };
+    }
+    outcomes.push(prefetch.outcome);
+    if (!prefetch.outcome.ok)
+        return { outcome: failed(null), cleanupWarning: null };
+    if (prefetch.status !== 0) {
+        return {
+            outcome: failed(ctx.adapter.presentation.callFailure("prepare", adapterContext)
+                .invalidStatus),
+            cleanupWarning: null,
+        };
+    }
     await owned(`cannot create directory: ${tmpParent}`, () => mkdir(tmpParent, { recursive: true }));
     let cleanupWarning = null;
     const outcome = await withWorkspace(tmpParent, ".superpowers.prepare.", async (workspace) => {
-        const outcomes = [];
-        const failed = (message) => ({
-            kind: "failed",
-            outcomes,
-            validator: NO_VALIDATOR_OUTPUT,
-            message,
-        });
         const candidate = join(workspace, location.stagingLeaf);
-        const selection = ctx.selection ?? (await computeEffectiveSelection(ctx.root, env));
-        let prefetch;
-        try {
-            prefetch =
-                await ctx.adapter.validatePreparationBeforeFetch(adapterContext);
-        }
-        catch {
-            return failed(ctx.adapter.presentation.callFailure("prepare", adapterContext)
-                .unexpected);
-        }
-        outcomes.push(prefetch.outcome);
-        if (!prefetch.outcome.ok)
-            return failed(null);
-        if (prefetch.status !== 0) {
-            return failed(ctx.adapter.presentation.callFailure("prepare", adapterContext)
-                .invalidStatus);
-        }
         await owned(`cannot create directory: ${cacheParent}`, () => mkdir(cacheParent, { recursive: true }));
         if (selection.selectionMode === "pinned") {
             await fetchExactCommit(selection.effectiveSource, selection.desiredCommit, cache, workspace);
@@ -244,7 +248,7 @@ async function gatherPrepare(ctx) {
         // the workspace on return, and the candidate lives in it.
         //
         // atomicReplaceDir delegates to beginDirectoryPublication, whose outer
-        // catch (`src/atomic.ts:341-348::if (cause`) wraps every non-SafetyError
+        // catch (`src/atomic.ts:319::if (cause`) wraps every non-SafetyError
         // into a SafetyError, so the callee owns every failure on this path and
         // re-emitting its own diagnostic is the sanctioned form of interpolation.
         // The hand-written prefix carries the live root, which the callee's message
@@ -291,58 +295,10 @@ async function performPrepare(argv, ctx) {
         run = await gatherPrepare(ctx);
     }
     catch (cause) {
-        // Hand-written messages, per AGENTS.md's reader-diagnostics rule.
-        // Reachable here: prepareError(), from this module's owned() wrappers,
-        // its two manifest-version checks, and asResolutionKind;
-        // readManifest's three hookError messages
-        // (`src/harnesses/codex/hooks.ts:113-138::readManifest`), pinned by
-        // `tests/unit/harnesses/codex/hooks.test.ts:95::void test("readManifest diagnostics` as carrying no reader vocabulary or
-        // errno; and SafetyErrors from gitSafeSource, writeProvenance, and
-        // withWorkspace.
-        //
-        // FOUR exceptions, all inherited and none a regression:
-        //   1. resolveRef splices git's combined stdout+stderr into its own text
-        //      on the NON-PINNED path (src/upstream.ts), reached via
-        //      computeEffectiveSelection (src/effective-selection.ts).
-        //      This is the DEFAULT invocation -- plain `prepare`, `track-latest`,
-        //      and any non-40-hex SUPERPOWERS_REF -- not an exotic corner. Pinned
-        //      by
-        //      `tests/unit/upstream.test.ts:453-462::void test("resolveRef reports a query failure for latest`,
-        //      :471-481, and :483-501.
-        //   2. fetchExactCommit splices the same combined stdout+stderr into its
-        //      own text on the PINNED path (both of its own splice sites in
-        //      src/upstream.ts, and proveCommit's, which it calls). This is the
-        //      rarer of the two raw-git-output paths, not the only one.
-        //   3. `src/selection-store.ts:120-124::cause.module === "selection") {`
-        //      (same shape at :49, :86, :98) is the
-        //      module AGENTS.md's `src/selection-store.ts` bullet grandfathers:
-        //      it interpolates the caught error's own message, so Node errno
-        //      prose can reach this stream -- sanctioned, nothing here needs
-        //      fixing.
-        //   4. Every runGit call site in this module (fetch, clone, checkout) can
-        //      reject instead of resolving: `src/git.ts:47-52::reject(new SafetyError` wraps every string
-        //      errno other than ENOENT in
-        //      `new SafetyError("git", \`cannot run git: ${failure.message}\`)`,
-        //      and that Node spawn-level message reaches ctx.stderr through this
-        //      catch. So the claim that the non-pinned clone/fetch/checkout
-        //      branch names only the source is true for a non-zero *exit status*
-        //      (handled explicitly below, in gatherPrepare) but false for a
-        //      *spawn-level* failure -- runGit throws rather than returning a
-        //      status in that case, and this outer catch is what stands between
-        //      it and the stream.
-        //
-        // oneLine() at this catch collapses each of exceptions 1, 2, and 4 -- the
-        // three carrying git-derived text -- to a single line. It collapses CR/LF
-        // only, so it bounds how much of that text lands, not what it may
-        // contain.
-        //
-        // runCodexOperation's closing `throw cause` (src/harnesses/codex/adapter.ts) does NOT arrive
-        // here -- the call site catches it and converts it to a hand-written
-        // message per AGENTS.md's reader-diagnostics rule.
-        //
-        // gatherPrepare performs no writes of its own, so this catch cannot also be
-        // reached by an EPIPE from prepare's own output: every write below runs
-        // only after this try/catch has resolved.
+        // Reader wrappers supply their own diagnostics. The saved-selection read
+        // path retains its sanctioned interpolation at
+        // `src/selection-store.ts:116-121::if (cause instanceof SafetyError && cause.module === "selection") {`.
+        // oneLine() bounds any inherited git or filesystem diagnostic to one line.
         ctx.stderr.write(`error: ${oneLine(cause)}\n`);
         return 1;
     }
@@ -372,7 +328,7 @@ async function performPrepare(argv, ctx) {
         // completed before cleanup ran, so it is not being reported as unverified
         // -- but something did still go wrong, and AGENTS.md's fail-closed rule
         // extends to it. Mirrors
-        // `src/commands/install.ts:561-570::if (cleanupWarning`.
+        // `src/commands/install.ts:446::if (cleanupWarning`.
         ctx.stderr.write(`error: ${cleanupWarning}\n`);
         return 1;
     }

package/dist/commands/probe.js

@@ -1,23 +1,11 @@
 import { assertFailureWritable, writeAdapterFailure, } from "../adapter-result.js";
 import { oneLine } from "../cli-arguments.js";
 import { computeEffectiveSelection } from "../effective-selection.js";
+import { callAdapter } from "./adapter-call.js";
 export const PROBE_USAGE = "error: usage: superpowers-manager probe [--porcelain]\n";
-// Ports scripts/core/validate-adapter-response.py's replay (:235-238) and its
-// error/hint block (:269-272). The shell ran that validator on EVERY adapter
-// response, so adapter messages reached the operator on their declared streams
-// in array order, and a controlled failure printed `error:` plus one `hint:`
-// per hint. DIAG-ADAPTER-01 retains that contract
-// (docs/adapter-result-contract.md); dropping it here would be a
-// silent diagnostics regression, not a simplification.
-//
-// Interpolating error.message and each hint is the sanctioned form (AGENTS.md):
-// src/harnesses/codex/adapter.ts has 52 `fail()` sites and none interpolates a caught error's
-// message, so the callee owns every failure reachable on this path. Those two
-// writes now live in writeAdapterFailure (src/adapter-result.ts), which
-// validates all three strings before the first of them reaches the stream.
-//
-// This writes to ctx, so it MUST NOT be called from inside gatherProbe's try
-// -- see the ProbeOutcome note below.
+// Replay adapter messages in order on their declared streams. Adapter failures
+// are emitted only after terminal-safety validation. This writes to ctx, so it
+// must run after gathering, outside a gather function's failure handling.
 export function replayOutcome(outcome, ctx) {
     // Hoisted ABOVE the message loop, and that ordering is the point: a failure
     // whose code, message, or a hint carries a terminal control character must
@@ -33,153 +21,14 @@ export function replayOutcome(outcome, ctx) {
     // stored, so scanning it here would re-check a population that cannot fail.
     writeAdapterFailure(ctx, outcome);
 }
-function record(value) {
-    return value !== null && typeof value === "object"
-        ? value
-        : null;
+function coherentControl(value) {
+    return (value.recoveryState !== "required" ||
+        (value.probeEligibility.kind === "blocked" &&
+            value.mutationEligibility.kind === "blocked"));
 }
-export function validOutput(value) {
-    const candidate = record(value);
-    return (candidate !== null &&
-        Array.isArray(candidate.stdout) &&
-        candidate.stdout.every((line) => typeof line === "string") &&
-        Array.isArray(candidate.stderr) &&
-        candidate.stderr.every((line) => typeof line === "string"));
-}
-function validDecision(value) {
-    const candidate = record(value);
-    return (candidate !== null &&
-        (candidate.kind === "allowed" ||
-            (candidate.kind === "blocked" && validOutput(candidate.output))));
-}
-function validCompatibility(value) {
-    const candidate = record(value);
-    if (candidate === null ||
-        typeof candidate.reason !== "string" ||
-        (candidate.kind !== "unknown" &&
-            candidate.kind !== "supported" &&
-            candidate.kind !== "experimental" &&
-            candidate.kind !== "unsupported"))
-        return false;
-    return ((candidate.kind !== "supported" && candidate.kind !== "experimental") ||
-        typeof candidate.generation === "string");
-}
-function validPreparedArtifact(value) {
-    const candidate = record(value);
-    return (candidate !== null &&
-        typeof candidate.root === "string" &&
-        typeof candidate.commit === "string" &&
-        typeof candidate.identity === "string" &&
-        validCompatibility(candidate.compatibility));
-}
-function validPrepared(value) {
-    const candidate = record(value);
-    return (candidate !== null &&
-        typeof candidate.observedIdentity === "string" &&
-        validCompatibility(candidate.compatibility) &&
-        (candidate.kind === "needs-prepare" ||
-            (candidate.kind === "current" &&
-                validPreparedArtifact(candidate.artifact))));
-}
-export function validInstalled(value) {
-    const candidate = record(value);
-    return (candidate !== null &&
-        (candidate.kind === "current" ||
-            candidate.kind === "mismatch" ||
-            candidate.kind === "absent") &&
-        typeof candidate.observedIdentity === "string" &&
-        (candidate.kind !== "absent" || candidate.observedIdentity === ""));
-}
-function validOwnership(value) {
-    const candidate = record(value);
-    return (candidate !== null &&
-        validDecision(candidate.installEligibility) &&
-        Object.prototype.hasOwnProperty.call(candidate, "removalInput") &&
-        validDecision(candidate.removalVerification) &&
-        validOutput(candidate.postRemovalOutput) &&
-        typeof candidate.presentationValue === "string" &&
-        (candidate.presentationConflicts === undefined ||
-            (Array.isArray(candidate.presentationConflicts) &&
-                candidate.presentationConflicts.every((conflict) => typeof conflict === "string"))));
-}
-function validControl(value) {
-    const candidate = record(value);
-    return (candidate !== null &&
-        validDecision(candidate.probeEligibility) &&
-        validDecision(candidate.mutationEligibility) &&
-        typeof candidate.presentationValue === "string" &&
-        (candidate.recoveryState === undefined ||
-            (candidate.recoveryState === "required" &&
-                candidate.probeEligibility.kind === "blocked" &&
-                candidate.mutationEligibility.kind === "blocked")));
-}
-// `runCodexOperation` reports a CONTROLLED failure by RETURN VALUE, not by throwing
-// (`src/adapter-result.ts:32-35::export interface AdapterResult`). The shell got
-// fail-closed behaviour for free: spw_invoke_adapter returned 1 and
-// scripts/probe ran under `set -eu`.
-// Omitting the status check here would read a failed inspection as absent
-// evidence and report it as success.
-//
-// It does still THROW for a non-AdapterFailure cause (runCodexOperation's closing
-// `throw cause`, src/harnesses/codex/adapter.ts). That is caught here rather than in runProbe's
-// outer catch, because the two need different diagnostics -- see spec §3.3a.
-//
-// Reached through ctx.adapter, not a direct module-level dependency on the
-// adapter module: src/commands/prepare.ts and this module are the two the
-// injected double must observe, because install reaches the adapter through
-// gatherProbe and runPrepare. Spec §4.5.
-async function inspect(call, unexpected, invalidStatus, valid) {
-    let result;
-    try {
-        result = await call();
-        if (!result ||
-            !Number.isInteger(result.status) ||
-            !result.outcome ||
-            typeof result.outcome.ok !== "boolean" ||
-            !Array.isArray(result.outcome.messages))
-            return { ok: false, result: null, message: invalidStatus };
-    }
-    catch {
-        return { ok: false, result: null, message: unexpected };
-    }
-    const outcome = result.outcome;
-    if (result.status !== 0 || !outcome.ok) {
-        // The `outcome.ok && status !== 0` combination cannot arise from
-        // successResult/failureResult, so it gets its own hand-written message
-        // rather than falling through to a replay that would print nothing.
-        return {
-            ok: false,
-            result,
-            message: outcome.ok ? invalidStatus : null,
-        };
-    }
-    try {
-        if (!valid(outcome.result)) {
-            return { ok: false, result, message: invalidStatus };
-        }
-    }
-    catch {
-        return { ok: false, result, message: invalidStatus };
-    }
-    return { ok: true, result: { status: result.status, outcome } };
-}
-// Runs every step that can throw or fail closed, returning the outcome as
-// data. It performs no writes of its own, so nothing inside runProbe's try can
-// raise EPIPE — the same shape as src/commands/unpin.ts's attemptUnpin.
-//
-// The outcomes are CARRIED OUT rather than replayed in place, for that same
-// reason: replayOutcome writes to ctx, and a write inside this try could
-// raise EPIPE and be caught and relabelled as a selection failure. runProbe
-// replays them, in collection order, after the try/catch has resolved. The
-// operator-visible result is identical -- probe emits nothing else until the
-// very end -- and the EPIPE hazard never exists.
-// Exported for src/commands/install.ts and src/commands/update.ts, which need
-// probe's FACTS rather than its rendering. The historical
-// `git show ad56569a4c161e7b122967442e2b026eeb6395f6:scripts/core/lifecycle.sh:39-41::spw_probe_field`
-// implementation awk-parsed the porcelain back into fields; that round trip is
-// gone.
+// Collect outcomes without writing so output failures cannot be classified as
+// inspection failures. Replay collected outcomes after gathering completes.
 export async function gatherProbe(ctx) {
-    // Order mirrors `git show ad56569a4c161e7b122967442e2b026eeb6395f6:scripts/probe:24-40::spw_compute_effective_selection` exactly.
     const selection = ctx.selection ?? (await computeEffectiveSelection(ctx.root, ctx.env));
     const outcomes = [];
     const adapterContext = { root: ctx.root, env: ctx.env };
@@ -196,19 +45,28 @@ export async function gatherProbe(ctx) {
     const before = resources === null
         ? []
         : await ctx.coordination.observeResources(resources);
-    const collect = async (call, unexpected, invalidStatus, valid, replaySuccess = true) => {
-        const result = await inspect(call, unexpected, invalidStatus, valid);
+    const collect = async (call, unexpected, invalidStatus, acceptValue, replaySuccess = true) => {
+        let result = await callAdapter(call, { unexpected, invalidStatus });
+        if (result.ok && acceptValue !== undefined) {
+            try {
+                if (!acceptValue(result.result.outcome.result))
+                    result = { ok: false, result: result.result, message: invalidStatus };
+            }
+            catch {
+                result = { ok: false, result: result.result, message: invalidStatus };
+            }
+        }
         if (result.result !== null && (replaySuccess || !result.result.outcome.ok))
             outcomes.push(result.result.outcome);
         return result;
     };
-    const prepared = await collect(() => ctx.adapter.inspectPrepared(selection, adapterContext), "cannot inspect prepared harness state", "adapter reported a failure status for prepared harness inspection", validPrepared);
+    const prepared = await collect(() => ctx.adapter.inspectPrepared(selection, adapterContext), "cannot inspect prepared harness state", "adapter reported a failure status for prepared harness inspection");
     if (!prepared.ok) {
         return { status: 1, outcomes, message: prepared.message };
     }
     const failure = (site) => ctx.adapter.presentation.callFailure(site, adapterContext);
     const installedFailure = failure("probe-installed");
-    const installed = await collect(() => ctx.adapter.inspectInstalled(selection, adapterContext), installedFailure.unexpected, installedFailure.invalidStatus, validInstalled);
+    const installed = await collect(() => ctx.adapter.inspectInstalled(selection, adapterContext), installedFailure.unexpected, installedFailure.invalidStatus);
     if (!installed.ok) {
         return { status: 1, outcomes, message: installed.message };
     }
@@ -219,22 +77,22 @@ export async function gatherProbe(ctx) {
             message: "cannot determine harness observation resources",
         };
     const ownershipFailure = failure("probe-ownership");
-    const ownership = await collect(() => ctx.adapter.inspectOwnership(adapterContext), ownershipFailure.unexpected, ownershipFailure.invalidStatus, validOwnership);
+    const ownership = await collect(() => ctx.adapter.inspectOwnership(adapterContext), ownershipFailure.unexpected, ownershipFailure.invalidStatus);
     if (!ownership.ok) {
         return { status: 1, outcomes, message: ownership.message };
     }
     const controlFailure = failure("probe-control");
-    const control = await collect(() => ctx.adapter.inspectUpdateControl(adapterContext), controlFailure.unexpected, controlFailure.invalidStatus, validControl);
+    const control = await collect(() => ctx.adapter.inspectUpdateControl(adapterContext), controlFailure.unexpected, controlFailure.invalidStatus, coherentControl);
     if (!control.ok) {
         return { status: 1, outcomes, message: control.message };
     }
-    const preparedAfter = await collect(() => ctx.adapter.inspectPrepared(selection, adapterContext), "cannot inspect prepared harness state", "adapter reported a failure status for prepared harness inspection", validPrepared, false);
+    const preparedAfter = await collect(() => ctx.adapter.inspectPrepared(selection, adapterContext), "cannot inspect prepared harness state", "adapter reported a failure status for prepared harness inspection", undefined, false);
     if (!preparedAfter.ok)
         return { status: 1, outcomes, message: preparedAfter.message };
-    const installedAfter = await collect(() => ctx.adapter.inspectInstalled(selection, adapterContext), installedFailure.unexpected, installedFailure.invalidStatus, validInstalled, false);
+    const installedAfter = await collect(() => ctx.adapter.inspectInstalled(selection, adapterContext), installedFailure.unexpected, installedFailure.invalidStatus, undefined, false);
     if (!installedAfter.ok)
         return { status: 1, outcomes, message: installedAfter.message };
-    const controlAfter = await collect(() => ctx.adapter.inspectUpdateControl(adapterContext), controlFailure.unexpected, controlFailure.invalidStatus, validControl, false);
+    const controlAfter = await collect(() => ctx.adapter.inspectUpdateControl(adapterContext), controlFailure.unexpected, controlFailure.invalidStatus, coherentControl, false);
     if (!controlAfter.ok)
         return { status: 1, outcomes, message: controlAfter.message };
     const after = await ctx.coordination.observeResources(resources);
@@ -270,7 +128,6 @@ export async function gatherProbe(ctx) {
             ownership: ownership.result.outcome.result,
             control: control.result.outcome.result,
             compatibility: preparedState.compatibility,
-            resources: after,
             resourceState: control.result.outcome.result.recoveryState === "required"
                 ? "recovery-required"
                 : after.some((observation) => observation.state === "owned")
@@ -285,16 +142,8 @@ export async function gatherProbe(ctx) {
     };
 }
 export async function runProbe(argv, ctx) {
-    // `git show ad56569a4c161e7b122967442e2b026eeb6395f6:scripts/probe:42::porcelain` tested only `[ "${1:-}" = "--porcelain" ]`, so a typo'd
-    // flag silently produced human output. Rejecting it is a deliberate
-    // narrowing from the historical shell behavior.
-    //
-    // This guard is NOT the production path. src/cli.ts's parseArgs rejects the
-    // same inputs first, before preflight, with the usage block the CLI's other
-    // usage errors carry — exactly the arrangement track-latest and unpin have,
-    // where the in-module check is an unreachable-from-CLI duplicate. It stays
-    // because runProbe is also called directly by tests and by any future
-    // in-process caller that has not been through parseArgs.
+    // The CLI parser rejects these inputs first. Keep this guard for direct
+    // in-process callers, which do not necessarily pass through that parser.
     const porcelain = argv.length === 1 && argv[0] === "--porcelain";
     if (!porcelain && argv.length !== 0) {
         ctx.stderr.write(PROBE_USAGE);
@@ -305,90 +154,14 @@ export async function runProbe(argv, ctx) {
         outcome = await gatherProbe(ctx);
     }
     catch (cause) {
-        // Hand-written messages, per AGENTS.md's reader-diagnostics rule. Reachable
-        // here: the selectionErrors validateSource raises
-        // (`src/selection.ts:137::malformed`, :140, requireSingleLineString at :77),
-        // reached from
-        // computeEffectiveSelection's validateSource call
-        // (src/effective-selection.ts); the ones validateRecord raises
-        // (`src/selection.ts:198::integer`, :219, requireObject at :47, requireExactKeys at
-        // :64, validatePinnedRecord at :170-183), reached from
-        // `src/selection-store.ts:103::return validateRecord` on the read path; the
-        // selectionErrors requireAbsolute and selectionConfigDir
-        // (src/effective-selection.ts) raise
-        // for a non-absolute or missing config directory; readConfigRef's `cannot
-        // read packaged upstream ref <path>` (src/upstream.ts); and resolveRef's own
-        // two no-match diagnostics, `no stable semver tag found for latest-release`
-        // and `cannot resolve upstream ref: <ref>` (src/upstream.ts). normalizeSaved
-        // (`src/selection.ts:222-241::normalizeSaved`) throws nothing at all.
-        //
-        // THREE exceptions, all inherited and none a regression:
-        //   1. resolveRef splices git's combined stdout+stderr into its own text
-        //      (its three `cannot query upstream ...` throws, src/upstream.ts),
-        //      reached via computeEffectiveSelection's resolveRef call
-        //      (src/effective-selection.ts). The packaged ref is `latest-release`,
-        //      which resolveRef answers with an ls-remote, so an ordinary unpinned
-        //      run reaches this rather than only an exotic corner -- though not
-        //      every unpinned run does: resolveRef's COMMIT_INPUT_RE branch returns
-        //      before any runGit call, so a 40-hex requested ref splices nothing.
-        //      Pinned by
-        //      `tests/unit/upstream.test.ts:453::void test("resolveRef reports a query failure for latest`,
-        //      :471, and :483.
-        //   2. The
-        //      `src/selection-store.ts:120-124::cause.module === "selection") {`
-        //      site (same shape at :49, :86, :98) is the module AGENTS.md's
-        //      `src/selection-store.ts` bullet grandfathers:
-        //      it interpolates the caught error's own message, so Node errno
-        //      prose can reach this stream. Reached on the READ path only, via
-        //      loadSavedSelection (src/effective-selection.ts) ->
-        //      readSelectionState
-        //      (`src/selection-store.ts:149::export async function readSelectionState`).
-        //      This module's four write-only interpolating sites -- ensureStateDirectory
-        //      (:172), finalStateDiagnostic (:197), and the two in
-        //      writeSelectionState's own catch (:225, :231) -- are all
-        //      unreachable from probe, which never writes.
-        //   3. Every runGit call site inside resolveRef (src/upstream.ts) can
-        //      reject instead of resolving. On the non-ENOENT arm of
-        //      `src/git.ts:47-52::if (typeof`, runGit builds the message
-        //      "cannot run git: " followed by the Node spawn error's own message
-        //      (:51) and rejects with a SafetyError carrying it (:52), so that
-        //      Node spawn-level text reaches ctx.stderr through this catch. The
-        //      ENOENT arm (:50) is hand-written and carries nothing. A non-zero
-        //      *exit status* is handled by exception 1 above; this is the
-        //      *spawn-level* case, where runGit throws rather than returning a
-        //      status.
-        //
-        // oneLine() at this catch collapses each of exceptions 1 and 3 -- the two
-        // carrying git-derived text -- to a single line. It collapses CR/LF only,
-        // so it bounds how much of that text lands, not what it may contain.
-        //
-        // fetchExactCommit is deliberately NOT in this list, unlike prepare's
-        // fetchExactCommit exception, which runPrepare's catch block documents.
-        // Its only remaining caller is gatherPrepare's call in
-        // src/commands/prepare.ts (git grep -n fetchExactCommit -- src/ is the
-        // check that keeps "only" true), so probe never reaches it and
-        // its splice sites cannot appear on this stream. Do not add it back by
-        // symmetry with prepare.
-        //
-        // generatedCommitOrEmpty is not in this list either: it cannot throw at
-        // all. It (src/provenance.ts) delegates to readGeneratedCommitLenient,
-        // which catches every failure and returns "".
-        //
-        // A non-AdapterFailure re-thrown by runCodexOperation's closing `throw cause`
-        // (src/harnesses/codex/adapter.ts) does NOT reach here: inspect() catches it and converts
-        // it to a hand-written message per AGENTS.md's reader-diagnostics rule -- a
-        // rethrown cause is exactly the failure src/harnesses/codex/adapter.ts declined to own, so
-        // its text must never reach this stream. See §3.3a.
-        //
-        // gatherProbe performs no writes of its own, so this catch cannot also be
-        // reached by an EPIPE from probe's own output — every write below runs
-        // only after this try/catch has resolved.
+        // Reader wrappers supply their own diagnostics. The saved-selection read
+        // path retains its sanctioned interpolation at
+        // `src/selection-store.ts:116-121::if (cause instanceof SafetyError && cause.module === "selection") {`.
+        // oneLine() bounds any inherited git or filesystem diagnostic to one line.
         ctx.stderr.write(`error: ${oneLine(cause)}\n`);
         return 1;
     }
-    // Replay first, on both paths: the shell validator replayed every response's
-    // messages whether or not that response was a failure at
-    // `git show ad56569a4c161e7b122967442e2b026eeb6395f6:scripts/core/validate-adapter-response.py:268::replay(messages)`.
+    // Replay before reporting a command-level result on either path.
     for (const each of outcome.outcomes)
         replayOutcome(each, ctx);
     if (outcome.status === 1) {

package/dist/commands/track-latest.js

@@ -15,7 +15,7 @@ export async function runTrackLatest(argv, ctx) {
         // writing, under "Invalid existing state must block overwrite" —
         // readSelectionState's own readOpenedRecord/parseRecordBytes is what
         // validates an existing record, via validateRecord at
-        // `src/selection-store.ts:103::return validateRecord`). Calling loadSavedSelection here preserves
+        // `src/selection-store.ts:99::return validateRecord`). Calling loadSavedSelection here preserves
         // `git show 349fe2ed405b371ec2de1347bb3fc50c6bc15dc4:scripts/track-latest:20-21::read`'s read-then-write shape, so this command
         // stays fail-closed on its own terms rather than solely by depending on
         // the store's internals.