@lannguyensi/harness 0.56.0 → 0.58.0

package/dist/io/project-name.js

@@ -0,0 +1,158 @@
+// `{project}` value validation and safe display, shared by every
+// `{project}`-shaped interpolation sink.
+//
+// Lives in `src/io/` rather than `src/runtime/` (where `isValidProjectName`
+// and `sanitizeProjectForDisplay` originated, task `c88461c1`) because
+// `buildLockEntries` (`src/io/harness-lock.ts`, task `b5e6ccb0`) is itself
+// one of those sinks, and `io/` may not import from `runtime/`
+// (`io-no-upward-imports`, `.dependency-cruiser.cjs`). This is the same
+// relocation pattern `.dependency-cruiser.cjs`'s header comment already
+// documents for `src/policies/duration.ts`, `src/policies/extract.ts`,
+// `src/runtime/ledger-record.ts` and `src/runtime/expand-home.ts`: a
+// utility needed below its original layer moves down rather than the
+// importing layer's boundary being relaxed. `src/runtime/git-context.ts`
+// re-exports both names so every existing consumer that imports them from
+// `../runtime/git-context.js` keeps working unchanged.
+/**
+ * Every C0 control character (U+0000 to U+001F, so NUL, LF, CR and ESC
+ * among them), DEL (U+007F), and every C1 control character (U+0080 to
+ * U+009F, NEL included). Shared by {@link isValidProjectName}, which
+ * rejects a name carrying one, and {@link sanitizeProjectForDisplay},
+ * which strips them from a name that was already rejected and is being
+ * echoed back.
+ */
+const PROJECT_NAME_CONTROL_CHARS = /[\u0000-\u001f\u007f-\u009f]/;
+/**
+ * {@link PROJECT_NAME_CONTROL_CHARS} with the `g` flag, for
+ * `String.prototype.replace`. Two objects built from one source rather
+ * than one shared `g`-flagged regex, because a `g`-flagged regex carries
+ * a stateful `lastIndex` that makes `.test()` alternate between hits and
+ * misses across calls.
+ */
+const PROJECT_NAME_CONTROL_CHARS_GLOBAL = new RegExp(PROJECT_NAME_CONTROL_CHARS.source, "g");
+/**
+ * Is `name` usable as a `{project}` value at all: both as an on-disk
+ * directory component (`<home>/projects/<name>/harness.overrides.yaml`,
+ * `resolvePaths`, `src/cli/loader.ts`) and as a value that will end up
+ * inside rendered CLI output? Two independent screens, both applied here
+ * at the SOURCE rather than at each consumer:
+ *
+ *  - PATH ESCAPE. Rejects the empty string, `"."`, and `".."` (the two
+ *    `path.join` special-cases that either no-op or climb a level,
+ *    `".."` being exactly the shape a crafted, un-normalized `commondir`
+ *    used to produce before the fix above), plus any name containing a
+ *    forward slash or a backslash (Windows separator; POSIX permits a
+ *    literal backslash IN a directory name, so this is not redundant
+ *    with the platform's own path parsing).
+ *  - CONTROL CHARACTERS. Rejects any name containing one of
+ *    {@link PROJECT_NAME_CONTROL_CHARS}, NUL included (which is why
+ *    there is no separate NUL clause). A newline would forge an extra,
+ *    diagnostic-looking line of caller-chosen text wherever the value is
+ *    rendered, an ESC would write raw terminal escapes into the
+ *    operator's terminal, and a CR would overwrite the line it landed
+ *    on. Screening here rather than at each rendering site is what makes
+ *    "an accepted project name is a plain single-line string" a property
+ *    of the VALUE: it also covers the surfaces that render the
+ *    SUBSTITUTED memory directory path rather than the name itself
+ *    (`harness doctor`'s "memory directory missing" line,
+ *    `src/cli/doctor/format.ts`; `harness list memories`' `path` row
+ *    field, `src/cli/list.ts`), which no per-site escaper of the name
+ *    would ever have reached.
+ *
+ * A name that passes both screens may still not exist on disk
+ * (`resolvePaths` already handles that with `fs.existsSync`); this only
+ * guards against the value escaping the single path segment it is meant
+ * to occupy and against it carrying control characters anywhere
+ * downstream.
+ *
+ * WHAT A REJECTION LOOKS LIKE. `deriveProjectName` (`src/runtime/git-
+ * context.ts`) validates its own return value at every exit, so a
+ * checkout directory whose basename contains a control character now
+ * takes the same path a `".."` basename already took: the helper returns
+ * `null`, no project override layer is looked up for that repository,
+ * and the base/machine value applies unchanged. There is no error and no
+ * warning; the operator sees the host-wide value instead of a per-repo
+ * one (`harness doctor`'s setup-version finding then carries
+ * `projectName: null` and renders no `(project: X)` suffix). An explicit
+ * `--project` carrying a control character is instead reported:
+ * `resolvePaths` resolves no project layer for it, and
+ * `substituteProject` (`src/probes/memory.ts`) degrades to the "no
+ * project supplied" branch, which `harness doctor` surfaces as its
+ * rejected-`--project` warn line.
+ *
+ * Exported (task c88461c1, review round 3 residual; task `1c4eb3ea`
+ * of the batch-44 follow-up run) so `resolvePaths` (`src/cli/loader.ts`)
+ * can apply the SAME guard at its own `path.join` sink, defense in
+ * depth: this function already rejects an unsafe name at every
+ * `deriveProjectName` exit, but an `opts.project` reaching
+ * `resolvePaths`' OWN sink from anywhere else (a caller building
+ * `LoaderOptions` by hand, a future producer) had no equivalent check
+ * of its own until now. Applied a THIRD time at `substituteProject`'s
+ * own sink (`src/probes/memory.ts`, task `e904f25a`): an invalid name
+ * there degrades to the "no project supplied" branch instead of being
+ * interpolated into the `{project}` placeholder. Applied a FOURTH time
+ * at `buildLockEntries`' own sink (`src/io/harness-lock.ts`, task
+ * `b5e6ccb0`): an invalid name there skips the templated directory's
+ * lock entry instead of the raw value being interpolated into the path
+ * this function stats, hashes and writes into `harness.lock`.
+ * `resolvePaths`, `substituteProject` and `buildLockEntries` are now all
+ * guarded; one `{project}` sink is NOT: `generate-memory-index.ts`'s own
+ * substitution still interpolates an operator-supplied `--project` value
+ * into a path unvalidated, left unguarded (reached only via the explicit
+ * CLI flag, not this module's derivation; see CHANGELOG.md for the
+ * reservation/follow-up). That one call site calls this function
+ * nowhere, so it inherits NOTHING from the control-character screen
+ * above either: a caller reading this comment should not assume this
+ * function guards every `{project}`-shaped sink in the codebase, for
+ * path escapes or for control characters.
+ */
+export function isValidProjectName(name) {
+    if (name.length === 0)
+        return false;
+    if (name === "." || name === "..")
+        return false;
+    if (PROJECT_NAME_CONTROL_CHARS.test(name))
+        return false;
+    return !name.includes("/") && !name.includes("\\");
+}
+/**
+ * Renders a REJECTED project name safe to interpolate into one line of
+ * CLI output. The invariant this helper is half of has two parts, and
+ * they are complementary rather than overlapping (task `e904f25a`):
+ *
+ *  - An ACCEPTED name cannot carry a control character at all.
+ *    {@link isValidProjectName} rejects C0, DEL and C1 at the source, so
+ *    every value that survives validation is already a plain
+ *    single-line string wherever it, or a path it was substituted into,
+ *    is rendered. Nothing downstream of the validator has to enumerate
+ *    its own rendering sites to stay safe.
+ *  - A REJECTED name is by definition unvalidated, and it is still
+ *    echoed back so the operator can see WHICH value was refused. Every
+ *    such echo goes through this helper: `harness doctor`'s
+ *    rejected-`--project` warn line and its per-directory note
+ *    (`src/cli/doctor/format.ts`), doctor's header `project:` clause
+ *    (which renders the raw `--project` whether it was accepted or
+ *    rejected), and `harness list memories`' `project_rejected` row
+ *    field (`src/cli/list.ts`, and with it the text table derived from
+ *    it).
+ *
+ * The `session_start_preflight.setup` finding's `(project: X)` suffix is
+ * also wrapped, as defense in depth rather than as an echo of a rejected
+ * value: `harness doctor` sets that finding's `projectName` only when
+ * `resolvePaths` actually resolved a project layer FILE, which requires
+ * the name to have passed {@link isValidProjectName} first. The wrap
+ * stays so a hand-built finding or a future producer cannot reintroduce
+ * a forged line through that one call site.
+ *
+ * Strips (rather than escapes) every character in
+ * {@link PROJECT_NAME_CONTROL_CHARS}. A name with no control character
+ * (`..`, `a/b`, every ordinary shape) passes through unchanged. Report
+ * DATA keeps the raw value (`DoctorReport.project`,
+ * `MemoryReport.projectRejected`), so a `--json` consumer still reads
+ * back exactly what the operator passed, carried by JSON's own escaping
+ * rather than by a raw control byte.
+ */
+export function sanitizeProjectForDisplay(name) {
+    return name.replace(PROJECT_NAME_CONTROL_CHARS_GLOBAL, "");
+}
+//# sourceMappingURL=project-name.js.map

