gsd-pi 2.78.1-dev.0fdacd524 → 2.78.1-dev.2d3fd6e71

package/dist/resources/extensions/gsd/metrics.js

@@ -1,3 +1,4 @@
+// GSD-2 + metrics.ts: token & cost tracking for auto-mode units
 /**
  * GSD Metrics — Token & Cost Tracking
  *
@@ -13,12 +14,14 @@
  *   4. On crash recovery or fresh start, the ledger is loaded from disk
  */
 import { join } from "node:path";
+import { openSync, closeSync, unlinkSync, statSync, writeFileSync } from "node:fs";
 import { gsdRoot } from "./paths.js";
 import { getAndClearSkills } from "./skill-telemetry.js";
 import { loadJsonFile, loadJsonFileOrNull, saveJsonFile } from "./json-persistence.js";
 import { parseUnitId } from "./unit-id.js";
 import { buildAuditEnvelope, emitUokAuditEvent } from "./uok/audit.js";
 import { isUnifiedAuditEnabled } from "./uok/audit-toggle.js";
+import { logWarning } from "./workflow-logger.js";
 // Re-export from shared — import directly from format-utils to avoid pulling
 // in the full barrel (mod.js → ui.js → @gsd/pi-tui) which breaks when loaded
 // outside jiti's alias resolution (e.g. dynamic import in auto-loop reports).
