@opengsd/gsd-core 1.7.0 → 1.8.0

package/gsd-core/bin/lib/plan-scan.cjs

@@ -12,10 +12,62 @@ const node_path_1 = require("node:path");
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const coreUtils = require("./core-utils.cjs");
 const { countMatchedSummaries } = coreUtils;
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const frontmatterMod = require("./frontmatter.cjs");
+const { extractFrontmatter } = frontmatterMod;
 // Excluded derivative files
 const PLAN_OUTLINE_RE = /-OUTLINE\.md$/i;
 const PLAN_PRE_BOUNCE_RE = /\.pre-bounce\.md$/i;
 const PLAN_REVIEW_RE = /-PLAN-REVIEW\.md$/i;
+// #2349: a plan's frontmatter always sits at byte 0 and closes well before the
+// body, so only a bounded prefix is ever needed to read the `status` marker.
+// Capping the read keeps scanPhasePlans — which loops over every phase directory
+// on hot paths (state sync/validate, roadmap progress) — from slurping a
+// pathologically large committed plan file into memory just to inspect one key.
+const PLAN_FRONTMATTER_READ_CAP = 64 * 1024;
+/**
+ * #2349: a plan whose frontmatter declares `status: superseded` was deliberately
+ * reassigned or never executed — its work moved to a later plan, so it can never
+ * gain a matching `*-SUMMARY.md`. Like a retired phase (#1514, one level up), such
+ * a plan must be excluded from BOTH the plan and summary counts; otherwise a phase
+ * with a deliberately-unexecuted plan reads `completed: false` forever, pinning the
+ * milestone below 100%. Reading only the frontmatter `status` key is the same seam
+ * verify.cts / phase.cts already use for plan metadata; a plan without the marker is
+ * counted exactly as before.
+ *
+ * This is the only path in scanPhasePlans that opens file *contents* (the rest is
+ * filename matching), so it is hardened accordingly: `statSync().isFile()` rejects
+ * anything that is not a regular file — a directory, socket, or a symlink resolving
+ * to a device such as `/dev/zero` (a git-committable DoS vector; cf. #2378/#2383) —
+ * BEFORE any open, and the read is bounded to a fixed prefix. Fail-safe throughout:
+ * a non-regular or unreadable plan is treated as a normal (counted) plan, never
+ * silently dropped.
+ */
+function isPlanSuperseded(planFullPath) {
+    let content;
+    try {
+        const st = (0, node_fs_1.statSync)(planFullPath); // follows symlinks → resolves to the target's real type
+        if (!st.isFile())
+            return false;
+        const length = Math.min(st.size, PLAN_FRONTMATTER_READ_CAP);
+        if (length === 0)
+            return false;
+        const fd = (0, node_fs_1.openSync)(planFullPath, 'r');
+        try {
+            const buf = Buffer.allocUnsafe(length);
+            const bytesRead = (0, node_fs_1.readSync)(fd, buf, 0, length, 0);
+            content = buf.toString('utf8', 0, bytesRead);
+        }
+        finally {
+            (0, node_fs_1.closeSync)(fd);
+        }
+    }
+    catch {
+        return false;
+    }
+    const status = extractFrontmatter(content)['status'];
+    return typeof status === 'string' && status.trim().toLowerCase() === 'superseded';
+}
 function isRootPlanFile(fileName) {
     if (PLAN_OUTLINE_RE.test(fileName))
         return false;
@@ -75,7 +127,16 @@ function scanPhasePlans(phaseDir) {
         }
         catch { /* ignore unreadable nested layout */ }
     }
