@opengsd/gsd-core 1.11.0 → 1.12.0

package/gsd-core/bin/lib/runtime-identity.cjs

@@ -0,0 +1,234 @@
+"use strict";
+/**
+ * Runtime identity — prove which package's `gsd-tools` actually executed (#3146).
+ *
+ * The predecessor package `get-shit-done-cc` publishes a colliding `gsd-tools`
+ * bin (verified 2026-08-24 against 1.42.3: `bin.gsd-tools -> bin/gsd-sdk.js`),
+ * and exposes verbs of the same name with different semantics. #3129 is the
+ * worked example: `phases.clear` archives here and **deletes** there, and the
+ * output is success-shaped either way, so 43 phase directories went missing
+ * with no warning.
+ *
+ * That collision is now prevented in the resolver rather than detected here:
+ * the launcher's PATH branch resolves `gsd_run`, which only this package
+ * publishes and which self-locates to its sibling shim, so a foreign binary is
+ * unreachable from PATH. The path-based branches — a project-local install, a
+ * runtime config directory — have no such structural guarantee: they trust
+ * their configured location. #3841 closes that remaining route by making the
+ * launcher preamble PROBE the resolved tool once, before any verb runs, and
+ * warn when it cannot prove it is this package. This module backs both the
+ * `runtime-identity` verb the preamble calls and the vocabulary that gate
+ * reports in (`IDENTITY_STATUS`).
+ *
+ * The rollout is warn-then-fail (the #3146 maintainer ruling): the preamble
+ * prints one actionable line and proceeds. It cannot hard-fail yet because
+ * `no_identity_verb` does not distinguish a foreign package from an
+ * `@opengsd/gsd-core` older than the verb — and during rollout the old-version
+ * case is the common one, so a hard failure would stop working installs.
+ *
+ * Parsing is deliberately STRICT. The whole value of the check is telling "us"
+ * from "not us"; a lenient parse that accepts the predecessor's usage text as
+ * close-enough would reproduce the exact silent success #3129 already produced.
+ * Liberality is spent on visibility instead — distinct reason codes, each
+ * naming what actually happened.
+ *
+ * The classifier and the shell preamble are held in agreement by a
+ * cross-surface parity test (#3841): both read stdout only and must reach the
+ * same verdict for the same payload, or the preamble's warning and this
+ * module's diagnostic would silently diverge on the same input.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.IDENTITY_RAW_PREFIX = exports.IDENTITY_STATUS = exports.EXPECTED_PACKAGE_NAME = void 0;
+exports.classifyIdentityProbe = classifyIdentityProbe;
+exports.statusForVerdict = statusForVerdict;
+exports.buildIdentityPayload = buildIdentityPayload;
+exports.explainVerdict = explainVerdict;
+exports.cmdRuntimeIdentity = cmdRuntimeIdentity;
+const package_identity_cjs_1 = require("./package-identity.cjs");
+const capability_loader_cjs_1 = require("./capability-loader.cjs");
+/** The package name a legitimate GSD runtime reports. Baked at build time (#498). */
+exports.EXPECTED_PACKAGE_NAME = package_identity_cjs_1.packageName;
+/**
+ * The two-valued status the launcher preamble exports as `GSD_IDENTITY_STATUS`
+ * (#3841). Frozen so it is a VALUE a test can assert on: CONTRIBUTING forbids
+ * proving the gate fired by matching its human-readable warning prose.
+ *
+ * Two values, not five: the shell has no use for the distinction between
+ * `no_identity_verb` and `unparseable` — it either holds proof or it does not.
+ * The five-way {@link IdentityReason} stays the diagnostic vocabulary;
+ * {@link statusForVerdict} is the only bridge between them.
+ */
+exports.IDENTITY_STATUS = Object.freeze({
+    OK: 'ok',
+    UNVERIFIED: 'unverified',
+});
+/**
+ * The exact byte prefix the preamble anchors its `case` pattern to.
+ *
+ * ANCHORED, never a substring search. `JSON.stringify` emits keys in insertion
+ * order and `buildIdentityPayload` inserts `packageName` first, so a genuine
+ * `--raw` payload always STARTS with this. An unanchored match would verify the
+ * decoy `{"packageName":"get-shit-done-cc","note":"@opengsd/gsd-core"}`, which
+ * is exactly the shape a colliding package could publish.
+ *
+ * The preamble anchors at BOTH ends: its `case` pattern is this prefix, then
+ * anything, then a literal `}`, so a truncated payload fails too. That is safe
+ * for any future additive field — a JSON object's own closing brace is always
+ * the last character, whatever the last value's type. It also pairs the literal
+ * `{` for the raw-text brace guards the preamble is inlined into (#3841); the
+ * pairing is a consequence of the stronger check, not the reason for it.
+ */
+exports.IDENTITY_RAW_PREFIX = `{"packageName":"${exports.EXPECTED_PACKAGE_NAME}"`;
+/** Cap on echoed probe output so a warning can never dump a whole usage screen. */
+const EVIDENCE_MAX_CHARS = 200;
+function excerpt(text) {
+    const flat = text.replace(/\s+/g, ' ').trim();
+    return flat.length > EVIDENCE_MAX_CHARS ? `${flat.slice(0, EVIDENCE_MAX_CHARS)}…` : flat;
+}
+/**
+ * `stdout` as a plain JSON object, or `null` when it is not one.
+ *
+ * `JSON.parse` accepts `0`, `"str"`, `[]`, `null` and `true`; arrays and `null`
+ * are also `object` to `typeof`. All are rejected here so no downstream
+ * truthiness check can mistake `[]` for a verified identity.
+ */
+function parseIdentityRecord(stdout) {
+    let parsed;
+    try {
+        parsed = JSON.parse(stdout);
+    }
+    catch {
+        return null;
+    }
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed))
+        return null;
+    return parsed;
+}
+/**
+ * Pure classifier: probe result -> verdict. Total — never throws, for any input.
+ *
+ * Non-object JSON (`0`, `"str"`, `[]`, `null`, `true`) is `unparseable`, not
+ * `ok` and not a crash: `JSON.parse` accepts all of them, so a naive truthiness
+ * check would let `[]` through as a verified identity.
+ */
+function classifyIdentityProbe(probe, expected = exports.EXPECTED_PACKAGE_NAME) {
+    if (probe.spawnFailed || probe.timedOut) {
+        return {
+            reason: 'probe_failed',
+            expected,
+            detail: probe.timedOut ? 'identity probe timed out' : 'identity probe could not be spawned',
+        };
+    }
+    // PARSE BEFORE CONSULTING THE EXIT CODE (#3841).
+    //
+    // The exit-code rule below is right for its stated reason -- the predecessor
+    // prints a usage screen and exits 1, and that is "something else answered",
+    // not a parse problem -- but it used to run FIRST, so it also caught a tool
+    // that had already proved its identity and merely exited non-zero afterwards.
+    // The shell preamble this module speaks for reads stdout ONLY (its command
+    // substitution discards the status), so the two surfaces disagreed on exactly
+    // that input: shell `ok`, classifier `no_identity_verb`. Measured against the
+    // real snippet, not inferred. Since this classifier is the engine for the
+    // announced hard-fail phase, such an install would have flipped from verified
+    // to refused at rollout, in the phase where that stops the run.
+    //
+    // The predecessor defence is unaffected: a usage screen yields no usable
+    // payload, so it still falls through to the exit-code branch below.
+    const record = parseIdentityRecord(probe.stdout);
+    if (record !== null) {
+        const actual = record.packageName;
+        if (typeof actual === 'string' && actual.length > 0) {
+            // Unknown keys are ignored so a future payload addition cannot fail an
+            // older check. The shell anchor is deliberately open in the middle for the
+            // same reason, and the parity suite pins both halves of that (case P10).
+            const version = typeof record.version === 'string' ? record.version : undefined;
+            if (actual !== expected)
+                return { reason: 'identity_mismatch', expected, actual, version };
+            // ANCHOR PARITY (#3841). The shell preamble cannot parse JSON: it matches
+            // a `case` pattern anchored at the START of stdout, so a payload only
+            // verifies there when it begins at the first byte and serializes
+            // `packageName` first. A purely structural parse would accept
+            // `{"note":"x","packageName":"<us>"}` and a leading-whitespace payload
+            // that the shell rejects -- a FAIL-OPEN disagreement between the two
+            // surfaces.
+            //
+            // Reproduce those two properties SEMANTICALLY rather than byte-matching
+            // IDENTITY_RAW_PREFIX. The prefix describes the `--raw` wire format, but
+            // this classifier is also handed the DEFAULT pretty serialization
+            // (`runtime-identity` with no `--raw`, which is two-space indented) --
+            // byte-matching the compact prefix rejected that, which the remote matrix
+            // caught. `startsWith('{')` and a first-key check hold for both.
+            const firstKey = Object.keys(record)[0];
+            if (!probe.stdout.startsWith('{') || firstKey !== 'packageName') {
+                return {
+                    reason: 'unparseable',
+                    expected,
+                    detail: 'payload names this package but is not in the anchored wire shape',
+                };
+            }
+            return { reason: 'ok', expected, actual, version };
+        }
+    }
+    // Nothing was proved. NOW the exit status is the discriminator: a non-zero
+    // exit means a binary that does not implement this verb answered.
+    if (probe.exitCode !== 0) {
+        return {
+            reason: 'no_identity_verb',
+            expected,
+            detail: `exit ${String(probe.exitCode)}: ${excerpt(probe.stdout)}`,
+        };
+    }
+    return {
+        reason: 'unparseable',
+        expected,
+        detail: record === null ? excerpt(probe.stdout) : 'payload has no usable packageName',
+    };
+}
+/**
+ * Collapse a five-way verdict onto the two-valued shell status.
+ *
+ * Total by construction: anything that is not `ok` is `unverified`. A future
+ * sixth reason code therefore fails CLOSED here rather than silently verifying.
+ */
+function statusForVerdict(verdict) {
+    return verdict.reason === 'ok' ? exports.IDENTITY_STATUS.OK : exports.IDENTITY_STATUS.UNVERIFIED;
+}
+/**
+ * Build this runtime's identity payload.
+ *
+ * Version is REPORTED but not asserted in the warn phase, so a dev tree
+ * reporting readHostVersion()'s fail-closed `0.0.0` still verifies. Carrying it
+ * now means the hard-fail phase can gate on compatibility without a payload
+ * change (and therefore without a second round of Hyrum's-Law exposure).
+ */
+function buildIdentityPayload(deps = {}) {
+    const readVersion = deps.readVersion ?? (() => (0, capability_loader_cjs_1.readHostVersion)());
+    const readName = deps.readPackageName ?? (() => exports.EXPECTED_PACKAGE_NAME);
+    return { packageName: readName(), version: readVersion() };
+}
+/** Render a verdict as the one-line actionable warning the preamble prints. */
+function explainVerdict(verdict, resolvedPath) {
+    const head = `WARNING: "${resolvedPath}" did not report a ${verdict.expected} identity.`;
+    const why = {
+        ok: 'identity verified',
+        identity_mismatch: `it reported "${verdict.actual ?? '(unknown)'}" instead`,
+        no_identity_verb: 'it does not implement the runtime-identity verb — either a different package, or a gsd-core predating the verb',
+        unparseable: 'its response could not be parsed as an identity payload',
+        probe_failed: 'the identity probe could not be run',
+    };
+    const tail = 'A workflow shipped by this package may be running against a different tool. ' +
+        'See docs/how-to/diagnose-a-foreign-gsd-tools.md';
+    const evidence = verdict.detail ? ` (${verdict.detail})` : '';
+    return `${head} Reason: ${why[verdict.reason]}${evidence}. ${tail}`;
+}
+/**
+ * CLI arm for `gsd-tools runtime-identity`.
+ *
+ * Kept on the CJS fast path for the same reason as `current-timestamp`: it is a
+ * pure local read, and the launcher preamble spawns it once per workflow run,
+ * so SDK bridge startup would be a per-run tax on every workflow.
+ */
+function cmdRuntimeIdentity(raw = false, deps = {}) {
+    const payload = buildIdentityPayload(deps);
+    process.stdout.write(`${JSON.stringify(payload, null, raw ? 0 : 2)}\n`);
+}

