@opengsd/gsd-core 1.10.0 → 1.12.0

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

@@ -0,0 +1,451 @@
+"use strict";
+/**
+ * Health Diagnostic — frozen rule-table types, enums, and evaluator for
+ * `validate health` (Phase 11, #3309, ADR-3180 §8.2/§8.3/§8.5).
+ *
+ * Establishes the exact contract every extracted rule builds onto: the
+ * frozen `SEVERITY`/`REMEDY_ACTION`/`REMEDY_RISK` enums, the
+ * `Diagnostic`/`Remedy`/`Rule` shapes, the `RULES` container (the 32 rules
+ * extracted from `cmdValidateHealth`, `src/verify.cts:1616-2577`, are
+ * concatenated in from each rule-group file under
+ * `src/health-diagnostic-rules/`), the `evaluateRules` evaluator, and the
+ * `applyRepairs` `--repair`/`--backfill` dispatcher — whose per-action
+ * handlers are REAL here (ported behavior-preserving from
+ * `verify.cts:2405-2553`'s repair switch), not stubs.
+ *
+ * `applyRepairs` does not receive a `PlanningSnapshot` (its call-site
+ * signature, `(cwd, diagnostics, repair, backfill)`, is a locked contract —
+ * see `tests/health-diagnostic.test.cjs`) — so, like `cmdValidateHealth`
+ * itself before this migration, it performs its own bounded filesystem I/O
+ * to apply a repair. This is not a §8.1 rule 1 violation: that rule
+ * constrains a RULE's `check(snapshot)` signature (no ambient I/O), not the
+ * evaluator/dispatcher, which the design doc's "subject-surface gap" section
+ * already establishes performs I/O once, up front, on the rules' behalf.
+ *
+ * `PlanningSnapshot` is deliberately NOT re-exported as a type from
+ * `planning-snapshot.cts` here (see the design doc's "Known limits" and this
+ * phase's brief): `ReturnType<typeof buildPlanningSnapshot>` is used inline
+ * instead, via a type-only `import ... = require(...)` that is fully erased
+ * at compile time — zero changes to the already-shipped, already-tested
+ * `planning-snapshot.cts`.
+ *
+ * Design: .gsd/phase/refactor-3309-health-diagnostic-rule-table/40-design.md
+ * Test matrix: .gsd/phase/refactor-3309-health-diagnostic-rule-table/50-test-matrix.md
+ *
+ * ADR-457 build-at-publish: source in src/health-diagnostic.cts, compiled to
+ * gsd-core/bin/lib/health-diagnostic.cjs (gitignored).
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+// Runtime values (SEVERITY/REMEDY_ACTION/REMEDY_RISK) are needed here — not
+// just types — for `applyRepairs`'s comparisons, so this is a normal
+// (non type-only) `import ... = require(...)`. `health-diagnostic-types.cjs`
+// is the leaf module these enums/types were extracted to, so that this file
+// can `require()` every rule-group file below without a circular dependency
+// (see that module's file-level comment for the full explanation).
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const healthDiagnosticTypesMod = require("./health-diagnostic-types.cjs");
+const { SEVERITY, REMEDY_ACTION, REMEDY_RISK } = healthDiagnosticTypesMod;
+// ─── Rule table ─────────────────────────────────────────────────────────────
+// Populated by concatenating each rule group's exported `RULES` array (design
+// doc, "Rule table organization" section) — the 32 rule functions extracted
+// from `cmdValidateHealth`, `src/verify.cts:1616-2577`.
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const rootExistenceMod = require("./health-diagnostic-rules/root-existence.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const stateConsistencyMod = require("./health-diagnostic-rules/state-consistency.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const configValidationMod = require("./health-diagnostic-rules/config-validation.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const phaseStructureMod = require("./health-diagnostic-rules/phase-structure.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const agentInstallMod = require("./health-diagnostic-rules/agent-install.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const roadmapDiskConsistencyMod = require("./health-diagnostic-rules/roadmap-disk-consistency.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const worktreeHealthMod = require("./health-diagnostic-rules/worktree-health.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const milestoneArchiveHygieneMod = require("./health-diagnostic-rules/milestone-archive-hygiene.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const consistencyMod = require("./health-diagnostic-rules/consistency.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const installSurfaceShadowingMod = require("./health-diagnostic-rules/install-surface-shadowing.cjs");
+const RULES = [
+    ...rootExistenceMod.RULES,
+    ...stateConsistencyMod.RULES,
+    ...configValidationMod.RULES,
+    ...phaseStructureMod.RULES,
+    ...agentInstallMod.RULES,
+    ...roadmapDiskConsistencyMod.RULES,
+    ...worktreeHealthMod.RULES,
+    ...milestoneArchiveHygieneMod.RULES,
+    ...installSurfaceShadowingMod.RULES,
+];
+/**
+ * `validate.consistency`'s own rule set (Phase 12, #3310, ADR-3180 §8.4,
+ * design doc "Which rules run where") — W006/W007 REUSED (the exact same
+ * `Rule` objects `RULES` above already carries, not new copies) plus the
+ * four new C0NN rules from `consistency.cts`. Deliberately NOT the full
+ * `RULES` table: running `validate.health`'s config/state/worktree rules
+ * under `validate.consistency` would be scope creep the issue never asked
+ * for.
+ */
+const CONSISTENCY_RULES = [
+    ...roadmapDiskConsistencyMod.RULES.filter((r) => ['W006', 'W007'].includes(r.code)),
+    ...consistencyMod.RULES,
+];
+// ─── Repair-handler runtime dependencies ───────────────────────────────────
+//
+// Same owners `cmdValidateHealth`'s pre-migration repair switch used
+// (`verify.cts:2405-2553`) — ported verbatim, not reinvented.
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const planningWorkspaceMod = require("./planning-workspace.cjs");
+const { planningDir } = planningWorkspaceMod;
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const configLoaderMod = require("./config-loader.cjs");
+const { CONFIG_DEFAULTS } = configLoaderMod;
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+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;
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const frontmatter = require("./frontmatter.cjs");
+const { extractFrontmatter } = frontmatter;
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const stateTransitionMod = require("./state-transition.cjs");
+const { rebuildStateTransaction } = stateTransitionMod;
+const clock_cjs_1 = require("./clock.cjs");
+const shell_command_projection_cjs_1 = require("./shell-command-projection.cjs");
+const runtime_slash_cjs_1 = require("./runtime-slash.cjs");
+// ─── Evaluator ──────────────────────────────────────────────────────────────
+/**
+ * Evaluate an explicit `rules` array against `snapshot`, throwing if any two
+ * entries share a `code` (defense in depth beside the static lint guard,
+ * §8.2 rule 1, `scripts/lint-health-diagnostic-rule-table.cjs`). Separated
+ * from `evaluateRules` so the duplicate-code guard is unit-testable against
+ * a small, locally-constructed fake rule array, independent of the real
+ * `RULES` table.
+ */
+function evaluateRuleTable(rules, snapshot) {
+    const seen = new Set();
+    for (const rule of rules) {
+        if (seen.has(rule.code)) {
+            throw new Error(`health-diagnostic: duplicate rule code "${rule.code}" in rule table`);
+        }
+        seen.add(rule.code);
+    }
+    return rules.flatMap((rule) => rule.check(snapshot));
+}
+/**
+ * Evaluate every rule in `RULES` against `snapshot`, flattening each rule's
+ * `Diagnostic[]` into one array.
+ */
+function evaluateRules(snapshot) {
+    return evaluateRuleTable(RULES, snapshot);
+}
+/**
+ * Evaluate `CONSISTENCY_RULES` (W006/W007 + C001-C004) against `snapshot` —
+ * `validate.consistency`'s evaluator entry point, mirroring `evaluateRules`
+ * exactly but over the smaller, command-specific rule subset.
+ */
+function evaluateConsistencyRules(snapshot) {
+    return evaluateRuleTable(CONSISTENCY_RULES, snapshot);
+}
+/**
+ * Derive every filesystem path a repair handler needs, from `cwd` alone —
+ * exactly how `cmdValidateHealth` derived them pre-migration
+ * (`verify.cts:1644-1652`/`2301-2302`). `config.json`/`MILESTONES.md`/
+ * `milestones/` are root-scoped (`planningRoot`); `STATE.md` is
+ * workstream-scoped (`planningDir`) — the same root-vs-workstream split
+ * `buildConfigField`/`buildStateFields` (`planning-snapshot.cts`) already
+ * document for the read side.
+ */
+function repairPaths(cwd) {
+    // #3749: the project root is PROJECT-aware but deliberately NOT workstream-
+    // scoped — under GSD_PROJECT, config.json/MILESTONES.md/milestones belong to
+    // `.planning/<project>/` (the same base init.new-project's config_path
+    // names); under GSD_WORKSTREAM they stay at the workstream PARENT, keeping
+    // the documented root-vs-workstream split. planningDir(cwd, null) is exactly
+    // that base: project env honored, ws env suppressed.
+    const rootBase = planningDir(cwd, null);
+    const wsBase = planningDir(cwd);
+    return {
+        rootBase,
+        configPath: node_path_1.default.join(rootBase, 'config.json'),
+        statePath: node_path_1.default.join(wsBase, 'STATE.md'),
+        milestonesPath: node_path_1.default.join(rootBase, 'MILESTONES.md'),
+        milestonesArchiveDir: node_path_1.default.join(rootBase, 'milestones'),
+    };
+}
+/** `verify.cts:2413-2429`'s default config.json payload, ported verbatim. */
+function defaultConfigPayload() {
+    return {
+        model_profile: CONFIG_DEFAULTS.model_profile,
+        commit_docs: CONFIG_DEFAULTS.commit_docs,
+        search_gitignored: CONFIG_DEFAULTS.search_gitignored,
+        branching_strategy: CONFIG_DEFAULTS.branching_strategy,
+        phase_branch_template: CONFIG_DEFAULTS.phase_branch_template,
+        milestone_branch_template: CONFIG_DEFAULTS.milestone_branch_template,
+        quick_branch_template: CONFIG_DEFAULTS.quick_branch_template,
+        workflow: {
+            research: CONFIG_DEFAULTS.research,
+            plan_check: CONFIG_DEFAULTS.plan_checker,
+            verifier: CONFIG_DEFAULTS.verifier,
+            nyquist_validation: CONFIG_DEFAULTS.nyquist_validation,
+        },
+        parallelization: CONFIG_DEFAULTS.parallelization,
+        brave_search: CONFIG_DEFAULTS.brave_search,
+    };
+}
+/**
+ * `verify.cts:2301-2335`'s W018 archived-vs-documented-versions diff,
+ * relocated verbatim (same two regexes, same two-file read) so
+ * `backfillMilestones` can recompute exactly which versions are missing
+ * without a `PlanningSnapshot` (`applyRepairs` is not a `Rule` and is not
+ * handed one — see this file's header comment). This is the same
+ * derivation `buildMilestoneArchiveStatusField`
+ * (`src/planning-snapshot.cts`) already performs for the W018 RULE's read
+ * side; recomputed here, not re-invented, because the rule's own
+ * `Diagnostic.remedy.args` carries no version list (confirmed by direct
+ * read of `src/health-diagnostic-rules/milestone-archive-hygiene.cts`).
+ */
+function computeMissingMilestoneVersions(milestonesArchiveDir, milestonesPath) {
+    let archivedVersions = [];
+    try {
+        if (node_fs_1.default.existsSync(milestonesArchiveDir)) {
+            const archiveFiles = node_fs_1.default.readdirSync(milestonesArchiveDir);
+            archivedVersions = archiveFiles
+                .map((f) => f.match(/^(v\d+\.\d+(?:\.\d+)?)-ROADMAP\.md$/))
+                .filter((m) => m !== null)
+                .map((m) => m[1]);
+        }
+    }
+    catch {
+        /* intentionally empty — mirrors the original's advisory try/catch */
+    }
+    let documentedVersions = [];
+    try {
+        if (node_fs_1.default.existsSync(milestonesPath)) {
+            const registryContent = node_fs_1.default.readFileSync(milestonesPath, 'utf-8');
+            documentedVersions = [...registryContent.matchAll(/^##\s+(v\d+\.\d+(?:\.\d+)?)/gm)].map((m) => m[1]);
+        }
+    }
+    catch {
+        /* intentionally empty */
+    }
+    const documented = new Set(documentedVersions);
+    return archivedVersions.filter((v) => !documented.has(v));
+}
+/**
+ * Execute exactly one real repair action, ported behavior-preserving from
+ * `verify.cts:2405-2553`'s `switch (repair)`. Throws are the caller's
+ * responsibility to catch (mirrors the original's per-action try/catch
+ * shape, collapsed to one seam here since every case now shares one
+ * caller).
+ */
+function runRepairAction(cwd, action, paths) {
+    const { rootBase, configPath, statePath, milestonesPath, milestonesArchiveDir } = paths;
+    switch (action) {
+        case REMEDY_ACTION.CREATE_CONFIG:
+        case REMEDY_ACTION.RESET_CONFIG: {
+            (0, shell_command_projection_cjs_1.platformWriteSync)(configPath, JSON.stringify(defaultConfigPayload(), null, 2));
+            return { success: true, path: 'config.json' };
+        }
+        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'))
+                .split(node_path_1.default.sep)
+                .join('/');
+            const slashRuntime = (0, runtime_slash_cjs_1.resolveRuntime)(cwd);
+            const slash = (name) => (0, runtime_slash_cjs_1.formatGsdSlash)(name, slashRuntime);
+            let stateContent = `# Session State\n\n`;
+            stateContent += `## Project Reference\n\n`;
+            stateContent += `See: ${projectRef}\n\n`;
+            stateContent += `## Position\n\n`;
+            stateContent += `**Milestone:** ${milestone?.version ?? ''} ${milestone?.name ?? ''}\n`;
+            stateContent += `**Current phase:** (determining...)\n`;
+            stateContent += `**Status:** Resuming\n\n`;
+            stateContent += `## Session Log\n\n`;
+            stateContent += `- ${clock_cjs_1.realClock.localToday()}: STATE.md regenerated by ${slash('health')} --repair\n`;
+            // ADR-3473 §8.6: `/gsd-health --repair` is a factory reset, so
+            // preservation must not run; the snapshot of the file being replaced is
+            // still captured, and `{}` is the correct, legal snapshot of a
+            // 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) ?? '') : '';
+            writeStateMd(statePath, stateContent, rebuildStateTransaction({
+                snapshot: extractFrontmatter(priorState, statePath),
+            }), cwd);
+            return { success: true, path: 'STATE.md', extraDetails };
+        }
+        case REMEDY_ACTION.ADD_NYQUIST_KEY:
+        case REMEDY_ACTION.ADD_AI_INTEGRATION_PHASE_KEY: {
+            const key = action === REMEDY_ACTION.ADD_NYQUIST_KEY ? 'nyquist_validation' : 'ai_integration_phase';
+            const configRaw = node_fs_1.default.readFileSync(configPath, 'utf-8');
+            const configParsed = JSON.parse(configRaw);
+            if (!configParsed['workflow'])
+                configParsed['workflow'] = {};
+            const wf = configParsed['workflow'];
+            if (wf[key] === undefined) {
+                wf[key] = true;
+                (0, shell_command_projection_cjs_1.platformWriteSync)(configPath, JSON.stringify(configParsed, null, 2));
+            }
+            return { success: true, path: 'config.json' };
+        }
+        case REMEDY_ACTION.BACKFILL_MILESTONES: {
+            const missing = computeMissingMilestoneVersions(milestonesArchiveDir, milestonesPath);
+            const today = clock_cjs_1.realClock.localToday();
+            const slashRuntime = (0, runtime_slash_cjs_1.resolveRuntime)(cwd);
+            const slash = (name) => (0, runtime_slash_cjs_1.formatGsdSlash)(name, slashRuntime);
+            let backfilled = 0;
+            for (const ver of missing) {
+                try {
+                    const snapshotPath = node_path_1.default.join(milestonesArchiveDir, `${ver}-ROADMAP.md`);
+                    const snapshot = (0, shell_command_projection_cjs_1.platformReadSync)(snapshotPath);
+                    const titleMatch = snapshot && snapshot.match(/^#\s+(.+)$/m);
+                    const milestoneName = titleMatch
+                        ? titleMatch[1].replace(/^Milestone\s+/i, '').replace(/^v[\d.]+\s*/, '').trim()
+                        : ver;
+                    const entry = `## ${ver}${milestoneName && milestoneName !== ver ? ` ${milestoneName}` : ''} (Backfilled: ${today})\n\n**Note:** Synthesized from archive snapshot by \`${slash('health')} --backfill\`. Original completion date unknown.\n\n---\n\n`;
+                    const milestonesContent = node_fs_1.default.existsSync(milestonesPath)
+                        ? node_fs_1.default.readFileSync(milestonesPath, 'utf-8')
+                        : '';
+                    if (!milestonesContent.trim()) {
+                        (0, shell_command_projection_cjs_1.platformWriteSync)(milestonesPath, `# Milestones\n\n${entry}`);
+                    }
+                    else {
+                        const headerMatch = milestonesContent.match(/^(#{1,3}\s+[^\n]*\n\n?)/);
+                        if (headerMatch) {
+                            const header = headerMatch[1];
+                            const rest = milestonesContent.slice(header.length);
+                            (0, shell_command_projection_cjs_1.platformWriteSync)(milestonesPath, header + entry + rest);
+                        }
+                        else {
+                            (0, shell_command_projection_cjs_1.platformWriteSync)(milestonesPath, entry + milestonesContent);
+                        }
+                    }
+                    backfilled++;
+                }
+                catch {
+                    /* intentionally empty — partial backfill is acceptable */
+                }
+            }
+            return { success: true, detail: `Backfilled ${backfilled} milestone(s) into MILESTONES.md` };
+        }
+        default:
+            return { success: false, error: `no repair handler registered for action "${action}"` };
+    }
+}
+/**
+ * `--repair`/`--backfill` dispatcher (design doc "`--repair` behavior
+ * change" section; §8.3 rule 3). For each diagnostic whose remedy is not
+ * `ADVISE`:
+ *
+ * - Not requested — `repair` is false, and for `backfillMilestones`
+ *   specifically `backfill` is also false (mirrors `cmdValidateHealth`'s
+ *   existing `backfillMilestones` gate, `verify.cts:2504`:
+ *   `if (!options['backfill'] && !options['repair']) break;`) — skipped
+ *   entirely, recorded in neither `applied` nor `refused`.
+ * - Requested and `remedy.risk === DESTRUCTIVE` — pushed onto `refused`,
+ *   handler never invoked. This is the §8.3 rule 3 breaking-change
+ *   enforcement point: a DESTRUCTIVE remedy is describable but is never
+ *   applied by `--repair`. A `details` row is still recorded, so the
+ *   refusal is VISIBLE in `cmdValidateHealth`'s `repairs_performed` output,
+ *   not silently dropped.
+ * - Requested and `remedy.risk === NONE` — the real handler is invoked,
+ *   pushed onto `applied`.
+ *
+ * `applied`/`refused` are unchanged in shape from the pre-existing skeleton
+ * (locked by `tests/health-diagnostic.test.cjs`, rows 11-12): arrays of
+ * diagnostic `code`s. `details` is ADDITIVE — every real action maps 1:1 to
+ * exactly one code in this rule table (confirmed: no `REMEDY_ACTION` other
+ * than `ADVISE` is used by more than one rule), so `cmdValidateHealth` can
+ * rebuild the legacy action-keyed `repairs_performed` shape directly from
+ * it.
+ */
+function applyRepairs(cwd, diagnostics, repair, backfill) {
+    const applied = [];
+    const refused = [];
+    const details = [];
+    const paths = repairPaths(cwd);
+    for (const diagnostic of diagnostics) {
+        const { remedy, code } = diagnostic;
+        if (remedy.action === REMEDY_ACTION.ADVISE)
+            continue;
+        const requested = remedy.action === REMEDY_ACTION.BACKFILL_MILESTONES ? repair || backfill : repair;
+        if (!requested)
+            continue;
+        if (remedy.risk === REMEDY_RISK.DESTRUCTIVE) {
+            refused.push(code);
+            details.push({
+                code,
+                action: remedy.action,
+                success: false,
+                error: `refused: '${remedy.action}' is a destructive remedy and is not auto-applied by --repair`,
+            });
+            continue;
+        }
+        try {
+            const outcome = runRepairAction(cwd, remedy.action, paths);
+            if (outcome.extraDetails) {
+                for (const extra of outcome.extraDetails) {
+                    details.push({ code, action: extra.action, success: extra.success, ...(extra.path ? { path: extra.path } : {}) });
+                }
+            }
+            details.push({
+                code,
+                action: remedy.action,
+                success: outcome.success,
+                ...(outcome.path ? { path: outcome.path } : {}),
+                ...(outcome.detail ? { detail: outcome.detail } : {}),
+                ...(outcome.error ? { error: outcome.error } : {}),
+            });
+            // `applied` means "the repair actually succeeded", not "was attempted"
+            // — a handler that returns `{success: false}` (or throws, caught
+            // below) is recorded in `details` with its failure, but must not be
+            // reported as applied. `refused` is reserved for the DESTRUCTIVE-risk
+            // gate above; a failed attempt is neither applied nor refused.
+            if (outcome.success)
+                applied.push(code);
+        }
+        catch (err) {
+            details.push({
+                code,
+                action: remedy.action,
+                success: false,
+                error: err instanceof Error ? err.message : String(err),
+            });
+        }
+    }
+    return { applied, refused, details };
+}
+// ─── Exports ────────────────────────────────────────────────────────────────
+const healthDiagnostic = {
+    SEVERITY,
+    REMEDY_ACTION,
+    REMEDY_RISK,
+    RULES,
+    evaluateRules,
+    // Additive beyond the phase's required-exports list — exposed so the
+    // duplicate-code guard (row 13) is directly unit-testable against a fake
+    // rule array without mutating the real, still-empty `RULES` export.
+    evaluateRuleTable,
+    applyRepairs,
+    // Phase 12 (#3310) — `validate.consistency`'s own rule subset + evaluator.
+    CONSISTENCY_RULES,
+    evaluateConsistencyRules,
+};
+module.exports = healthDiagnostic;

package/gsd-core/bin/lib/host-integration.cjs

@@ -653,10 +653,25 @@ function extensionEventSurfaceFor(extensionEvents) {
  * per-host branch ADR-1239 exists to remove. Omit `prompt` entirely and the
  * resolution is byte-identical to Phase 2's (the unconsumed-resolver shape).
  *
- * Argv order is base args → cwd flag → prompt, so the prompt stays the final
- * positional token for the hosts that read it that way.
+ * Argv order is base args → model flag → cwd flag → prompt, so the prompt
+ * stays the final positional token for the hosts that read it that way. The
+ * model flag is placed BEFORE the cwd flag (not after, and not appended at
+ * the very end) purely to keep it clear of that trailing positional — the
+ * model value itself is never the prompt-adjacent token a host might scan
+ * for last.
+ *
+ * `model` (Phase 4, #3714) is optional, descriptor-gated exactly like prompt:
+ * a `modelFlag` string on the descriptor names the flag that pins the
+ * spawned executor's model (codex: `--model`); `null`/absent means the host
+ * exposes no such override on this exec path, and `[modelFlag, model]` is
+ * appended ONLY when both the descriptor's `modelFlag` and the caller's
+ * `model` are non-empty strings. Omitting `model` entirely (or passing it to
+ * a host with no `modelFlag`) is byte-identical to the resolver's behavior
+ * before this parameter existed. This function decides no policy about WHICH
+ * model to pass or what 'inherit' means — that is entirely the caller's job;
+ * this seam only shapes descriptor + values into argv.
  */
-function resolveOrchestratorExec(orchestratorExec, cwd, prompt) {
+function resolveOrchestratorExec(orchestratorExec, cwd, prompt, model) {
     if (!orchestratorExec || typeof orchestratorExec !== 'object' || Array.isArray(orchestratorExec)) {
         return { ok: false, reason: 'missing_command' };
     }
@@ -676,11 +691,22 @@ function resolveOrchestratorExec(orchestratorExec, cwd, prompt) {
     if (oe.promptFlag !== undefined && oe.promptFlag !== null && typeof oe.promptFlag !== 'string') {
         return { ok: false, reason: 'invalid_prompt_flag' };
     }
+    if (oe.modelFlag !== undefined && oe.modelFlag !== null && typeof oe.modelFlag !== 'string') {
+        return { ok: false, reason: 'invalid_model_flag' };
+    }
     // An executor spawned with no instruction is a hang, not a degraded run —
     // fail closed rather than launching a prompt-less process.
     if (prompt !== undefined && (typeof prompt !== 'string' || prompt.length === 0)) {
         return { ok: false, reason: 'invalid_prompt' };
     }
+    // Unlike `prompt` — where empty is a hang, not a degraded run, hence the
+    // fail-closed check above — an absent/null/empty model is simply "use the
+    // host default", the same benign degradation `cwdFlag: null` already
+    // expresses. Only a present-but-non-string value (number/bool/array/object)
+    // is a caller error; null/undefined/'' fall through to "omit the flag".
+    if (model !== undefined && model !== null && typeof model !== 'string') {
+        return { ok: false, reason: 'invalid_model' };
+    }
     // Leading-dash guard, mirroring worktree-safety.cts's `unsafe_leading_dash`
     // check on git arguments. A positional prompt (or a cwd) beginning with '-'
     // is parsed by the spawned CLI as a FLAG, not a value — the same failure the
@@ -695,10 +721,17 @@ function resolveOrchestratorExec(orchestratorExec, cwd, prompt) {
     if (cwd.startsWith('-')) {
         return { ok: false, reason: 'unsafe_leading_dash_cwd' };
     }
+    if (typeof model === 'string' && model.startsWith('-')) {
+        return { ok: false, reason: 'unsafe_leading_dash_model' };
+    }
     const baseArgs = Array.isArray(oe.args) ? [...oe.args] : [];
-    const args = typeof oe.cwdFlag === 'string' && oe.cwdFlag.length > 0
-        ? [...baseArgs, oe.cwdFlag, cwd]
-        : baseArgs;
+    let args = baseArgs;
+    if (typeof oe.modelFlag === 'string' && oe.modelFlag.length > 0 && typeof model === 'string' && model.length > 0) {
+        args = [...args, oe.modelFlag, model];
+    }
+    args = typeof oe.cwdFlag === 'string' && oe.cwdFlag.length > 0
+        ? [...args, oe.cwdFlag, cwd]
+        : args;
     if (typeof prompt === 'string') {
         if (typeof oe.promptFlag === 'string' && oe.promptFlag.length > 0) {
             args.push(oe.promptFlag, prompt);

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

@@ -0,0 +1,134 @@
+"use strict";
+/**
+ * Host runtime detection — ADR-2313 Phase 5 (#3245, folded from #2320).
+ *
+ * `init`'s reported `agent_runtime` was hardcoding `claude` even when run
+ * inside a Codex session, because resolveRuntime's ladder only checks the
+ * explicit `GSD_RUNTIME` env var and `.planning/config.json`'s `runtime`
+ * field — there was no fallback that looked at the actual host process.
+ *
+ * This module adds a host-detection rung strictly BELOW those two explicit
+ * sources: it only runs when neither `GSD_RUNTIME` nor config `runtime` is
+ * set. It never writes anything (#2297 — no shared-defaults poisoning: this
+ * module never touches .planning/config.json or any other file). It never
+ * shells out, so there is no subprocess to time-bound — detection is pure
+ * env-var and existence-check inspection.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CODEX_CONFIG_HOME_ENV = exports.CODEX_SESSION_ENV_SIGNALS = exports.CODEX_CONFIG_MARKER = void 0;
+exports.detectHostRuntime = detectHostRuntime;
+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 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.
+// Evidence: openai/codex AGENTS.md — "The sandbox environment automatically
+// sets CODEX_SANDBOX_NETWORK_DISABLED=1 when using the shell tool, and
+// CODEX_SANDBOX=seatbelt for child processes spawned via Seatbelt." (injected
+// by spawn_child_async in codex-rs/core/src/spawn.rs). These are absent under
+// sandbox_mode = "danger-full-access", so this signal is best-effort and
+// degrades to the default when unset.
+//
+// Note: CODEX_THREAD_ID (which appears in src/active-workstream-store.cts's
+// WORKSTREAM_SESSION_ENV_KEYS) is deliberately NOT used here — it is
+// undocumented in Codex's published env-var reference and source, so it
+// fails this repo's citation bar.
+exports.CODEX_SESSION_ENV_SIGNALS = Object.freeze([
+    'CODEX_SANDBOX',
+    'CODEX_SANDBOX_NETWORK_DISABLED',
+]);
+// Evidence: learn.chatgpt.com/docs/config-file/environment-variables —
+// "Sets the root for Codex state, including config…". The marker FILENAME
+// (`config.toml`) is single-sourced from `update-context.cts`'s
+// `inferPreferredRuntime` (imported above and re-exported for existing
+// importers) — that is the only thing shared between the two functions. The
+// TRUTHINESS RULE deliberately differs: `inferPreferredRuntime` treats a
+// bare, unchecked `CODEX_HOME` as sufficient to resolve an update context,
+// while THIS module additionally requires the marker file to exist, because
+// it is asserting session identity rather than resolving an update context
+// and needs the stronger signal. That difference is intentional and pinned
+// by a test in `tests/host-runtime-detection.test.cjs` rather than left
+// implicit.
+//
+// The DEFAULT `~/.codex/config.toml` is deliberately NEVER probed here:
+// every machine that has ever run Codex has that file, so probing it
+// unconditionally would misreport Claude Code sessions (or any other
+// runtime) as codex just because Codex was installed at some point. An
+// explicitly-exported CODEX_HOME is the user designating a Codex root for
+// the CURRENT session, which is a much stronger signal.
+exports.CODEX_CONFIG_HOME_ENV = 'CODEX_HOME';
+// The degraded no-detection result. Also the fallback returned when ANY step
+// of detection throws (see the module's stated no-throw premise below).
+const NO_DETECTION = { runtime: null, source: 'none', signal: null };
+/**
+ * Detect the host runtime from process environment signals, without ever
+ * consulting the explicit GSD_RUNTIME/config.json sources (those are a
+ * higher-priority rung handled by resolveExplicitRuntime).
+ *
+ * Never throws: the whole body — including the raw `env[key]` reads, which a
+ * caller could supply as a throwing Proxy — is wrapped in a single guarded
+ * region that degrades to `NO_DETECTION` on any unexpected error, rather than
+ * only guarding the `fileExists` probe.
+ */
+function detectHostRuntime(deps) {
+    try {
+        const env = deps?.env ?? process.env;
+        const fileExists = deps?.fileExists ?? ((p) => node_fs_1.default.existsSync(p));
+        for (const key of exports.CODEX_SESSION_ENV_SIGNALS) {
+            const value = env[key];
+            if (typeof value === 'string' && value.trim() !== '') {
+                return { runtime: 'codex', source: 'session-env', signal: key };
+            }
+        }
+        const codexHome = env[exports.CODEX_CONFIG_HOME_ENV];
+        if (typeof codexHome === 'string' && codexHome.trim() !== '') {
+            try {
+                if (fileExists(node_path_1.default.join(codexHome, update_context_cjs_1.CODEX_CONFIG_MARKER))) {
+                    return { runtime: 'codex', source: 'config-home', signal: exports.CODEX_CONFIG_HOME_ENV };
+                }
+            }
+            catch {
+                // Swallow probe failures (EACCES etc.) and fall through to no-detection.
+            }
+        }
+        return NO_DETECTION;
+    }
+    catch {
+        // A malformed `deps.env` (e.g. a throwing Proxy) must degrade like any
+        // other unreadable signal, not propagate — this function's contract is
+        // that it never throws.
+        return NO_DETECTION;
+    }
+}
+/**
+ * Resolve the runtime to report from init: explicit sources first, then the
+ * host-detection rung, then the 'claude' default. This is intentionally
+ * separate from resolveRuntime — only init's agent_runtime reporting call
+ * site uses this ladder; every other resolveRuntime caller is unaffected.
+ *
+ * Never throws: degrades to the 'claude' default on any unexpected error
+ * (e.g. a throwing `deps.env`), matching detectHostRuntime's no-throw
+ * contract.
+ */
+function resolveReportedRuntime(projectDir, deps) {
+    try {
+        return resolveReportedRuntimeUnsafe(projectDir, deps);
+    }
+    catch {
+        return 'claude';
+    }
+}
+function resolveReportedRuntimeUnsafe(projectDir, deps) {
+    const explicit = (0, runtime_slash_cjs_1.resolveExplicitRuntime)(projectDir, deps?.env ?? process.env);
+    if (explicit)
+        return explicit;
+    const detected = detectHostRuntime(deps);
+    if (detected.runtime)
+        return detected.runtime;
+    return 'claude';
+}