-    const planFiles = rootPlanFiles.concat(nestedPlanFiles);
+    const allPlanFiles = rootPlanFiles.concat(nestedPlanFiles);
+    // #2349: drop plans explicitly marked `status: superseded` from the plan set
+    // BEFORE counting, so they inflate neither the denominator (planCount) nor,
+    // via countMatchedSummaries below, the numerator (summaryCount). Plans without
+    // the marker are untouched, so behaviour is byte-for-behaviour identical for
+    // every existing phase — only a phase carrying the new marker changes.
+    const supersededPlanFiles = allPlanFiles.filter((f) => isPlanSuperseded((0, node_path_1.join)(phaseDir, f)));
+    const planFiles = supersededPlanFiles.length === 0
+        ? allPlanFiles
+        : allPlanFiles.filter((f) => !supersededPlanFiles.includes(f));
     const summaryFiles = rootSummaryFiles.concat(nestedSummaryFiles);
     const planCount = planFiles.length;
     // Count only summaries that are the PLAN→SUMMARY partner of an existing plan
@@ -87,7 +148,14 @@ function scanPhasePlans(phaseDir) {
     return {
         planCount,
         summaryCount,
-        completed: planCount > 0 && summaryCount >= planCount,
+        // #2349: gate completion on whether the phase had ANY plans on disk
+        // (allPlanFiles), NOT on the post-exclusion planCount. A phase whose plans
+        // were ALL marked superseded has planCount 0, but it is NOT an unplanned
+        // empty phase — there is simply no remaining work, so it must read complete
+        // (0 >= 0) rather than being pinned below 100% forever, which is the very
+        // failure this fix removes. A genuinely empty phase (no plans authored)
+        // still has allPlanFiles.length 0 and stays not-completed, exactly as before.
+        completed: allPlanFiles.length > 0 && summaryCount >= planCount,
         hasNestedPlans,
         planFiles,
         summaryFiles,

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

@@ -511,12 +511,15 @@ function getMilestonePhaseFilter(cwd, versionOverride, phaseIdConvention) {
         return id.split('-').map(seg => seg.replace(/^0+(?=\d)/, '') || '0').join('-');
     }
     const roadmapUsesHyphenedIds = [...normalized].some(n => n.includes('-'));
-    // #2043: milestone-prefixed sub-phase components must be zero-padded (≥2 digits)
-    // — "-\d{2,}" instead of "-0*\d+" — so a single-digit slug word after the phase
+    // #2043: milestone-prefixed sub-phase components must be zero-padded — so a
+    // single-digit slug word after the phase
     // number (e.g. dir "46-6-rs-…") captures "46" and is not silently excluded from
-    // the milestone as a bogus "46-6" id.
+    // the milestone as a bogus "46-6" id. #2232: the continuation width is exactly 2
+    // (PHASE_CONTINUATION_SEGMENT_SOURCE), so a year-leading slug word (dir
+    // "14-2026-photos-…") captures "14" and is not excluded as a bogus "14-2026" id.
+    // Built via new RegExp (no /i — the [A-Za-z] letter class does real case handling).
     const numericRe = roadmapUsesHyphenedIds
-        ? /^0*(\d+(?:-\d{2,})*[A-Za-z]?(?:\.\d+)*)/
+        ? new RegExp(`^0*(\\d+(?:-${phaseIdModule.PHASE_CONTINUATION_SEGMENT_SOURCE})*[A-Za-z]?(?:\\.\\d+)*)`)
         // phase-id-owner: the [A-Za-z] letter class does real case handling here — this regex carries NO /i flag; kept literal, not source-byte-equal to the canonical PHASE_NUMBER_TOKEN_SOURCE.
         : /^0*(\d+[A-Za-z]?(?:\.\d+)*)/;
     function isDirInMilestone(dirName) {

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

@@ -170,9 +170,19 @@ function getRoadmapPhaseWithFallback(cwd, phaseNum) {
     if (/^999(?:\.|$)/.test(stripProjectCodePrefix(phaseNum)))
         return null;
     const roadmapPath = planningPaths(cwd).roadmap;
-    if (!node_fs_1.default.existsSync(roadmapPath))
-        return null;
-    const rawContent = node_fs_1.default.readFileSync(roadmapPath, 'utf-8');
+    // Read directly rather than gating on fs.existsSync: existsSync returns false
+    // on EACCES/EIO too, which would mask an UNREADABLE roadmap as "missing" and
+    // let a blocking gate certify empty scope (#2365 review). Honor the documented
+    // contract — null only when genuinely absent (ENOENT), otherwise throw.
+    let rawContent;
+    try {
+        rawContent = node_fs_1.default.readFileSync(roadmapPath, 'utf-8');
+    }
+    catch (err) {
+        if (err?.code === 'ENOENT')
+            return null;
+        throw err;
+    }
     const milestoneContent = extractCurrentMilestone(rawContent, cwd);
     const fullContent = stripShippedMilestones(rawContent);
     // #2121/#2114: iterate the shared lookup-source list (exact → numeric →

package/gsd-core/bin/lib/runtime-artifact-conversion.cjs

@@ -868,7 +868,13 @@ function convertClaudeCommandToCursorSkill(content, skillName) {
     description = toSingleLine(description);
     const shortDescription = description.length > 180 ? `${description.slice(0, 177)}...` : description;
     const adapter = getCursorSkillAdapterHeader(skillName);
-    return `---\nname: ${yamlIdentifier(skillName)}\ndescription: ${yamlQuote(shortDescription)}\n---\n\n${adapter}\n\n${body.trimStart()}`;
+    // #2341: mark user-invocable:false so the skill is NOT shown in Cursor's '/'
+    // menu (it defaults to true). Cursor also writes a commands/ surface (#785),
+    // and surfacing both duplicated every /gsd-* entry. This mirrors the #789
+    // CodeBuddy de-dup: the commands/ surface is the sole '/' entry point; skills
+    // stay model-invocable background knowledge. (user-invocable:false hides from
+    // '/' while keeping model invocation — distinct from disable-model-invocation.)
+    return `---\nname: ${yamlIdentifier(skillName)}\ndescription: ${yamlQuote(shortDescription)}\nuser-invocable: false\n---\n\n${adapter}\n\n${body.trimStart()}`;
 }
 /**
  * Convert a Claude Code command to a Cursor 1.6 slash command (#785).

package/gsd-core/bin/lib/runtime-artifact-layout.cjs

@@ -227,8 +227,12 @@ function kimiAgentsKind(destSubpath, prefix, configDir) {
  *                       arg so scope-aware converters (antigravity, copilot) can choose
  *                       between global home paths and workspace-relative paths without
  *                       colliding with the `runtime` string at position 3.
+ * @param capabilityRegistry #2322: optional capability registry — captured in the
+ *                       stage() closure so third-party capability skills are bound to
+ *                       their declaring capId at staging time. Absent -> stage() stages
+ *                       nothing third-party (fail closed).
  */
-function skillsKind(destSubpath, prefix, converterName, runtime, configDir, nested = false, scope = 'global') {
+function skillsKind(destSubpath, prefix, converterName, runtime, configDir, nested = false, scope = 'global', capabilityRegistry) {
     return {
         kind: 'skills',
         destSubpath,
@@ -247,7 +251,7 @@ function skillsKind(destSubpath, prefix, converterName, runtime, configDir, nest
                 : [];
             const isGlobal = scope === 'global';
             const wrappedConverter = (content, skillName) => realConverter(content, skillName, runtime, cmdNames, isGlobal);
-            return stageSkillsForRuntimeAsSkills(findInstallSourceRoot(configDir), resolved, wrappedConverter, prefix, nested);
+            return stageSkillsForRuntimeAsSkills(findInstallSourceRoot(configDir), resolved, wrappedConverter, prefix, nested, capabilityRegistry);
         },
     };
 }
@@ -285,7 +289,7 @@ function getRegistry() {
  * Map a single ArtifactKindDescriptor entry to an ArtifactKind using the
  * matching builder function. Mirrors the hand-built calls in the old switch.
  */
-function dispatchKindEntry(entry, runtime, configDir, scope) {
+function dispatchKindEntry(entry, runtime, configDir, scope, capabilityRegistry) {
     const { kind, destSubpath, prefix, nesting, converter } = entry;
     const nested = nesting === 'nested';
     let result;
@@ -304,7 +308,7 @@ function dispatchKindEntry(entry, runtime, configDir, scope) {
             if (converter == null) {
                 throw new TypeError(`resolveRuntimeArtifactLayout: skills entry for '${runtime}' has converter=null (converter is required for skills)`);
             }
-            result = skillsKind(destSubpath, prefix, converter, runtime, configDir, nested, scope);
+            result = skillsKind(destSubpath, prefix, converter, runtime, configDir, nested, scope, capabilityRegistry);
             break;
         case 'kimi-agents':
             result = kimiAgentsKind(destSubpath, prefix, configDir);
@@ -322,11 +326,21 @@ function dispatchKindEntry(entry, runtime, configDir, scope) {
  *
  * ADR-857 phase 5d: driven by the capability-registry artifactLayout descriptor
  * instead of a hardcoded switch statement.
+ *
+ * @param capabilityRegistry #2322: optional — when the caller has a composed
+ *   capability registry in scope (e.g. capability-writer.cts's `capability set`
+ *   path, or a fresh install's registry-aware profile resolution), pass it here
+ *   so the skills kind's stage() closure can materialize installed third-party
+ *   capability skills bound to their declaring capId. Both call paths (surface
+ *   apply AND the installer) must pass their registry here — resolveProfile's
+ *   own `'*'` (full profile) short-circuit never carries a registry, so if it
+ *   is not threaded in at layout-build time a `full`-profile install stages no
+ *   third-party capability skills regardless of registration (#2322 blocker 2).
  */
-function resolveRuntimeArtifactLayout(runtime, configDir, scope = 'global') {
-    return resolveRuntimeArtifactLayoutFromRegistry(getRegistry(), runtime, configDir, scope);
+function resolveRuntimeArtifactLayout(runtime, configDir, scope = 'global', capabilityRegistry) {
+    return resolveRuntimeArtifactLayoutFromRegistry(getRegistry(), runtime, configDir, scope, capabilityRegistry);
 }
-function resolveRuntimeArtifactLayoutFromRegistry(registry, runtime, configDir, scope = 'global') {
+function resolveRuntimeArtifactLayoutFromRegistry(registry, runtime, configDir, scope = 'global', capabilityRegistry) {
     if (typeof configDir !== 'string' || configDir === '') {
         throw new TypeError('configDir must be a non-empty string');
     }
@@ -338,7 +352,7 @@ function resolveRuntimeArtifactLayoutFromRegistry(registry, runtime, configDir,
         throw new TypeError(`Unknown runtime: '${runtime}' — add to runtime-artifact-layout.cjs table`);
     }
     const entries = desc[scope] ?? [];
-    const kinds = entries.map((entry) => dispatchKindEntry(entry, runtime, configDir, scope));
+    const kinds = entries.map((entry) => dispatchKindEntry(entry, runtime, configDir, scope, capabilityRegistry));
     return { runtime, configDir, scope, kinds };
 }
 module.exports = { resolveRuntimeArtifactLayout, resolveRuntimeArtifactLayoutFromRegistry, findInstallSourceRoot };

package/gsd-core/bin/lib/runtime-hooks-surface.cjs

@@ -309,6 +309,22 @@ function normalizeNodePath(execPath, opts) {
         if (existsSync(shim))
             return shim;
     }
+    // volta pins a concrete node image at <VOLTA_HOME>/tools/image/node/<ver>/bin/node
+    // (Windows: <VOLTA_HOME>/tools/image/node/<ver>/node.exe — volta's own layout
+    // puts node.exe at the image root, no bin/). `volta uninstall node@<ver>` prunes
+    // that image, so a baked hook command 404s — the same ephemeral-path failure
+    // #977 fixed for fnm and #1619 for mise. The stable alias is the shim
+    // <VOLTA_HOME>/bin/node, a symlink to volta-shim that always resolves to the
+    // active pin. Derive <VOLTA_HOME> from execPath rather than the env so a custom
+    // VOLTA_HOME and the Windows %LOCALAPPDATA%\Volta default both work (#2185's
+    // reasoning), and only rewrite when the shim exists — otherwise fall back to
+    // the raw execPath unchanged.
+    const voltaMatch = normalizedForMatch.match(/^(.*)\/tools\/image\/node\/[^/]+\/(?:bin\/)?node(\.exe)?$/);
+    if (voltaMatch) {
+        const shim = `${voltaMatch[1]}/bin/node${voltaMatch[2] || ''}`;
+        if (existsSync(shim))
+            return shim;
+    }
     return execPath;
 }
 function resolveNodeRunner(opts) {

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

@@ -52,6 +52,9 @@ const { planningPaths } = planningWorkspace;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const frontmatter = require("./frontmatter.cjs");
 const { extractFrontmatter } = frontmatter;
+// eslint-disable-next-line @typescript-eslint/no-require-imports -- phase-lifecycle.cjs is an export= CommonJS module
+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;
@@ -245,6 +248,8 @@ function detectSignals(cwd, now = Date.now) {
         has_git: git.has_git,
         verify_failed: false,
         stale_activity: false,
+        roadmap_total_phases: null,
+        roadmap_completed_phases: null,
     };
     if (!hasPlanning)
         return empty;
@@ -291,6 +296,24 @@ function detectSignals(cwd, now = Date.now) {
     // STATUS: marker on the current phase's summary/verify artifact.
     const verifyFailed = /\bverify-fail(ed)?|verification-fail|uat-fail\b/i.test(statusRaw || '') ||
         detectVerifyFailed(cwd, currentPhaseRaw);
+    // #2427: derive global phase counts from ROADMAP.md's Progress table. These
+    // are preferred over STATE.md's cached milestone-scoped `total_phases` (which
+    // goes stale when phases are appended after a milestone switch) for the
+    // completion check. Null when ROADMAP.md is absent or has no parseable
+    // Progress table — isComplete falls back to the legacy comparison in that case.
+    let roadmapTotalPhases = null;
+    let roadmapCompletedPhases = null;
+    if (hasRoadmap) {
+        try {
+            const roadmapContent = node_fs_1.default.readFileSync(paths.roadmap, 'utf8');
+            const derived = deriveProgressFromRoadmap(roadmapContent);
+            roadmapTotalPhases = derived.totalPhases;
+            roadmapCompletedPhases = derived.completedPhases;
+        }
+        catch {
+            /* ROADMAP.md unreadable — leave null; isComplete falls back to legacy. */
+        }
+    }
     return {
         current_phase: parseIntOrNull(currentPhaseRaw),
         total_phases: parseIntOrNull(totalPhasesRaw),
@@ -305,14 +328,56 @@ function detectSignals(cwd, now = Date.now) {
         has_git: git.has_git,
         verify_failed: verifyFailed,
         stale_activity: staleActivity,
+        roadmap_total_phases: roadmapTotalPhases,
+        roadmap_completed_phases: roadmapCompletedPhases,
     };
 }
 // ─── Situation classification ─────────────────────────────────────────────────
-/** True when the workflow has fully completed all phases. */
+/**
+ * True when the workflow has fully completed all phases.
+ *
+ * #2427: completion is grounded in ROADMAP.md's Progress table (global,
+ * authoritative, never stale) when available, with a legacy fallback to
+ * STATE.md's cached `total_phases` when the roadmap has no parseable Progress
+ * table (e.g. a fresh project or a non-standard roadmap layout). The status
+ * regex was tightened to require milestone-level completion language
+ * (`milestone complete` / `all phases complete` / `complete(d)`) and no longer
+ * matches per-phase messages like "Phase X shipped — PR #N" that falsely
+ * satisfied the pre-fix alternation (`\bcomplete(d)?|done|shipped\b`).
+ */
 function isComplete(s) {
-    if (s.total_phases === null || s.current_phase === null)
-        return false;
-    return s.current_phase >= s.total_phases && /\bcomplete(d)?|done|shipped\b/i.test(s.status);
+    // Prefer ROADMAP-derived counts (global, authoritative) over STATE.md's
+    // cached milestone-scoped total_phases (stale-prone). Fall back to legacy
+    // when the roadmap has no Progress table.
+    if (s.roadmap_total_phases !== null && s.roadmap_completed_phases !== null) {
+        if (s.roadmap_total_phases === 0)
+            return false;
+        if (s.roadmap_completed_phases < s.roadmap_total_phases)
+            return false;
+    }
+    else {
+        // Legacy path: STATE.md comparison. Still subject to the two-scale bug,
+        // but only fires when ROADMAP.md is absent or has no Progress table.
+        if (s.total_phases === null || s.current_phase === null)
+            return false;
+        if (s.current_phase < s.total_phases)
+            return false;
+    }
+    // Status regex: require milestone-level completion language. The pre-fix
+    // regex matched any "shipped" / "done" substring (per-phase language).
+    // Tightened to match:
+    //   - "milestone complete" (ADR-2207 terminal status — usually written as
+    //     "<version> milestone complete", e.g. "v1.0 milestone complete"; the
+    //     substring match handles both forms)
+    //   - "all phases complete" (ADR-2207 intermediate terminal)
+    //   - "complete" / "completed" (legacy short form — STATE.md milestone
+    //     status is a single value, not a per-phase log)
+    // Intentionally does NOT match "done" alone even though normalizeStateStatus
+    // (state-document.cts) treats "done" as "completed" — in the milestone
+    // status field, "done" is per-phase noise (e.g. "Phase X done"), not a
+    // milestone-completion signal. Mirrors workstream-inventory-builder.cts's
+    // terminal pattern \bmilestone\s+complete\b.
+    return /\b(milestone\s+complete|all\s+phases\s+complete|complete(d)?)\b/i.test(s.status);
 }
 /** Idle-stranded: clean tree, committed work not shipped, optionally stale. */
 function isIdleStranded(s) {

package/gsd-core/bin/lib/state-document.cjs

@@ -153,11 +153,14 @@ function shouldPreserveExistingProgress(existingProgress, derivedProgress) {
         return false;
     const existing = existingProgress;
     const derived = derivedProgress;
-    // total_phases is intentionally excluded from the ratchet: it must always
-    // take the freshly derived value so it can correct downward (#1446).
-    // Only completed_phases, total_plans, and completed_plans keep ratchet behaviour.
+    // total_phases (#1446) and total_plans (#2440) are intentionally excluded
+    // from the ratchet: both must always take the freshly derived value so they
+    // can correct in BOTH directions. total_plans legitimately moves up (a new
+    // phase adds plans) and down (milestone reorganization removes phases).
+    // Ratcheting it freezes stale values. Only completed_phases and
+    // completed_plans keep ratchet behaviour — they are monotonic (once a
+    // phase/plan is complete, it stays complete).
     return (existingProgressExceedsDerived(existing, derived, 'completed_phases') ||
-        existingProgressExceedsDerived(existing, derived, 'total_plans') ||
         existingProgressExceedsDerived(existing, derived, 'completed_plans'));
 }
 function normalizeProgressNumbers(progress) {

package/gsd-core/bin/lib/state-transition.cjs

@@ -100,7 +100,28 @@ function applyStatePreservation(input) {
         !resync &&
         preFm &&
         preFm['progress']) {
-        postFm['progress'] = preFm['progress'];
+        // #2440: when the caller opts in (deriveProgressKeys), total_plans and
+        // total_phases always take the derived (post-sync) value even under !resync.
+        // This is used by cmdStatePlannedPhase where total_plans must correct upward
+        // after plans are added. For body-only writes (state.update/patch without
+        // the flag), the wholesale restore preserves everything as before — the
+        // #3242 Bug A protection stays fully in force.
+        if (input.deriveProgressKeys && postFm['progress']) {
+            const curated = preFm['progress'];
+            const derived = (postFm['progress'] ?? {});
+            const merged = { ...derived };
+            if (curated) {
+                for (const [key, value] of Object.entries(curated)) {
+                    if (key !== 'total_plans' && key !== 'total_phases') {
+                        merged[key] = value;
+                    }
+                }
+            }
+            postFm['progress'] = merged;
+        }
+        else {
+            postFm['progress'] = preFm['progress'];
+        }
         mutated = true;
     }
     // status — #1230 body-delta heuristic. Table: preserve-when-unchanged.

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

@@ -170,6 +170,12 @@ function cmdStateLoad(cwd, raw) {
         state_exists: stateExists,
         roadmap_exists: roadmapExists,
         config_exists: configExists,
+        // #2376: absolute (anchored on cwd), not orchestrator-cwd-relative — a
+        // spawned subagent's own cwd may differ from the orchestrator's.
+        // debug.md has no init.* call of its own; it reads this field from
+        // `state load` to build debug_file_path for its gsd-debug-session-manager
+        // spawns instead of hardcoding '.planning/debug/{slug}.md'.
+        debug_dir: (0, shell_command_projection_cjs_1.toPosixPath)(node_path_1.default.join(planDir, 'debug')),
     };
     // For --raw, output a condensed key=value format
     if (raw) {
@@ -1003,6 +1009,15 @@ function cmdStateRecordSession(cwd, options, raw) {
             // duplicate section alongside an existing one.
             const existingCanonicalSession = /^## Session[ \t]*$/im.test(content);
             const existingSessionContinuity = /^## Session Continuity[ \t]*$/im.test(content);
+            // Track whether the chosen branch's rewrite actually matched. The detector
+            // regexes (existingCanonicalSession/existingSessionContinuity) are CRLF-
+            // tolerant ($ under /m treats \r as a line terminator); the writer regexes
+            // below must be too. If a writer regex silently fails to match (line-ending
+            // mismatch, unexpected heading shape, ...), do NOT report success — the
+            // caller would believe fields were persisted that were silently dropped
+            // (#2450). The append branch always sets rewriteMatched=true (it always
+            // mutates content).
+            let rewriteMatched = false;
             if (existingCanonicalSession) {
                 // Normalize in place: replace the ENTIRE BODY of the existing ## Session
                 // section (heading + all content up to the next ## heading or EOF) with
@@ -1010,7 +1025,13 @@ function cmdStateRecordSession(cwd, options, raw) {
                 // `(?!^## )[\s\S]` consumes every line that doesn't start with "## ",
                 // which correctly stops at the next section boundary without consuming it.
                 // A trailing blank line is added so the next ## heading keeps its spacing.
-                content = content.replace(/^(## Session[ \t]*\n(?:(?!^## )[\s\S])*)/m, [
+                //
+                // CRLF-tolerant (`\r?\n` after `[ \t]*`): the prior literal `\n` could not
+                // match a CRLF STATE.md (`---\r\n`), silently no-op'ing the replace while
+                // updated.push(...) reported success — #2450. The detector regex on the
+                // line above (`/^## Session[ \t]*$/im`) was already CRLF-tolerant, so the
+                // asymmetry armed the bug.
+                const canonicalReplacement = [
                     '## Session',
                     '',
                     `**Last session:** ${now}`,
@@ -1018,7 +1039,11 @@ function cmdStateRecordSession(cwd, options, raw) {
                     `**Resume file:** ${resumeValue}`,
                     '',
                     '',
-                ].join('\n'));
+                ].join('\n');
+                content = content.replace(/^(## Session[ \t]*\r?\n(?:(?!^## )[\s\S])*)/m, () => {
+                    rewriteMatched = true;
+                    return canonicalReplacement;
+                });
             }
             else if (existingSessionContinuity) {
                 // #1101: a `## Session Continuity` section already exists (bootstrap
@@ -1029,6 +1054,8 @@ function cmdStateRecordSession(cwd, options, raw) {
                 // (e.g. prose like "Next recommended action"). Fields already updated in
                 // place above (needs* false) are not re-inserted. A function replacement
                 // is used so `$`-bearing caller values are inserted literally (#3454).
+                //
+                // CRLF-tolerant (`\r?\n`): same #2450 fix as the canonical branch above.
                 const linesToInsert = [];
                 if (needsLastSession)
                     linesToInsert.push(`**Last session:** ${now}`);
@@ -1040,8 +1067,18 @@ function cmdStateRecordSession(cwd, options, raw) {
                     // Case-insensitive to match the `existingSessionContinuity` detection
                     // above (#1101 review F3) — otherwise a lowercase heading would detect
                     // but no-op the insert while still reporting the fields as updated.
-                    content = content.replace(/^(## Session Continuity[ \t]*\n)/im, (_m, heading) => heading + linesToInsert.join('\n') + '\n');
+                    content = content.replace(/^(## Session Continuity[ \t]*\r?\n)/im, (_m, heading) => {
+                        rewriteMatched = true;
+                        return heading + linesToInsert.join('\n') + '\n';
+                    });
                 }
+                // No `else` branch: if linesToInsert.length === 0 the outer guard at
+                // :1144 (callerSuppliedValues && (needsStoppedAt || needsResumeFile
+                // || needsLastSession)) could not have fired, so this whole block is
+                // unreachable. Leaving `rewriteMatched = false` here is the fail-loud
+                // posture — a future change to the outer guard or needs* computation
+                // that makes this branch reachable will surface as a missing
+                // updated[] entry (silent recorded:false) rather than re-arming #2450.
             }
             else {
                 // No session heading exists at all — append a new canonical section.
@@ -1055,14 +1092,30 @@ function cmdStateRecordSession(cwd, options, raw) {
                     '',
                 ].join('\n');
                 content = content.trimEnd() + '\n' + scaffold;
+                rewriteMatched = true;
+            }
+            // #2450 defensive invariant: only report sessionCreated/updated when the
+            // chosen branch's rewrite actually mutated content. Unreachable when the
+            // writer regexes above stay in sync with the CRLF-tolerant detector —
+            // but unreachable-defensive is the right posture for a silent-success
+            // gate. A no-op replace here means a future line-ending or shape drift
+            // between detector and writer; fail to record rather than claim success.
+            //
+            // Scope limitation (not a regression of this fix): the gate covers only
+            // the section-rewrite block. The earlier in-place stateReplaceField
+            // successes at :1081/:1083/:1089/:1101/:1108/:1114 push to `updated`
+            // unconditionally — those represent fields that DID land on disk via
+            // same-line replace (CRLF-agnostic seam), so unconditional push is
+            // correct. The class-defect防御 here is for the INSERT path only.
+            if (rewriteMatched) {
+                sessionCreated = true;
+                if (needsLastSession)
+                    updated.push('Last session');
+                if (needsStoppedAt)
+                    updated.push('Stopped At');
+                if (needsResumeFile)
+                    updated.push('Resume File');
             }
-            sessionCreated = true;
-            if (needsLastSession)
-                updated.push('Last session');
-            if (needsStoppedAt)
-                updated.push('Stopped At');
-            if (needsResumeFile)
-                updated.push('Resume File');
         }
         return content;
     }, cwd);
@@ -1970,6 +2023,7 @@ function readModifyWriteStateMd(statePath, transformFn, cwd, options, clock) {
         const postFm = extractFrontmatter(synced);
         const preservation = applyStatePreservation({
             preFm, postFm, preFmSnapshot, resync,
+            deriveProgressKeys: options?.deriveProgressKeys === true,
             preBodyStatus, postBodyStatus,
             preBodyStoppedAt, postBodyStoppedAt,
             preBodyPhaseSource, postBodyPhaseSource,
@@ -2313,7 +2367,7 @@ function cmdStatePlannedPhase(cwd, phaseNumber, planCount, raw) {
         const result = transitionCore(content, intent, deps);
         updated = result.updated;
         return result.content;
-    }, cwd, { resync: false });
+    }, cwd, { resync: false, deriveProgressKeys: true });
     output({ updated, phase: phaseNumber, plan_count: planCount }, raw, updated.length > 0 ? 'true' : 'false');
 }
 /**