@opengsd/gsd-core 1.10.0 → 1.11.0

package/gsd-core/bin/lib/check-command-router.cjs

@@ -28,6 +28,7 @@ const { extractFrontmatter } = frontmatterMod;
 const markdown_sectionizer_cjs_1 = require("./markdown-sectionizer.cjs");
 const security_cjs_1 = require("./security.cjs");
 const ui_safety_gate_cjs_1 = require("./ui-safety-gate.cjs");
+const ui_frontend_evidence_cjs_1 = require("./ui-frontend-evidence.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const verifyModule = require("./verify.cjs");
 const { cmdVerifySchemaDrift, cmdVerifyCodebaseDrift } = verifyModule;
@@ -45,6 +46,12 @@ const { evaluatePredicate } = gatePredicateEval;
 const apiCoverageMod = require("./api-coverage.cjs");
 const { detectApiIntegration, validateCoverageMatrix } = apiCoverageMod;
 const shell_command_projection_cjs_1 = require("./shell-command-projection.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const planScanMod = require("./plan-scan.cjs");
+const { scanPhasePlans } = planScanMod;
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const planningScopeMod = require("./planning-scope.cjs");
+const { SCOPE } = planningScopeMod;
 // ─── Helpers ──────────────────────────────────────────────────────────────────
 function normalizePhrase(text) {
     // eslint-disable-next-line @typescript-eslint/no-base-to-string
@@ -128,14 +135,13 @@ function gateEnabled(projectDir) {
 function loadPlanContents(phaseDir) {
     if (!node_fs_1.default.existsSync(phaseDir))
         return [];
-    try {
-        return node_fs_1.default.readdirSync(phaseDir)
-            .filter((entry) => /-PLAN\.md$/.test(entry))
-            .map((entry) => readIfExists(node_path_1.default.join(phaseDir, entry)));
-    }
-    catch {
-        return [];
-    }
+    // #3183 (lint-plan-count-drift): source live plan files from the single
+    // owner (scanPhasePlans) instead of a local `-PLAN.md` readdirSync filter
+    // — picks up bare PLAN.md and nested plans/, and excludes plans marked
+    // `status: superseded`, which the prior root-only exact-suffix filter did
+    // neither for.
+    return scanPhasePlans(phaseDir).planFiles
+        .map((entry) => readIfExists(node_path_1.default.join(phaseDir, entry)));
 }
 const DESIGNATED_HEADINGS_RE = /^#{1,6}\s+(?:must[_ ]haves?|truths?|tasks?|objective)\b/i;
 // #2372: scanned-tag set must match the planner-canonical surfaces where a D-NN citation
@@ -337,6 +343,7 @@ function recentCommitMessages(projectDir) {
             encoding: 'utf-8',
             maxBuffer: 4 * 1024 * 1024,
             windowsHide: true,
+            timeout: 15_000,
         });
     }
     catch {
@@ -411,8 +418,11 @@ function cmdDecisionCoverageVerify(projectDir, args, raw) {
         return;
     }
     const planContents = loadPlanContents(phaseDir);
+    // #3183 (lint-plan-count-drift): same single-owner sourcing as
+    // loadPlanContents above — scanPhasePlans's summaryFiles instead of a
+    // local `-SUMMARY.md` readdirSync filter.
     const summaryParts = node_fs_1.default.existsSync(phaseDir)
-        ? node_fs_1.default.readdirSync(phaseDir).filter((entry) => /-SUMMARY\.md$/.test(entry)).map((entry) => readIfExists(node_path_1.default.join(phaseDir, entry)))
+        ? scanPhasePlans(phaseDir).summaryFiles.map((entry) => readIfExists(node_path_1.default.join(phaseDir, entry)))
         : [];
     const haystack = [
         planContents.join('\n\n'),
@@ -442,8 +452,9 @@ function cmdDecisionCoverageVerify(projectDir, args, raw) {
  * ui-plan-gate: given a phase number, checks whether the phase has frontend
  * indicators and whether a *-UI-SPEC.md already exists in the phase directory.
  *
- * Returns JSON: { frontend: boolean, hasUiSpec: boolean, block: boolean }
- *   block = frontend && !hasUiSpec (gate fires when UI work is detected but no spec exists)
+ * Returns JSON: { frontend, hasFrontendEvidence, hasUiSpec, block, uiSpecPath, matchedToken, matchedLine }
+ *   block = frontend && hasFrontendEvidence && !hasUiSpec (#3312: gate fires when
+ *   UI work is detected AND the repo has static frontend evidence but no spec exists)
  *
  * Invocable as: gsd_run check ui-plan-gate <phase>
  *
@@ -477,10 +488,21 @@ function findUiSpecInDir(phaseDir) {
  *   (b) Runs checkUiPresence (frontend detection) — no reimplementation.
  *   (c) Resolves the phase directory via findPhaseInternal (phase-locator.cjs); checks for *-UI-SPEC.md.
  *
- * Returns: { frontend, hasUiSpec, block, uiSpecPath, phaseLookupFailed }
- *   block = frontend && !hasUiSpec
+ * Returns: { frontend, hasFrontendEvidence, hasUiSpec, block, uiSpecPath, matchedToken, matchedLine, phaseLookupFailed }
+ *   block = frontend && hasFrontendEvidence && !hasUiSpec   (#3312)
  *   phaseLookupFailed = ROADMAP.md present but phase header not found (surfaced for
  *                       onError:halt gates so a missing phase doesn't silently bypass)
+ *
+ * #3312 — structural corroboration: `frontend` is a vocabulary signal only. A
+ * hyphen is a word boundary, so a phase naming the repo `dashboard-financeiro`
+ * matches the token `dashboard` exactly like the real compound `micro-frontend`
+ * (the boundary rule of #3718 is intentional and untouched). The gate therefore
+ * blocks only when the token match is corroborated by static frontend evidence
+ * in the repo tree (hasStaticFrontendEvidence: package.json UI-framework dep or
+ * a component-framework file). This mirrors the sibling post-wave gate
+ * computeUiSafetyGate, which requires `hasUiFiles` (git diff) before blocking.
+ * matchedToken/matchedLine surface what tripped the sniffer so an operator can
+ * judge the flag in one second instead of reaching for --skip-ui.
  */
 function computeUiPlanGate(projectDir, phase) {
     // (a) Read the phase section text using the same two-pass lookup as roadmap.get-phase.
@@ -509,6 +531,9 @@ function computeUiPlanGate(projectDir, phase) {
     // (b) Run checkUiPresence (frontend detection) — reuse existing helper; no reimplementation
     const presenceResult = (0, ui_safety_gate_cjs_1.checkUiPresence)(phaseSection);
     const frontend = presenceResult.hasUI;
+    // (b') #3312 — static structural corroboration. Only probed when the sniffer
+    // matched (evidence is irrelevant otherwise); failures degrade to false.
+    const hasFrontendEvidence = frontend ? (0, ui_frontend_evidence_cjs_1.hasStaticFrontendEvidence)(projectDir) : false;
     // (c) Resolve phase directory via findPhaseInternal and check for *-UI-SPEC.md
     let phaseDir = '';
     try {
@@ -528,10 +553,13 @@ function computeUiPlanGate(projectDir, phase) {
     catch { /* phase dir lookup failure → hasUiSpec=false */ }
     const uiSpecPath = findUiSpecInDir(phaseDir);
     const hasUiSpec = uiSpecPath !== '';
-    // block = frontend phase with no UI-SPEC
-    const block = frontend && !hasUiSpec;
+    // block = frontend phase with structural frontend evidence and no UI-SPEC (#3312)
+    const block = frontend && hasFrontendEvidence && !hasUiSpec;
     const result = {
-        frontend, hasUiSpec, block, uiSpecPath: hasUiSpec ? uiSpecPath : null,
+        frontend, hasFrontendEvidence, hasUiSpec, block,
+        uiSpecPath: hasUiSpec ? uiSpecPath : null,
+        matchedToken: presenceResult.matchedToken,
+        matchedLine: presenceResult.matchedLine,
     };
     if (phaseLookupFailed)
         result.phaseLookupFailed = true;
@@ -613,6 +641,7 @@ function computeUiSafetyGate(projectDir, phase) {
             encoding: 'utf-8',
             maxBuffer: 2 * 1024 * 1024,
             windowsHide: true,
+            timeout: 10_000,
         });
         hasUiFiles = changed.split('\n').some((f) => f.trim() && (UI_FILE_EXTENSIONS_RE.test(f) || UI_PATH_PATTERNS_RE.test(f)));
     }
@@ -679,7 +708,9 @@ function cmdTddReviewCheckpoint(projectDir, args, raw) {
     const tddPlanFiles = [];
     if (phaseDir) {
         try {
-            const files = node_fs_1.default.readdirSync(phaseDir).filter(f => f.endsWith('-PLAN.md'));
+            // #3183: canonical plan set (root+nested, superseded-excluded) from the
+            // single owner, rather than a root-only hand-rolled readdirSync filter.
+            const files = scanPhasePlans(phaseDir).planFiles;
             for (const file of files) {
                 const planPath = node_path_1.default.join(phaseDir, file);
                 const content = readIfExists(planPath);
@@ -728,17 +759,17 @@ function cmdTddReviewCheckpoint(projectDir, args, raw) {
         let green = false;
         let refactor = false;
         try {
-            const redCommit = (0, node_child_process_1.execFileSync)('git', ['log', '--oneline', `--grep=^test(${planId}):`, '--', '.'], { cwd: projectDir, encoding: 'utf-8', maxBuffer: 1024 * 1024, windowsHide: true });
+            const redCommit = (0, node_child_process_1.execFileSync)('git', ['log', '--oneline', `--grep=^test(${planId}):`, '--', '.'], { cwd: projectDir, encoding: 'utf-8', maxBuffer: 1024 * 1024, windowsHide: true, timeout: 10_000 });
             red = redCommit.trim().length > 0;
         }
         catch { /* git unavailable or no match */ }
         try {
-            const greenCommit = (0, node_child_process_1.execFileSync)('git', ['log', '--oneline', `--grep=^feat(${planId}):`, '--', '.'], { cwd: projectDir, encoding: 'utf-8', maxBuffer: 1024 * 1024, windowsHide: true });
+            const greenCommit = (0, node_child_process_1.execFileSync)('git', ['log', '--oneline', `--grep=^feat(${planId}):`, '--', '.'], { cwd: projectDir, encoding: 'utf-8', maxBuffer: 1024 * 1024, windowsHide: true, timeout: 10_000 });
             green = greenCommit.trim().length > 0;
         }
         catch { /* git unavailable or no match */ }
         try {
-            const refactorCommit = (0, node_child_process_1.execFileSync)('git', ['log', '--oneline', `--grep=^refactor(${planId}):`, '--', '.'], { cwd: projectDir, encoding: 'utf-8', maxBuffer: 1024 * 1024, windowsHide: true });
+            const refactorCommit = (0, node_child_process_1.execFileSync)('git', ['log', '--oneline', `--grep=^refactor(${planId}):`, '--', '.'], { cwd: projectDir, encoding: 'utf-8', maxBuffer: 1024 * 1024, windowsHide: true, timeout: 10_000 });
             refactor = refactorCommit.trim().length > 0;
         }
         catch { /* git unavailable or no match */ }
@@ -1207,12 +1238,26 @@ function isRealReadFailure(err) {
 function readPhaseScope(projectDir, phaseDir, phaseNumber) {
     const chunks = [];
     let readError = null;
-    try {
-        const entries = node_fs_1.default.readdirSync(phaseDir, { withFileTypes: true });
-        const plans = entries
-            .filter((e) => e.isFile() && /-PLAN\.md$/i.test(e.name))
-            .map((e) => e.name)
-            .sort();
+    // A MISSING phase directory is fine (no plans yet → fall through to the
+    // roadmap). Checked up front (rather than via a readdirSync catch) because
+    // #3183 (lint-plan-count-drift) now sources the plan-file list from the
+    // single owner (scanPhasePlans) instead of a local `-PLAN\.md$` readdirSync
+    // filter — picks up bare PLAN.md and nested plans/, and excludes
+    // superseded plans, none of which the prior root-only exact-suffix filter
+    // did.
+    if (node_fs_1.default.existsSync(phaseDir)) {
+        const scan = scanPhasePlans(phaseDir);
+        if (scan.scope === SCOPE.UNREADABLE) {
+            // Directory exists but scanPhasePlans's own readdirSync(phaseDir) call
+            // failed (EACCES/EIO race) — a real read failure the gate must not
+            // silently pass (#2365 review), mirroring the prior isRealReadFailure
+            // branch below for the readdirSync-throws case.
+            return {
+                text: '',
+                readError: 'could not read the phase directory: scanPhasePlans reported scope UNREADABLE',
+            };
+        }
+        const plans = [...scan.planFiles].sort();
         for (const p of plans) {
             try {
                 chunks.push(node_fs_1.default.readFileSync(node_path_1.default.join(phaseDir, p), 'utf8'));
@@ -1226,17 +1271,6 @@ function readPhaseScope(projectDir, phaseDir, phaseNumber) {
             }
         }
     }
-    catch (err) {
-        // A MISSING phase directory is fine (no plans yet → fall through to the
-        // roadmap). A directory that exists but cannot be enumerated (EACCES/EIO)
-        // is a real read failure the gate must not silently pass (#2365 review).
-        if (isRealReadFailure(err)) {
-            return {
-                text: '',
-                readError: `could not read the phase directory: ${err instanceof Error ? err.message : String(err)}`,
-            };
-        }
-    }
     if (readError)
         return { text: chunks.join('\n\n'), readError };
     if (chunks.join('').trim().length > 0)

package/gsd-core/bin/lib/claude-orchestration.cjs

@@ -470,13 +470,43 @@ function emitWorkflowScript(input) {
         lines.push('// read-only in a Workflow script — set it via the caller\'s token directive.');
     }
     lines.push('');
+    // #3302: the generated script must hand the per-agent executor results back
+    // to the orchestrator so it can feed the wave merge chain. Emitted right
+    // after the header comments (meta stays the first statement): a helper that
+    // extracts the executor's <worktree_metadata> JSON (agents/gsd-executor.md
+    // <worktree_metadata_capture>) from one agent() result, plus the outcomes
+    // accumulator the stage barriers below push into. `metadata` is null when
+    // the result carried no parseable block — the LOUD-failure input the
+    // orchestrator halts on for expects_worktree plans (never a silent skip).
+    lines.push('// #3302: extract the executor-returned <worktree_metadata> JSON so the');
+    lines.push('// orchestrator can record it into WAVE_WORKTREE_MANIFEST after the run');
+    lines.push('// (worktree.record-agent -> worktree.cleanup-wave, the same manifest-scoped');
+    lines.push('// merge chain inline dispatch feeds). null = absent/unparseable/interrupted.');
+    lines.push('function gsdWorktreeMetadata(agentResult) {');
+    lines.push('  if (typeof agentResult !== \'string\') return null;');
+    lines.push('  const m = agentResult.match(/<worktree_metadata>([\\s\\S]*?)<\\/worktree_metadata>/);');
+    lines.push('  if (m === null) return null;');
+    lines.push('  try {');
+    lines.push('    const parsed = JSON.parse(m[1]);');
+    lines.push('    return (parsed !== null && typeof parsed === \'object\') ? parsed : null;');
+    lines.push('  } catch (e) {');
+    lines.push('    return null;');
+    lines.push('  }');
+    lines.push('}');
+    lines.push('const gsdAgentOutcomes = [];');
+    lines.push('');
     const stagesByWave = [];
     let totalPlans = 0;
+    let worktreePlans = 0;
     for (let wi = 0; wi < waves.length; wi++) {
         const wave = waves[wi];
         const stages = partitionStages(wave.plans);
         stagesByWave.push(stages);
         totalPlans += wave.plans.length;
+        for (const p of wave.plans) {
+            if (p.use_worktree !== false)
+                worktreePlans += 1;
+        }
         lines.push('// Wave ' + wave.id);
         // Title must match this wave's meta.phases entry EXACTLY.
         lines.push('phase(' + quoteString('Wave ' + wave.id) + ')');
@@ -491,17 +521,37 @@ function emitWorkflowScript(input) {
             // threw "parallel() expects an array of functions" (#2590). Passing
             // agent() results directly would also start every agent eagerly, before
             // parallel() could bound concurrency.
-            lines.push('await parallel([');
+            // #3302: capture the barrier's resolved results (one per thunk, in thunk
+            // order — the documented parallel() contract) so each plan's outcome can
+            // be tagged and returned below. Discarding them stranded every
+            // worktree-wf_* branch: the merge chain had no input (#3302).
+            lines.push('const gsdStage_' + wi + '_' + si + ' = await parallel([');
             for (const p of stagePlans) {
                 lines.push('  () => agent(' + quoteString(p.brief) + ', ' + agentOptions(p, executorModel) + '),');
             }
             lines.push('])');
+            // Positional tagging is decided at EMIT time from the validated manifest,
+            // so attribution survives out-of-order completion and needs no runtime
+            // introspection. expects_worktree mirrors agentOptions' own per-plan
+            // decision (use_worktree !== false).
+            lines.push('gsdAgentOutcomes.push(');
+            for (let pi = 0; pi < stagePlans.length; pi++) {
+                const p = stagePlans[pi];
+                const tail = pi < stagePlans.length - 1 ? ',' : '';
+                lines.push('  { plan: ' + quoteString(p.id) + ', expects_worktree: ' + (p.use_worktree !== false) + ', metadata: gsdWorktreeMetadata(gsdStage_' + wi + '_' + si + '[' + pi + ']) }' + tail);
+            }
+            lines.push(')');
         }
         if (wi < waves.length - 1)
             lines.push('');
     }
-    lines.push('// Each agent writes SUMMARY.md on its worktree branch; commits land there');
-    lines.push('// and are merged by the orchestrator exactly as in inline wave dispatch.');
+    // #3302: the script's top-level return value is what the Workflow tool hands
+    // back to the orchestrator. One { plan, expects_worktree, metadata } entry
+    // per dispatched plan; the orchestrator records every worktree entry via
+    // `gsd_run query worktree.record-agent` and HALTS on a null metadata entry
+    // for an expects_worktree plan (see the execute:wave:pre fragment) — a
+    // silently-empty manifest is the exact #3302 failure mode.
+    lines.push('return gsdAgentOutcomes');
     const script = lines.join('\n');
     return {
         ok: true,
@@ -509,6 +559,9 @@ function emitWorkflowScript(input) {
         summary: {
             waves: waves.length,
             plans: totalPlans,
+            // #3302: the number of record-agent entries the orchestrator must end up
+            // with in WAVE_WORKTREE_MANIFEST after the run — the loud count check.
+            worktreePlans,
             stagesByWave,
             resumeRunId: runId,
             budgetTokens,

package/gsd-core/bin/lib/codex-agent-toml.cjs

@@ -0,0 +1,329 @@
+"use strict";
+/**
+ * Codex Agent TOML — typed IR for `~/.codex/agents/<agent>.toml` (#3243, ADR-2313).
+ *
+ * A genuine leaf: node builtins only. This is a **document model**, not a policy —
+ * it knows how to parse/render/strip two known keys (`model`,
+ * `model_reasoning_effort`) from a Codex agent `.toml`. It does NOT know which
+ * `model` values are illegal for Codex (that predicate — Anthropic-flavored
+ * detection — stays in `model-catalog.cts`; callers decide what to strip).
+ *
+ * Moved here (not copied) from `agent-install-check.cts` (#3242, Phase 2), which
+ * wrote the hard half: block-range detection, BOM stripping, TOML value
+ * unquoting, and the lenient header scan. That module's behavior is UNCHANGED —
+ * it imports `stripBOM`/`scanTomlLines` from here and its regression suite
+ * (`tests/agent-install-check.test.cjs`) is the proof.
+ *
+ * ── The reconciliation (40-design.md) ──────────────────────────────────────
+ *
+ * Phase 2's reader and this phase's writer disagree on how to handle an
+ * unterminated `developer_instructions` block, deliberately:
+ *
+ *   - The READER (`scanTomlLines`, used directly by `checkCodexModelPosture`)
+ *     stays LENIENT: an unterminated block still excludes "the rest of the
+ *     file" from the header scan (findDeveloperInstructionsBlockRange's
+ *     existing fallback), because misreading prompt prose as a pin is only a
+ *     false positive — it wastes a user's time, nothing more.
+ *   - The WRITER (`parseCodexAgentToml`, used by the Codex sync) is STRICT: an
+ *     unterminated block makes the whole document `{ok:false}`, because a
+ *     writer that proceeds on a malformed document risks rewriting it.
+ *
+ * One block-range detector, two call sites, two policies — never two detectors
+ * that could silently drift from each other.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PARSE_REASON = void 0;
+exports.stripBOM = stripBOM;
+exports.unquoteTomlValue = unquoteTomlValue;
+exports.findDeveloperInstructionsBlockRange = findDeveloperInstructionsBlockRange;
+exports.scanTomlLines = scanTomlLines;
+exports.parseCodexAgentToml = parseCodexAgentToml;
+exports.renderCodexAgentToml = renderCodexAgentToml;
+exports.stripModel = stripModel;
+exports.stripReasoningEffort = stripReasoningEffort;
+/** Frozen reason enum for a failed {@link parseCodexAgentToml}. */
+exports.PARSE_REASON = Object.freeze({
+    UNTERMINATED_BLOCK: 'unterminated_block',
+});
+// The UTF-8 BOM codepoint, spelled as an escape rather than the literal
+// character so the source file never carries an invisible codepoint.
+const BOM_CHAR = String.fromCharCode(0xfeff);
+// Strips a leading UTF-8 BOM (U+FEFF), which fs.readFileSync(..., 'utf8') does not
+// strip on its own, and unwraps a TOML basic/literal string value's surrounding
+// quotes so `model = "sonnet"` yields `sonnet`, not `"sonnet"`.
+function stripBOM(content) {
+    return content.charCodeAt(0) === 0xfeff ? content.slice(1) : content;
+}
+function unquoteTomlValue(rawValue) {
+    const trimmed = rawValue.trim();
+    const quoted = trimmed.match(/^"([^"]*)"/) ?? trimmed.match(/^'([^']*)'/);
+    return quoted ? quoted[1] : trimmed;
+}
+// The `developer_instructions` block is a TOML multi-line literal string
+// (`developer_instructions = '''...'''`) that `generateCodexAgentToml` always
+// emits after the header fields. Prompt prose inside that block discusses models
+// constantly, so a `model = ...`-shaped line inside it must never be read as a
+// live pin — but the block can legally appear anywhere in the file (a
+// hand-reordered agent can move `model` after it), and another key's *value* can
+// legally contain the literal text `developer_instructions = '''` (e.g. a
+// `description` field quoting it) without that being the real block opener. So
+// instead of truncating the file at the first textual occurrence of the marker
+// anywhere in the content, this locates the block by its anchored line-start
+// opener (`^\s*developer_instructions\s*=\s*'''`, never a mid-line/mid-value
+// match) and its closing `'''` line, and excludes only the lines between them —
+// every other line in the file, before AND after the block, is scanned.
+//
+// If no opener is found, nothing is excluded (the whole file is scanned) and
+// `terminated` is trivially true. If the block IS opened but never closed before
+// EOF (malformed file), `terminated` is false: the lenient reader (scanTomlLines)
+// still treats the rest of the file as inside the block (the safe direction for
+// a reader — see module header comment); the strict writer (parseCodexAgentToml)
+// reads `terminated` and refuses instead. The emitter always uses `'''` (a TOML
+// literal string), never a `"""` basic multi-line string, so only `'''` is
+// treated as the block delimiter here.
+function findDeveloperInstructionsBlockRange(lines) {
+    const openIndex = lines.findIndex((line) => /^\s*developer_instructions\s*=\s*'''/.test(line));
+    if (openIndex === -1) {
+        return { start: -1, end: -1, terminated: true };
+    }
+    const afterOpenMarker = lines[openIndex].replace(/^\s*developer_instructions\s*=\s*'''/, '');
+    if (afterOpenMarker.includes("'''")) {
+        // Same-line block: developer_instructions = '''one line'''
+        return { start: openIndex, end: openIndex, terminated: true };
+    }
+    for (let i = openIndex + 1; i < lines.length; i++) {
+        if (lines[i].includes("'''")) {
+            return { start: openIndex, end: i, terminated: true };
+        }
+    }
+    return { start: openIndex, end: lines.length - 1, terminated: false };
+}
+// Line-oriented scan of every line OUTSIDE the `developer_instructions` block
+// (see findDeveloperInstructionsBlockRange). Full-key-name anchoring —
+// `^([A-Za-z_][\w]*)\s*=` for a bare key, or `^"([^"]*)"\s*=` / `^'([^']*)'\s*=`
+// for TOML's legal quoted-key forms, normalized to the same key name — means
+// `model_verbosity` / `model_reasoning_effort` never satisfy a `model` probe,
+// and vice versa; `#`-prefixed lines (after trimming leading whitespace) are
+// treated as comments, never live pins. Shared by both scanTomlLines (the
+// lenient reader, boolean-only for reasoning effort) and parseCodexAgentToml
+// (the strict writer, which also needs the effort's value and both keys' line
+// indices so stripModel/stripReasoningEffort can remove exactly one line).
+function scanHeaderLines(lines, blockStart, blockEnd) {
+    let model = null;
+    let modelLineIndex = null;
+    let reasoningEffort = null;
+    let reasoningEffortLineIndex = null;
+    for (let i = 0; i < lines.length; i++) {
+        if (blockStart !== -1 && i >= blockStart && i <= blockEnd)
+            continue;
+        const trimmed = lines[i].trim();
+        if (trimmed === '' || trimmed.startsWith('#'))
+            continue;
+        const match = trimmed.match(/^(?:"([^"]*)"|'([^']*)'|([A-Za-z_][\w]*))\s*=\s*(.*)$/);
+        if (!match)
+            continue;
+        const key = match[1] ?? match[2] ?? match[3];
+        const rawValue = match[4];
+        if (key === 'model') {
+            model = unquoteTomlValue(rawValue);
+            modelLineIndex = i;
+        }
+        else if (key === 'model_reasoning_effort') {
+            reasoningEffort = unquoteTomlValue(rawValue);
+            reasoningEffortLineIndex = i;
+        }
+    }
+    return { model, modelLineIndex, reasoningEffort, reasoningEffortLineIndex };
+}
+/**
+ * The LENIENT reader entry point (Phase 2, moved verbatim in behavior). Never
+ * fails: an unterminated block falls back to "rest of file is inside the
+ * block" via {@link findDeveloperInstructionsBlockRange}'s own fallback.
+ * `content` is expected already BOM-stripped (callers pass `stripBOM(raw)`).
+ */
+function scanTomlLines(content) {
+    const lines = content.split(/\r?\n/);
+    const { start, end } = findDeveloperInstructionsBlockRange(lines);
+    const { model, reasoningEffort } = scanHeaderLines(lines, start, end);
+    return { model, hasReasoningEffort: reasoningEffort !== null };
+}
+// Splits `content` into `{lines, terminators}` where `terminators[i]` is the
+// terminator that FOLLOWS `lines[i]` (`'\r\n'`, `'\r'`, `'\n'`, or `''` for a
+// line with none — only possible as the file's last line). The two arrays are
+// always the same length and there is NEVER a phantom trailing entry: a
+// source ending in a terminator (the common case) yields exactly as many
+// lines as it has content lines, not one more. `render` is then a plain
+// `lines[i] + terminators[i]` concatenation with no special-casing of "the
+// last line" — see `renderCodexAgentToml`.
+//
+// `String#split` with a capturing group interleaves the delimiters into the
+// result array — `"a\r\nb\nc".split(/(\r\n|\r|\n)/)` yields
+// `["a","\r\n","b","\n","c"]` — so even indices are line content and odd
+// indices are that line's terminator. When `content` ends WITH a terminator,
+// `split` appends one extra empty-string element after the last real
+// terminator (e.g. `"a\n".split(...)` → `["a","\n",""]`); that trailing `""`
+// is not a real line, it is `split`'s "nothing after the last delimiter"
+// marker, so the loop below stops before consuming it instead of recording it
+// as a phantom empty final line (the defect this replaced — see A29: a doc
+// with a phantom last element made every removal rule reason about the wrong
+// element for any trailing-newline-terminated file, the common case). `\r\n`
+// is tried before the bare `\r` alternative so a CRLF is never misread as a
+// lone-CR line followed by an empty LF-terminated line.
+function splitPreservingTerminators(content) {
+    if (content === '')
+        return { lines: [], terminators: [] };
+    const parts = content.split(/(\r\n|\r|\n)/);
+    const lastIndex = parts.length - 1;
+    const lines = [];
+    const terminators = [];
+    for (let i = 0; i < parts.length; i += 2) {
+        if (i === lastIndex && parts[i] === '')
+            break; // split's post-terminator marker, not a real line
+        lines.push(parts[i]);
+        terminators.push(parts[i + 1] ?? '');
+    }
+    return { lines, terminators };
+}
+/**
+ * The STRICT parse entry point (Phase 3, the writer's half of the
+ * reconciliation). Returns `{ok:false, reason:UNTERMINATED_BLOCK}` rather than
+ * guessing when the `developer_instructions` block is opened but never closed.
+ * On success, `doc` carries enough (the original `lines`/`terminators`, BOM/
+ * trailing-newline flags, and the two resolved values with their line indices)
+ * for {@link renderCodexAgentToml} to reproduce the source byte-identically —
+ * including a source with mixed line-ending styles — and for
+ * {@link stripModel}/{@link stripReasoningEffort} to remove exactly one line
+ * and its own terminator.
+ */
+function parseCodexAgentToml(content) {
+    const hadBOM = content.charCodeAt(0) === 0xfeff;
+    const stripped = stripBOM(content);
+    // Informational only — see CodexAgentDoc.eol's docstring. Never used by
+    // renderCodexAgentToml.
+    const eol = stripped.includes('\r\n') ? '\r\n' : '\n';
+    const trailingNewline = /(\r\n|\r|\n)$/.test(stripped);
+    const { lines, terminators } = splitPreservingTerminators(stripped);
+    const { start, end, terminated } = findDeveloperInstructionsBlockRange(lines);
+    if (start !== -1 && !terminated) {
+        return { ok: false, reason: exports.PARSE_REASON.UNTERMINATED_BLOCK };
+    }
+    const { model, modelLineIndex, reasoningEffort, reasoningEffortLineIndex } = scanHeaderLines(lines, start, end);
+    const doc = {
+        lines,
+        terminators,
+        eol,
+        hadBOM,
+        trailingNewline,
+        blockRange: { start, end },
+        model,
+        modelLineIndex,
+        reasoningEffort,
+        reasoningEffortLineIndex,
+    };
+    return { ok: true, doc };
+}
+/**
+ * Renders `doc` back to a string. For an unmodified doc this is
+ * byte-identical to the original `parseCodexAgentToml` input (matrix row
+ * A14) — it never re-derives line content, only rejoins each line with its
+ * OWN recorded terminator (`terminators[i]`, never the whole-file `eol`) and
+ * re-prepends a BOM if one was present. This is a plain concatenation of the
+ * surviving `[line, terminator]` pieces, so a source with mixed `\r\n`/`\n`/
+ * lone-`\r` line endings round-trips exactly, and a strip
+ * ({@link stripModel}/{@link stripReasoningEffort}) removes only the target
+ * line and its own terminator — every other line's ending is untouched.
+ */
+function renderCodexAgentToml(doc) {
+    let body = '';
+    for (let i = 0; i < doc.lines.length; i++) {
+        body += doc.lines[i] + (doc.terminators[i] ?? '');
+    }
+    return doc.hadBOM ? BOM_CHAR + body : body;
+}
+// Removes exactly one line (by index) — AND its own terminator — from
+// `doc.lines`/`doc.terminators`, re-indexing the block range and the OTHER
+// key's line index so a subsequent strip/render still sees a consistent doc.
+// Never touches any other line's content or terminator.
+//
+// The one exception is when `index` names the file's LAST line: a plain
+// slice-out would drop the removed line's terminator but leave the
+// *previous* line's terminator standing in its place, which silently
+// invents (or drops) a trailing newline the source never had — a middle-line
+// removal never has this problem because the terminator that survives (the
+// one that WAS between the previous line and the removed one) is exactly the
+// terminator the new neighbors should have between them. For a last-line
+// removal, the file's trailing-newline-or-not status lives in whether the
+// REMOVED line's own terminator was empty (that is what `trailingNewline`
+// was computed from) — so the new last line inherits the removed line's
+// EMPTINESS only: if the removed terminator was `''`, the new last line's
+// terminator is cleared to `''` too. If the removed terminator was
+// non-empty, the source already ended with a newline and the new last line
+// already has the right one (its OWN, unchanged) — overwriting it with the
+// removed line's terminator would silently change the new last line's own
+// ending style on a mixed-EOL source (see A26). Removing the only remaining
+// line is the degenerate case: there is no new last line, so the result is
+// the empty document.
+function removeLine(doc, index, which) {
+    const isLastLine = index === doc.lines.length - 1;
+    let lines;
+    let terminators;
+    if (doc.lines.length === 1) {
+        lines = [];
+        terminators = [];
+    }
+    else if (isLastLine) {
+        lines = doc.lines.slice(0, index);
+        terminators = doc.terminators.slice(0, index);
+        // Inherit the removed line's EMPTINESS, never its STYLE: if the removed
+        // line had no terminator (the source had no trailing newline), the new
+        // last line's terminator becomes '' too. Otherwise the source DID end
+        // with a newline, and the new last line already has the right one — its
+        // OWN terminator (already carried over by the slice above), which may
+        // differ in style from the removed line's (a mixed-EOL source) — so it is
+        // left unchanged rather than overwritten.
+        if (doc.terminators[index] === '') {
+            terminators[terminators.length - 1] = '';
+        }
+    }
+    else {
+        lines = doc.lines.slice(0, index).concat(doc.lines.slice(index + 1));
+        terminators = doc.terminators.slice(0, index).concat(doc.terminators.slice(index + 1));
+    }
+    const reindex = (i) => (i === null ? null : i > index ? i - 1 : i);
+    const blockRange = { ...doc.blockRange };
+    if (blockRange.start !== -1) {
+        if (blockRange.start > index)
+            blockRange.start -= 1;
+        if (blockRange.end > index)
+            blockRange.end -= 1;
+    }
+    return {
+        ...doc,
+        lines,
+        terminators,
+        blockRange,
+        model: which === 'model' ? null : doc.model,
+        modelLineIndex: which === 'model' ? null : reindex(doc.modelLineIndex),
+        reasoningEffort: which === 'reasoningEffort' ? null : doc.reasoningEffort,
+        reasoningEffortLineIndex: which === 'reasoningEffort' ? null : reindex(doc.reasoningEffortLineIndex),
+    };
+}
+/**
+ * Returns a new doc with the `model` line removed (a no-op copy if there was
+ * no `model` line). Every other byte — comments, other keys, the
+ * `developer_instructions` block, line endings, BOM — is untouched.
+ */
+function stripModel(doc) {
+    if (doc.modelLineIndex === null)
+        return doc;
+    return removeLine(doc, doc.modelLineIndex, 'model');
+}
+/**
+ * Returns a new doc with the `model_reasoning_effort` line removed (a no-op
+ * copy if there was none). Every other byte is untouched.
+ */
+function stripReasoningEffort(doc) {
+    if (doc.reasoningEffortLineIndex === null)
+        return doc;
+    return removeLine(doc, doc.reasoningEffortLineIndex, 'reasoningEffort');
+}