package/dist/io/project-name.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"project-name.js","sourceRoot":"","sources":["../../src/io/project-name.ts"],"names":[],"mappings":"AAAA,iEAAiE;AACjE,yCAAyC;AACzC,EAAE;AACF,4EAA4E;AAC5E,uEAAuE;AACvE,2EAA2E;AAC3E,+DAA+D;AAC/D,wEAAwE;AACxE,wEAAwE;AACxE,uEAAuE;AACvE,qEAAqE;AACrE,qEAAqE;AACrE,yEAAyE;AACzE,0EAA0E;AAC1E,uDAAuD;AAEvD;;;;;;;GAOG;AACH,MAAM,0BAA0B,GAAG,8BAA8B,CAAC;AAElE;;;;;;GAMG;AACH,MAAM,iCAAiC,GAAG,IAAI,MAAM,CAAC,0BAA0B,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;AAE7F;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2EG;AACH,MAAM,UAAU,kBAAkB,CAAC,IAAY;IAC7C,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IACpC,IAAI,IAAI,KAAK,GAAG,IAAI,IAAI,KAAK,IAAI;QAAE,OAAO,KAAK,CAAC;IAChD,IAAI,0BAA0B,CAAC,IAAI,CAAC,IAAI,CAAC;QAAE,OAAO,KAAK,CAAC;IACxD,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;AACrD,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,MAAM,UAAU,yBAAyB,CAAC,IAAY;IACpD,OAAO,IAAI,CAAC,OAAO,CAAC,iCAAiC,EAAE,EAAE,CAAC,CAAC;AAC7D,CAAC"}

package/dist/io/read-json-dir-entries.js

