@opengsd/gsd-core 1.13.0 → 1.14.0

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

@@ -25,7 +25,7 @@ const coreUtils = require("./core-utils.cjs");
 const { normalizeLineEndings } = coreUtils;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const planningWorkspace = require("./planning-workspace.cjs");
-const { planningDir, quickDirFrom } = planningWorkspace;
+const { planningDir, quickDirFrom, todosDir } = planningWorkspace;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const frontmatter = require("./frontmatter.cjs");
 const { extractFrontmatter, spliceFrontmatter } = frontmatter;
@@ -277,7 +277,7 @@ function scanDebugSessions(planDir) {
         const filePath = node_path_1.default.join(debugDir, entry.name);
         let safeFilePath;
         try {
-            safeFilePath = (0, security_cjs_1.requireSafePath)(filePath, planDir, 'debug session file', { allowAbsolute: true });
+            safeFilePath = (0, security_cjs_1.requireSafePath)(filePath, planDir, 'debug session file', security_cjs_1.PathAcceptance.AbsoluteInsideRoot);
         }
         catch {
             continue;
@@ -387,7 +387,7 @@ function scanQuickTasks(planDir) {
         const taskDir = node_path_1.default.join(quickDir, dirName);
         let safeTaskDir;
         try {
-            safeTaskDir = (0, security_cjs_1.requireSafePath)(taskDir, planDir, 'quick task dir', { allowAbsolute: true });
+            safeTaskDir = (0, security_cjs_1.requireSafePath)(taskDir, planDir, 'quick task dir', security_cjs_1.PathAcceptance.AbsoluteInsideRoot);
         }
         catch {
             continue;
@@ -399,7 +399,7 @@ function scanQuickTasks(planDir) {
         if (summaryPath && node_fs_1.default.existsSync(summaryPath)) {
             let safeSum;
             try {
-                safeSum = (0, security_cjs_1.requireSafePath)(summaryPath, planDir, 'quick task summary', { allowAbsolute: true });
+                safeSum = (0, security_cjs_1.requireSafePath)(summaryPath, planDir, 'quick task summary', security_cjs_1.PathAcceptance.AbsoluteInsideRoot);
             }
             catch {
                 continue;
@@ -475,7 +475,7 @@ function scanThreads(planDir) {
         const filePath = node_path_1.default.join(threadsDir, entry.name);
         let safeFilePath;
         try {
-            safeFilePath = (0, security_cjs_1.requireSafePath)(filePath, planDir, 'thread file', { allowAbsolute: true });
+            safeFilePath = (0, security_cjs_1.requireSafePath)(filePath, planDir, 'thread file', security_cjs_1.PathAcceptance.AbsoluteInsideRoot);
         }
         catch {
             continue;
@@ -522,9 +522,16 @@ function scanThreads(planDir) {
  * Scan .planning/todos/pending/ for pending todos.
  * Returns array of { filename, priority, area, summary }.
  * Display limited to first 5 + count of remainder.
+ *
+ * #4256: takes the ROOT-scoped todos base (`todosDir(cwd)`), NOT the
+ * workstream-scoped planning dir the other scans use — todos are shared
+ * project state (the migrateToWorkstreams contract keeps them at
+ * .planning/todos/), so the close gate must read the root or it clears
+ * vacuously under a workstream. The requireSafePath boundary below moves
+ * with the base.
  */
-function scanTodos(planDir) {
-    const pendingDir = node_path_1.default.join(planDir, 'todos', 'pending');
+function scanTodos(todosBase) {
+    const pendingDir = node_path_1.default.join(todosBase, 'pending');
     if (!node_fs_1.default.existsSync(pendingDir))
         return { items: [], acknowledged: 0 };
     let files;
@@ -550,7 +557,7 @@ function scanTodos(planDir) {
         const filePath = node_path_1.default.join(pendingDir, entry.name);
         let safeFilePath;
         try {
-            safeFilePath = (0, security_cjs_1.requireSafePath)(filePath, planDir, 'todo file', { allowAbsolute: true });
+            safeFilePath = (0, security_cjs_1.requireSafePath)(filePath, todosBase, 'todo file', security_cjs_1.PathAcceptance.AbsoluteInsideRoot);
         }
         catch {
             continue;
@@ -622,7 +629,7 @@ function scanSeeds(planDir) {
         const filePath = node_path_1.default.join(seedsDir, entry.name);
         let safeFilePath;
         try {
-            safeFilePath = (0, security_cjs_1.requireSafePath)(filePath, planDir, 'seed file', { allowAbsolute: true });
+            safeFilePath = (0, security_cjs_1.requireSafePath)(filePath, planDir, 'seed file', security_cjs_1.PathAcceptance.AbsoluteInsideRoot);
         }
         catch {
             continue;
@@ -785,7 +792,7 @@ function scanUatGaps(planDir, cwd) {
             const filePath = node_path_1.default.join(target.fullPath, file);
             let safeFilePath;
             try {
-                safeFilePath = (0, security_cjs_1.requireSafePath)(filePath, planDir, 'UAT file', { allowAbsolute: true });
+                safeFilePath = (0, security_cjs_1.requireSafePath)(filePath, planDir, 'UAT file', security_cjs_1.PathAcceptance.AbsoluteInsideRoot);
             }
             catch {
                 continue;
@@ -858,7 +865,7 @@ function scanVerificationGaps(planDir, cwd) {
             const filePath = node_path_1.default.join(target.fullPath, file);
             let safeFilePath;
             try {
-                safeFilePath = (0, security_cjs_1.requireSafePath)(filePath, planDir, 'VERIFICATION file', { allowAbsolute: true });
+                safeFilePath = (0, security_cjs_1.requireSafePath)(filePath, planDir, 'VERIFICATION file', security_cjs_1.PathAcceptance.AbsoluteInsideRoot);
             }
             catch {
                 continue;
@@ -920,7 +927,7 @@ function scanContextQuestions(planDir, cwd) {
             const filePath = node_path_1.default.join(target.fullPath, file);
             let safeFilePath;
             try {
-                safeFilePath = (0, security_cjs_1.requireSafePath)(filePath, planDir, 'CONTEXT file', { allowAbsolute: true });
+                safeFilePath = (0, security_cjs_1.requireSafePath)(filePath, planDir, 'CONTEXT file', security_cjs_1.PathAcceptance.AbsoluteInsideRoot);
             }
             catch {
                 continue;
@@ -1008,7 +1015,7 @@ function scanDeferredItems(planDir, cwd) {
             continue;
         let safeFilePath;
         try {
-            safeFilePath = (0, security_cjs_1.requireSafePath)(filePath, planDir, 'deferred items file', { allowAbsolute: true });
+            safeFilePath = (0, security_cjs_1.requireSafePath)(filePath, planDir, 'deferred items file', security_cjs_1.PathAcceptance.AbsoluteInsideRoot);
         }
         catch {
             continue;
@@ -1076,8 +1083,13 @@ function auditOpenArtifacts(cwd) {
         }
     })();
     const todos = (() => {
+        // #4256: the ONE root-scoped category — todos are shared project state,
+        // so the close gate reads todosDir(cwd) (the root), not the workstream-
+        // scoped planDir every other scan below receives. Reading planDir here
+        // made audit-open print "All artifact types clear. Safe to proceed."
+        // with pending todos on disk under a workstream.
         try {
-            return scanTodos(planDir);
+            return scanTodos(todosDir(cwd));
         }
         catch {
             return { items: [{ scan_error: true, filename: '', priority: '', area: '', summary: '' }], acknowledged: 0 };
@@ -1421,7 +1433,7 @@ function cmdAuditAcknowledge(cwd, args, raw) {
             ioError(`no phase directory found for phase "${phase}"${archivedMilestone ? ` (archived-milestone "${archivedMilestone}")` : ''}`);
         }
         const filePath = node_path_1.default.join(targetDir, file);
-        const safeFilePath = (0, security_cjs_1.requireSafePath)(filePath, planDir, 'audit acknowledge target', { allowAbsolute: true });
+        const safeFilePath = (0, security_cjs_1.requireSafePath)(filePath, planDir, 'audit acknowledge target', security_cjs_1.PathAcceptance.AbsoluteInsideRoot);
         if (!node_fs_1.default.existsSync(safeFilePath))
             ioError(`file not found: ${file}`);
         if (category === 'deferred_items') {
@@ -1503,7 +1515,7 @@ function cmdAuditAcknowledge(cwd, args, raw) {
     if (category === 'debug_sessions') {
         if (!slug)
             ioError('--slug is required for --category debug_sessions');
-        safeFilePath = (0, security_cjs_1.requireSafePath)(node_path_1.default.join(planDir, 'debug', `${slug}.md`), planDir, 'audit acknowledge target', { allowAbsolute: true });
+        safeFilePath = (0, security_cjs_1.requireSafePath)(node_path_1.default.join(planDir, 'debug', `${slug}.md`), planDir, 'audit acknowledge target', security_cjs_1.PathAcceptance.AbsoluteInsideRoot);
         if (!node_fs_1.default.existsSync(safeFilePath))
             ioError(`file not found: debug/${slug}.md`);
         const content = node_fs_1.default.readFileSync(safeFilePath, 'utf-8');
@@ -1512,7 +1524,7 @@ function cmdAuditAcknowledge(cwd, args, raw) {
     else if (category === 'threads') {
         if (!slug)
             ioError('--slug is required for --category threads');
-        safeFilePath = (0, security_cjs_1.requireSafePath)(node_path_1.default.join(planDir, 'threads', `${slug}.md`), planDir, 'audit acknowledge target', { allowAbsolute: true });
+        safeFilePath = (0, security_cjs_1.requireSafePath)(node_path_1.default.join(planDir, 'threads', `${slug}.md`), planDir, 'audit acknowledge target', security_cjs_1.PathAcceptance.AbsoluteInsideRoot);
         if (!node_fs_1.default.existsSync(safeFilePath))
             ioError(`file not found: threads/${slug}.md`);
         const content = node_fs_1.default.readFileSync(safeFilePath, 'utf-8');
@@ -1521,7 +1533,7 @@ function cmdAuditAcknowledge(cwd, args, raw) {
     else if (category === 'seeds') {
         if (!seedId)
             ioError('--seed-id is required for --category seeds');
-        safeFilePath = (0, security_cjs_1.requireSafePath)(node_path_1.default.join(planDir, 'seeds', `${seedId}.md`), planDir, 'audit acknowledge target', { allowAbsolute: true });
+        safeFilePath = (0, security_cjs_1.requireSafePath)(node_path_1.default.join(planDir, 'seeds', `${seedId}.md`), planDir, 'audit acknowledge target', security_cjs_1.PathAcceptance.AbsoluteInsideRoot);
         if (!node_fs_1.default.existsSync(safeFilePath))
             ioError(`file not found: seeds/${seedId}.md`);
         const content = node_fs_1.default.readFileSync(safeFilePath, 'utf-8');
@@ -1530,7 +1542,12 @@ function cmdAuditAcknowledge(cwd, args, raw) {
     else if (category === 'todos') {
         if (!filename)
             ioError('--filename is required for --category todos');
-        safeFilePath = (0, security_cjs_1.requireSafePath)(node_path_1.default.join(planDir, 'todos', 'pending', filename), planDir, 'audit acknowledge target', { allowAbsolute: true });
+        // #4256: todos are root-scoped shared state — derive the todos base and
+        // pass it as BOTH the path base and the requireSafePath boundary. The
+        // old workstream-scoped planDir boundary would refuse a root todos file
+        // outright, and even a path fix alone would have thrown here.
+        const rootTodos = todosDir(cwd);
+        safeFilePath = (0, security_cjs_1.requireSafePath)(node_path_1.default.join(rootTodos, 'pending', filename), rootTodos, 'audit acknowledge target', security_cjs_1.PathAcceptance.AbsoluteInsideRoot);
         if (!node_fs_1.default.existsSync(safeFilePath))
             ioError(`file not found: todos/pending/${filename}`);
         currentValue = ''; // presence-only — see scanTodos
@@ -1538,14 +1555,14 @@ function cmdAuditAcknowledge(cwd, args, raw) {
     else if (category === 'quick_tasks') {
         if (!quickDir)
             ioError('--dir is required for --category quick_tasks');
-        const taskDir = (0, security_cjs_1.requireSafePath)(node_path_1.default.join(planDir, 'quick', quickDir), planDir, 'audit acknowledge target dir', { allowAbsolute: true });
+        const taskDir = (0, security_cjs_1.requireSafePath)(node_path_1.default.join(planDir, 'quick', quickDir), planDir, 'audit acknowledge target dir', security_cjs_1.PathAcceptance.AbsoluteInsideRoot);
         if (!node_fs_1.default.existsSync(taskDir))
             ioError(`directory not found: quick/${quickDir}`);
         // Shared with scanQuickTasks (#3458 follow-up) so the reader and this
         // writer can never disagree about which file is the task's record.
         const resolvedSummaryPath = resolveQuickTaskSummaryFile(taskDir, quickDir);
         if (resolvedSummaryPath) {
-            safeFilePath = (0, security_cjs_1.requireSafePath)(resolvedSummaryPath, planDir, 'audit acknowledge target', { allowAbsolute: true });
+            safeFilePath = (0, security_cjs_1.requireSafePath)(resolvedSummaryPath, planDir, 'audit acknowledge target', security_cjs_1.PathAcceptance.AbsoluteInsideRoot);
             const content = node_fs_1.default.readFileSync(safeFilePath, 'utf-8');
             currentValue = (extractFrontmatter(content, safeFilePath).status || 'unknown').toLowerCase();
         }
@@ -1556,7 +1573,7 @@ function cmdAuditAcknowledge(cwd, args, raw) {
             // acknowledgment's own snapshot of "no summary exists yet", which
             // self-invalidates the moment a real SUMMARY.md is written (the
             // scanner then reads THAT file's own status instead).
-            safeFilePath = (0, security_cjs_1.requireSafePath)(node_path_1.default.join(taskDir, `${quickDir}-SUMMARY.md`), planDir, 'audit acknowledge target', { allowAbsolute: true });
+            safeFilePath = (0, security_cjs_1.requireSafePath)(node_path_1.default.join(taskDir, `${quickDir}-SUMMARY.md`), planDir, 'audit acknowledge target', security_cjs_1.PathAcceptance.AbsoluteInsideRoot);
             currentValue = 'missing';
             createIfMissing = true;
             fmForCreate = { status: 'missing' };

package/gsd-core/bin/lib/broken-windows.cjs

@@ -7,7 +7,10 @@
  * When `workflow.windows_enforce` is true, `/gsd-ship` blocks while any entry is
  * `open`; an entry can be `waived` only with a recorded reason or `fixed`.
  *
- * LEAF MODULE — imports ONLY: node:fs, node:path. No other src/ imports.
+ * LEAF MODULE — imports node:fs + node:path, plus two compiled sibling lib
+ * modules require()d at runtime: workstream-inventory.cjs (the #4487
+ * milestone stamp) and capability-lock.cjs (the #3780 cross-process ledger
+ * lock). No other src/ imports.
  *
  * Storage format (`.planning/WINDOWS.md`):
  *   ---
@@ -58,12 +61,15 @@ exports.parseLedger = parseLedger;
 exports.renderLedger = renderLedger;
 exports.renderTable = renderTable;
 exports.extractTableRegion = extractTableRegion;
+exports.withLedgerLock = withLedgerLock;
 exports.cmdWindowsStatus = cmdWindowsStatus;
 exports.cmdWindowsAppend = cmdWindowsAppend;
 exports.cmdWindowsWaive = cmdWindowsWaive;
 exports.cmdWindowsMarkFixed = cmdWindowsMarkFixed;
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const workstreamInventory = require("./workstream-inventory.cjs");
 // ─── Constants ─────────────────────────────────────────────────────────────
 exports.LEDGER_FILE_NAME = 'WINDOWS.md';
 exports.SCHEMA_VERSION = 1;
@@ -90,6 +96,11 @@ exports.REASON = Object.freeze({
     // sole source of truth) at the pre-write seam — refuse rather than silently
     // reconcile by overwriting the operator's hand-edit or dropping a row.
     WINDOWS_LEDGER_TABLE_DRIFT: 'windows_ledger_table_drift',
+    // #3780: the read-compute-write cycle is serialized on a cross-process
+    // ledger lock; this fires only when another writer held the lock past the
+    // whole bounded retry budget — a typed, actionable refusal instead of a
+    // silently-lost mutation reported as success.
+    WINDOWS_LEDGER_LOCK: 'windows_ledger_lock',
 });
 /** Allowed window kinds. Aligned with the issue's enumerated sources. */
 exports.KINDS = Object.freeze([
@@ -219,12 +230,14 @@ function nextId(entries) {
  * Append a window to the ledger. Assigns the next dense id (max+1), sets
  * status=open, timestamps via opts.now.
  *
- * Concurrency (issue #1950 review L2): NOT safe for concurrent writers. Two
- * parallel `gsd_run windows append` invocations both read the same snapshot,
- * both compute the same nextId, both write — the second atomic rename wins
- * and the first append (and the entry it added) is silently lost. This is
- * acceptable in the current single-executor-per-phase model; document if the
- * executor ever gains parallel wave-level append.
+ * Concurrency (issue #1950 review L2, superseded by #3780): as a PURE
+ * function this operates on whatever ledger snapshot it is passed and cannot
+ * see concurrent writers — serialization is the CALLER's job. The I/O entry
+ * points below (cmdWindowsAppend/Waive/MarkFixed) now discharge that duty by
+ * holding the cross-process ledger lock across their whole
+ * read-compute-write cycle, so the previously-documented loss (two parallel
+ * writers, second rename wins, first entry silently gone) can no longer
+ * occur through the CLI.
  */
 function appendWindow(ledger, input, opts = { now: new Date().toISOString() }) {
     validateKind(input.kind);
@@ -243,6 +256,7 @@ function appendWindow(ledger, input, opts = { now: new Date().toISOString() }) {
         reason: '',
         recorded_at: opts.now,
         resolved_at: null,
+        milestone: input.milestone ?? null,
     };
     const entries = [...ledger.entries, entry];
     const result = recomputeCounts({ ...ledger, entries, last_updated: opts.now });
@@ -475,6 +489,19 @@ function validateEntryShape(e, i) {
         reason: o.reason,
         recorded_at: recordedStr,
         resolved_at: resolvedStr,
+        // #4487: NOT in `required` above -- an entry recorded before this field
+        // existed has no `milestone` key at all, and that must parse cleanly.
+        // Preserve the absence itself -- by not materializing the property at
+        // all, via the conditional spread below, rather than assigning it
+        // `milestone: undefined` (an object literal property set to `undefined`
+        // is still an OWN property; `'milestone' in entry` reads true either
+        // way) -- so a genuinely absent key stays absent both to `in` and to
+        // JSON.stringify on re-render. Collapsing absence to an explicit null
+        // instead would stamp every legacy entry with permanent
+        // `"milestone": null` noise the moment the ledger is next touched. A
+        // genuinely-recorded-but-unresolvable milestone (set by appendWindow)
+        // is still an explicit null and round-trips as one.
+        ...('milestone' in o ? { milestone: typeof o.milestone === 'string' ? o.milestone : null } : {}),
     };
 }
 function parseLedger(raw) {
@@ -685,6 +712,78 @@ function diffTableRowIds(expectedTable, actualTable) {
 function ledgerPath(cwd) {
     return node_path_1.default.join(cwd, '.planning', exports.LEDGER_FILE_NAME);
 }
+/**
+ * The SHARED hardened cross-process lock primitive (single source of truth
+ * for capability-lifecycle + capability-consent, extracted so locks cannot
+ * diverge). Required LAZILY: capability-lock captures the process start time
+ * at module load — a `ps` subprocess on macOS, PowerShell on win32 — and
+ * this module is loaded by lock-free readers (`windows status`, the
+ * /gsd-ship gate) that must not pay that per-invocation cost (#3780
+ * review). `require` is cached, so writers pay it once per process.
+ */
+let _lockMod = null;
+function ledgerLock() {
+    if (_lockMod === null) {
+        /* eslint-disable @typescript-eslint/no-require-imports */
+        _lockMod = require('./capability-lock.cjs');
+        /* eslint-enable @typescript-eslint/no-require-imports */
+    }
+    return _lockMod;
+}
+/**
+ * Budget mirrors capability-consent's CONSENT_LOCK_MAX_ATTEMPTS: two
+ * genuinely-racing writers must SERIALIZE, not fail. The ledger's critical
+ * section is sub-millisecond and the primitive backs off ~25-50ms per
+ * attempt, so 50 attempts is orders of magnitude beyond any real contention
+ * while keeping the worst case (a holder that never releases until the
+ * primitive's own liveness/deadman protocol reclaims it) bounded at ~2s
+ * before the typed refusal below.
+ */
+const LEDGER_LOCK_MAX_ATTEMPTS = 50;
+function ledgerLockPath(cwd) {
+    return node_path_1.default.join(cwd, '.planning', '.WINDOWS.lock');
+}
+function acquireLedgerLock(cwd) {
+    return ledgerLock().acquireLock(ledgerLockPath(cwd), {
+        maxAttempts: LEDGER_LOCK_MAX_ATTEMPTS,
+        // A contended fresh/live holder is WAITED FOR (back off + retry), not
+        // failed-fast — racing wave-level executors serialize (issue #3780).
+        waitForFresh: true,
+    });
+}
+function releaseLedgerLock(handle) {
+    ledgerLock().releaseLock(handle);
+}
+/**
+ * Run `fn` (a full ledger read-compute-write cycle) while holding the
+ * cross-process ledger lock. Throws a typed WindowsError — never falls back
+ * to an unlocked mutation — when the lock cannot be acquired within the
+ * budget, mirroring capability-consent finding 3: a locked store must refuse
+ * the write rather than silently race for it. Readers (cmdWindowsStatus, the
+ * ship gate) deliberately do NOT take this lock: the atomic rename already
+ * gives them a whole-file snapshot.
+ *
+ * EXPORTED (#3780) because `withLedgerLock` is the ONE serialization seam
+ * for WINDOWS.md: every writer of the ledger — the cmd* entry points here
+ * and any sibling module with its own read-compute-write cycle on the same
+ * file (refactor-trigger-command-router's strict-window record/resolve) —
+ * must hold this lock, or the lost-update race #3780 fixed survives on that
+ * path.
+ */
+function withLedgerLock(cwd, fn) {
+    const handle = acquireLedgerLock(cwd);
+    if (!handle) {
+        throw new WindowsError(exports.REASON.WINDOWS_LEDGER_LOCK, `Another writer holds the ledger lock at ${ledgerLockPath(cwd)}; WINDOWS.md ` +
+            'mutations are serialized per project. Re-run the command once the other ' +
+            'writer finishes — the lock is reclaimed automatically if its holder died.');
+    }
+    try {
+        return fn();
+    }
+    finally {
+        releaseLedgerLock(handle);
+    }
+}
 function readLedgerOrNull(cwd) {
     const p = ledgerPath(cwd);
     let raw;
@@ -910,24 +1009,36 @@ function cmdWindowsAppend(cwd, args, opts = {}) {
         flags: ['--kind', '--phase', '--file', '--line', '--description'],
         required: ['--kind', '--phase', '--description'],
     });
-    let ledger;
-    try {
-        ledger = readLedgerOrNull(cwd) ?? emptyLedger(nowIso());
-    }
-    catch (e) {
-        if (e instanceof WindowsError)
-            throw e;
-        throw new WindowsError(exports.REASON.WINDOWS_LEDGER_MALFORMED, e.message);
-    }
-    const result = appendWindow(ledger, {
-        kind: parsed.values['--kind'],
-        phase: parsed.values['--phase'] ?? '',
-        file: parsed.values['--file'] ?? '',
-        line: parsed.values['--line'] == null ? null : Number(parsed.values['--line']),
-        description: parsed.values['--description'] ?? '',
-    }, { now: nowIso() });
-    writeLedgerAtomic(cwd, result.ledger);
-    emit({ ok: true, ledger: result.ledger, entry: result.entry });
+    // #3780: the whole read-compute-write cycle — snapshot, milestone stamp,
+    // id allocation, atomic rename — holds the ledger lock, so two parallel
+    // invocations can no longer compute the same nextId from the same snapshot
+    // and silently lose the first append to the second rename.
+    withLedgerLock(cwd, () => {
+        let ledger;
+        try {
+            ledger = readLedgerOrNull(cwd) ?? emptyLedger(nowIso());
+        }
+        catch (e) {
+            if (e instanceof WindowsError)
+                throw e;
+            throw new WindowsError(exports.REASON.WINDOWS_LEDGER_MALFORMED, e.message);
+        }
+        // #4487: stamp the workstream's resolved milestone at record time -- the
+        // same STATE.md-first, ROADMAP-fallback resolution workstream-inventory.cts
+        // already uses. Best-effort: an unreadable/missing STATE.md or ROADMAP.md
+        // resolves to null, same as an entry recorded before this field existed.
+        const milestone = workstreamInventory.readCurrentMilestoneVersion(node_path_1.default.join(cwd, '.planning', 'STATE.md'), node_path_1.default.join(cwd, '.planning', 'ROADMAP.md'));
+        const result = appendWindow(ledger, {
+            kind: parsed.values['--kind'],
+            phase: parsed.values['--phase'] ?? '',
+            file: parsed.values['--file'] ?? '',
+            line: parsed.values['--line'] == null ? null : Number(parsed.values['--line']),
+            description: parsed.values['--description'] ?? '',
+            milestone,
+        }, { now: nowIso() });
+        writeLedgerAtomic(cwd, result.ledger);
+        emit({ ok: true, ledger: result.ledger, entry: result.entry });
+    });
 }
 /** `gsd-tools windows waive <id> "<reason>"`. */
 function cmdWindowsWaive(cwd, args, opts = {}) {
@@ -936,36 +1047,44 @@ function cmdWindowsWaive(cwd, args, opts = {}) {
     const idStr = positionals[0];
     const reason = positionals[1];
     const id = parseIdOrThrow(idStr);
-    let ledger;
-    try {
-        ledger = readLedgerOrNull(cwd) ?? emptyLedger(nowIso());
-    }
-    catch (e) {
-        if (e instanceof WindowsError)
-            throw e;
-        throw new WindowsError(exports.REASON.WINDOWS_LEDGER_MALFORMED, e.message);
-    }
-    const updated = markWaived(ledger, id, reason ?? '', { now: nowIso() });
-    writeLedgerAtomic(cwd, updated);
-    emit({ ok: true, ledger: updated });
+    // #3780: same serialization as append — a concurrent append holding a stale
+    // snapshot would otherwise overwrite the waive and resurrect the entry.
+    withLedgerLock(cwd, () => {
+        let ledger;
+        try {
+            ledger = readLedgerOrNull(cwd) ?? emptyLedger(nowIso());
+        }
+        catch (e) {
+            if (e instanceof WindowsError)
+                throw e;
+            throw new WindowsError(exports.REASON.WINDOWS_LEDGER_MALFORMED, e.message);
+        }
+        const updated = markWaived(ledger, id, reason ?? '', { now: nowIso() });
+        writeLedgerAtomic(cwd, updated);
+        emit({ ok: true, ledger: updated });
+    });
 }
 /** `gsd-tools windows fixed <id>`. */
 function cmdWindowsMarkFixed(cwd, args, opts = {}) {
     void opts;
     const { positionals } = parseArgs(args, { flags: [], required: [], positionals: 1 });
     const id = parseIdOrThrow(positionals[0]);
-    let ledger;
-    try {
-        ledger = readLedgerOrNull(cwd) ?? emptyLedger(nowIso());
-    }
-    catch (e) {
-        if (e instanceof WindowsError)
-            throw e;
-        throw new WindowsError(exports.REASON.WINDOWS_LEDGER_MALFORMED, e.message);
-    }
-    const updated = markFixed(ledger, id, { now: nowIso() });
-    writeLedgerAtomic(cwd, updated);
-    emit({ ok: true, ledger: updated });
+    // #3780: same serialization as append — a concurrent writer holding a
+    // stale snapshot would otherwise overwrite the resolved status.
+    withLedgerLock(cwd, () => {
+        let ledger;
+        try {
+            ledger = readLedgerOrNull(cwd) ?? emptyLedger(nowIso());
+        }
+        catch (e) {
+            if (e instanceof WindowsError)
+                throw e;
+            throw new WindowsError(exports.REASON.WINDOWS_LEDGER_MALFORMED, e.message);
+        }
+        const updated = markFixed(ledger, id, { now: nowIso() });
+        writeLedgerAtomic(cwd, updated);
+        emit({ ok: true, ledger: updated });
+    });
 }
 function parseIdOrThrow(raw) {
     if (raw == null || raw === '') {

package/gsd-core/bin/lib/capability-lifecycle.cjs

@@ -25,6 +25,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
 const node_crypto_1 = __importDefault(require("node:crypto"));
+const security_cjs_1 = require("./security.cjs");
 /* eslint-disable @typescript-eslint/no-require-imports */
 const sourceMod = require('./capability-source.cjs');
 const ledgerMod = require('./capability-ledger.cjs');
@@ -202,7 +203,10 @@ function safeRmUnder(runtimeDir, rel) {
     catch {
         return false;
     }
-    if (realParent !== realRoot && !realParent.startsWith(realRoot + node_path_1.default.sep))
+    // Containment decision is the canonical LEXICAL predicate (ADR-4650 decision 6); lexical because
+    // both operands are already realpath-resolved here and the final component is deliberately
+    // handled as a link (see above).
+    if ((0, security_cjs_1.tryWithinRootLexical)(realParent, realRoot) === null)
         return false;
     const realTarget = node_path_1.default.join(realParent, node_path_1.default.basename(target));
     let st;
@@ -250,11 +254,11 @@ function confinedSharedFile(runtimeDir, relFile) {
     catch {
         // Parent does not exist yet (created inside the scope on write): a non-existent path cannot be a
         // symlink escaping the root, so a lexical containment check is sufficient.
-        if (parentDir !== realRoot && !parentDir.startsWith(realRoot + node_path_1.default.sep))
+        if ((0, security_cjs_1.tryWithinRootLexical)(parentDir, realRoot) === null)
             return null;
         return target;
     }
-    if (realParent !== realRoot && !realParent.startsWith(realRoot + node_path_1.default.sep))
+    if ((0, security_cjs_1.tryWithinRootLexical)(realParent, realRoot) === null)
         return null;
     return node_path_1.default.join(realParent, node_path_1.default.basename(target));
 }
@@ -363,7 +367,7 @@ function confinedBundleScript(capDirPath, script) {
         // disk): a non-existent root cannot be a symlink escaping itself, so confine lexically.
         realCapRoot = node_path_1.default.resolve(capDirPath);
         const targetLex = node_path_1.default.resolve(realCapRoot, script);
-        if (targetLex !== realCapRoot && !targetLex.startsWith(realCapRoot + node_path_1.default.sep))
+        if ((0, security_cjs_1.tryWithinRootLexical)(targetLex, realCapRoot) === null)
             return null;
         return targetLex;
     }
@@ -376,13 +380,13 @@ function confinedBundleScript(capDirPath, script) {
     catch {
         // Parent does not exist yet (created inside the bundle): lexical containment is sufficient
         // because a non-existent path cannot be a symlink escaping the root.
-        if (parentDir !== realCapRoot && !parentDir.startsWith(realCapRoot + node_path_1.default.sep))
+        if ((0, security_cjs_1.tryWithinRootLexical)(parentDir, realCapRoot) === null)
             return null;
         return target;
     }
     // The realpath'd parent chain must remain inside the bundle — an ancestor symlink escaping the
     // bundle is refused here (the symlink is followed by realpathSync, so its real location is checked).
-    if (realParent !== realCapRoot && !realParent.startsWith(realCapRoot + node_path_1.default.sep))
+    if ((0, security_cjs_1.tryWithinRootLexical)(realParent, realCapRoot) === null)
         return null;
     return node_path_1.default.join(realParent, node_path_1.default.basename(target));
 }