@@ -48,10 +51,15 @@ export function classifyUnitPhase(unitType) {
 // ─── In-memory state ──────────────────────────────────────────────────────────
 let ledger = null;
 let basePath = "";
+// Per-workspace ledger map, keyed by workspace.identityKey.
+// Populated by initMetricsByScope; independent of the module singleton.
+const scopedLedgers = new Map();
 // ─── Public API ───────────────────────────────────────────────────────────────
 /**
  * Initialize the metrics system for a given project.
  * Loads existing ledger from disk if present.
+ *
+ * @deprecated TODO(C-future): remove module singleton. Use initMetricsByScope instead.
  */
 export function initMetrics(base) {
     basePath = base;
@@ -59,6 +67,8 @@ export function initMetrics(base) {
 }
 /**
  * Reset in-memory state. Called when auto-mode stops.
+ *
+ * @deprecated TODO(C-future): remove module singleton. Use resetMetricsByScope instead.
  */
 export function resetMetrics() {
     ledger = null;
@@ -67,6 +77,8 @@ export function resetMetrics() {
 /**
  * Snapshot usage metrics from the current session before it's wiped.
  * Scans session entries for AssistantMessage usage data.
+ *
+ * @deprecated TODO(C-future): remove module singleton. Use snapshotUnitMetricsByScope instead.
  */
 export function snapshotUnitMetrics(ctx, unitType, unitId, startedAt, model, opts) {
     if (!ledger)
@@ -180,6 +192,147 @@ export function snapshotUnitMetrics(ctx, unitType, unitId, startedAt, model, opt
 export function getLedger() {
     return ledger;
 }
+// ─── Scope-aware API (canonical) ─────────────────────────────────────────────
+/**
+ * Initialize the metrics system for a given workspace scope.
+ * Loads existing ledger from disk into the per-scope ledger map.
+ * Does NOT touch the module-level singleton.
+ */
+export function initMetricsByScope(scope) {
+    const base = scope.workspace.projectRoot;
+    const loaded = loadLedger(base);
+    scopedLedgers.set(scope.workspace.identityKey, loaded);
+}
+/**
+ * Get the in-memory ledger for the given scope, or null if not initialized.
+ */
+export function getLedgerByScope(scope) {
+    return scopedLedgers.get(scope.workspace.identityKey) ?? null;
+}
+/**
+ * Reset scoped in-memory state for a workspace. Called when auto-mode stops.
+ */
+export function resetMetricsByScope(scope) {
+    scopedLedgers.delete(scope.workspace.identityKey);
+}
+/**
+ * Snapshot usage metrics using an explicit workspace scope.
+ *
+ * This is the canonical variant. It derives the metrics path from
+ * scope.workspace.projectRoot rather than the module singleton, so it
+ * remains correct across session resume and in multi-workspace processes.
+ *
+ * Preserves the atomic write-merge logic from saveLedger so concurrent
+ * workers cannot silently discard each other's entries.
+ *
+ * If initMetricsByScope has not been called, the ledger is loaded from
+ * disk on first call (lazy init).
+ */
+export function snapshotUnitMetricsByScope(scope, ctx, unitType, unitId, startedAt, model, opts) {
+    const base = scope.workspace.projectRoot;
+    const key = scope.workspace.identityKey;
+    // Lazy init: load from disk if not yet in scoped map.
+    if (!scopedLedgers.has(key)) {
+        scopedLedgers.set(key, loadLedger(base));
+    }
+    const scopedLedger = scopedLedgers.get(key);
+    const entries = ctx.sessionManager.getEntries();
+    if (!entries || entries.length === 0)
+        return null;
+    const tokens = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 };
+    let cost = 0;
+    let toolCalls = 0;
+    let assistantMessages = 0;
+    let userMessages = 0;
+    for (const entry of entries) {
+        if (entry.type !== "message")
+            continue;
+        const msg = entry.message;
+        if (!msg)
+            continue;
+        if (msg.role === "assistant") {
+            assistantMessages++;
+            if (msg.usage) {
+                tokens.input += msg.usage.input ?? 0;
+                tokens.output += msg.usage.output ?? 0;
+                tokens.cacheRead += msg.usage.cacheRead ?? 0;
+                tokens.cacheWrite += msg.usage.cacheWrite ?? 0;
+                tokens.total += msg.usage.totalTokens ?? 0;
+                if (msg.usage.cost != null) {
+                    const c = msg.usage.cost;
+                    cost += typeof c === "number" ? c : (c.total ?? 0);
+                }
+            }
+            if (msg.content && Array.isArray(msg.content)) {
+                for (const block of msg.content) {
+                    if (block.type === "toolCall")
+                        toolCalls++;
+                }
+            }
+        }
+        else if (msg.role === "user") {
+            userMessages++;
+        }
+    }
+    const unit = {
+        type: unitType,
+        id: unitId,
+        model,
+        startedAt,
+        finishedAt: Date.now(),
+        ...(opts?.autoSessionKey ? { autoSessionKey: opts.autoSessionKey } : {}),
+        tokens,
+        cost,
+        toolCalls,
+        assistantMessages,
+        userMessages,
+        apiRequests: assistantMessages,
+        ...(opts?.tier ? { tier: opts.tier } : {}),
+        ...(opts?.modelDowngraded !== undefined ? { modelDowngraded: opts.modelDowngraded } : {}),
+        ...(opts?.contextWindowTokens !== undefined ? { contextWindowTokens: opts.contextWindowTokens } : {}),
+        ...(opts?.truncationSections !== undefined ? { truncationSections: opts.truncationSections } : {}),
+        ...(opts?.continueHereFired !== undefined ? { continueHereFired: opts.continueHereFired } : {}),
+        ...(opts?.promptCharCount != null ? { promptCharCount: opts.promptCharCount } : {}),
+        ...(opts?.baselineCharCount != null ? { baselineCharCount: opts.baselineCharCount } : {}),
+    };
+    // Auto-capture skill telemetry (#599)
+    const skills = getAndClearSkills();
+    if (skills.length > 0) {
+        unit.skills = skills;
+    }
+    // Compute cache hit rate
+    if (tokens.cacheRead > 0 || tokens.input > 0) {
+        const totalInput = tokens.cacheRead + tokens.input;
+        unit.cacheHitRate = totalInput > 0 ? Math.round((tokens.cacheRead / totalInput) * 100) : 0;
+    }
+    // Idempotency guard: update in-place on duplicate, append otherwise.
+    const dupeIdx = scopedLedger.units.findIndex((u) => u.type === unit.type && u.id === unit.id && u.startedAt === unit.startedAt);
+    if (dupeIdx >= 0) {
+        scopedLedger.units[dupeIdx] = unit;
+    }
+    else {
+        scopedLedger.units.push(unit);
+    }
+    saveLedger(base, scopedLedger);
+    if (isUnifiedAuditEnabled()) {
+        emitUokAuditEvent(base, buildAuditEnvelope({
+            traceId: opts?.traceId ?? `metrics:${unitType}:${unitId}`,
+            turnId: opts?.turnId,
+            causedBy: opts?.causedBy,
+            category: "metrics",
+            type: "unit-metrics-snapshot",
+            payload: {
+                unitType,
+                unitId,
+                model,
+                tokens: unit.tokens,
+                cost: unit.cost,
+                toolCalls: unit.toolCalls,
+            },
+        }));
+    }
+    return unit;
+}
 function emptyTokens() {
     return { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 };
 }
@@ -423,6 +576,12 @@ export function pruneMetricsLedger(base, keepCount) {
     if (ledger) {
         ledger.units = ledger.units.slice(-keepCount);
     }
+    // Invalidate all scoped ledger cache entries. Prune is rare; clearing the
+    // entire map is simpler than tracking which entry belongs to `base`. Without
+    // this, scopedLedgers entries for the pruned workspace hold a pre-prune
+    // MetricsLedger that snapshotUnitMetricsByScope would merge back in, causing
+    // pruned units to reappear in subsequent snapshots.
+    scopedLedgers.clear();
     return removed;
 }
 /**
@@ -461,6 +620,133 @@ function deduplicateUnits(units) {
     }
     return Array.from(map.values());
 }
+// How long a lock file must be untouched (in ms) before it is considered
+// orphaned from a crashed process. Set to 2× the acquire timeout.
+export const STALE_LOCK_THRESHOLD_MS = 4000;
+// Retry interval between lock acquire attempts (ms). Caps syscall rate at
+// ~200 attempts over a 2s timeout instead of ~20,000 without any sleep.
+// Exposed for tests.
+export const LOCK_RETRY_INTERVAL_MS = 5;
+// Sync sleep via Atomics.wait — true OS-level sleep, no CPU spin.
+// Int32Array must reference a SharedArrayBuffer; we wait on index 0 which
+// will never be woken by a Atomics.notify, so the wait always times out.
+const _lockSleepBuf = new Int32Array(new SharedArrayBuffer(4));
+function syncSleep(ms) {
+    Atomics.wait(_lockSleepBuf, 0, 0, ms);
+}
+// Counts the number of sleepy retries (non-stale-evicting) made by acquireLock
+// across all calls since the last reset. Exported for test instrumentation only.
+let _lockSleepyRetries = 0;
+export function getLockSleepyRetries() { return _lockSleepyRetries; }
+export function resetLockSleepyRetries() { _lockSleepyRetries = 0; }
+/**
+ * Acquire an exclusive .lock sentinel file via O_EXCL.
+ *
+ * Improvements over the original:
+ *  - No busy spin: the inner `while (Date.now() < waitUntil) {}` spin that
+ *    burned CPU doing nothing useful is removed. Each retry attempt now makes
+ *    one `openSync` syscall and immediately re-checks the deadline, which is
+ *    orders of magnitude cheaper than a tight spin loop.
+ *  - Stale-lock detection: if the existing lock file's mtime is older than
+ *    STALE_LOCK_THRESHOLD_MS, the lock is considered orphaned (e.g. the
+ *    writing process crashed) and is forcibly removed before retrying.
+ *    A warning is logged so operators can detect crash patterns.
+ *  - PID stamp: on success, writes the acquiring process's PID and a
+ *    timestamp into the lock file so external monitors can identify orphans.
+ *  - Retry sleep: after each non-stale-evicting retry, sleeps
+ *    LOCK_RETRY_INTERVAL_MS (5ms) via Atomics.wait so the process yields to
+ *    the OS. This caps syscall rate at ~200–400/s under contention instead of
+ *    the ~20,000/s that would result from a tight openSync loop.
+ *    After a stale-lock eviction (lock already removed), no sleep is injected
+ *    — we retry immediately to close the short race window.
+ *
+ * Returns true on success, false on timeout.
+ */
+function acquireLock(lockPath, timeoutMs = 2000) {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        try {
+            const fd = openSync(lockPath, "wx"); // O_WRONLY | O_CREAT | O_EXCL
+            closeSync(fd);
+            // Write PID stamp so external monitors can identify the lock owner.
+            try {
+                writeFileSync(lockPath, `${process.pid}\n${new Date().toISOString()}\n`, "utf-8");
+            }
+            catch { /* non-fatal — stamp is diagnostic only */ }
+            return true;
+        }
+        catch {
+            // Lock held by another process — check for staleness before retrying.
+            try {
+                const st = statSync(lockPath);
+                if (Date.now() - st.mtimeMs > STALE_LOCK_THRESHOLD_MS) {
+                    logWarning("fs", `stale metrics lock at ${lockPath} (age ${Date.now() - st.mtimeMs}ms); forcibly removing and retrying`);
+                    try {
+                        unlinkSync(lockPath);
+                    }
+                    catch { /* already gone */ }
+                    // Do NOT sleep after stale-lock eviction — retry the open
+                    // immediately. The lock file was just removed; a short race window
+                    // exists and sleeping here would unnecessarily delay recovery.
+                    continue;
+                }
+            }
+            catch { /* lock file disappeared between the failed open and stat — retry */ }
+            // Sleep between retries to yield to the OS and cap syscall rate.
+            // Uses Atomics.wait for a true blocking sleep (no CPU spin).
+            _lockSleepyRetries++;
+            syncSleep(LOCK_RETRY_INTERVAL_MS);
+        }
+    }
+    return false;
+}
+function releaseLock(lockPath) {
+    try {
+        unlinkSync(lockPath);
+    }
+    catch { /* ignore */ }
+}
+/**
+ * Save the ledger with cross-process merge semantics.
+ *
+ * Acquires a .lock sentinel file, reads the current on-disk ledger,
+ * merges worker units with existing peer units (worker's entry wins on
+ * type+id+startedAt conflict since it has the latest finishedAt),
+ * then writes atomically. This prevents parallel auto-mode workers from
+ * silently discarding each other's metrics entries.
+ *
+ * Falls back to a direct write (no merge) if the lock cannot be acquired
+ * within the timeout — better to potentially overwrite than to lose data
+ * entirely.
+ */
 function saveLedger(base, data) {
-    saveJsonFile(metricsPath(base), data);
+    const path = metricsPath(base);
+    const lockPath = `${path}.lock`;
+    const acquired = acquireLock(lockPath);
+    if (acquired) {
+        try {
+            // Read current on-disk state and merge with worker's in-memory units.
+            // Worker units take precedence on conflict (by finishedAt in deduplicateUnits).
+            const onDisk = loadJsonFileOrNull(path, isMetricsLedger);
+            if (onDisk && onDisk.units.length > 0) {
+                const merged = deduplicateUnits([...onDisk.units, ...data.units]);
+                saveJsonFile(path, { ...data, units: merged });
+            }
+            else {
+                saveJsonFile(path, data);
+            }
+        }
+        finally {
+            releaseLock(lockPath);
+        }
+    }
+    else {
+        // Lock could not be acquired within the timeout. Fall back to a direct
+        // write (no cross-process merge) to avoid losing this worker's data
+        // entirely. A concurrent writer may overwrite us, but that is preferable
+        // to a torn write caused by two writers simultaneously executing the
+        // read-merge-write sequence without mutual exclusion.
+        logWarning("fs", "saveLedger: lock not acquired — falling back to direct write (no merge)");
+        saveJsonFile(path, data);
+    }
 }

package/dist/resources/extensions/gsd/migrate/command.js

@@ -13,8 +13,8 @@ import { resolve, join, dirname } from "node:path";
 import { gsdRoot } from "../paths.js";
 import { fileURLToPath } from "node:url";
 import { showNextAction } from "../../shared/tui.js";
-import { getHomeDir } from "../home-dir.js";
 import { validatePlanningDirectory, parsePlanningDirectory, transformToGSD, generatePreview, writeGSDDirectory, } from "./index.js";
+import { homedir } from "node:os";
 /** Format preview stats for embedding in the review prompt. */
 function formatPreviewStats(preview) {
     const lines = [
@@ -51,10 +51,10 @@ export async function handleMigrate(args, ctx, pi) {
     // Default to cwd when no args given; expand ~ to HOME
     let rawPath = args.trim() || ".";
     if (rawPath.startsWith("~/")) {
-        rawPath = join(getHomeDir(), rawPath.slice(2));
+        rawPath = join(homedir(), rawPath.slice(2));
     }
     else if (rawPath === "~") {
-        rawPath = getHomeDir();
+        rawPath = homedir();
     }
     let sourcePath = resolve(process.cwd(), rawPath);
     if (!sourcePath.endsWith(".planning")) {

package/dist/resources/extensions/gsd/milestone-scope-classifier.js

@@ -120,13 +120,14 @@ function mentionsWithoutNegation(text, term) {
         const start = m.index ?? 0;
         const windowStart = Math.max(0, start - 30);
         const window = lower.slice(windowStart, start);
-        // Negator anywhere in the 30-char lookback window counts as negation —
-        // covers "no backend", "without a server", "not using api", "zero
-        // dependencies on an api". If a sentence break intervenes between the
-        // negator and the term, treat as a different clause (positive mention).
-        const hasNegator = /(^|[^a-z0-9])(no|without|not|zero|skip(s|ping)?|drops?)\b/i.test(window);
-        const hasSentenceBreak = /[.;!?]/.test(window);
-        if (hasNegator && !hasSentenceBreak)
+        // Negator anywhere in the same clause counts as negation — covers "no
+        // backend", "without a server", "not using api", "zero dependencies on
+        // an api". Only inspect text after the most recent sentence break so
+        // "No backend. Add API" still treats API as a positive mention.
+        const lastBreak = Math.max(window.lastIndexOf("."), window.lastIndexOf(";"), window.lastIndexOf("!"), window.lastIndexOf("?"));
+        const clauseWindow = window.slice(lastBreak + 1);
+        const hasNegator = /(^|[^a-z0-9])(no|without|not|zero|skip(s|ping)?|drops?)\b/i.test(clauseWindow);
+        if (hasNegator)
             continue;
         return true;
     }
@@ -220,7 +221,8 @@ export function classifyMilestoneScope(input) {
         input.verificationOperational ?? "",
         input.verificationUat ?? "",
     ].join("\n");
-    const overrideHits = containsAnyKeyword(haystack, OVERRIDE_KEYWORDS);
+    const overrideHits = containsAnyKeyword(haystack, OVERRIDE_KEYWORDS)
+        .filter((kw) => mentionsWithoutNegation(haystack, kw));
     const complexHits = containsAnyKeyword(haystack, COMPLEX_KEYWORDS);
     const trivialHits = containsAnyKeyword(haystack, TRIVIAL_KEYWORDS);
     const fileCountHint = extractFileCountHint(haystack);

package/dist/resources/extensions/gsd/native-git-bridge.js

@@ -216,6 +216,20 @@ export function nativeIsRepo(basePath) {
         return false;
     }
 }
+/** Return true only when the repository has a reachable committed HEAD. */
+export function nativeHasCommittedHead(basePath) {
+    try {
+        execFileSync("git", ["rev-parse", "--verify", "HEAD"], {
+            cwd: basePath,
+            stdio: ["ignore", "ignore", "ignore"],
+            env: GIT_NO_PROMPT_ENV,
+        });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 /**
  * Check if there are staged changes (index differs from HEAD).
  * Native: libgit2 tree-to-index diff.
@@ -746,56 +760,19 @@ export function nativeResetPaths(basePath, paths) {
         gitExec(basePath, ["reset", "HEAD", "--", p], true);
     }
 }
-/**
- * Read `commit.gpgsign` from the repo config. Returns true only if the value
- * is the literal string "true". Any other state (unset, false, error) → false.
- *
- * Used by nativeCommit to route signing-required commits through the git CLI,
- * because the libgit2 native path does not invoke configured signers.
- * (Issue #4980 CRIT-2)
- */
-function shouldSignCommits(basePath) {
-    try {
-        const result = execFileSync("git", ["config", "--get", "commit.gpgsign"], {
-            cwd: basePath,
-            stdio: ["ignore", "pipe", "pipe"],
-            encoding: "utf-8",
-            env: GIT_NO_PROMPT_ENV,
-        }).trim();
-        return result === "true";
-    }
-    catch {
-        return false;
-    }
-}
 /**
  * Create a commit from the current index.
  * Returns the commit SHA on success, or null if nothing to commit.
- * Native: libgit2 commit create.
- * Fallback: `git commit -F -` (runs hooks; honors commit.gpgsign).
+ * Uses `git commit -F -` so normal user hooks run and commit.gpgsign is honored.
  *
  * The fallback intentionally does NOT use --no-verify — user pre-commit /
  * commit-msg / prepare-commit-msg hooks must fire on every GSD-automated
  * commit. (Issue #4980 CRIT-1)
  */
 export function nativeCommit(basePath, message, options) {
-    const native = loadNative();
-    // libgit2's commit-create does not invoke configured GPG/SSH signers. When
-    // commit.gpgsign=true, route through the git CLI fallback so signing
-    // happens. (Issue #4980 CRIT-2)
-    if (native && !shouldSignCommits(basePath)) {
-        try {
-            return native.gitCommit(basePath, message, options?.allowEmpty);
-        }
-        catch (e) {
-            const msg = getErrorMessage(e);
-            if (msg.includes("nothing to commit"))
-                return null;
-            throw e;
-        }
-    }
-    // Fallback / signed-commit path: use git CLI with stdin pipe for safe
-    // multi-line messages. Hooks run; commit.gpgsign honored.
+    // Use git CLI with stdin pipe for safe multi-line messages. Hooks run;
+    // commit.gpgsign honored. libgit2 commit-create bypasses hooks, so automated
+    // GSD commits intentionally stay on the CLI path even when native git is on.
     try {
         const args = ["commit", "-F", "-"];
         if (options?.allowEmpty)
@@ -981,7 +958,7 @@ export function nativeBranchDelete(basePath, branch, force = true) {
         native.gitBranchDelete(basePath, branch, force);
         return;
     }
-    gitFileExec(basePath, ["branch", force ? "-D" : "-d", branch], true);
+    gitFileExec(basePath, ["branch", force ? "-D" : "-d", branch]);
 }
 /**
  * Force-reset a branch to point at a target ref.

package/dist/resources/extensions/gsd/onboarding-state.js

@@ -4,9 +4,9 @@
 // web boot probe all read the same source of truth. Replaces the implicit
 // "settings.defaultProvider exists" heuristic.
 import { existsSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
-import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 import { logWarning } from "./workflow-logger.js";
+import { gsdHome } from "./gsd-home.js";
 /**
  * Bump `FLOW_VERSION` whenever a new required step is added to ONBOARDING_STEPS.
  * Records with an older flowVersion are treated as "needs partial re-onboarding"
@@ -18,7 +18,7 @@ const RECORD_VERSION = 1;
 // rootDir-clean for the resources tsconfig; importing from src/ pulls files
 // outside src/resources and breaks the build.
 const AGENT_DIR = process.env.GSD_CODING_AGENT_DIR ||
-    join(process.env.GSD_HOME || join(homedir(), ".gsd"), "agent");
+    join(gsdHome(), "agent");
 const FILE = join(AGENT_DIR, "onboarding.json");
 const DEFAULT = {
     version: RECORD_VERSION,

package/dist/resources/extensions/gsd/parallel-merge.js

@@ -8,7 +8,7 @@ import { existsSync, readdirSync } from "node:fs";
 import { join } from "node:path";
 import { spawnSync } from "node:child_process";
 import { loadFile } from "./files.js";
-import { resolveMilestoneFile } from "./paths.js";
+import { resolveGsdPathContract, resolveMilestoneFile } from "./paths.js";
 import { mergeMilestoneToMain } from "./auto-worktree.js";
 import { MergeConflictError } from "./git-service.js";
 import { removeSessionStatus } from "./session-status-io.js";
@@ -16,12 +16,13 @@ import { getErrorMessage } from "./error-utils.js";
 import { logWarning } from "./workflow-logger.js";
 // ─── Merge Queue ───────────────────────────────────────────────────────────
 /**
- * Check whether a milestone is complete by querying its worktree SQLite DB.
+ * Check whether a milestone is complete by querying the canonical project DB.
  * Uses a subprocess to avoid disrupting the global DB singleton.
- * Returns true when milestones.status = 'complete' in the worktree's gsd.db.
+ * Returns true when milestones.status = 'complete' in project gsd.db.
  */
-export function isMilestoneCompleteInWorktreeDb(basePath, mid) {
-    const dbPath = join(basePath, ".gsd", "worktrees", mid, ".gsd", "gsd.db");
+export function isMilestoneCompleteInProjectDb(basePath, mid) {
+    const workRoot = join(basePath, ".gsd", "worktrees", mid);
+    const dbPath = resolveGsdPathContract(workRoot, basePath).projectDb;
     if (!existsSync(dbPath))
         return false;
     try {
@@ -34,15 +35,15 @@ export function isMilestoneCompleteInWorktreeDb(basePath, mid) {
     }
 }
 /**
- * Discover milestone IDs with status='complete' in their worktree DB,
- * scanning .gsd/worktrees/<MID>/.gsd/gsd.db for each worktree directory.
+ * Discover milestone IDs with status='complete' in the canonical DB,
+ * using worktree directories only to enumerate active parallel workers.
  */
 function discoverDbCompletedMilestones(basePath) {
     const completed = new Set();
     const worktreeDir = join(basePath, ".gsd", "worktrees");
     try {
         for (const entry of readdirSync(worktreeDir)) {
-            if (entry.startsWith("M") && isMilestoneCompleteInWorktreeDb(basePath, entry)) {
+            if (entry.startsWith("M") && isMilestoneCompleteInProjectDb(basePath, entry)) {
                 completed.add(entry);
             }
         }
@@ -57,15 +58,15 @@ function discoverDbCompletedMilestones(basePath) {
  * Sequential: merge in milestone ID order (M001 before M002).
  * By-completion: merge in the order milestones finished.
  *
- * When basePath is provided, also checks worktree SQLite DBs as the
- * source of truth — workers with stale orchestrator state (e.g. "error")
- * are included if their worktree DB shows status='complete'.
+ * When basePath is provided, also checks the canonical project DB as the
+ * source of truth. Workers with stale orchestrator state (e.g. "error")
+ * are included if their project DB row shows status='complete'.
  * See: https://github.com/gsd-build/gsd-2/issues/2812
  */
 export function determineMergeOrder(workers, order = "sequential", basePath) {
     // Start with workers the orchestrator already knows are stopped
     const stoppedIds = new Set(workers.filter(w => w.state === "stopped").map(w => w.milestoneId));
-    // When basePath is available, also check worktree DBs for milestones
+    // When basePath is available, also check the project DB for milestones
     // whose orchestrator state is stale but are actually complete (#2812)
     const dbCompleted = basePath ? discoverDbCompletedMilestones(basePath) : new Set();
     // Union: milestone is mergeable if stopped OR DB-complete
@@ -80,7 +81,7 @@ export function determineMergeOrder(workers, order = "sequential", basePath) {
             allMergeable.push(w);
         }
         else {
-            // Milestone discovered from worktree DB but not in workers list
+            // Milestone discovered from project DB but not in workers list
             allMergeable.push({
                 milestoneId: mid,
                 title: mid,

package/dist/resources/extensions/gsd/parallel-monitor-overlay.js

@@ -13,6 +13,7 @@ import { spawnSync } from "node:child_process";
 import { matchesKey, Key } from "@gsd/pi-tui";
 import { formatDuration } from "../shared/mod.js";
 import { formattedShortcutPair } from "./shortcut-defs.js";
+import { resolveGsdPathContract } from "./paths.js";
 // ─── Data Helpers ─────────────────────────────────────────────────────────
 function readJsonSafe(filePath) {
     try {
@@ -74,7 +75,8 @@ function discoverWorkers(basePath) {
     return [...mids].sort();
 }
 function querySliceProgress(basePath, mid) {
-    const dbPath = join(basePath, ".gsd", "worktrees", mid, ".gsd", "gsd.db");
+    const workRoot = join(basePath, ".gsd", "worktrees", mid);
+    const dbPath = resolveGsdPathContract(workRoot, basePath).projectDb;
     if (!existsSync(dbPath))
         return [];
     try {
@@ -119,7 +121,8 @@ function extractCostFromNdjson(basePath, mid) {
     }
 }
 function queryRecentCompletions(basePath, mid) {
-    const dbPath = join(basePath, ".gsd", "worktrees", mid, ".gsd", "gsd.db");
+    const workRoot = join(basePath, ".gsd", "worktrees", mid);
+    const dbPath = resolveGsdPathContract(workRoot, basePath).projectDb;
     if (!existsSync(dbPath))
         return [];
     try {