@@ -3,6 +3,16 @@ import * as path from "node:path";
 import { readRegularFileRejectingSymlink } from "./read-regular-file.js";
 import { safeJsonParse } from "./safe-json-parse.js";
 export function readJsonDirEntriesRejectingSymlinks(dir, opts) {
+    let dirStat;
+    try {
+        dirStat = fs.lstatSync(dir);
+    }
+    catch {
+        return { dirPresent: false, entries: [], unreadableCount: 0 };
+    }
+    if (!dirStat.isDirectory()) {
+        return { dirPresent: false, entries: [], unreadableCount: 0 };
+    }
     let dirents;
     try {
         dirents = fs.readdirSync(dir, { withFileTypes: true });

package/dist/io/read-json-dir-entries.js.map

@@ -1 +1 @@
-{"version":3,"file":"read-json-dir-entries.js","sourceRoot":"","sources":["../../src/io/read-json-dir-entries.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,SAAS,CAAC;AAC9B,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAClC,OAAO,EAAE,+BAA+B,EAAE,MAAM,wBAAwB,CAAC;AACzE,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAuCrD,MAAM,UAAU,mCAAmC,CACjD,GAAW,EACX,IAAkC;IAElC,IAAI,OAAoB,CAAC;IACzB,IAAI,CAAC;QACH,OAAO,GAAG,EAAE,CAAC,WAAW,CAAC,GAAG,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,CAAC;IACzD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,UAAU,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE,EAAE,eAAe,EAAE,CAAC,EAAE,CAAC;IAChE,CAAC;IAED,MAAM,OAAO,GAAQ,EAAE,CAAC;IACxB,IAAI,eAAe,GAAG,CAAC,CAAC;IAExB,KAAK,MAAM,CAAC,IAAI,OAAO,EAAE,CAAC;QACxB,MAAM,IAAI,GAAG,CAAC,CAAC,IAAI,CAAC;QACpB,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC,IAAI,CAAC;YAAE,SAAS;QAEhC,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;QAClC,MAAM,IAAI,GAAG,+BAA+B,CAAC,IAAI,CAAC,CAAC;QACnD,IAAI,IAAI,CAAC,IAAI,KAAK,SAAS,IAAI,IAAI,CAAC,IAAI,KAAK,aAAa,IAAI,IAAI,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;YACtF,SAAS;QACX,CAAC;QACD,IAAI,IAAI,CAAC,IAAI,KAAK,YAAY,EAAE,CAAC;YAC/B,eAAe,EAAE,CAAC;YAClB,SAAS;QACX,CAAC;QACD,MAAM,MAAM,GAAG,aAAa,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QAC3C,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;QACvC,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;YACnB,eAAe,EAAE,CAAC;YAClB,SAAS;QACX,CAAC;QACD,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IACtB,CAAC;IAED,OAAO,EAAE,UAAU,EAAE,IAAI,EAAE,OAAO,EAAE,eAAe,EAAE,CAAC;AACxD,CAAC"}
+{"version":3,"file":"read-json-dir-entries.js","sourceRoot":"","sources":["../../src/io/read-json-dir-entries.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,SAAS,CAAC;AAC9B,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAClC,OAAO,EAAE,+BAA+B,EAAE,MAAM,wBAAwB,CAAC;AACzE,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAuCrD,MAAM,UAAU,mCAAmC,CACjD,GAAW,EACX,IAAkC;IAElC,IAAI,OAAiB,CAAC;IACtB,IAAI,CAAC;QACH,OAAO,GAAG,EAAE,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC;IAC9B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,UAAU,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE,EAAE,eAAe,EAAE,CAAC,EAAE,CAAC;IAChE,CAAC;IACD,IAAI,CAAC,OAAO,CAAC,WAAW,EAAE,EAAE,CAAC;QAC3B,OAAO,EAAE,UAAU,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE,EAAE,eAAe,EAAE,CAAC,EAAE,CAAC;IAChE,CAAC;IACD,IAAI,OAAoB,CAAC;IACzB,IAAI,CAAC;QACH,OAAO,GAAG,EAAE,CAAC,WAAW,CAAC,GAAG,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,CAAC;IACzD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,UAAU,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE,EAAE,eAAe,EAAE,CAAC,EAAE,CAAC;IAChE,CAAC;IAED,MAAM,OAAO,GAAQ,EAAE,CAAC;IACxB,IAAI,eAAe,GAAG,CAAC,CAAC;IAExB,KAAK,MAAM,CAAC,IAAI,OAAO,EAAE,CAAC;QACxB,MAAM,IAAI,GAAG,CAAC,CAAC,IAAI,CAAC;QACpB,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC,IAAI,CAAC;YAAE,SAAS;QAEhC,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;QAClC,MAAM,IAAI,GAAG,+BAA+B,CAAC,IAAI,CAAC,CAAC;QACnD,IAAI,IAAI,CAAC,IAAI,KAAK,SAAS,IAAI,IAAI,CAAC,IAAI,KAAK,aAAa,IAAI,IAAI,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;YACtF,SAAS;QACX,CAAC;QACD,IAAI,IAAI,CAAC,IAAI,KAAK,YAAY,EAAE,CAAC;YAC/B,eAAe,EAAE,CAAC;YAClB,SAAS;QACX,CAAC;QACD,MAAM,MAAM,GAAG,aAAa,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QAC3C,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;QACvC,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;YACnB,eAAe,EAAE,CAAC;YAClB,SAAS;QACX,CAAC;QACD,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IACtB,CAAC;IAED,OAAO,EAAE,UAAU,EAAE,IAAI,EAAE,OAAO,EAAE,eAAe,EAAE,CAAC;AACxD,CAAC"}

package/dist/io/version-compare.d.ts

@@ -22,3 +22,62 @@
 export declare const NUMERIC_VERSION_PATTERN: RegExp;
 export declare const NUMERIC_VERSION_MESSAGE = "min_version must be numeric semver-shape: digits separated by up to three dots (e.g. \"1\", \"1.2\", \"1.2.3\", \"1.2.3.4\"). Pre-release suffixes and leading \"v\" are rejected.";
 export declare function compareNumericVersions(a: string, b: string): number;
+/**
+ * Extracts a numeric-semver-shape version from free-form `--version`
+ * probe output (e.g. "preflight 0.6.0-rc.1\n"), plus whether the
+ * matched numeric run was immediately followed by a `-` prerelease/
+ * build suffix. Matches ONLY the leading numeric run itself (mirrors
+ * the pre-existing `/(\d+(?:\.\d+){0,3})/` extraction every version
+ * floor check used before task 65952a0c), so `version` here is exactly
+ * what a plain, non-prerelease-aware caller would have parsed; the
+ * `isPrerelease` flag is the new information a caller can act on.
+ *
+ * Returns `null` when no numeric run is found at all (unparseable
+ * probe output), matching the pre-existing "no match" contract.
+ *
+ * Two suffix strings are returned, deliberately different:
+ * - `raw` is the regex's own match (`m[0]`): the numeric run plus a
+ *   `-` suffix restricted to `[0-9A-Za-z.]`, so it TRUNCATES a suffix
+ *   containing any other character (a git-describe suffix's second
+ *   hyphen, e.g. "0.6.0-4-gabc123" matches only as far as "0.6.0-4";
+ *   a platform suffix, e.g. "0.6.0-linux-x64" matches only as far as
+ *   "0.6.0-linux"). Kept only because `isPrerelease` is derived from
+ *   whether `m[2]` (the restricted suffix group) matched at all.
+ * - `token` is the full probed version token as printed: everything
+ *   from the start of the numeric run up to the next whitespace
+ *   character (or end of string), with no character-class
+ *   restriction. This is what a human-facing message should quote;
+ *   `raw`'s truncation would otherwise misreport what the probe
+ *   actually printed. See docs/decisions/2026-09-08-preflight-floors.md.
+ */
+export declare function parseProbedVersion(stdout: string): {
+    version: string;
+    isPrerelease: boolean;
+    raw: string;
+    token: string;
+} | null;
+/**
+ * `compareNumericVersions`, but a prerelease `a` (as reported by
+ * `parseProbedVersion`'s `isPrerelease`) is treated as strictly BELOW
+ * a numerically-equal `b` floor, matching semver precedence
+ * (`0.6.0-rc.1 < 0.6.0`) and the intent every `min_version` floor in
+ * this codebase already carries: `NUMERIC_VERSION_PATTERN` rejects a
+ * prerelease shape for `b` itself (a `min_version` field can never
+ * BE a prerelease), so `aIsPrerelease` is the only side this can ever
+ * apply to. When the base numeric comparison is not a tie, the
+ * prerelease flag is irrelevant and the numeric result wins outright
+ * (a genuinely older release, prerelease or not, is still older).
+ *
+ * Decision: docs/decisions/2026-09-08-preflight-floors.md (see the
+ * Reopen criteria section for task db44ab46, which extended the rule
+ * from its original two consumers to all `min_version` floor checks in
+ * this codebase). Consumers as of task db44ab46: `checkHookVersion` and
+ * `checkCli`'s `tools.cli[]` check plus `checkMcpVersions`'s
+ * `tools.mcp[]` check (all in src/cli/doctor/index.ts),
+ * `checkSessionStartPreflightSetupVersion`
+ * (src/cli/doctor/session-start-preflight-setup-version.ts), validate's
+ * `tools.cli[]` check (src/cli/validate/checks.ts), `memory.router`'s
+ * version probe (src/probes/memory.ts), and the pack-level floor
+ * (src/policy-packs/version-check.ts).
+ */
+export declare function compareVersionFloor(a: string, aIsPrerelease: boolean, b: string): number;

package/dist/io/version-compare.js

@@ -37,4 +37,71 @@ export function compareNumericVersions(a, b) {
     }
     return 0;
 }
+/**
+ * Extracts a numeric-semver-shape version from free-form `--version`
+ * probe output (e.g. "preflight 0.6.0-rc.1\n"), plus whether the
+ * matched numeric run was immediately followed by a `-` prerelease/
+ * build suffix. Matches ONLY the leading numeric run itself (mirrors
+ * the pre-existing `/(\d+(?:\.\d+){0,3})/` extraction every version
+ * floor check used before task 65952a0c), so `version` here is exactly
+ * what a plain, non-prerelease-aware caller would have parsed; the
+ * `isPrerelease` flag is the new information a caller can act on.
+ *
+ * Returns `null` when no numeric run is found at all (unparseable
+ * probe output), matching the pre-existing "no match" contract.
+ *
+ * Two suffix strings are returned, deliberately different:
+ * - `raw` is the regex's own match (`m[0]`): the numeric run plus a
+ *   `-` suffix restricted to `[0-9A-Za-z.]`, so it TRUNCATES a suffix
+ *   containing any other character (a git-describe suffix's second
+ *   hyphen, e.g. "0.6.0-4-gabc123" matches only as far as "0.6.0-4";
+ *   a platform suffix, e.g. "0.6.0-linux-x64" matches only as far as
+ *   "0.6.0-linux"). Kept only because `isPrerelease` is derived from
+ *   whether `m[2]` (the restricted suffix group) matched at all.
+ * - `token` is the full probed version token as printed: everything
+ *   from the start of the numeric run up to the next whitespace
+ *   character (or end of string), with no character-class
+ *   restriction. This is what a human-facing message should quote;
+ *   `raw`'s truncation would otherwise misreport what the probe
+ *   actually printed. See docs/decisions/2026-09-08-preflight-floors.md.
+ */
+export function parseProbedVersion(stdout) {
+    const m = stdout.match(/(\d+(?:\.\d+){0,3})(-[0-9A-Za-z.]+)?/);
+    if (!m || !m[1] || m.index === undefined)
+        return null;
+    const rest = stdout.slice(m.index);
+    const wsIndex = rest.search(/\s/);
+    const token = wsIndex === -1 ? rest : rest.slice(0, wsIndex);
+    return { version: m[1], isPrerelease: m[2] !== undefined, raw: m[0], token };
+}
+/**
+ * `compareNumericVersions`, but a prerelease `a` (as reported by
+ * `parseProbedVersion`'s `isPrerelease`) is treated as strictly BELOW
+ * a numerically-equal `b` floor, matching semver precedence
+ * (`0.6.0-rc.1 < 0.6.0`) and the intent every `min_version` floor in
+ * this codebase already carries: `NUMERIC_VERSION_PATTERN` rejects a
+ * prerelease shape for `b` itself (a `min_version` field can never
+ * BE a prerelease), so `aIsPrerelease` is the only side this can ever
+ * apply to. When the base numeric comparison is not a tie, the
+ * prerelease flag is irrelevant and the numeric result wins outright
+ * (a genuinely older release, prerelease or not, is still older).
+ *
+ * Decision: docs/decisions/2026-09-08-preflight-floors.md (see the
+ * Reopen criteria section for task db44ab46, which extended the rule
+ * from its original two consumers to all `min_version` floor checks in
+ * this codebase). Consumers as of task db44ab46: `checkHookVersion` and
+ * `checkCli`'s `tools.cli[]` check plus `checkMcpVersions`'s
+ * `tools.mcp[]` check (all in src/cli/doctor/index.ts),
+ * `checkSessionStartPreflightSetupVersion`
+ * (src/cli/doctor/session-start-preflight-setup-version.ts), validate's
+ * `tools.cli[]` check (src/cli/validate/checks.ts), `memory.router`'s
+ * version probe (src/probes/memory.ts), and the pack-level floor
+ * (src/policy-packs/version-check.ts).
+ */
+export function compareVersionFloor(a, aIsPrerelease, b) {
+    const cmp = compareNumericVersions(a, b);
+    if (cmp !== 0)
+        return cmp;
+    return aIsPrerelease ? -1 : 0;
+}
 //# sourceMappingURL=version-compare.js.map

package/dist/io/version-compare.js.map

@@ -1 +1 @@
-{"version":3,"file":"version-compare.js","sourceRoot":"","sources":["../../src/io/version-compare.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG,qBAAqB,CAAC;AAE7D,MAAM,CAAC,MAAM,uBAAuB,GAClC,0KAA0K,CAAC;AAE7K,MAAM,UAAU,sBAAsB,CAAC,CAAS,EAAE,CAAS;IACzD,MAAM,EAAE,GAAG,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC;IAC3D,MAAM,EAAE,GAAG,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC;IAC3D,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,CAAC;IAC3C,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC;QAC7B,MAAM,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;QACtB,MAAM,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;QACtB,IAAI,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,IAAI,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC;YAAE,OAAO,CAAC,CAAC;QACnD,IAAI,EAAE,GAAG,EAAE;YAAE,OAAO,CAAC,CAAC;QACtB,IAAI,EAAE,GAAG,EAAE;YAAE,OAAO,CAAC,CAAC,CAAC;IACzB,CAAC;IACD,OAAO,CAAC,CAAC;AACX,CAAC"}
+{"version":3,"file":"version-compare.js","sourceRoot":"","sources":["../../src/io/version-compare.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG,qBAAqB,CAAC;AAE7D,MAAM,CAAC,MAAM,uBAAuB,GAClC,0KAA0K,CAAC;AAE7K,MAAM,UAAU,sBAAsB,CAAC,CAAS,EAAE,CAAS;IACzD,MAAM,EAAE,GAAG,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC;IAC3D,MAAM,EAAE,GAAG,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC;IAC3D,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,CAAC;IAC3C,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC;QAC7B,MAAM,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;QACtB,MAAM,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;QACtB,IAAI,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,IAAI,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC;YAAE,OAAO,CAAC,CAAC;QACnD,IAAI,EAAE,GAAG,EAAE;YAAE,OAAO,CAAC,CAAC;QACtB,IAAI,EAAE,GAAG,EAAE;YAAE,OAAO,CAAC,CAAC,CAAC;IACzB,CAAC;IACD,OAAO,CAAC,CAAC;AACX,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,MAAM,UAAU,kBAAkB,CAChC,MAAc;IAEd,MAAM,CAAC,GAAG,MAAM,CAAC,KAAK,CAAC,sCAAsC,CAAC,CAAC;IAC/D,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,KAAK,KAAK,SAAS;QAAE,OAAO,IAAI,CAAC;IACtD,MAAM,IAAI,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;IACnC,MAAM,OAAO,GAAG,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IAClC,MAAM,KAAK,GAAG,OAAO,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC;IAC7D,OAAO,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,YAAY,EAAE,CAAC,CAAC,CAAC,CAAC,KAAK,SAAS,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC;AAC/E,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,UAAU,mBAAmB,CAAC,CAAS,EAAE,aAAsB,EAAE,CAAS;IAC9E,MAAM,GAAG,GAAG,sBAAsB,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IACzC,IAAI,GAAG,KAAK,CAAC;QAAE,OAAO,GAAG,CAAC;IAC1B,OAAO,aAAa,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAChC,CAAC"}

package/dist/policy-packs/builtin/solution-acceptance-reconnect.d.ts

@@ -0,0 +1,50 @@
+/** The grounding-mcp version this reconnect lifecycle was verified against. */
+export declare const RECONNECT_PRODUCER_FLOOR = "grounding-mcp >= 0.11.0";
+/** Rendered qualifier prefix both surfaces open the guidance with. */
+export declare const RECONNECT_VERSION_QUALIFIER = "With grounding-mcp >= 0.11.0:";
+export declare const RECONNECT_STATUS_TOOL = "mcp__grounding-mcp__solution_evaluate_status";
+export declare const RECONNECT_RESULT_TOOL = "mcp__grounding-mcp__solution_evaluate_result";
+export declare const RECONNECT_TASK_ID_PLACEHOLDER = "<task-id>";
+export declare const RECONNECT_POLL_MS_ADVERTISED = "5000ms";
+export declare const RECONNECT_RETENTION = "24h";
+export declare const RECONNECT_RETENTION_FLOOR = "100x pollAfterMs";
+/**
+ * The three readings `gate.verdict === null` covers. The hook
+ * (`classifyNullVerdictReading` / `readAttemptLockLiveness` in
+ * `../../cli/pack/hook-solution-acceptance.ts`) reads the documented
+ * attempt-lock anchor to rule two of the three out and select the one it
+ * detected; this module only owns the wording listing them, consumed by
+ * `renderReconnectDenyParagraph` below for its reading-(2)-only paragraph.
+ */
+export declare const RECONNECT_THREE_READINGS_LABELS: readonly ["`solution_evaluate` was never called for \"<task-id>\"", "a `solution_evaluate` call for it is still running in the background", "a marker path exists but what is there was not accepted as a verdict"];
+/** Fact 1: reconnect by attempt id, not by starting a fresh call. */
+export declare const RECONNECT_FACT_RECONNECT_BY_ID: string;
+/**
+ * Fact 2: never retry while the lock is held; a second call JOINS, it does
+ * not refuse. It deliberately begins lowercase because each renderer owns
+ * its own lead-in sentence.
+ */
+export declare const RECONNECT_FACT_JOIN_NOT_RETRY: string;
+/**
+ * Fact 3: poll interval and retention bounds, from the released
+ * grounding-mcp version. Both renderers use this fact as a fresh sentence
+ * (after a period), so it is capitalized.
+ */
+export declare const RECONNECT_FACT_POLL_AND_RETENTION: string;
+/**
+ * Compact paragraph appended to the completion-gate's deny reason
+ * (`blockJson` in hook-solution-acceptance.ts) when `gate.verdict ===
+ * null` AND the hook detected reading (2), a live attempt-lock
+ * (`reconnectGuidanceFor`). Renders the SAME fact constants as
+ * `renderReconnectInstructionsSection` below.
+ */
+export declare function renderReconnectDenyParagraph(taskId: string): string;
+/**
+ * "Reconnecting vs. retrying" section body rendered into the pack's
+ * `instructions.md` operator audit copy (`buildInstructions` in
+ * solution-acceptance.ts). Renders the SAME fact constants as
+ * `renderReconnectDenyParagraph` above; a large repo can outlive a single
+ * `solution_evaluate` call, so this section documents reconnecting to an
+ * in-flight attempt rather than treating a timeout as a stall to retry.
+ */
+export declare function renderReconnectInstructionsSection(): string;

package/dist/policy-packs/builtin/solution-acceptance-reconnect.js

@@ -0,0 +1,151 @@
+// Reconnect-vs-retry facts for the `solution-acceptance` pack (task
+// 5c9cad05), owned as DATA in exactly one place so the two rendered
+// surfaces cannot drift apart the way they did across review rounds 1-2:
+//
+//   1. `buildInstructions` (solution-acceptance.ts) renders the operator
+//      audit copy's "Reconnecting vs. retrying" section from
+//      `renderReconnectInstructionsSection`.
+//   2. `blockJson` (../../cli/pack/hook-solution-acceptance.ts) renders the
+//      agent-facing deny paragraph from `renderReconnectDenyParagraph`,
+//      shown only when `gate.verdict === null` AND the hook detected
+//      reading (2), a live attempt-lock (see `reconnectGuidanceFor` in
+//      hook-solution-acceptance.ts; the three readings are listed in
+//      `RECONNECT_THREE_READINGS_LABELS`
+//      below).
+//
+// Both renderers are built from the SAME fact constants below (not just
+// the same values restated in prose twice), and
+// `tests/policy-packs/solution-acceptance-reconnect.test.ts` asserts each
+// fact constant appears verbatim in both rendered surfaces, so a future
+// edit that updates one surface but not the other fails that test instead
+// of shipping a silent drift.
+//
+// Scope: this module documents grounding-mcp's ATTEMPT lifecycle
+// (`solution_evaluate_status` / `solution_evaluate_result`, `attemptId`,
+// `pollAfterMs`, retention), which the pack's producer floor (>= 0.3.2)
+// does not itself guarantee (that lifecycle shipped in grounding-mcp
+// 0.11.0), so every rendering below is explicitly qualified with
+// `RECONNECT_VERSION_QUALIFIER` rather than stated as if it held
+// unconditionally under the pack's own (older) producer floor.
+//
+// grounding-mcp's README also documents an attempt-lock anchor
+// (`<verdict dir>/<id>.attempt-lock`, beside the
+// `<id>.attempt-lock.lock` directory `proper-lockfile` manages, from
+// which the producer itself derives its own `running-unconfirmed`
+// status). The anchor IS read: `classifyNullVerdictReading` /
+// `readAttemptLockLiveness` in `../../cli/pack/hook-solution-acceptance.ts`
+// read it to rule two of the three readings below out and select the
+// one it detected (harness/799de976). This module does not touch the
+// filesystem itself; it only owns the WORDING both rendered surfaces
+// share, including `renderReconnectDenyParagraph`'s reading-(2)-only
+// paragraph below, which the hook appends solely when it has detected
+// the live-attempt reading.
+/** The grounding-mcp version this reconnect lifecycle was verified against. */
+export const RECONNECT_PRODUCER_FLOOR = "grounding-mcp >= 0.11.0";
+/** Rendered qualifier prefix both surfaces open the guidance with. */
+export const RECONNECT_VERSION_QUALIFIER = `With ${RECONNECT_PRODUCER_FLOOR}:`;
+export const RECONNECT_STATUS_TOOL = "mcp__grounding-mcp__solution_evaluate_status";
+export const RECONNECT_RESULT_TOOL = "mcp__grounding-mcp__solution_evaluate_result";
+export const RECONNECT_TASK_ID_PLACEHOLDER = "<task-id>";
+export const RECONNECT_POLL_MS_ADVERTISED = "5000ms";
+export const RECONNECT_RETENTION = "24h";
+export const RECONNECT_RETENTION_FLOOR = "100x pollAfterMs";
+/**
+ * The three readings `gate.verdict === null` covers. The hook
+ * (`classifyNullVerdictReading` / `readAttemptLockLiveness` in
+ * `../../cli/pack/hook-solution-acceptance.ts`) reads the documented
+ * attempt-lock anchor to rule two of the three out and select the one it
+ * detected; this module only owns the wording listing them, consumed by
+ * `renderReconnectDenyParagraph` below for its reading-(2)-only paragraph.
+ */
+export const RECONNECT_THREE_READINGS_LABELS = [
+    `\`solution_evaluate\` was never called for "${RECONNECT_TASK_ID_PLACEHOLDER}"`,
+    "a `solution_evaluate` call for it is still running in the background",
+    "a marker path exists but what is there was not accepted as a verdict",
+];
+/** Fact 1: reconnect by attempt id, not by starting a fresh call. */
+export const RECONNECT_FACT_RECONNECT_BY_ID = `poll \`${RECONNECT_STATUS_TOOL}\` /\n` +
+    `\`${RECONNECT_RESULT_TOOL}\` for the SAME \`id\`,\n` +
+    `passing the \`attemptId\` you were given (or omitting it to resolve the latest attempt,\n` +
+    `the recovery path when your own call timed out before it ever returned one)`;
+/**
+ * Fact 2: never retry while the lock is held; a second call JOINS, it does
+ * not refuse. It deliberately begins lowercase because each renderer owns
+ * its own lead-in sentence.
+ */
+export const RECONNECT_FACT_JOIN_NOT_RETRY = `a second \`solution_evaluate\` call for an \`id\` whose attempt is still live just joins\n` +
+    `that attempt and returns its \`attemptId\`, never starting a second \`preflight\` run;\n` +
+    `only \`forceNewAttempt\` is refused while that attempt's lock holds`;
+/**
+ * Fact 3: poll interval and retention bounds, from the released
+ * grounding-mcp version. Both renderers use this fact as a fresh sentence
+ * (after a period), so it is capitalized.
+ */
+export const RECONNECT_FACT_POLL_AND_RETENTION = `Wait at least the returned \`pollAfterMs\` (advertised as \`${RECONNECT_POLL_MS_ADVERTISED}\`)\n` +
+    `between polls; attempt records are retained \`${RECONNECT_RETENTION}\` by default (always at\n` +
+    `least \`${RECONNECT_RETENTION_FLOOR}\`), and a pruned terminal attempt\n` +
+    `reads \`expired\``;
+/** The three readings, as one clause, with the task id interpolated. */
+function threeReadingsClause(taskId) {
+    const [neverCalled, stillRunning, unreadable] = RECONNECT_THREE_READINGS_LABELS;
+    return [
+        neverCalled.replace(RECONNECT_TASK_ID_PLACEHOLDER, taskId),
+        stillRunning,
+        `or ${unreadable}`,
+    ].join(",\n");
+}
+/**
+ * Compact paragraph appended to the completion-gate's deny reason
+ * (`blockJson` in hook-solution-acceptance.ts) when `gate.verdict ===
+ * null` AND the hook detected reading (2), a live attempt-lock
+ * (`reconnectGuidanceFor`). Renders the SAME fact constants as
+ * `renderReconnectInstructionsSection` below.
+ */
+export function renderReconnectDenyParagraph(taskId) {
+    return `\n${[
+        `Reconnecting vs. retrying. ${RECONNECT_VERSION_QUALIFIER} this same`,
+        `"no readable verdict marker" case covers three readings:`,
+        threeReadingsClause(taskId),
+        `(the verdict marker only appears once an attempt finishes, and is validated on read;`,
+        `this hook read the documented attempt-lock anchor and is showing you this paragraph`,
+        `because it detected reading (2): an attempt is still live). If you already called`,
+        `\`solution_evaluate\` for this \`id\`, do not call it again:`,
+        `${RECONNECT_FACT_RECONNECT_BY_ID}.`,
+        `Never re-call \`solution_evaluate\`:`,
+        `${RECONNECT_FACT_JOIN_NOT_RETRY}.`,
+        `${RECONNECT_FACT_POLL_AND_RETENTION}.`,
+    ].join("\n")}\n`;
+}
+/**
+ * "Reconnecting vs. retrying" section body rendered into the pack's
+ * `instructions.md` operator audit copy (`buildInstructions` in
+ * solution-acceptance.ts). Renders the SAME fact constants as
+ * `renderReconnectDenyParagraph` above; a large repo can outlive a single
+ * `solution_evaluate` call, so this section documents reconnecting to an
+ * in-flight attempt rather than treating a timeout as a stall to retry.
+ */
+export function renderReconnectInstructionsSection() {
+    return `## Reconnecting vs. retrying (${RECONNECT_PRODUCER_FLOOR})
+
+${RECONNECT_VERSION_QUALIFIER} a large repo can outlive the call: \`solution_evaluate\` may
+hand back \`{status: "running", attemptId, id, pollAfterMs}\` instead of a verdict, or your
+own call may time out with nothing at all. Either way the \`preflight\` run keeps going in
+the background; reconnect as follows:
+${RECONNECT_FACT_RECONNECT_BY_ID}.
+
+Never re-call \`solution_evaluate\` as a stall workaround:
+${RECONNECT_FACT_JOIN_NOT_RETRY}.
+A prior attempt's reported status (\`completed\`,
+\`failed\`, \`unknown\`, or \`expired\`) is informational, not the gate: \`unknown\`/
+\`expired\` never license a new attempt by themselves while another process still holds the
+id's lock. A genuinely new attempt becomes possible only once the previous one is terminal and
+the id's lock is free again, at which point an ordinary \`solution_evaluate\` call starts
+one.
+
+${RECONNECT_FACT_POLL_AND_RETENTION}. \`running-unconfirmed\` still means keep
+polling, not stall or escalate: it resolves by itself, into \`running\`
+or once the lock is reclaimed as stale. Never escalate to a human before
+the poll hint has elapsed.
+`;
+}
+//# sourceMappingURL=solution-acceptance-reconnect.js.map

package/dist/policy-packs/builtin/solution-acceptance-reconnect.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"solution-acceptance-reconnect.js","sourceRoot":"","sources":["../../../src/policy-packs/builtin/solution-acceptance-reconnect.ts"],"names":[],"mappings":"AAAA,oEAAoE;AACpE,oEAAoE;AACpE,yEAAyE;AACzE,EAAE;AACF,yEAAyE;AACzE,6DAA6D;AAC7D,6CAA6C;AAC7C,4EAA4E;AAC5E,wEAAwE;AACxE,qEAAqE;AACrE,uEAAuE;AACvE,qEAAqE;AACrE,yCAAyC;AACzC,eAAe;AACf,EAAE;AACF,wEAAwE;AACxE,gDAAgD;AAChD,0EAA0E;AAC1E,wEAAwE;AACxE,0EAA0E;AAC1E,8BAA8B;AAC9B,EAAE;AACF,iEAAiE;AACjE,yEAAyE;AACzE,wEAAwE;AACxE,qEAAqE;AACrE,iEAAiE;AACjE,iEAAiE;AACjE,+DAA+D;AAC/D,EAAE;AACF,+DAA+D;AAC/D,iDAAiD;AACjD,qEAAqE;AACrE,kEAAkE;AAClE,8DAA8D;AAC9D,4EAA4E;AAC5E,qEAAqE;AACrE,qEAAqE;AACrE,qEAAqE;AACrE,qEAAqE;AACrE,sEAAsE;AACtE,4BAA4B;AAE5B,+EAA+E;AAC/E,MAAM,CAAC,MAAM,wBAAwB,GAAG,yBAAyB,CAAC;AAElE,sEAAsE;AACtE,MAAM,CAAC,MAAM,2BAA2B,GAAG,QAAQ,wBAAwB,GAAG,CAAC;AAE/E,MAAM,CAAC,MAAM,qBAAqB,GAAG,8CAA8C,CAAC;AACpF,MAAM,CAAC,MAAM,qBAAqB,GAAG,8CAA8C,CAAC;AACpF,MAAM,CAAC,MAAM,6BAA6B,GAAG,WAAW,CAAC;AAEzD,MAAM,CAAC,MAAM,4BAA4B,GAAG,QAAQ,CAAC;AACrD,MAAM,CAAC,MAAM,mBAAmB,GAAG,KAAK,CAAC;AACzC,MAAM,CAAC,MAAM,yBAAyB,GAAG,kBAAkB,CAAC;AAE5D;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,+BAA+B,GAAG;IAC7C,+CAA+C,6BAA6B,GAAG;IAC/E,sEAAsE;IACtE,sEAAsE;CAC9D,CAAC;AAEX,qEAAqE;AACrE,MAAM,CAAC,MAAM,8BAA8B,GACzC,UAAU,qBAAqB,QAAQ;IACvC,KAAK,qBAAqB,2BAA2B;IACrD,2FAA2F;IAC3F,6EAA6E,CAAC;AAEhF;;;;GAIG;AACH,MAAM,CAAC,MAAM,6BAA6B,GACxC,4FAA4F;IAC5F,0FAA0F;IAC1F,qEAAqE,CAAC;AAExE;;;;GAIG;AACH,MAAM,CAAC,MAAM,iCAAiC,GAC5C,+DAA+D,4BAA4B,OAAO;IAClG,iDAAiD,mBAAmB,4BAA4B;IAChG,WAAW,yBAAyB,sCAAsC;IAC1E,mBAAmB,CAAC;AAEtB,wEAAwE;AACxE,SAAS,mBAAmB,CAAC,MAAc;IACzC,MAAM,CAAC,WAAW,EAAE,YAAY,EAAE,UAAU,CAAC,GAAG,+BAA+B,CAAC;IAChF,OAAO;QACL,WAAW,CAAC,OAAO,CAAC,6BAA6B,EAAE,MAAM,CAAC;QAC1D,YAAY;QACZ,MAAM,UAAU,EAAE;KACnB,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;AAChB,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,4BAA4B,CAAC,MAAc;IACzD,OAAO,KAAK;QACV,8BAA8B,2BAA2B,YAAY;QACrE,0DAA0D;QAC1D,mBAAmB,CAAC,MAAM,CAAC;QAC3B,sFAAsF;QACtF,qFAAqF;QACrF,mFAAmF;QACnF,8DAA8D;QAC9D,GAAG,8BAA8B,GAAG;QACpC,sCAAsC;QACtC,GAAG,6BAA6B,GAAG;QACnC,GAAG,iCAAiC,GAAG;KACxC,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC;AACnB,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,kCAAkC;IAChD,OAAO,iCAAiC,wBAAwB;;EAEhE,2BAA2B;;;;EAI3B,8BAA8B;;;EAG9B,6BAA6B;;;;;;;;EAQ7B,iCAAiC;;;;CAIlC,CAAC;AACF,CAAC"}

package/dist/policy-packs/builtin/solution-acceptance-runtime.d.ts

@@ -170,12 +170,51 @@ export declare function verdictPathFor(dir: string, id: string): string;
  * active-claim is present.
  */
 export declare function resolveExplicitVerdictId(env?: NodeJS.ProcessEnv): string | null;
+/**
+ * WHY the verdict marker for an id yielded no verdict, as ONE observation.
+ * `readVerdict` below answers `null` for every non-`ok` kind, which is all
+ * the gate DECISION needs; the deny TEXT needs to say which one, and must
+ * not learn it from a second look at the path. A second look can disagree
+ * with the first (a background attempt finishing in between is exactly the
+ * case this pack exists for), and a note rendered from the later one then
+ * describes a rejection the gate never made: it would tell the agent its
+ * fresh marker was refused when the gate had simply not seen it yet
+ * (review finding, harness/799de976, round 6). Both consumers therefore
+ * read through this one function.
+ */
+export type VerdictReadOutcome = {
+    kind: "ok";
+    verdict: Verdict;
+} | {
+    kind: "invalid-id";
+} | {
+    kind: "missing";
+} | {
+    kind: "symlink";
+} | {
+    kind: "not-regular";
+} | {
+    kind: "unreadable";
+} | {
+    kind: "invalid-record";
+};
+/**
+ * Read + validate the verdict marker for `id` in ONE filesystem
+ * observation, reporting the outcome instead of collapsing it. The
+ * symlink-rejecting read is the shared `src/io/read-regular-file.ts`
+ * helper (same defense-in-depth as `checkApprovalMarker` against a symlink
+ * planted at the marker path pointing at agent-controlled content), and
+ * its four non-ok kinds pass straight through, so this outcome set cannot
+ * drift from the reader's own. `invalid-record` is the one kind added on
+ * top: a regular file that WAS read but is not a verdict (unparseable
+ * JSON, or JSON missing one of the three required fields).
+ */
+export declare function readVerdictDetailed(dir: string, id: string): VerdictReadOutcome;
 /**
  * Read + validate the verdict marker for `id`, or null when it is absent,
- * unparseable, a symlink, or not a regular file. The symlink-rejecting read
- * is the shared `src/io/read-regular-file.ts` helper (same defense-in-depth
- * as `checkApprovalMarker` against a symlink planted at the marker path
- * pointing at agent-controlled content).
+ * unparseable, a symlink, or not a regular file: `readVerdictDetailed`
+ * above with the reason dropped. Behaviour is unchanged for every caller
+ * that only needs the gate decision.
  */
 export declare function readVerdict(dir: string, id: string): Verdict | null;
 export interface GateResult {