package/gsd-core/bin/lib/runtime-slash.cjs

@@ -29,6 +29,9 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.formatGsdSlash = formatGsdSlash;
+exports.readInstallRuntimeMarker = readInstallRuntimeMarker;
+exports._setInstallRuntimeMarkerForTests = _setInstallRuntimeMarkerForTests;
+exports._resetInstallRuntimeMarkerCacheForTests = _resetInstallRuntimeMarkerCacheForTests;
 exports.resolveExplicitRuntime = resolveExplicitRuntime;
 exports.resolveRuntime = resolveRuntime;
 exports.formatGsdSlashFor = formatGsdSlashFor;
@@ -75,6 +78,58 @@ function formatGsdSlash(commandName, runtime) {
     }
     return `/gsd-${token}${tail}`;
 }
+// ─── #3897 rung 2: the per-install `.gsd-runtime` marker, promoted from ──────
+// model-resolver.cts (#2297) to this module — the canonical owner of runtime
+// identity (resolveRuntime, formatGsdSlash). `bin/install.js` writes
+// `<install>/gsd-core/.gsd-runtime` beside VERSION for every runtime install
+// (#2297). This module compiles to `gsd-core/bin/lib/runtime-slash.cjs`
+// (ADR-457) — the SAME directory `model-resolver.cjs` compiles to — so the
+// `__dirname`-relative path below is unchanged from the promoted original.
+//
+// Cache + test-seam shape, byte-for-behaviour preserved from
+// model-resolver.cts:65-77 (N5): module-level `let`, `try/catch -> null`,
+// `_setInstallRuntimeMarkerForTests` / `_resetInstallRuntimeMarkerCacheForTests`.
+// `model-resolver.cts` now imports this implementation instead of holding its
+// own copy; the two `hooks/*.js` marker readers delegate here too (through
+// `ensureRuntimeBuild()`, per `scripts/lint-hooks-runtime-build-seam.cjs`).
+let _installMarkerCache;
+/**
+ * Read the per-install runtime marker, cached for the process lifetime.
+ * Never throws (N4) — an absent/unreadable marker (dev/source tree, an
+ * install predating #2297, EACCES, hostile content, ...) is "no signal",
+ * never a resolution failure; a throw here would break a session in
+ * `gsd-agent-isolation-guard.js`, which is worse than resolving the wrong
+ * runtime.
+ *
+ * The raw marker string is returned as-is (trimmed) — callers MUST route it
+ * through `resolveRuntimeNameFromCandidates` before trusting it (N1); this
+ * function itself does not normalize so its cached value matches exactly
+ * what #2297's tests already assert about the underlying file read.
+ */
+function readInstallRuntimeMarker() {
+    if (_installMarkerCache !== undefined)
+        return _installMarkerCache;
+    try {
+        const markerPath = node_path_1.default.join(__dirname, '..', '..', '.gsd-runtime');
+        const raw = node_fs_1.default.readFileSync(markerPath, 'utf8').trim();
+        _installMarkerCache = raw || null;
+    }
+    catch {
+        // No marker: dev/source tree, or an install predating #2297. Fall through
+        // to the 'claude' default (keeps tier aliases — never worse than the bug).
+        _installMarkerCache = null;
+    }
+    return _installMarkerCache;
+}
+// Test seams for the install-marker rung (the dev/source tree has no marker,
+// so the file read always bottoms out at 'claude' — these let tests exercise
+// the third precedence rung and reset the module-level cache between cases).
+function _setInstallRuntimeMarkerForTests(value) {
+    _installMarkerCache = value;
+}
+function _resetInstallRuntimeMarkerCacheForTests() {
+    _installMarkerCache = undefined;
+}
 /**
  * Resolve the explicit runtime for a project directory, from the two
  * explicit sources only — no default is applied.
@@ -121,17 +176,32 @@ function resolveExplicitRuntime(projectDir, env = process.env) {
 /**
  * Resolve the effective runtime for a project directory.
  *
- *   process.env.GSD_RUNTIME  >  config.runtime  >  'claude'
+ *   process.env.GSD_RUNTIME  >  config.runtime  >  install marker  >  'claude'
  *
  * Mirrors the precedence already used by profile-output.cjs and the rest of
  * the runtime resolution chain. Returns a lowercased string so downstream
  * comparisons can be case-blind.
  *
+ * #3897 rung 2: the per-install `.gsd-runtime` marker is the THIRD rung,
+ * between the two explicit sources and the 'claude' default — matching
+ * model-resolver.cts's own description of it as "the third precedence rung"
+ * before this reader was promoted here. The marker's raw contents are never
+ * trusted verbatim (N1): they are routed through the SAME
+ * `resolveRuntimeNameFromCandidates` normalization the env rung uses, so an
+ * unknown or hostile marker value degrades exactly like an unknown
+ * GSD_RUNTIME value would.
+ *
  * @param projectDir - path to the project directory, or null/undefined
  * @returns the resolved runtime name
  */
 function resolveRuntime(projectDir) {
-    return resolveExplicitRuntime(projectDir) ?? 'claude';
+    const explicit = resolveExplicitRuntime(projectDir);
+    if (explicit)
+        return explicit;
+    const markerRuntime = (0, runtime_name_policy_cjs_1.resolveRuntimeNameFromCandidates)(readInstallRuntimeMarker());
+    if (markerRuntime)
+        return markerRuntime;
+    return 'claude';
 }
 /**
  * Convenience: format using the runtime resolved from a project directory.

package/gsd-core/bin/lib/shell-command-projection.cjs

@@ -19,6 +19,7 @@ exports.PATH_ACTION_REASON = void 0;
 exports.toPosixPath = toPosixPath;
 exports.toNativePath = toNativePath;
 exports.posixNormalize = posixNormalize;
+exports.toComparablePathKey = toComparablePathKey;
 exports.hookCommandNeedsPowerShellCallOperator = hookCommandNeedsPowerShellCallOperator;
 exports.formatHookCommandForRuntime = formatHookCommandForRuntime;
 exports.shellHookOmitsBashRunner = shellHookOmitsBashRunner;
@@ -43,6 +44,7 @@ exports.projectPersistentPathExportActions = projectPersistentPathExportActions;
 exports.isSpawnTimeout = isSpawnTimeout;
 exports.execGit = execGit;
 exports.execNpm = execNpm;
+exports.envGet = envGet;
 exports.resolveExecutableBinary = resolveExecutableBinary;
 exports.projectSpawnInvocation = projectSpawnInvocation;
 exports.execTool = execTool;
@@ -50,6 +52,7 @@ exports.resolveGsdToolsPath = resolveGsdToolsPath;
 exports.dispatchGsdCommand = dispatchGsdCommand;
 exports.probeTty = probeTty;
 exports.normalizeContent = normalizeContent;
+exports.contentChangedAfterNormalize = contentChangedAfterNormalize;
 exports.retryRenameSync = retryRenameSync;
 exports.platformWriteSync = platformWriteSync;
 exports.platformReadSync = platformReadSync;
@@ -95,6 +98,20 @@ function toNativePath(p) {
 function posixNormalize(p) {
     return p.replace(/\\/g, '/');
 }
+/**
+ * #3663 — comparison key for a path that must equal another path regardless
+ * of spelling: separator form (forward slashes via posixNormalize), relative
+ * segments and trailing separators (path.resolve + strip), and — ONLY on
+ * win32's case-insensitive filesystem — letter casing. POSIX stays
+ * case-sensitive: differently-cased paths are genuinely different
+ * directories there. This module owns the platform-conditional fold so the
+ * policy lives at the seam instead of accreting per-call-site copies (the
+ * class init.cts's normalizeForCompare/toComparableRaw predate).
+ */
+function toComparablePathKey(p, platform = process.platform) {
+    const normalized = posixNormalize(node_path_1.default.resolve(p)).replace(/\/+$/g, '');
+    return platform === 'win32' ? normalized.toLowerCase() : normalized;
+}
 /**
  * Return true when a managed hook command must be prefixed with PowerShell's
  * call operator so a quoted executable token is invokable by the target
@@ -218,6 +235,13 @@ const MANAGED_HOOK_BASENAMES_BY_SURFACE = {
         'gsd-read-injection-scanner.js',
         'gsd-update-banner.js',
         'gsd-workflow-guard.js',
+        // #3662: the three PreToolUse guards are GSD-managed JS hooks (registered
+        // only-if-absent by applySettingsJsonHooks) but sat outside this set, so
+        // the #2979 runner rewriter never reached them — the issue's reported
+        // mixed state lived on exactly these hooks.
+        'gsd-write-guard.js',
+        'gsd-agent-isolation-guard.js',
+        'gsd-worktree-path-guard.js',
     ]),
     'codex-toml': new Set([
         'gsd-check-update.js',
@@ -237,6 +261,14 @@ const MANAGED_HOOK_COMMAND_BASENAMES_BY_SURFACE = {
         'gsd-session-state.sh',
         'gsd-validate-commit.sh',
         'gsd-phase-boundary.sh',
+        // #3662: same three guards as MANAGED_HOOK_BASENAMES_BY_SURFACE above —
+        // their absence here meant isManagedHookCommand never recognized them, so
+        // the settings.json→settings.local.json migration filter (and uninstall
+        // cleanup) skipped GSD's own guard entries. Folded-in fix, surfaced by the
+        // #3662 issue thread.
+        'gsd-write-guard.js',
+        'gsd-agent-isolation-guard.js',
+        'gsd-worktree-path-guard.js',
     ]),
     'codex-toml': new Set([
         'gsd-check-update.js',
@@ -330,9 +362,15 @@ const ANCHORED_HOOK_SCRIPT_TOKEN = /^"\$[A-Za-z_][A-Za-z0-9_]*"\//;
  * Non-Windows keeps the original script token shape when provided (single
  * quote / bareword / quoted), while Windows normalizes to double-quoted
  * forward-slash path tokens for stable cross-shell behavior.
+ *
+ * #3662: `runnerToken` is the runner the current install would emit — since
+ * #3662 that is the runtime-resolving chain token (see
+ * buildNodeRunnerChainToken), not a bare absolute path, so re-projected
+ * entries converge onto a runner that resolves in every environment sharing
+ * the config root.
  */
