@opengsd/gsd-core 1.14.0 → 1.16.0

package/gsd-core/bin/lib/gate-verdict.cjs

@@ -0,0 +1,64 @@
+"use strict";
+/**
+ * GateVerdict — the value a gate module returns instead of printing (#5139, epic #5056,
+ * ADR-5057 §4 first bullet, design D1).
+ *
+ * A gate module decides; the command router formats. A gate imports no io module and performs no
+ * direct console/stdout/stderr write (ESLint-enforced) — it returns one of two shapes:
+ *
+ *   - `GateVerdict`      the gate reached an answer. `outcome` names it, `block` is the gate's
+ *                        own blocking decision (set explicitly by each arm, never derived from
+ *                        `outcome`), and `payload` is the exact ordered object the router
+ *                        serializes (insertion order is the wire order).
+ *   - `GateUsageFailure` the caller invoked the gate wrongly (missing argument, escaping path).
+ *                        The router turns it into `error(message, code)`.
+ *
+ * Pure: no I/O, no imports.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GATE_FAILURE_CODE = void 0;
+exports.gateVerdict = gateVerdict;
+exports.gateUnreadable = gateUnreadable;
+exports.gateUsageFailure = gateUsageFailure;
+exports.isGateUsageFailure = isGateUsageFailure;
+/**
+ * The `GateUsageFailure.failure.code` values a gate module produces. A gate module may not import
+ * `./io.cjs` (whose `ERROR_REASON` owns these wire strings), so it names them here; the router
+ * hands the code straight to `error()`. Values are pinned equal to `ERROR_REASON.USAGE` /
+ * `ERROR_REASON.SDK_MISSING_ARG` / `ERROR_REASON.UNKNOWN` by the cutover-equivalence goldens and
+ * the parity test in tests/check-router-cutover-equivalence.test.cjs.
+ *
+ * `UNKNOWN` is the reason `error()` records when its caller names none: the drift verbs' usage
+ * failures never named one (#5219), and the JSON diagnostic's `reason` and the exit-contract v2
+ * status (UNKNOWN is FAIL, 1; SDK_MISSING_ARG is USAGE, 64) are observable, so they keep it.
+ */
+exports.GATE_FAILURE_CODE = Object.freeze({
+    USAGE: 'usage',
+    SDK_MISSING_ARG: 'sdk_missing_arg',
+    UNKNOWN: 'unknown',
+});
+/**
+ * Build a verdict. `payload` is copied (insertion order preserved) and the copy frozen, so a
+ * verdict cannot be mutated after the gate returned it.
+ */
+function gateVerdict(outcome, block, payload) {
+    return { outcome, block, payload: Object.freeze({ ...payload }) };
+}
+/**
+ * Build the verdict for evidence that could not be read. `block` is the gate's own policy for that
+ * arm (unchanged by this outcome); the exit status is derived from the outcome, never from `block`.
+ */
+function gateUnreadable(block, payload) {
+    return gateVerdict('unreadable', block, payload);
+}
+/** Build a usage failure: exactly `{ failure: { code, message } }`. */
+function gateUsageFailure(code, message) {
+    return { failure: { code, message } };
+}
+/** Narrow a `GateResult` (or any value) to a `GateUsageFailure`. */
+function isGateUsageFailure(result) {
+    if (result === null || typeof result !== 'object')
+        return false;
+    const failure = result.failure;
+    return typeof failure === 'object' && failure !== null;
+}

package/gsd-core/bin/lib/gate-verify-command-paths.cjs

