@opengsd/gsd-core 1.11.0 → 1.12.0

package/gsd-core/bin/lib/active-workstream-store.cjs

@@ -85,6 +85,14 @@ function getControllingTtyToken() {
     return probeControllingTtyToken();
 }
 function getWorkstreamSessionKey() {
+    // #3883 (ADR-3473 §8.3): DECLARED DIFFERENT from generateSlugInternal
+    // (core-utils.cts), the canonical slug formula — deliberately, not a
+    // consolidation gap. The text slugified here is never caller-supplied: it
+    // is always one of the fixed ASCII WORKSTREAM_SESSION_ENV_KEYS identifier
+    // names above (e.g. "GSD_SESSION_KEY"), which already agree with the
+    // canonical's output byte-for-byte on this restricted input domain (no
+    // unicode, no length anywhere near the 60-char truncation boundary) — so
+    // delegating would add a require() edge for zero behavioral change.
     for (const envKey of WORKSTREAM_SESSION_ENV_KEYS) {
         const raw = process.env[envKey];
         const token = sanitizeWorkstreamSessionToken(raw);

package/gsd-core/bin/lib/adr-parser.cjs

@@ -14,6 +14,9 @@ const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
 const security_cjs_1 = require("./security.cjs");
 const markdown_sectionizer_cjs_1 = require("./markdown-sectionizer.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const cliExitModule = require("./cli-exit.cjs");
+const { ExitError, runMain } = cliExitModule;
 const STATUS_REJECT_SET = new Set(['superseded', 'rejected', 'deprecated']);
 const CANONICAL_HEADERS = {
     status: ['status', 'state', 'lifecycle', 'stage'],
@@ -405,13 +408,16 @@ function main(argv) {
     process.stdout.write(JSON.stringify(parsed, null, 2));
 }
 if (require.main === module) {
-    try {
-        main(process.argv.slice(2));
-    }
-    catch (error) {
-        process.stderr.write(`Error: ${error.message}\n`);
-        process.exit(1);
-    }
+    runMain(() => {
+        try {
+            main(process.argv.slice(2));
+        }
+        catch (err) {
+            // ExitError with a message so runMain's catch writes it verbatim
+            // (byte-identical to the prior `Error: ${message}\n` process.exit(1)).
+            throw new ExitError(1, `Error: ${err.message}`);
+        }
+    });
 }
 module.exports = {
     CANONICAL_HEADERS,

package/gsd-core/bin/lib/agent-install-check.cjs

@@ -29,6 +29,20 @@ const model_catalog_cjs_1 = require("./model-catalog.cjs");
 // locally. Behavior is unchanged: scanTomlLines/stripBOM here are the exact
 // same lenient functions that used to live in this file — see
 // codex-agent-toml.cts's module header for the reader/writer reconciliation.
+// #3897 CAUSE A fix: `deriveCodexSandboxMode` needs the resolved `tools:`
+// frontmatter VALUE, not raw content — this module used to reach that via
+// `runtime-artifact-conversion.cjs`'s general-purpose
+// `extractFrontmatterAndBody`/`extractFrontmatterField`, but that module's
+// dependency chain (`command-roster.cjs` -> `scripts/fix-slash-commands.cjs`,
+// a dev-only repo script) does not resolve from an installed tree — any test
+// exercising a synthetic install dir blew up at module load. `codex-agent-toml.cjs`
+// is already imported here, is a genuine leaf (node builtins only, zero
+// side effects), and now exports `extractToolsValue` — a single-purpose
+// `tools:`-VALUE reader (inline AND YAML block-list form, #3897 list-form
+// parse fix), not a general frontmatter parser — for exactly this caller,
+// shared with `bin/install.js`'s emitter so the two sandbox-feeding paths
+// can never silently disagree, and no fourth copy of frontmatter parsing is
+// added.
 const codex_agent_toml_cjs_1 = require("./codex-agent-toml.cjs");
 /**
  * Frozen reason enum for {@link checkCodexModelPosture}. Per CONTRIBUTING's
@@ -305,6 +319,153 @@ function checkCodexModelPosture(runtime, projectRoot) {
         agent_runtime: resolvedRuntime,
     };
 }
+// #3897 rung 3 — the canonical bundled `agents/*.md` source directory (the
+// tool-contract source of truth), resolved the same install-relative way
+// getAgentsDir resolves the claude case, WITHOUT that function's npm-global
+// node_modules redirect: that redirect exists so a Codex/claude INSTALL is
+// never validated against itself, but here we deliberately want the bundled
+// copy every time — it is the only place the `tools:` contract a role
+// derives its sandbox_mode from actually lives, in every install shape
+// (repo-dev tree or npm-global package, where the package still ships its
+// own agents/ alongside bin/ and gsd-core/).
+function _canonicalAgentSourceDir() {
+    return node_path_1.default.join(__dirname, '..', '..', '..', 'agents');
+}
+/**
+ * Validate installed Codex `.toml` agents' `sandbox_mode` against what each
+ * role's own tool contract derives (#3897, ADR-3473 §8.3 criterion 3,
+ * HALT.md option 2). Sibling to {@link checkCodexModelPosture} — same shape,
+ * same short-circuits — but a different defect class: a TOML whose
+ * `sandbox_mode` disagrees with the derived expectation, not a bad `model`.
+ *
+ * `deriveCodexSandboxMode` (and the `CODEX_SANDBOX_HOLDS` hold list + its own
+ * self-invalidation check it embeds) is imported from `codex-agent-toml.cjs`
+ * — the shared, side-effect-free leaf both `bin/install.js`'s emitter and
+ * this posture check import from (CAUSE A fix, #3897: this function used to
+ * lazily `require('bin/install.js')` to reach the same derivation, but
+ * requiring `bin/install.js` runs its whole CLI top-level, including an
+ * ASCII banner print to stdout, which corrupted every stdout-JSON caller of
+ * this posture check, e.g. `gsd-tools validate agents`) — so the emitter and
+ * this posture check can never silently diverge on the same tool-contract
+ * predicate — the exact generative-fix-divergence shape this epic exists to
+ * close. `deriveCodexSandboxMode` itself is total (never throws, #3897
+ * CAUSE C fix) — a held role whose supplied content no longer derives
+ * broader than its pin simply returns `read-only` rather than failing,
+ * because the pin is then a no-op. The staleness invariant (S4/S5) this
+ * check's imports still carry is enforced separately, at the real `agents/`
+ * roster level, by `validateCodexSandboxHolds` and
+ * `tests/codex-config.test.cjs` T24/T25 — not by this per-call derivation.
+ *
+ * Read-only: detects, never repairs — same posture as {@link checkCodexModelPosture}.
+ *
+ * @param runtime - the active runtime name; defaults to GSD_RUNTIME env, then 'claude'
+ * @param projectRoot - canonical project root for local-install discovery
+ */
+function checkCodexSandboxPosture(runtime, projectRoot) {
+    const resolvedRuntime = runtime ?? (process.env['GSD_RUNTIME'] || 'claude');
+    if (resolvedRuntime !== 'codex') {
+        return {
+            ok: true,
+            violations: [],
+            checked: [],
+            agents_dir: '',
+            agent_runtime: resolvedRuntime,
+            reason: POSTURE_REASON.NOT_CODEX,
+        };
+    }
+    const agentsDir = getAgentsDir(resolvedRuntime, projectRoot);
+    if (!node_fs_1.default.existsSync(agentsDir)) {
+        return {
+            ok: true,
+            violations: [],
+            checked: [],
+            agents_dir: agentsDir,
+            agent_runtime: resolvedRuntime,
+            reason: POSTURE_REASON.AGENTS_DIR_MISSING,
+        };
+    }
+    const canonicalAgentsDir = _canonicalAgentSourceDir();
+    // Same symlink guard as checkCodexModelPosture, same reason (never follow
+    // an agents-dir symlink into an arbitrary file's content).
+    const tomlFiles = node_fs_1.default
+        .readdirSync(agentsDir)
+        .filter((entry) => {
+        if (!entry.endsWith('.toml'))
+            return false;
+        try {
+            return node_fs_1.default.lstatSync(node_path_1.default.join(agentsDir, entry)).isFile();
+        }
+        catch {
+            return false;
+        }
+    })
+        .sort();
+    const checked = [];
+    const violations = [];
+    for (const entry of tomlFiles) {
+        const agentName = entry.slice(0, -'.toml'.length);
+        const filePath = node_path_1.default.join(agentsDir, entry);
+        checked.push(agentName);
+        let raw;
+        try {
+            raw = node_fs_1.default.readFileSync(filePath, 'utf8');
+        }
+        catch {
+            violations.push({ agent: agentName, file: filePath, reason: POSTURE_REASON.UNREADABLE });
+            continue;
+        }
+        // #3897 rung 4 (isolated correctness review, MINOR finding 2): route
+        // through the same block-aware `scanTomlLines` the sibling
+        // `checkCodexModelPosture` already uses, rather than a naive whole-file
+        // regex — a `sandbox_mode = "..."`-shaped line inside the
+        // `developer_instructions` block (prose) must never be read as a live
+        // value. A prior naive `raw.match(/^sandbox_mode.../m)` here produced a
+        // FALSE violation whenever an agent's own prompt prose happened to
+        // contain that shape.
+        const found = (0, codex_agent_toml_cjs_1.scanTomlLines)((0, codex_agent_toml_cjs_1.stripBOM)(raw)).sandboxMode;
+        if (found === null) {
+            // No sandbox_mode line at all (e.g. sandboxTier "none") is a deliberate,
+            // documented state elsewhere — not this check's business.
+            continue;
+        }
+        const canonicalFile = node_path_1.default.join(canonicalAgentsDir, `${agentName}.md`);
+        let canonicalContent;
+        try {
+            canonicalContent = node_fs_1.default.readFileSync(canonicalFile, 'utf8');
+        }
+        catch {
+            // No canonical role source (a custom/non-roster agent) — nothing to
+            // derive an expectation from, so this is not this check's business.
+            continue;
+        }
+        // `canonicalContent` is always a real string here (read via fs.readFileSync
+        // above), so extractToolsValue's `undefined` (non-string input) branch is
+        // unreachable on this path — the `?? ''` is a type-level formality, not a
+        // behavior change (F4, #3897 security review: extractToolsValue is TOTAL).
+        const toolsRaw = (0, codex_agent_toml_cjs_1.extractToolsValue)(canonicalContent) ?? '';
+        const expected = (0, codex_agent_toml_cjs_1.deriveCodexSandboxMode)(agentName, toolsRaw);
+        if (expected !== found) {
+            // #3897 rung 4 (isolated correctness review, MINOR finding 3):
+            // truncatePostureValue matches the sibling checkCodexModelPosture's
+            // convention (see its own `value: truncatePostureValue(model)` above)
+            // so an oversized or secret-shaped `sandbox_mode` value can never
+            // reach `validate agents --raw` output at full length.
+            violations.push({
+                agent: agentName,
+                file: filePath,
+                expected: truncatePostureValue(expected),
+                found: truncatePostureValue(found),
+            });
+        }
+    }
+    return {
+        ok: violations.length === 0,
+        violations,
+        checked,
+        agents_dir: agentsDir,
+        agent_runtime: resolvedRuntime,
+    };
+}
 /**
  * Probe a single agents dir for `<name>` across runtime filename variants.
  * Mirrors {@link checkAgentsInstalled}'s probe (`.md`, `.agent.md`, `.toml`,
@@ -368,6 +529,7 @@ module.exports = {
     getAgentsDir,
     checkAgentsInstalled,
     checkCodexModelPosture,
+    checkCodexSandboxPosture,
     POSTURE_REASON,
     resolveAgentHint,
 };

package/gsd-core/bin/lib/api-coverage.cjs

@@ -52,9 +52,13 @@
  *   renderCoverageMatrix(rows) -> string
  *   DEFAULT_API_COVERAGE_TERMS
  *
- * CLI:
+ * CLI (ADR-3889 Phase 3, #3907):
  *   echo "$SCOPE" | node gsd-core/bin/lib/api-coverage.cjs [--json]
- *     exit 0 = integration detected, 1 = none, 2 = startup error
+ *     exit 0 = integration detected, 1 = none (real input, examined, no signal),
+ *     NO_INPUT (registry, src/cli-exit.cts) = stdin empty/whitespace-only,
+ *     UNAVAILABLE (registry) = stdin read failed
+ *     --json additionally prints the typed IR on stdout (unchanged for 0/1);
+ *     NO_INPUT/UNAVAILABLE print {skipped:true, reason:"no_input"|"stdin_error"}
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.DEFAULT_API_COVERAGE_TERMS = void 0;
@@ -849,11 +853,24 @@ function renderCoverageMatrix(rows) {
 // ── CLI entry point ──────────────────────────────────────────────────────────
 // Reads phase-scope text from STDIN (not argv) to avoid OS ARG_MAX limits.
 // Invoked by workflow bash as: echo "$SCOPE" | node .../api-coverage.cjs [--json]
-// Exit 0 = integration detected, 1 = none, 2 = startup error. Mirrors
-// assumption-delta.cjs / ui-safety-gate.cjs.
+//
+// Exit codes (ADR-3889 Phase 3, #3907): 0 = integration detected, 1 = none
+// (real input, examined, no signal), NO_INPUT (registry — src/cli-exit.cts) =
+// stdin empty/whitespace-only, UNAVAILABLE (registry) = stdin read failed.
+// The prior single "2 = startup error" arm let empty input flow into the
+// detector and exit 1 — an unexamined input reported as an authoritative
+// negative. Under --json, NO_INPUT/UNAVAILABLE emit `{skipped:true,
+// reason:"no_input"|"stdin_error"}` — no `detected` key, so a stale
+// `detected:false` can never sit beside `skipped:true`; the detected/no-signal
+// `--json` payloads are byte-identical to before. Terminates via terminateNow
+// (write-then-terminate, total by construction), not raw process.exit — these
+// exits fire from inside a stdin event handler. Mirrors assumption-delta.cjs /
+// ui-safety-gate.cjs.
 if (require.main === module) {
     const argv = process.argv.slice(2);
     const wantJson = argv.includes('--json');
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const cliExit = require('./cli-exit.cjs');
     let termsOverride;
     const verbsIdx = argv.indexOf('--verbs');
     const verbsVal = verbsIdx !== -1 ? argv[verbsIdx + 1] : undefined;
@@ -877,14 +894,18 @@ if (require.main === module) {
     process.stdin.on('data', (chunk) => chunks.push(chunk));
     process.stdin.on('end', () => {
         const input = chunks.join('');
-        const result = detectApiIntegration(input, termsOverride);
-        if (wantJson) {
-            process.stdout.write(JSON.stringify(result) + '\n');
+        // Whitespace-only counts as empty (ADR-3889 §1's NO_INPUT: "zero units
+        // were in scope, and that emptiness is known to be genuine"). Real input
+        // — including a lone NUL byte, which .trim() does not strip — always
+        // falls through to the detector.
+        if (input.trim().length === 0) {
+            cliExit.terminateNow('NO_INPUT', wantJson ? { skipped: true, reason: 'no_input' } : undefined);
         }
-        process.exit(result.detected ? 0 : 1);
+        const result = detectApiIntegration(input, termsOverride);
+        cliExit.terminateNow(result.detected ? 'PASS' : 'FAIL', wantJson ? result : undefined);
     });
     process.stdin.on('error', (err) => {
         process.stderr.write(`ERROR: api-coverage.cjs stdin read failed: ${err.message}\n`);
-        process.exit(2);
+        cliExit.terminateNow('UNAVAILABLE', wantJson ? { skipped: true, reason: 'stdin_error' } : undefined);
     });
 }

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

@@ -30,6 +30,8 @@ exports.CANONICAL_EXACT = new Set([
     'WINDOWS.md', // #3224: broken-windows ledger (src/broken-windows.cts, LEDGER_FILE_NAME)
     'STATE-ARCHIVE.md', // state.cts's cmdStatePrune writes this at the .planning/ root
     'milestone.lock', // #3311: milestone (phase + session) claim (src/milestone-lock.cts); persistent, unlike the transient STATE.md.lock/WAITING.json
+    'state.json', // #3227: machine-readable state contract published at step boundaries (src/state-contract.cts)
+    'skill-manifest.json', // init.cts routeSkillManifest --write (project-scoped planning root, #3964)
 ]);
 // Pattern-match canonical file names (regex tests on the basename)
 // Each pattern includes the name of the workflow that produces it as a comment.

package/gsd-core/bin/lib/assumption-delta.cjs

@@ -21,17 +21,19 @@
  *    tunable (config + the `terms` parameter) so teams can widen it.
  *  - FENCED CODE BLOCKS ARE STRIPPED first (via the markdown-sectionizer seam)
  *    so a trigger term that appears only inside a code snippet does not fire.
- *  - Mirrors ui-safety-gate.cts: a pure function + a STDIN-reading CLI whose
- *    exit codes mirror grep (0 = signal found, 1 = none, 2 = usage error).
+ *  - Mirrors ui-safety-gate.cts: a pure function + a STDIN-reading CLI.
  *
  * Public API:
  *   detectAssumptionDelta(text, terms?) -> { detected, signals, terms }
  *   DEFAULT_ASSUMPTION_DELTA_TERMS
  *
- * CLI:
+ * CLI (ADR-3889 Phase 3, #3907):
  *   echo "$PHASE_SECTION" | node gsd-core/bin/lib/assumption-delta.cjs [--json]
- *     exit 0 = signal detected, 1 = none, 2 = startup error
- *     --json additionally prints the typed IR on stdout
+ *     exit 0 = signal detected, 1 = none (real input, examined, no signal),
+ *     NO_INPUT (registry, src/cli-exit.cts) = stdin empty/whitespace-only,
+ *     UNAVAILABLE (registry) = stdin read failed
+ *     --json additionally prints the typed IR on stdout (unchanged for 0/1);
+ *     NO_INPUT/UNAVAILABLE print {skipped:true, reason:"no_input"|"stdin_error"}
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.DEFAULT_ASSUMPTION_DELTA_TERMS = void 0;
@@ -192,10 +194,23 @@ function detectAssumptionDelta(text, terms) {
 // ── CLI entry point ──────────────────────────────────────────────────────────
 // Reads phase-section text from STDIN (not argv) to avoid OS ARG_MAX limits.
 // Invoked by workflow bash as: echo "$PHASE_SECTION" | node .../assumption-delta.cjs [--json]
-// Exit 0 = signal detected, 1 = none, 2 = startup error. Mirrors ui-safety-gate.
+//
+// Exit codes (ADR-3889 Phase 3, #3907): 0 = signal detected, 1 = none (real
+// input, examined, no signal), NO_INPUT (registry — src/cli-exit.cts) = stdin
+// empty/whitespace-only, UNAVAILABLE (registry) = stdin read failed. The prior
+// single "2 = startup error" arm let empty input flow into the detector and
+// exit 1 — an unexamined input reported as an authoritative negative. Under
+// --json, NO_INPUT/UNAVAILABLE emit `{skipped:true, reason:"no_input"|
+// "stdin_error"}` — no `detected` key, so a stale `detected:false` can never
+// sit beside `skipped:true`; the detected/no-signal `--json` payloads are
+// byte-identical to before. Terminates via terminateNow (write-then-terminate,
+// total by construction), not raw process.exit — these exits fire from inside
+// a stdin event handler. Mirrors ui-safety-gate.cjs / api-coverage.cjs.
 if (require.main === module) {
     const argv = process.argv.slice(2);
     const wantJson = argv.includes('--json');
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const cliExit = require('./cli-exit.cjs');
     // --terms <csv>: config-tunable vocabulary override. Replaces the
     // pluralization cues (the primary trigger); optional/chosen keep defaults.
     // An EMPTY value ("") or a flag-shaped value restores the curated defaults
@@ -216,14 +231,18 @@ if (require.main === module) {
     process.stdin.on('data', (chunk) => chunks.push(chunk));
     process.stdin.on('end', () => {
         const input = chunks.join('');
-        const result = detectAssumptionDelta(input, termsOverride);
-        if (wantJson) {
-            process.stdout.write(JSON.stringify(result) + '\n');
+        // Whitespace-only counts as empty (ADR-3889 §1's NO_INPUT: "zero units
+        // were in scope, and that emptiness is known to be genuine"). Real input
+        // — including a lone NUL byte, which .trim() does not strip — always
+        // falls through to the detector.
+        if (input.trim().length === 0) {
+            cliExit.terminateNow('NO_INPUT', wantJson ? { skipped: true, reason: 'no_input' } : undefined);
         }
-        process.exit(result.detected ? 0 : 1);
+        const result = detectAssumptionDelta(input, termsOverride);
+        cliExit.terminateNow(result.detected ? 'PASS' : 'FAIL', wantJson ? result : undefined);
     });
     process.stdin.on('error', (err) => {
         process.stderr.write(`ERROR: assumption-delta.cjs stdin read failed: ${err.message}\n`);
-        process.exit(2);
+        cliExit.terminateNow('UNAVAILABLE', wantJson ? { skipped: true, reason: 'stdin_error' } : undefined);
     });
 }