-function projectLegacySettingsHookCommand({ absoluteRunner, scriptPath, scriptToken, runtime = 'generic', platform = process.platform, }) {
-    if (!absoluteRunner || !scriptPath)
+function projectLegacySettingsHookCommand({ runnerToken, scriptPath, scriptToken, runtime = 'generic', platform = process.platform, }) {
+    if (!runnerToken || !scriptPath)
         return null;
     const normalizedScriptPath = platform === 'win32' ? posixNormalize(scriptPath) : scriptPath;
     // #1693: a script path already carrying a `"$CLAUDE_PROJECT_DIR"`-anchored
@@ -351,7 +389,7 @@ function projectLegacySettingsHookCommand({ absoluteRunner, scriptPath, scriptTo
             : JSON.stringify(normalizedScriptPath))
         : (scriptToken || JSON.stringify(normalizedScriptPath));
     return projectShellCommandText({
-        runnerToken: absoluteRunner,
+        runnerToken,
         argTokens: [commandScriptToken],
         runtime,
         platform,
@@ -628,8 +666,12 @@ function _isFile(candidate, requireExecutable = false, platform = process.platfo
  *
  * Exact match wins when present, so a caller who sets the canonical name pays
  * no scan.
+ *
+ * Exported so callers outside this seam can route an exact-case-sensitive env
+ * read through it instead of accessing a non-`process.env` object directly
+ * (see `local/no-exact-case-env-access`).
  */
-function _envGet(env, name) {
+function envGet(env, name) {
     const exact = env[name];
     if (exact !== undefined)
         return exact;
@@ -728,7 +770,7 @@ function resolveExecutableBinary(name, opts = {}) {
         return _isFile(name, requireExecutable, platform) ? name : null;
     }
     const env = opts.env ?? process.env;
-    const rawPath = opts.pathOverride !== undefined ? opts.pathOverride : (_envGet(env, 'PATH') || '');
+    const rawPath = opts.pathOverride !== undefined ? opts.pathOverride : (envGet(env, 'PATH') || '');
     const pathSegments = String(rawPath).split(node_path_1.default.delimiter).filter(Boolean);
     const segments = [...(opts.prependPaths ?? []), ...pathSegments];
     if (platform !== 'win32') {
@@ -739,7 +781,7 @@ function resolveExecutableBinary(name, opts = {}) {
         }
         return null;
     }
-    const exts = String(_envGet(env, 'PATHEXT') || DEFAULT_PATHEXT).split(';').filter(Boolean);
+    const exts = String(envGet(env, 'PATHEXT') || DEFAULT_PATHEXT).split(';').filter(Boolean);
     // A name already ending in a PATHEXT-listed extension is an address, not a stem:
     // probing `foo.exe` as `foo.exe.EXE` would miss the file sitting right there.
     // Compared case-insensitively because PATHEXT casing is not guaranteed.
@@ -840,7 +882,7 @@ function projectSpawnInvocation(command, args = [], opts = {}) {
         return resolved ? { command: resolved, args, resolved } : { command, args, resolved: null };
     }
     return {
-        command: String(_envGet(env, 'ComSpec') || 'cmd.exe'),
+        command: String(envGet(env, 'ComSpec') || 'cmd.exe'),
         args: ['/d', '/s', '/c', _buildVerbatimCmdLine(target, args)],
         resolved,
         windowsVerbatimArguments: true,
@@ -1022,7 +1064,11 @@ function _normalizeMd(content) {
             if (i === 0 || !insideFence[i - 1])
                 result.push('');
         }
-        if (/^(\s*[-*+]\s|\s*\d+\.\s)/.test(line) && i > 0 && prevTrimmed !== '' && !/^(\s*[-*+]\s|\s*\d+\.\s)/.test(prev) && prevTrimmed !== '---')
+        // #3854: the `!/^\s/.test(prev)` guard mirrors the after-a-bullet rule below —
+        // an indented non-bullet line is a CONTINUATION of the previous list item, not a
+        // preceding paragraph, so no separating blank may be injected before this bullet
+        // (that injection converted every tight multi-line list to a loose one on write).
+        if (/^(\s*[-*+]\s|\s*\d+\.\s)/.test(line) && i > 0 && prevTrimmed !== '' && !/^(\s*[-*+]\s|\s*\d+\.\s)/.test(prev) && !/^\s/.test(prev) && prevTrimmed !== '---')
             result.push('');
         result.push(line);
         if (/^#{1,6}\s/.test(trimmed) && i < lines.length - 1 && (lines[i + 1] ?? '').trimEnd() !== '')
@@ -1052,6 +1098,23 @@ function normalizeContent(filePath, content, opts = {}) {
     }
     return { content: normalized, encoding };
 }
+/**
+ * True iff persisting `after` via `platformWriteSync` would land different
+ * on-disk bytes than `before` already has (or would have, normalized the
+ * same way). `platformWriteSync` runs Markdown normalization (CRLF strip,
+ * blank-line-run collapse, single trailing newline) before writing, so a
+ * caller comparing raw pre-normalize strings (`after !== before`) can report
+ * `true` even when the persisted bytes are byte-identical — e.g. a
+ * transform that regenerates a section fresh on every call, including a
+ * genuine no-op re-run, in a different-but-equivalent raw shape than the
+ * already-normalized on-disk original (#3685 / #3691). Any "did this write
+ * change the file?" flag MUST go through this seam (or an equivalent
+ * post-write re-read of the actual on-disk bytes) instead of a raw `!==` —
+ * do not simplify this back to a direct string comparison.
+ */
+function contentChangedAfterNormalize(filePath, before, after) {
+    return normalizeContent(filePath, after).content !== normalizeContent(filePath, before).content;
+}
 // Rename errnos that are transient on Windows: a concurrent reader (or an AV
 // scanner / indexer) holding the target open makes renameSync fail briefly.
 // Same idiom as capability-ledger.cts / capability-consent.cts.

package/gsd-core/bin/lib/smart-entry.cjs

@@ -43,6 +43,10 @@ const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
 const node_child_process_1 = require("node:child_process");
 const markdown_sectionizer_cjs_1 = require("./markdown-sectionizer.cjs");
+// #3696: the calendar-validity predicate moved to the STATE.md document module
+// so `state validate` can assert the same `last_activity` invariant this reader
+// already enforces (ADR-227). Two copies would let the two surfaces disagree
+// about whether a STATE.md is usable — which is the defect #3696 reports.
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const ioMod = require("./io.cjs");
 const { output } = ioMod;
@@ -160,26 +164,6 @@ const ISO_LEADING_RE = /^(\d{4})-(\d{2})-(\d{2})((?:[T ]\d{2}:\d{2}(?::\d{2}(?:\
  * failed open on every letter-led description and re-opened #2570.
  */
 const ZONE_DESIGNATOR_RE = /^\s*[A-Z]{2,5}(?![A-Za-z])/;
-/**
- * True only when y/m/d name a date that actually exists on the calendar.
- *
- * `Date.parse` validates shape but not value: it rolls an out-of-range day
- * FORWARD rather than rejecting it (`2026-02-30` -> `2026-03-02`,
- * `2026-04-31` -> `2026-05-01`). Shape-only validation would therefore
- * propagate a different, wrong instant instead of failing safe — precisely
- * what ADR-227 ("validate shape AND value; on failure of either layer coerce
- * to the contract's safe default, never propagate") exists to prevent. A
- * round-trip through Date.UTC detects the rollover: any component the
- * constructor normalised comes back changed.
- */
-function isRealCalendarDate(year, month, day) {
-    if (month < 1 || month > 12 || day < 1 || day > 31)
-        return false;
-    const probe = new Date(Date.UTC(year, month - 1, day));
-    return (probe.getUTCFullYear() === year &&
-        probe.getUTCMonth() === month - 1 &&
-        probe.getUTCDate() === day);
-}
 function parseActivityTimestamp(raw) {
     if (!raw)
         return null;
@@ -190,7 +174,7 @@ function parseActivityTimestamp(raw) {
         // Reject an impossible calendar date outright rather than letting
         // Date.parse substitute a rolled-forward one. null = "no activity signal",
         // the safe default staleActivity already fails open on.
-        if (!isRealCalendarDate(Number(year), Number(month), Number(day)))
+        if (!stateDocument.isRealCalendarDate(Number(year), Number(month), Number(day)))
             return null;
         // The date is real, so stay as liberal as before (Postel): a whole-string
         // parse still wins when the engine can make sense of the value. Reading the
@@ -542,7 +526,13 @@ function classify(s) {
         return 'planning';
     if (/\bexecut(e|ing)|active|in.progress|building\b/i.test(s.status))
         return 'executing';
-    if (/\bverify|review|needs.review|pending.review\b/i.test(s.status))
+    // #3864: `verif` (not `verify`) — the same stem state-document's
+    // normalizeStateStatus matches. "verified" and "verification" contain no
+    // "verify" substring, so the exact word left them falling through to
+    // `unknown` (or idle-stranded on a clean unpushed tree — differently
+    // wrong). verify_failed is tested above, so a failed verification still
+    // wins over this branch.
+    if (/\bverif|review|needs.review|pending.review\b/i.test(s.status))
         return 'verify-pending';
     if (isIdleStranded(s))
         return 'idle-stranded';

package/gsd-core/bin/lib/spec-section.cjs

@@ -26,6 +26,9 @@ exports.SECTION_HEADERS = void 0;
 exports.countSectionDataRows = countSectionDataRows;
 exports.specSectionStatus = specSectionStatus;
 const node_fs_1 = __importDefault(require("node:fs"));
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const cliExitModule = require("./cli-exit.cjs");
+const { ExitError, runMain } = cliExitModule;
 /**
  * Canonical SPEC section header matchers — the SINGLE source of truth for the headings
  * `templates/spec.md` renders. Suffix-tolerant by design: `prohibitions` matches BOTH
@@ -101,11 +104,13 @@ const VALID_KEYS = ['edges', 'prohibitions'];
 // 2 only on a usage error (missing args / bad key). `require.main === module` so it runs only when
 // the compiled `.cjs` is executed directly, never when imported by tests.
 if (require.main === module) {
-    const specFile = process.argv[2];
-    const key = process.argv[3];
-    if (!specFile || !key || !VALID_KEYS.includes(key)) {
-        process.stderr.write('usage: spec-section.cjs <specFile> <edges|prohibitions>\n');
-        process.exit(2);
-    }
-    process.stdout.write(JSON.stringify(specSectionStatus(specFile, key)) + '\n');
+    runMain(() => {
+        const specFile = process.argv[2];
+        const key = process.argv[3];
+        if (!specFile || !key || !VALID_KEYS.includes(key)) {
+            process.stderr.write('usage: spec-section.cjs <specFile> <edges|prohibitions>\n');
+            throw new ExitError(2);
+        }
+        process.stdout.write(JSON.stringify(specSectionStatus(specFile, key)) + '\n');
+    });
 }