@@ -0,0 +1,78 @@
+"use strict";
+/**
+ * `check verify-command-paths` as a gate module (#5139, epic #5056, ADR-5057 §4 first bullet,
+ * #2401): it returns a `GateResult`; the command router formats it. Imports no io module and
+ * performs no direct console/stdout/stderr write (ESLint-enforced).
+ *
+ * Probes every `<automated>` verify command declared in a phase's `-PLAN.md` files against the
+ * filesystem WITHOUT executing anything — see `verify-command-grounding.cts` for the recognizer
+ * contract.
+ *
+ * Argv after the verb: `<phase>` | `--dir <plan-dir>`.
+ *
+ * `--dir` (#4767) names a directory holding `-PLAN.md` files directly, for plans that live outside
+ * `.planning/phases/` (quick mode's `.planning/quick/<id>/`). It is resolved against the project
+ * root AND CONTAINED WITHIN IT — an absolute or climbing `--dir` that lands outside the root is
+ * `unresolvable`, never read — then probed exactly as a phase directory is; `projectRoot` stays the
+ * project root in both forms. `--dir <value>` is the only accepted spelling: `--dir=<value>`
+ * yields no `dir` flag and falls through to the no-argument arm, as does an empty value (both are
+ * `partitionPredicateArgs` behaviour, inherited and unchanged).
+ *
+ * When the phase cannot be resolved (or `--dir` escapes the root, or neither is given) the gate
+ * returns a non-throwing degraded payload (status/commands/counts zeroed, `readError` populated)
+ * rather than a usage failure — the plan-checker parses this result and must be able to tell
+ * "nothing to report" from "could not look", which a thrown error would collapse.
+ *
+ * Containment is decided on the resolved target (ADR-4650: the probe's reads follow symlinks).
+ * RESIDUAL, stated rather than left to be rediscovered: this is check-then-use, so a symlink
+ * planted at the resolved path BETWEEN the containment check and the reads inside the probe would
+ * be followed. A link already in place when the command runs IS refused. Closing the window needs
+ * O_NOFOLLOW/dirfd semantics inside the ADR-4650 predicate — a wider change than this gate.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.evaluateVerifyCommandPaths = evaluateVerifyCommandPaths;
+const gate_verdict_cjs_1 = require("./gate-verdict.cjs");
+const gate_args_cjs_1 = require("./gate-args.cjs");
+const gate_phase_context_cjs_1 = require("./gate-phase-context.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const verifyCommandGroundingMod = require("./verify-command-grounding.cjs");
+const { probePhaseVerifyCommands } = verifyCommandGroundingMod;
+function evaluateVerifyCommandPaths(input) {
+    const { projectDir } = input;
+    const { flags, positionals } = (0, gate_args_cjs_1.partitionPredicateArgs)(input.args);
+    const dirFlag = typeof flags['dir'] === 'string' ? flags['dir'] : '';
+    // First non-flag positional: `--raw` (valueless) lands in positionals too, and its position
+    // relative to the phase argument is the caller's choice.
+    const phase = positionals.find(p => !p.startsWith('--')) ?? '';
+    if (!phase && !dirFlag) {
+        return (0, gate_phase_context_cjs_1.unresolvableProbeVerdict)('verify-command-paths requires a phase argument or --dir: check verify-command-paths <phase> | --dir <plan-dir>');
+    }
+    let phaseDir = '';
+    if (dirFlag) {
+        // `--dir` is CALLER-SUPPLIED: contain it before it reaches the reads in the probe. Read the
+        // value the predicate RETURNED; never re-derive the path. An escape degrades to the same
+        // non-throwing payload the unresolvable-phase arm emits.
+        const contained = (0, gate_phase_context_cjs_1.resolveContainedPath)(dirFlag, projectDir);
+        if ((0, gate_verdict_cjs_1.isGateUsageFailure)(contained)) {
+            return (0, gate_phase_context_cjs_1.unresolvableProbeVerdict)(`--dir resolves outside the project root: ${dirFlag}`);
+        }
+        phaseDir = contained;
+    }
+    else {
+        const located = (0, gate_phase_context_cjs_1.resolvePhaseDir)(projectDir, phase);
+        if (located.kind === 'unreadable') {
+            return (0, gate_phase_context_cjs_1.unresolvableProbeVerdict)(`could not read the phase directory for phase ${phase}: ${located.reason}`);
+        }
+        if (located.kind === 'found')
+            phaseDir = located.value;
+    }
+    if (!phaseDir) {
+        return (0, gate_phase_context_cjs_1.unresolvableProbeVerdict)(`could not resolve phase directory for phase ${phase}`);
+    }
+    const probed = probePhaseVerifyCommands({ phaseDir, projectRoot: projectDir });
+    const blocked = probed.counts.blocker > 0;
+    // A probe that could not look (`unresolvable`) is `unreadable`: never a pass, exit UNAVAILABLE (#5170).
+    if (!blocked && probed.status === 'unresolvable')
+        return (0, gate_verdict_cjs_1.gateUnreadable)(false, { ...probed });
+    return (0, gate_verdict_cjs_1.gateVerdict)(blocked ? 'block' : 'pass', blocked, { ...probed });
+}

package/gsd-core/bin/lib/gate-verify-failure-directions.cjs

@@ -0,0 +1,41 @@
+"use strict";
+/**
+ * `check verify-failure-directions` as a gate module (#5139, epic #5056, ADR-5057 §4 first bullet,
+ * #3172): it returns a `GateResult`; the command router formats it. Imports no io module and
+ * performs no direct console/stdout/stderr write (ESLint-enforced).
+ *
+ * Probes every `<automated>` verify command declared in a phase's `-PLAN.md` files for a stated
+ * `<fails_when>` failing direction — see `verify-command-grounding.cts` for the recognizer
+ * contract.
+ *
+ * Argv after the verb: `<phase>`. When the phase is missing or cannot be resolved to a directory
+ * the gate returns a non-throwing degraded payload (status/commands/counts zeroed, `readError`
+ * populated) rather than a usage failure — the plan-checker parses this result and must be able to
+ * tell "nothing to report" from "could not look".
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.evaluateVerifyFailureDirections = evaluateVerifyFailureDirections;
+const gate_verdict_cjs_1 = require("./gate-verdict.cjs");
+const gate_phase_context_cjs_1 = require("./gate-phase-context.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const verifyCommandGroundingMod = require("./verify-command-grounding.cjs");
+const { probePhaseFailingDirections } = verifyCommandGroundingMod;
+function evaluateVerifyFailureDirections(input) {
+    const phase = input.args[0] || '';
+    if (!phase) {
+        return (0, gate_phase_context_cjs_1.unresolvableProbeVerdict)('verify-failure-directions requires a phase argument: check verify-failure-directions <phase>');
+    }
+    const located = (0, gate_phase_context_cjs_1.resolvePhaseDir)(input.projectDir, phase);
+    if (located.kind === 'unreadable') {
+        return (0, gate_phase_context_cjs_1.unresolvableProbeVerdict)(`could not read the phase directory for phase ${phase}: ${located.reason}`);
+    }
+    if (located.kind === 'none') {
+        return (0, gate_phase_context_cjs_1.unresolvableProbeVerdict)(`could not resolve phase directory for phase ${phase}`);
+    }
+    const probed = probePhaseFailingDirections({ phaseDir: located.value });
+    const blocked = probed.counts.blocker > 0;
+    // A probe that could not look (`unresolvable`) is `unreadable`: never a pass, exit UNAVAILABLE (#5170).
+    if (!blocked && probed.status === 'unresolvable')
+        return (0, gate_verdict_cjs_1.gateUnreadable)(false, { ...probed });
+    return (0, gate_verdict_cjs_1.gateVerdict)(blocked ? 'block' : 'pass', blocked, { ...probed });
+}

package/gsd-core/bin/lib/graphify.cjs

@@ -445,14 +445,17 @@ function graphifyStatus(cwd) {
         return disabledResponse();
     const { graphPath, configured } = resolveGraphLocation(cwd, planningDir);
     if (!node_fs_1.default.existsSync(graphPath)) {
-        return { exists: false, message: configured
+        return { exists: false, graph_path: graphPath, message: configured
                 ? `Configured graph not found at ${graphPath}. Set graphify.graph_path or run /gsd:graphify build.`
                 : 'No graph built yet. Run graphify build to create one.' };
     }
     const stat = node_fs_1.default.statSync(graphPath);
     const graph = safeReadJson(graphPath);
     if (!graph) {
-        return { error: 'Failed to parse graph.json' };
+        // Still surface graph_path (#4836 Minor 1): callers gate on `exists`, not
+        // on this outcome, so without it they'd fall through to the CLI-first
+        // branch with no --graph value to substitute for the <graph> placeholder.
+        return { error: 'Failed to parse graph.json', graph_path: graphPath };
     }
     const STALE_MS = 24 * 60 * 60 * 1000; // 24 hours
     const age = Date.now() - stat.mtimeMs;
@@ -482,6 +485,11 @@ function graphifyStatus(cwd) {
         (lastBuildAutoUpdate.status === 'failed' || lastBuildAutoUpdate.status === 'running');
     return {
         exists: true,
+        // The absolute location the whole graphify surface reads, already resolved
+        // through `graphify.graph_path` (#1825). Callers that shell out to the
+        // graphify CLI pass this as `--graph` so the umbrella override is honoured
+        // there too, instead of re-deriving `.planning/graphs/graph.json` (#4836).
+        graph_path: graphPath,
         last_build: stat.mtime.toISOString(),
         node_count: (graph.nodes || []).length,
         edge_count: (graph.edges || graph.links || []).length,

package/gsd-core/bin/lib/health-diagnostic-rules/phase-structure.cjs

@@ -4,7 +4,7 @@
  * ADR-3180 §8.2/§8.3/§8.5).
  *
  * Group: "Phase directory structure" (design doc, "Rule table organization"
- * table) — W005, W023, I001, W009.
+ * table) — W005, W023, I001, W009, and W030 (#5118).
  *
  * Ported behavior-preserving from `cmdValidateHealth`
  * (`src/verify.cts:1893-1990`, the exact call sites for W005/W023/I001/W009),
@@ -15,25 +15,14 @@
  *   phases.value[i]` exposes only `planCount`/`summaryCount`, not per-plan
  *   filenames) — this rule reports a coarser per-PHASE message instead.
  * - W023's original "described" list called `determinePhaseStatus`
- *   (`commands.cts:154`), a SIX-way status string ('Not Started'/'Planned'/
- *   'In Progress'/'Executed'/'Needs Review'/'Complete') computed from its own
- *   raw `readdirSync` + `*-VERIFICATION.md` frontmatter read of `phaseDir`.
- *   This rule cannot re-run that raw read (§8.1 rule 1 forbids ambient I/O in
- *   `check`), so `derivePhaseStatusLabel` below reconstructs the same
- *   six-way label from fields `PlanningSnapshot` already exposes —
- *   `PhaseSnapshot.planCount`/`summaryCount` (the plan/no-plan and
- *   in-progress/planned branches, identical inputs to the original) and
- *   `PhaseSnapshot.complete`/`verificationStatus` (`isPhaseComplete`'s own
- *   §7.4 disk-strict routing of the SAME `*-VERIFICATION.md` file) for the
- *   verification-gated branches. This is a disclosed fidelity reduction, not
- *   a byte-for-byte guarantee: `verificationStatus` is the DIFFERENT,
- *   `readVerificationStatus`-routed vocabulary ('passed'/'gaps_found'/
- *   'human_needed'/'stale'/'unknown'/'missing') and can disagree with a raw
- *   frontmatter re-read in edge cases (e.g. a stale-but-frontmatter-"passed"
- *   VERIFICATION.md routes to 'stale', not 'passed', under §7.4's staleness
- *   handling — this rule reports 'Executed' there, not 'Complete'). No new
- *   ambient I/O and no new `PlanningSnapshot` field were needed — every input
- *   was already on `PhaseSnapshot`.
+ *   (`commands.cts:154`, since deleted, #5060). The label now comes from the
+ *   Phase Status Module's pure ladder (`phaseStatusFromFacts` +
+ *   `toDisplayLabel`, `../phase-status.cjs`) over the same `PhaseSnapshot`
+ *   facts this rule already had — `planCount`/`summaryCount`,
+ *   `complete`/`verificationStatus` (`isPhaseComplete`'s §7.4 disk-strict
+ *   routing of the SAME `*-VERIFICATION.md` file). §8.1 rule 1 (no ambient
+ *   I/O in `check`) still holds: the module's ladder is a pure function of
+ *   facts already on the snapshot, no new I/O or snapshot field is needed.
  *
  * W009's original message interpolates `${slash('plan-phase')}`
  * (`verify.cts:1982`, ``Re-run ${slash('plan-phase')} with --research to
@@ -66,6 +55,8 @@ const { isPhaseDirName } = validateMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const phaseIdMod = require("../phase-id.cjs");
 const { extractPhaseToken, normalizePhaseName, comparePhaseNum } = phaseIdMod;
+// #5060: the Phase Status Module owns the status-label ladder.
+const phase_status_cjs_1 = require("../phase-status.cjs");
 // ─── W005 — phase directory doesn't follow NN-name format (verify.cts:1893-1902) ─
 function checkW005(snapshot) {
     const diagnostics = [];
@@ -89,31 +80,6 @@ function checkW005(snapshot) {
 // `comparePhaseNum` + a `localeCompare` tiebreak, mirroring
 // `verify.cts:1930-1932`'s deterministic-output rationale. See the file-level
 // comment for the disclosed "described" fidelity reduction.
-/**
- * Reconstruct `commands.cts:154`'s `determinePhaseStatus` six-way label from
- * fields `PhaseSnapshot` already exposes (no ambient I/O, no new snapshot
- * field — see file-level comment). `complete`/`verificationStatus` come from
- * `isPhaseComplete`'s §7.4 disk-strict routing of the same `*-VERIFICATION.md`
- * file the original raw read targeted.
- */
-function derivePhaseStatusLabel(planCount, summaryCount, complete, verificationStatus) {
-    if (planCount === 0)
-        return 'Not Started';
-    if (summaryCount < planCount && summaryCount > 0)
-        return 'In Progress';
-    if (summaryCount < planCount)
-        return 'Planned';
-    // summaryCount >= planCount > 0 — verification-gated, same as the original's
-    // post-count fall-through.
-    if (complete)
-        return 'Complete';
-    if (verificationStatus === 'human_needed')
-        return 'Needs Review';
-    // gaps_found / stale / missing / unknown all land here, same as the
-    // original's "verification exists but unrecognized" and "no verification
-    // file" branches both returning 'Executed'.
-    return 'Executed';
-}
 function checkW023(snapshot) {
     const groups = new Map();
     for (const name of snapshot.phaseDirs.value) {
@@ -138,8 +104,8 @@ function checkW023(snapshot) {
             const plans = phase ? phase.planCount : 0;
             const summaries = phase ? phase.summaryCount : 0;
             const complete = phase ? phase.complete : false;
-            const verificationStatus = phase ? phase.verificationStatus : 'missing';
-            const status = derivePhaseStatusLabel(plans, summaries, complete, verificationStatus);
+            const verificationStatus = phase ? phase.verificationStatus : null;
+            const status = (0, phase_status_cjs_1.toDisplayLabel)((0, phase_status_cjs_1.phaseStatusFromFacts)({ planCount: plans, summaryCount: summaries, complete, verificationStatus }), { pendingWord: 'Not Started' });
             return `${d} (${status})`;
         })
             .join(', ');
@@ -194,6 +160,29 @@ function checkW009(snapshot) {
     }
     return diagnostics;
 }
