@opengsd/gsd-core 1.10.0 → 1.11.0

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

@@ -43,6 +43,8 @@ exports.projectPersistentPathExportActions = projectPersistentPathExportActions;
 exports.isSpawnTimeout = isSpawnTimeout;
 exports.execGit = execGit;
 exports.execNpm = execNpm;
+exports.resolveExecutableBinary = resolveExecutableBinary;
+exports.projectSpawnInvocation = projectSpawnInvocation;
 exports.execTool = execTool;
 exports.resolveGsdToolsPath = resolveGsdToolsPath;
 exports.dispatchGsdCommand = dispatchGsdCommand;
@@ -58,6 +60,7 @@ const node_fs_1 = __importDefault(require("node:fs"));
 // can intercept calls from this seam — destructured imports capture references
 // at load time and become un-mockable.
 const node_child_process_1 = __importDefault(require("node:child_process"));
+const pattern_cjs_1 = require("./pattern.cjs");
 /**
  * Convert a filesystem path to POSIX form (forward slashes) by translating the
  * platform-native separator. Single seam for native→POSIX conversion.
@@ -306,7 +309,7 @@ function isManagedHookCommand(commandText, opts = {}) {
             return false;
     }
     for (const basename of managedBasenames) {
-        const escapedBasename = basename.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+        const escapedBasename = (0, pattern_cjs_1.escapeRegex)(basename);
         const pattern = new RegExp(`(^|[\\\\/\\s"'` + '`' + `])${escapedBasename}(?=$|[\\s"'` + '`' + `])`);
         if (pattern.test(normalizedCommand))
             return true;
@@ -589,15 +592,283 @@ function execNpm(args, opts = {}) {
     });
     return _spawnResult(result, 'npm');
 }
+/**
+ * Default PATHEXT when Windows does not supply one. Matches the value
+ * `gsd-tools.cjs`'s `resolveSpawnBinary` shipped in #3275; kept identical so the
+ * delegation is a behavior-preserving move rather than a redefinition.
+ */
+const DEFAULT_PATHEXT = '.EXE;.CMD;.BAT;.COM';
+/** Windows extensions that must be mediated through cmd.exe rather than spawned. */
+const CMD_MEDIATED_EXT = /\.(cmd|bat)$/i;
+function _isFile(candidate, requireExecutable = false, platform = process.platform) {
+    try {
+        if (!node_fs_1.default.statSync(candidate).isFile())
+            return false;
+        if (requireExecutable && platform !== 'win32')
+            node_fs_1.default.accessSync(candidate, node_fs_1.default.constants.X_OK);
+        return true;
+    }
+    catch {
+        // Missing, unreadable (EACCES), a broken link, or (when requireExecutable
+        // is set) not executable — all mean "not this one".
+        return false;
+    }
+}
+/**
+ * Read an environment variable by name, case-insensitively.
+ *
+ * Windows environment variable names are case-insensitive and conventionally
+ * cased `Path` / `ComSpec`, and `process.env` is a case-insensitive proxy that
+ * hides the difference. Spreading it (`{ ...process.env, ...opts.env }`, which
+ * `execTool` does whenever a caller supplies `opts.env`) produces a PLAIN object
+ * that keeps the OS's actual casing and loses the proxy — so an exact-case
+ * `env['PATH']` lookup returns undefined there and the PATH scan silently sees
+ * nothing. Caught by the Windows CI lane on #3617; the #3445 tests never hit it
+ * because they pass uppercase keys explicitly.
+ *
+ * Exact match wins when present, so a caller who sets the canonical name pays
+ * no scan.
+ */
+function _envGet(env, name) {
+    const exact = env[name];
+    if (exact !== undefined)
+        return exact;
+    const lower = name.toLowerCase();
+    for (const key of Object.keys(env)) {
+        if (key.toLowerCase() === lower)
+            return env[key];
+    }
+    return undefined;
+}
+/** cmd.exe's own quoting rule inside a `/c` string: a literal quote is doubled. */
+function _cmdQuoteToken(token) {
+    return `"${token.replace(/"/g, '""')}"`;
+}
+/**
+ * Build a single verbatim command-line string for `cmd.exe /c` where every
+ * token is force-quoted, then wrap the whole thing in one more outer pair.
+ * cmd.exe strips exactly one outer quote pair when the string begins with a
+ * quote and contains at least two — so the outer wrap disappears and what's
+ * left is a sequence of individually-quoted tokens. Force-quoting is the
+ * point: an unquoted `a&b` is split by cmd's own metacharacter parsing, but a
+ * quoted `"a&b"` is one literal argument.
+ */
+function _buildVerbatimCmdLine(target, args) {
+    return `"${[target, ...args].map(_cmdQuoteToken).join(' ')}"`;
+}
+/**
+ * #3411: resolve a DECLARED command name to the file a spawn can actually start.
+ * The single canonical answer to "where is this binary?" for the whole tree.
+ *
+ * This is the seam `CONTEXT.md` declares as "All OS-facing I/O; single platform
+ * seam". Four divergent implementations of this logic existed (#3411): `execNpm`'s
+ * `shell:true`, `execTool`'s absence of any handling, `gsd-tools.cjs`'s private
+ * scan, and `fallow-runner.cts`'s own candidate array. #3275 folded two of them
+ * together in `bin/`; this lifts that resolver into the seam so `bin/` delegates
+ * instead of owning a copy.
+ *
+ * **win32** tries PATHEXT entries ONLY — never the bare name. npm global installs
+ * drop an EXTENSIONLESS POSIX sh shim (`...\npm\codex`) next to `codex.CMD`; a
+ * bare-name-first scan resolves to it, the cmd.exe mediation gate sees no `.cmd`,
+ * and the ENOENT returns unchanged (field-reported on Windows 11 — see #3275).
+ * A name that ALREADY carries a PATHEXT-listed extension is tried as-is first, so
+ * `foo.exe` resolves to `foo.exe` rather than being probed as `foo.exe.EXE`; a
+ * suffix that is not in PATHEXT (`foo.txt`) is not an extension and only feeds the
+ * append loop.
+ *
+ * **POSIX** answers EXISTENCE by scanning PATH for the bare name. `execTool` does
+ * NOT consult this on POSIX — the bare name goes to spawnSync unchanged and Node's
+ * own PATH search does the work, so macOS/Linux behavior is untouched (#3275
+ * acceptance contract).
+ *
+ * Path-like names (any `/` or `\`) bypass the PATH scan: the name is already an
+ * address, so it passes through when it names an existing file.
+ *
+ * **`opts.prependPaths`** — directories searched BEFORE `env.PATH`, in array
+ * order (e.g. a project-local `node_modules/.bin`). Defaults to `[]`, so
+ * Phase 1's callers (`execTool`, and `gsd-tools.cjs`'s `resolveSpawnBinary` /
+ * `deps.spawn` / `hasBinary`), which set neither new option, are byte-identical
+ * to today. The existing per-directory candidate logic (win32 as-is-then-append-
+ * PATHEXT; POSIX bare name) applies to prepended directories exactly as it does
+ * to `PATH` segments — there is no special-casing.
+ *
+ * **`opts.requireExecutable`** — when `true` and the platform is not `win32`,
+ * a candidate must additionally pass `fs.accessSync(candidate, fs.constants.X_OK)`
+ * to count as a match. On `win32` this is a no-op (mode bits do not mean
+ * execute on Windows — the same carve-out `fallow-runner`'s prior private
+ * resolver already had). Defaults to `false`, so `accessSync` is never called
+ * unless a caller opts in. It is opt-in rather than the default because making
+ * `X_OK` unconditional would break #3445's suite: those tests stage candidates
+ * with plain `fs.writeFileSync` and never set an exec bit (the repo bans
+ * `chmod` in tests), so every one of them would resolve to `null` on POSIX.
+ *
+ * **`opts.pathOverride`** — "search THIS PATH, but read everything else —
+ * PATHEXT included — from the ambient environment." When set (`!== undefined`),
+ * the PATH search segments come from splitting `pathOverride` on `path.delimiter`
+ * instead of from `env.PATH`; `pathOverride: ''` means an explicit EMPTY search
+ * path (zero segments), never a fallback to `env.PATH` — use `!== undefined`,
+ * not truthiness, to tell "caller supplied a PATH string" apart from "caller
+ * supplied nothing". `opts.prependPaths` still comes first. PATHEXT resolution
+ * is UNAFFECTED by this option — it still reads from `env` (which defaults to
+ * `process.env`) exactly as it does when `pathOverride` is omitted. This exists
+ * so a caller that already has its own search path in hand (e.g.
+ * `resolveFallowBinary`'s `envPath`) does not have to hand-thread PATHEXT
+ * alongside it — a private PATHEXT read is the very shape
+ * `local/no-private-binary-resolution` forbids outside this seam.
+ *
+ * @returns the resolved path, or `null` when nothing matched. Callers fall back to
+ *   the declared name on `null` so a genuine ENOENT still surfaces (#3086).
+ */
+function resolveExecutableBinary(name, opts = {}) {
+    if (!name)
+        return null;
+    const requireExecutable = opts.requireExecutable ?? false;
+    const platform = opts.platform ?? process.platform;
+    if (name.includes('/') || name.includes('\\')) {
+        return _isFile(name, requireExecutable, platform) ? name : null;
+    }
+    const env = opts.env ?? process.env;
+    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') {
+        for (const dir of segments) {
+            const candidate = node_path_1.default.join(dir, name);
+            if (_isFile(candidate, requireExecutable, platform))
+                return candidate;
+        }
+        return null;
+    }
+    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.
+    const lower = name.toLowerCase();
+    const carriesKnownExt = exts.some((ext) => lower.endsWith(ext.toLowerCase()));
+    for (const dir of segments) {
+        if (carriesKnownExt) {
+            const asIs = node_path_1.default.join(dir, name);
+            if (_isFile(asIs, requireExecutable, platform))
+                return asIs;
+        }
+        for (const ext of exts) {
+            const candidate = node_path_1.default.join(dir, name + ext);
+            if (_isFile(candidate, requireExecutable, platform))
+                return candidate;
+        }
+    }
+    return null;
+}
+/**
+ * #3411: project a declared `(command, args)` into the pair `spawnSync` can
+ * actually execute on this platform.
+ *
+ * Resolution alone does not make Windows work: `CreateProcess` cannot execute a
+ * `.cmd`/`.bat` at all, so the cmd.exe mediation is inseparable from the lookup.
+ * Exporting only the resolver would leave every caller to re-derive that half —
+ * which is precisely how #3411's four copies accumulated.
+ *
+ * cmd.exe is invoked as an ordinary program with an EXPLICIT argv array, never via
+ * `shell: true`. `shell:true` on Windows is the mechanism behind CVE-2024-27980
+ * (argument injection through `.bat`/`.cmd`), and Node 26 deprecates it with an
+ * args array (DEP0190) because arguments are concatenated rather than escaped.
+ *
+ * Mediation fires when the target — the resolved path, or the declared name when
+ * resolution found nothing — carries a `.cmd`/`.bat` extension. A BARE name that
+ * resolved to nothing is passed through verbatim so the spawn fails with ENOENT;
+ * mediating it would turn `{exitCode:127, 'foo: not found'}` into cmd.exe's exit
+ * 9009 and silently change the not-found contract callers depend on.
+ *
+ * POSIX is a strict no-op: the declared command is returned unchanged and the
+ * environment is never consulted.
+ *
+ * The mediated command line is built VERBATIM rather than left to libuv: libuv's
+ * `quote_cmd_arg` only force-quotes an argument that contains a space, tab, or
+ * quote — it does not know about cmd.exe metacharacters (`&`, `|`, `>`, `<`,
+ * `^`, ...) at all, so an argument like `a&calc` reaches cmd.exe unquoted and
+ * gets re-parsed as two commands (the CVE-2024-27980 argument-injection class).
+ * Node's own CVE-2024-27980 escaping does not help here because it only fires
+ * when the spawned FILE itself is a `.bat`/`.cmd` — in this seam the spawned
+ * file is `cmd.exe`, not the target. Building the line ourselves and passing
+ * `windowsVerbatimArguments: true` (the shape Rust's std uses for the sibling
+ * CVE-2024-24576) means every token is force-quoted inside one outer pair, so
+ * a metacharacter inside a quoted token can never split the command line.
+ *
+ * KNOWN LIMIT: `%VAR%` still expands inside a cmd `/c` string, and there is no
+ * escape for `%` outside a batch file — an argument containing `%FOO%` is
+ * substituted with the environment value regardless of quoting. That is an
+ * information-disclosure limit, not arbitrary execution, and it's the same
+ * limit Rust's std documents for its own `CommandExt::raw_arg` escape hatch.
+ *
+ * CALLER CHOICE: this function's return value carries two independently
+ * adoptable pieces of information, and a caller may take either, both, or
+ * neither. `windowsVerbatimArguments: true` marks the cases where mediation
+ * was REQUIRED — the caller MUST adopt `command`+`args` together, since a
+ * `.cmd`/`.bat` genuinely cannot be spawned any other way. A merely-resolved
+ * `.exe` path (no mediation flag set) is only an OFFER: a caller may decline
+ * it and keep spawning the declared name instead, to hold its own observable
+ * contract stable. `execTool` (this file, below) is exactly such a caller —
+ * it adopts the mediated pair when `windowsVerbatimArguments` is set, but
+ * otherwise passes the declared `program`/`args` through untouched.
+ */
+function projectSpawnInvocation(command, args = [], opts = {}) {
+    const platform = opts.platform ?? process.platform;
+    if (platform !== 'win32')
+        return { command, args, resolved: null };
+    const env = opts.env ?? process.env;
+    const resolved = resolveExecutableBinary(command, { platform, env });
+    // Mediate against the resolved path when we have one, else against the declared
+    // name. An unresolved name is mediated ONLY when it already declares .cmd/.bat:
+    // PATH-only resolution misses a batch file sitting in the current directory,
+    // which `cmd.exe /c` still finds — the behavior gsd-tools.cjs shipped before
+    // this consolidation, preserved here rather than silently narrowed.
+    const target = resolved ?? command;
+    if (!CMD_MEDIATED_EXT.test(node_path_1.default.basename(target))) {
+        // A BARE name that resolved to nothing is passed through untouched so the
+        // spawn fails with ENOENT. Mediating it would turn {exitCode:127,
+        // '<name>: not found'} into cmd.exe's exit 9009 and silently change the
+        // not-found contract `_spawnResult` and its 53 dependent files rely on.
+        return resolved ? { command: resolved, args, resolved } : { command, args, resolved: null };
+    }
+    // A CR/LF cannot be represented inside a Windows command line at all — cmd.exe
+    // treats it as a line terminator, so mediating it would silently truncate the
+    // argument rather than pass it through. Fail visibly instead: fall back to the
+    // unmediated shape so the spawn either fails with ENOENT (bare unresolved name)
+    // or hands the raw string to CreateProcess, whichever the caller was already
+    // prepared to see for a non-.cmd/.bat target.
+    if (/[\r\n]/.test(target) || args.some((a) => /[\r\n]/.test(a))) {
+        return resolved ? { command: resolved, args, resolved } : { command, args, resolved: null };
+    }
+    return {
+        command: String(_envGet(env, 'ComSpec') || 'cmd.exe'),
+        args: ['/d', '/s', '/c', _buildVerbatimCmdLine(target, args)],
+        resolved,
+        windowsVerbatimArguments: true,
+    };
+}
 function execTool(program, args, opts = {}) {
-    const result = node_child_process_1.default.spawnSync(program, args, {
+    // #3411: Windows cannot spawn a .cmd/.bat at all — CreateProcess refuses it —
+    // so those are mediated through cmd.exe. Everything else keeps the DECLARED
+    // program name: libuv's CreateProcess path already performs PATH + PATHEXT
+    // search, so resolving a .exe here would buy nothing and would change what
+    // this seam's 167 dependents observe being spawned. `tests/graphify.test.cjs`
+    // pins that contract by spying on spawnSync's first argument. POSIX never
+    // reaches the mediation branch at all.
+    const spawnEnv = opts.env ? { ...process.env, ...opts.env } : undefined;
+    const invocation = projectSpawnInvocation(program, args, { env: spawnEnv ?? process.env });
+    const mediated = invocation.windowsVerbatimArguments === true;
+    const result = node_child_process_1.default.spawnSync(mediated ? invocation.command : program, mediated ? invocation.args : args, {
         cwd: opts.cwd,
-        env: opts.env ? { ...process.env, ...opts.env } : undefined,
+        env: spawnEnv,
         encoding: 'utf-8',
         stdio: 'pipe',
         timeout: opts.timeout ?? 30_000,
         windowsHide: true,
+        ...(mediated ? { windowsVerbatimArguments: true } : {}),
     });
+    // Stamp the DECLARED name, never the resolved path: `_spawnResult` renders
+    // `${program}: not found`, and callers across 53 files match on the string they
+    // passed. Resolution must not leak an absolute path into that message.
     return _spawnResult(result, program);
 }
 /**
@@ -704,6 +975,7 @@ function probeTty(opts = {}) {
         const ttyPath = node_child_process_1.default.execFileSync('tty', [], {
             encoding: 'utf-8',
             stdio: ['inherit', 'pipe', 'ignore'],
+            timeout: 5_000,
         }).trim();
         if (!ttyPath || ttyPath === 'not a tty')
             return null;

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

@@ -57,10 +57,13 @@ const phaseLifecycle = require("./phase-lifecycle.cjs");
 const { deriveProgressFromRoadmap } = phaseLifecycle;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const stateDocument = require("./state-document.cjs");
-const { stateExtractField } = stateDocument;
+const { stateFieldValue } = stateDocument;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const phaseId = require("./phase-id.cjs");
-const { comparePhaseNum, extractPhaseToken, normalizePhaseName, phaseTokenMatches } = phaseId;
+const { comparePhaseNum, extractPhaseToken, matchPhaseDirs, normalizePhaseName, stripProjectCodePrefix } = phaseId;
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const stateMod = require("./state.cjs");
+const { readStateHeadFreshness } = stateMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const unusableInput = require("./unusable-input.cjs");
 const { warnUnusableInput, UNUSABLE_REASON } = unusableInput;
@@ -86,15 +89,6 @@ exports.SITUATIONS = Object.freeze([
     'unknown',
 ]);
 // ─── Detection ─────────────────────────────────────────────────────────────────
-/** Frontmatter scalar helper: prefer YAML frontmatter, fall back to body field. */
-function fmScalar(fm, body, key, bodyField) {
-    const v = fm[key];
-    if (typeof v === 'string' && v.trim())
-        return v.trim();
-    if (typeof v === 'number' || typeof v === 'boolean')
-        return String(v);
-    return stateExtractField(body, bodyField);
-}
 /** Read a scalar value from a nested frontmatter object (e.g. progress.total_phases). */
 function fmScalarKey(obj, key) {
     if (!obj || typeof obj !== 'object')
@@ -115,17 +109,115 @@ function parseIntOrNull(s) {
 }
 function phaseTokenFromDirName(name) {
     const token = extractPhaseToken(name);
-    return /^\d+(?:[A-Z])?(?:\.\d+)*(?:-|$)/i.test(token) ? token : null;
+    // #2528: the shape probe runs on the PROJECT-CODE-STRIPPED token. A prefixed
+    // directory tokenizes to `MEM-05-80-20`, which does not start with a digit,
+    // so the unstripped probe rejected it and the entry was dropped before any
+    // resolution ran — every phase in a project-coded plan was invisible here.
+    // The full token is still what is returned: `comparePhaseNum` strips the
+    // prefix itself, so the sort is unaffected, and `matchPhaseDirs` needs the
+    // real directory name.
+    const probe = stripProjectCodePrefix(token);
+    return /^\d+(?:[A-Z])?(?:\.\d+)*(?:-|$)/i.test(probe) ? token : null;
 }
 /**
  * Parse a `last_activity` value that may be an ISO date or a free-form string
  * into an epoch-ms timestamp. Returns null when unparseable.
+ *
+ * #2570: `last_activity` routinely carries a trailing " — <description>" — the
+ * shape `templates/state.md` itself prescribes (`Last activity: [YYYY-MM-DD] —
+ * [What happened]`), which gsd-core's own STATE.md mirrors into frontmatter.
+ * `Date.parse` on the whole string returns NaN, and because `staleActivity`
+ * treats null as "not stale" (fails open), the ONLY idle/staleness detector
+ * never fired on any project whose last_activity retained its description.
+ * Be liberal in what we accept (Postel): read the leading ISO date/time token
+ * when the value carries one, so the description suffix — whatever separator
+ * (em dash or hyphen) it uses — no longer silently blinds the detector; fall
+ * back to a whole-string parse for any other shape a hand edit might use.
  */
+/** Leading ISO date, with an optional time-of-day and offset. */
+const ISO_LEADING_RE = /^(\d{4})-(\d{2})-(\d{2})((?:[T ]\d{2}:\d{2}(?::\d{2}(?:\.\d+)?)?(?:Z|[+-]\d{2}:?\d{2})?)?)/;
+/**
+ * A NAMED timezone designator at the start of the un-reconstructable remainder
+ * (#2571). ISO_LEADING_RE's offset group captures only `Z` / `±HH:MM`, so a
+ * named zone (GMT, EST, ...) is not in the leading token — it sits here.
+ * Reconstructing the token without it would let Date.parse read the time as
+ * LOCAL, shifting the instant by the host's offset (a wrong, host-dependent
+ * value), so a zone-shaped remainder must fail open (ADR-227).
+ *
+ * The shape is a short all-caps run (2–5 letters) that stands alone — the
+ * negative lookahead excludes the first letter of a Capitalised word like
+ * "Milestone", and an optional trailing offset is subsumed because the leading
+ * all-caps run already matches. Everything else — a lowercase or Capitalised
+ * description, a separator — is describable text and is reconstructed from the
+ * leading date.
+ *
+ * Consulted ONLY when the leading token captured a time-of-day (see the caller):
+ * a zone designator qualifies a clock time, so a BARE date can carry no zone
+ * hazard — reconstructing it is always just that date's UTC midnight, whatever
+ * trails it. Gating on the time keeps a description that merely opens with a
+ * tech acronym ("2026-06-08 CI green", "API refactor") on the reconstruct path
+ * instead of failing open. The prior "any letter" guard was too liberal — it
+ * 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;
-    const ms = Date.parse(raw);
-    return Number.isNaN(ms) ? null : ms;
+    const trimmed = raw.trim();
+    const iso = trimmed.match(ISO_LEADING_RE);
+    if (iso) {
+        const [, year, month, day, time] = iso;
+        // 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)))
+            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
+        // token first would silently DROP a trailing zone name -- "2026-06-08
+        // 12:34:56 GMT" parses whole as 12:34:56Z but as local time from the token,
+        // shifting the instant by the host's UTC offset.
+        const whole = Date.parse(trimmed);
+        if (!Number.isNaN(whole))
+            return whole;
+        // Whole-string failed: the value carries a suffix the engine can't read as
+        // one instant (#2570). Reconstruct from the leading token UNLESS the remainder
+        // is a named zone the token dropped (GMT, EST, ...): reconstructing without it
+        // reads the time as LOCAL and shifts the instant by the host's offset, so a
+        // zone-shaped remainder fails open (ADR-227: never propagate a wrong instant;
+        // null is the base's not-stale default). An ordinary description -- the #2570
+        // template's " -- description", or a hand edit's bare-space/tab/colon suffix --
+        // carries no zone and IS reconstructed. See ZONE_DESIGNATOR_RE for the shape;
+        // the earlier "any letter" guard failed open on every description and re-opened
+        // #2570 for whitespace-separated suffixes.
+        const rest = trimmed.slice(iso[0].length);
+        if (time && ZONE_DESIGNATOR_RE.test(rest))
+            return null;
+        const ms = Date.parse(`${year}-${month}-${day}${time}`);
+        return Number.isNaN(ms) ? null : ms;
+    }
+    const direct = Date.parse(trimmed);
+    return Number.isNaN(direct) ? null : direct;
 }
 /** Read-only git signals. Any git error is swallowed → "no git signal". */
 function readGitSignals(cwd) {
@@ -137,6 +229,7 @@ function readGitSignals(cwd) {
                 maxBuffer: 4 * 1024 * 1024,
                 windowsHide: true,
                 stdio: ['pipe', 'pipe', 'pipe'],
+                timeout: 10_000,
             });
         }
         catch {
@@ -186,7 +279,16 @@ function detectVerifyFailed(cwd, currentPhaseRaw) {
     let targetDir;
     if (phaseToken) {
         const normalized = normalizePhaseName(phaseToken);
-        targetDir = entries.find((name) => phaseTokenMatches(name, normalized));
+        // #2528: the fourth directory-resolution site, and the one where a miss is
+        // silent — a phase whose directory cannot be found reports "not failed",
+        // which reads identically to a healthy phase. It must therefore apply the
+        // same canonical selection as the locator and the two command scans, or a
+        // dir like `05-80-20-cleanup` (phase 5 named "80/20 Cleanup") never
+        // surfaces its own failed verification. `entries` is already sorted, and
+        // `matchPhaseDirs` filters without reordering, so taking the first match
+        // preserves the previous `.find()` selection exactly.
+        const { matches } = matchPhaseDirs(entries, normalized);
+        targetDir = matches[0];
         if (!targetDir)
             return false;
     }
@@ -253,6 +355,9 @@ function detectSignals(cwd, now = Date.now) {
         stale_activity: false,
         roadmap_total_phases: null,
         roadmap_completed_phases: null,
+        // No STATE.md (or unreadable) → no stamp to compare. Unknown, not fresh.
+        state_commits_behind: null,
+        state_commit_stale: null,
     };
     if (!hasPlanning)
         return empty;
@@ -266,21 +371,29 @@ function detectSignals(cwd, now = Date.now) {
     //   - body prose:         `Phase: 3`, `**Status:** verifying`, `Total Phases: 5`
     // Read each field across every form, scalar-first then nested then body, so
     // the classifier works on real STATE.md files written by current GSD.
-    const statusRaw = fmScalar(fm, body, 'status', 'Status');
-    const pausedAtRaw = fmScalar(fm, body, 'paused_at', 'Paused At');
-    const lastActivityRaw = fmScalar(fm, body, 'last_activity', 'Last Activity');
+    const statusRaw = stateFieldValue(fm, body, 'status', 'Status').value;
+    const pausedAtRaw = stateFieldValue(fm, body, 'paused_at', 'Paused At').value;
+    const lastActivityRaw = stateFieldValue(fm, body, 'last_activity', 'Last Activity').value;
     // current_phase: scalar fm → nested (none) → body "Current Phase" → body "Phase".
     // The body `Phase:` field is the canonical location in prose-form STATE.md
     // (e.g. "Phase: 3" or "Phase: 3 — ui-review"); parse the leading number.
-    const currentPhaseRaw = fmScalar(fm, body, 'current_phase', 'Current Phase') ??
-        stateExtractField(body, 'Phase');
+    // #3187 / ADR-3180 Amendment 3 ("0.x split"): this read is DELIBERATELY
+    // unscoped — smart-entry classifies `gsd next` routing over the whole body,
+    // whereas state.cts's copies of this same field scope it to `## Current
+    // Position` (#1776/#2956). Those are two different questions sharing a
+    // name; folding the scoped read in here would silently change smart-entry's
+    // routing, an undisclosed Tier-2 change (design's Rejected #3). Both owner
+    // calls below intentionally pass the unscoped `body`, never a Current-
+    // Position slice.
+    const currentPhaseRaw = stateFieldValue(fm, body, 'current_phase', 'Current Phase').value ??
+        stateFieldValue(fm, body, null, 'Phase').value;
     // total_phases & percent: nested `progress:` object takes precedence in the
     // nested schema; scalar fm / body fields cover the flat schema.
     const progressFm = typeof fm.progress === 'object' ? fm.progress : null;
     const totalPhasesRaw = fmScalarKey(progressFm, 'total_phases') ??
-        fmScalar(fm, body, 'total_phases', 'Total Phases');
+        stateFieldValue(fm, body, 'total_phases', 'Total Phases').value;
     const progressRaw = fmScalarKey(progressFm, 'percent') ??
-        fmScalar(fm, body, 'progress', 'Progress');
+        stateFieldValue(fm, body, 'progress', 'Progress').value;
     // Blockers list: `- <text>` items under a `## Blockers` heading.
     const blockers = [];
     const blockersSection = (0, markdown_sectionizer_cjs_1.collectSection)(body, (h) => h.level === 2 && h.text.trim().toLowerCase() === 'blockers', { levelBounded: true });
@@ -326,6 +439,11 @@ function detectSignals(cwd, now = Date.now) {
             /* ROADMAP.md unreadable — leave null; isComplete falls back to legacy. */
         }
     }
+    // #2573: commit-age freshness proxy. Derived through state.cjs's
+    // readStateHeadFreshness so the tri-state and the hash fence stay identical
+    // to validate.health's W024 — one derivation, two surfaces.
+    const stateHeadRaw = stateFieldValue(fm, body, 'state_head', 'State Head').value;
+    const freshness = readStateHeadFreshness(cwd, stateHeadRaw);
     return {
         current_phase: parseIntOrNull(currentPhaseRaw),
         total_phases: parseIntOrNull(totalPhasesRaw),
@@ -342,6 +460,8 @@ function detectSignals(cwd, now = Date.now) {
         stale_activity: staleActivity,
         roadmap_total_phases: roadmapTotalPhases,
         roadmap_completed_phases: roadmapCompletedPhases,
+        state_commits_behind: freshness.commits_behind,
+        state_commit_stale: freshness.commit_stale,
     };
 }
 // ─── Situation classification ─────────────────────────────────────────────────

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

@@ -144,7 +144,11 @@ function routeStateCommand({ state, args, cwd, raw, error }) {
             'signal-resume': () => state.cmdSignalResume(cwd, raw),
             'planned-phase': () => {
                 const a = (0, command_arg_projection_cjs_1.parseNamedArgs)(args, ['phase', 'name', 'plans']);
-                state.cmdStatePlannedPhase(cwd, strArg(a, 'phase'), parsePlans(strArg(a, 'plans')), raw);
+                // #3395: --name was parsed here but never forwarded (the StateModule
+                // signature had no channel for it), so the argument was silently
+                // dropped. It now persists into the Current Position `Phase:` line and
+                // the authoritative current_phase_name, mirroring begin-phase.
+                state.cmdStatePlannedPhase(cwd, strArg(a, 'phase'), strArg(a, 'name'), parsePlans(strArg(a, 'plans')), raw);
             },
             validate: () => state.cmdStateValidate(cwd, raw),
             sync: () => {