+// ─── W030 — verification report status outside the closed set (#5118) ─────
+//
+// `isPhaseComplete` absorbs an out-of-set report `status` (its no-throw
+// contract) and the snapshot carries the typed error's file and message. A
+// diagnostics surface must survive the defect it diagnoses, so health reports
+// the file instead of failing with `verification_status_invalid` like the
+// query surfaces do: `validate health` (exit 0) lists each such report as one
+// W030 finding, built from the error the snapshot carries.
+function checkW030(snapshot) {
+    const diagnostics = [];
+    for (const phase of snapshot.phases.value) {
+        const invalid = phase.verificationStatusError;
+        if (!invalid)
+            continue;
+        diagnostics.push({
+            code: 'W030',
+            severity: SEVERITY.WARNING,
+            message: `Phase ${phase.dir}: ${invalid.message}`,
+            remedy: adviseRemedy('Set the report frontmatter `status` to one of passed | gaps_found | human_needed, or delete the report and re-run the phase verification'),
+        });
+    }
+    return diagnostics;
+}
 // ─── Exports ────────────────────────────────────────────────────────────────
 const RULES = [
     {
@@ -224,5 +213,12 @@ const RULES = [
         repairable: false,
         check: checkW009,
     },
+    {
+        code: 'W030',
+        severity: SEVERITY.WARNING,
+        description: 'Phase verification report status is outside the closed set',
+        repairable: false,
+        check: checkW030,
+    },
 ];
 module.exports = { RULES };

package/gsd-core/bin/lib/health-diagnostic.cjs

@@ -95,6 +95,10 @@ const RULES = [
  */
 const CONSISTENCY_RULES = [
     ...roadmapDiskConsistencyMod.RULES.filter((r) => ['W006', 'W007'].includes(r.code)),
+    // #5118: W030 (a verification report status outside the closed set) is
+    // REUSED too — the snapshot carries the error, and a diagnostics surface
+    // reports it as a finding instead of failing on the defect it diagnoses.
+    ...phaseStructureMod.RULES.filter((r) => r.code === 'W030'),
     ...consistencyMod.RULES,
 ];
 // ─── Repair-handler runtime dependencies ───────────────────────────────────
@@ -112,7 +116,7 @@ const roadmapParserMod = require("./roadmap-parser.cjs");
 const { getMilestoneInfo } = roadmapParserMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const stateMod = require("./state.cjs");
-const { writeStateMd } = stateMod;
+const { writeStateMd, assertVerificationReportsReadable } = stateMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const frontmatter = require("./frontmatter.cjs");
 const { extractFrontmatter } = frontmatter;
@@ -149,7 +153,7 @@ function evaluateRules(snapshot) {
     return evaluateRuleTable(RULES, snapshot);
 }
 /**
- * Evaluate `CONSISTENCY_RULES` (W006/W007 + C001-C004) against `snapshot` —
+ * Evaluate `CONSISTENCY_RULES` (W006/W007/W030 + C001-C004) against `snapshot` —
  * `validate.consistency`'s evaluator entry point, mirroring `evaluateRules`
  * exactly but over the smaller, command-specific rule subset.
  */
@@ -258,12 +262,6 @@ function runRepairAction(cwd, action, paths) {
         }
         case REMEDY_ACTION.REGENERATE_STATE: {
             const extraDetails = [];
-            if (node_fs_1.default.existsSync(statePath)) {
-                const timestamp = new Date().toISOString().replace(/[:.]/g, '-').slice(0, 19);
-                const backupPath = `${statePath}.bak-${timestamp}`;
-                node_fs_1.default.copyFileSync(statePath, backupPath);
-                extraDetails.push({ action: 'backupState', success: true, path: backupPath });
-            }
             const milestone = getMilestoneInfo(cwd).value;
             const projectRef = node_path_1.default
                 .relative(cwd, node_path_1.default.join(rootBase, 'PROJECT.md'))
@@ -286,6 +284,17 @@ function runRepairAction(cwd, action, paths) {
             // STATE.md that had no parseable frontmatter — which is the usual
             // reason this repair fires.
             const priorState = node_fs_1.default.existsSync(statePath) ? ((0, shell_command_projection_cjs_1.platformReadSync)(statePath) ?? '') : '';
+            // #5118: the write below rebuilds the STATE frontmatter from every
+            // phase's report and throws on a `status` outside the closed set.
+            // `applyRepairs` validates ONCE, before the run's first write
+            // (`assertVerificationReportsReadable`), so this handler is only reached
+            // over readable reports and no earlier repair has written.
+            if (node_fs_1.default.existsSync(statePath)) {
+                const timestamp = new Date().toISOString().replace(/[:.]/g, '-').slice(0, 19);
+                const backupPath = `${statePath}.bak-${timestamp}`;
+                node_fs_1.default.copyFileSync(statePath, backupPath);
+                extraDetails.push({ action: 'backupState', success: true, path: backupPath });
+            }
             writeStateMd(statePath, stateContent, rebuildStateTransaction({
                 snapshot: extractFrontmatter(priorState, statePath),
             }), cwd);
@@ -381,6 +390,23 @@ function applyRepairs(cwd, diagnostics, repair, backfill) {
     const refused = [];
     const details = [];
     const paths = repairPaths(cwd);
+    // #5118 (no write before the error): a requested REGENERATE_STATE rewrites
+    // STATE.md from every phase's report and throws on one whose `status` is
+    // outside the closed set — but other repairs in the SAME run (config,
+    // MILESTONES.md) may be ordered before it and would already have written.
+    // Validate once, before the run's first write; on a refusal no repair in the
+    // run is applied (each is reported failed — the dispatcher's exit-0 shape;
+    // the defect itself is W030) and the tree is untouched.
+    const regenerateRequested = repair && diagnostics.some((d) => d.remedy.action === REMEDY_ACTION.REGENERATE_STATE && d.remedy.risk !== REMEDY_RISK.DESTRUCTIVE);
+    let abortMessage = null;
+    if (regenerateRequested) {
+        try {
+            assertVerificationReportsReadable('', cwd);
+        }
+        catch (err) {
+            abortMessage = err instanceof Error ? err.message : String(err);
+        }
+    }
     for (const diagnostic of diagnostics) {
         const { remedy, code } = diagnostic;
         if (remedy.action === REMEDY_ACTION.ADVISE)
@@ -398,6 +424,17 @@ function applyRepairs(cwd, diagnostics, repair, backfill) {
             });
             continue;
         }
+        if (abortMessage !== null) {
+            details.push({
+                code,
+                action: remedy.action,
+                success: false,
+                error: remedy.action === REMEDY_ACTION.REGENERATE_STATE
+                    ? abortMessage
+                    : `not applied: the run stopped before its first write — ${abortMessage}`,
+            });
+            continue;
+        }
         try {
             const outcome = runRepairAction(cwd, remedy.action, paths);
             if (outcome.extraDetails) {

package/gsd-core/bin/lib/host-runtime-detection.cjs

@@ -24,6 +24,7 @@ exports.resolveReportedRuntime = resolveReportedRuntime;
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
 const runtime_slash_cjs_1 = require("./runtime-slash.cjs");
+const runtime_name_policy_cjs_1 = require("./runtime-name-policy.cjs");
 const update_context_cjs_1 = require("./update-context.cjs");
 Object.defineProperty(exports, "CODEX_CONFIG_MARKER", { enumerable: true, get: function () { return update_context_cjs_1.CODEX_CONFIG_MARKER; } });
 // Codex sandbox env vars set by the shell tool / Seatbelt child-process spawn.
@@ -127,6 +128,14 @@ function resolveReportedRuntimeUnsafe(projectDir, deps) {
     const explicit = (0, runtime_slash_cjs_1.resolveExplicitRuntime)(projectDir, deps?.env ?? process.env);
     if (explicit)
         return explicit;
+    // #4717: the per-install marker names the runtime that owns THIS tree — a
+    // stronger signal than host sniffing, which misreports every session on a
+    // multi-runtime machine (e.g. a globally exported CODEX_HOME makes a Claude
+    // Code session read as codex). Marker-less trees (dev/source, pre-#2297
+    // installs) fall through to host detection unchanged.
+    const marker = (0, runtime_name_policy_cjs_1.resolveRuntimeNameFromCandidates)((0, runtime_slash_cjs_1.readInstallRuntimeMarker)());
+    if (marker)
+        return marker;
     const detected = detectHostRuntime(deps);
     if (detected.runtime)
         return detected.runtime;