@vibecompass/vibecompass 0.10.8 → 0.11.0

package/src/docs-review.js

@@ -16,6 +16,9 @@ import {
 } from './source-inventory.js';
 import { readSyncCursor, resolveSyncBinding } from './sync-binding.js';
 import { PACKAGE_VERSION } from './version.js';
+import { withMemoryRootLock } from './serialization.js';
+import { listDecisionFileNames, readNextDecisionId } from './decisions.js';
+import { looksLikeGroupedDecisionIndex } from './decision-index.js';
 
 const DOCS_REVIEW_PROMPT_VERSION = 'VibeCompass Docs Review Prompt v7';
 const DOCS_REVIEW_PARSER_VERSION = 'docs-review-parser-v1';
@@ -229,6 +232,10 @@ async function completeDocsReview(options) {
 }
 
 async function applyDocsReviewOutput(options) {
+  return withMemoryRootLock(options.rootDir, 'docs-review-apply-output', () => applyDocsReviewOutputLocked(options));
+}
+
+async function applyDocsReviewOutputLocked(options) {
   const current = await readDocsReviewMarker(options.statePath);
   const outputPath = options.outputPath
     ? path.resolve(options.rootDir, options.outputPath)
@@ -391,6 +398,10 @@ async function applyDocsReviewOutput(options) {
 }
 
 async function applyDecisionArtifact(options) {
+  return withMemoryRootLock(options.rootDir, 'docs-review-apply-decision-artifact', () => applyDecisionArtifactLocked(options));
+}
+
+async function applyDecisionArtifactLocked(options) {
   const current = await readDocsReviewMarker(options.statePath);
   const artifactId = normalizeOptionalString(options.artifactId);
   if (!artifactId) {
@@ -1949,33 +1960,8 @@ async function applyDecisionRecommendations(options) {
   };
 }
 
-async function readNextDecisionId(rootDir) {
-  const decisionsDir = path.join(rootDir, 'decisions');
-  let max = 0;
-
-  for (const fileName of await listDecisionFileNames(decisionsDir)) {
-    const content = await readFile(path.join(decisionsDir, fileName), 'utf8');
-    for (const match of content.matchAll(/^###\s+D-(\d+)\b/gm)) {
-      max = Math.max(max, Number(match[1]));
-    }
-  }
-
-  return max + 1;
-}
-
-async function listDecisionFileNames(decisionsDir) {
-  try {
-    return (await readdir(decisionsDir))
-      .filter((fileName) =>
-        fileName.endsWith('.md') &&
-        !['INDEX.md', 'README.md', 'EXAMPLE.md'].includes(fileName),
-      )
-      .sort((left, right) => left.localeCompare(right));
-  } catch (error) {
-    if (error?.code === 'ENOENT') return [];
-    throw error;
-  }
-}
+// readNextDecisionId and listDecisionFileNames moved to decisions.js so the
+// atomic append path (D-276) and these apply paths share one allocation scan.
 
 function renderDecisionEntry(options) {
   const decisionNumber = `D-${String(options.decisionId).padStart(3, '0')}`;
@@ -2023,6 +2009,20 @@ async function refreshDecisionIndex(rootDir) {
   const warnings = [];
   const rows = [];
 
+  // D-283/D-255 quarantine: the flat generator must never be pointed at a
+  // grouped index — a wholesale rewrite would destroy the hand-authored
+  // session group headings. Any "## " heading counts as grouped-shaped, so a
+  // malformed grouped index survives too.
+  const existingIndex = await readFile(indexPath, 'utf8').catch(() => null);
+  if (existingIndex !== null && looksLikeGroupedDecisionIndex(existingIndex)) {
+    return {
+      refreshed: false,
+      warnings: [
+        'decisions/INDEX.md uses the grouped session shape; --refresh-index (the flat D-209 generator) refuses to overwrite it. Use `vibecompass refresh-decision-index` (D-283) instead.',
+      ],
+    };
+  }
+
   for (const fileName of await listDecisionFileNames(decisionsDir)) {
     const relativePath = `decisions/${fileName}`;
     const content = await readFile(path.join(decisionsDir, fileName), 'utf8');

package/src/docs-update.js

@@ -1,8 +1,10 @@
 import { execFile } from 'node:child_process';
-import { readFile } from 'node:fs/promises';
+import { readFile, readdir, stat } from 'node:fs/promises';
 import path from 'node:path';
 import { promisify } from 'node:util';
 import { parseFrontmatter } from './frontmatter.js';
+import { readCurrentRepoHead, resolveRepoSourceDir } from './git-binding.js';
+import { resolveLaneMarkerContext, resolveLaneSelection } from './lane-marker.js';
 import { scanProjectMemory } from './project-memory.js';
 import { parseSimpleYaml } from './simple-yaml.js';
 
@@ -19,13 +21,39 @@ const PACKAGE_OWNED_PATH_PATTERNS = [
 
 export async function planDocsUpdate(options = {}) {
   const normalized = normalizeDocsUpdateOptions(options);
+  // D-280: docs-update shares the same context resolution as session
+  // commands — explicit --root wins, else the nearest valid marker's
+  // memory_root, else cwd/.compass — and the same D-277 lane selection.
+  const markerContext = await resolveLaneMarkerContext({
+    cwd: normalized.cwd,
+    explicitRootDir: options.rootDir ?? null,
+    explicitSessionId: normalized.sessionId,
+  });
+  normalized.rootDir = markerContext.rootDir;
+  // suppressLaneWarnings marks the embedded close-session plan, which already
+  // carries the same marker-context warnings on the close result itself.
+  const warnings = options.suppressLaneWarnings === true ? [] : [...markerContext.warnings];
   const scan = await scanProjectMemory(normalized.rootDir);
   const project = scan.project?.extracted ?? {};
-  const activeSession = await readActiveSession(normalized.rootDir, normalized.sessionId);
+  const activeSession = await readActiveSession(normalized.rootDir, normalized.sessionId, {
+    markerContext,
+    warnings,
+    suppressLaneWarnings: options.suppressLaneWarnings === true,
+  });
   const changedFiles = await resolveChangedFiles({
     cwd: normalized.cwd,
+    // Repo working copies live as siblings of the memory root (the
+    // workspace), not relative to wherever the command runs — a worktree or
+    // nested cwd previously made every repo dir resolve to a nonexistent
+    // path whose git-status errors were silently swallowed.
+    workspaceDir: path.dirname(normalized.rootDir),
+    // D-281: a git-bound lane's diff lives in its recorded worktrees, not the
+    // source checkouts — scan those for bound repos so the delta carries
+    // correct `repo-id:` prefixes.
+    laneWorktrees: activeSession?.worktrees ?? {},
     explicitChangedFiles: normalized.changedFiles,
     repos: project.repos ?? [],
+    warnings,
   });
   const architectureDocs = scan.documents
     .filter((document) => document.kind === 'architecture')
@@ -41,6 +69,19 @@ export async function planDocsUpdate(options = {}) {
     .filter((file) => isPackageOwnedPath(file.normalizedPath))
     .map((file) => file.raw);
   const decisionStatus = summarizeDecisionStatus(scan, activeSession);
+  // A:192 (D-281): the pre-close staleness set is computed on every
+  // docs-update run for the selected lane and re-emitted by close-session, so
+  // mid-session and close-out see the same target set.
+  const staleness = activeSession
+    ? await buildPreCloseStaleness({
+        rootDir: normalized.rootDir,
+        workspaceDir: path.dirname(normalized.rootDir),
+        activeSession,
+        otherLanes: await listOtherActiveLanes(path.join(normalized.rootDir, 'sessions', 'active'), activeSession.id),
+        decisionStatus,
+        projectRepos: project.repos ?? [],
+      })
+    : null;
   const recommendations = buildRecommendations({
     changedFiles,
     affectedArchitectureDocs,
@@ -70,8 +111,10 @@ export async function planDocsUpdate(options = {}) {
       needsNewDoc: changedFiles.some((file) => isImplementationLikePath(file.normalizedPath)) && affectedArchitectureDocs.length === 0,
     },
     decisions: decisionStatus,
+    staleness,
     packageOwnedChanges,
     recommendations,
+    warnings,
   };
 }
 
@@ -109,6 +152,20 @@ export function renderDocsUpdatePlan(plan) {
     lines.push('- No new decisions detected since lane start.');
   }
 
+  if (plan.staleness) {
+    lines.push('Pre-close staleness set:');
+    if (plan.staleness.entries.length === 0) {
+      lines.push('- none detected');
+    } else {
+      for (const entry of plan.staleness.entries) {
+        lines.push(`- ${entry}`);
+      }
+    }
+    for (const skipped of plan.staleness.notEvaluated) {
+      lines.push(`- (not evaluated) ${skipped}`);
+    }
+  }
+
   if (plan.packageOwnedChanges.length > 0) {
     lines.push('Package-owned generated/state surfaces:');
     for (const filePath of plan.packageOwnedChanges) {
@@ -121,6 +178,10 @@ export function renderDocsUpdatePlan(plan) {
     lines.push(`- ${recommendation}`);
   }
 
+  for (const warning of plan.warnings ?? []) {
+    lines.push(`Warning: ${warning}`);
+  }
+
   return `${lines.join('\n')}\n`;
 }
 
@@ -134,20 +195,25 @@ function normalizeDocsUpdateOptions(options) {
   };
 }
 
-async function readActiveSession(rootDir, requestedSessionId) {
+async function readActiveSession(rootDir, requestedSessionId, laneContext = {}) {
   const activeRoot = path.join(rootDir, 'sessions', 'active');
-  const indexPath = path.join(activeRoot, 'index.yaml');
-  let sessionId = normalizeOptionalString(requestedSessionId);
-
-  if (!sessionId) {
-    try {
-      const indexData = parseSimpleYaml(await readFile(indexPath, 'utf8'), { sourceName: indexPath });
-      sessionId = normalizeOptionalString(indexData.current);
-    } catch {
-      sessionId = null;
-    }
+  // D-277 lane selection via the shared resolver: explicit --session wins,
+  // then the worktree marker (stale markers fail closed), then the single
+  // active lane; with 2+ lanes and no selection this throws instead of
+  // silently trusting the root-global index pointer.
+  const selection = resolveLaneSelection({
+    explicitSessionId: normalizeOptionalString(requestedSessionId),
+    marker: laneContext.markerContext?.marker ?? null,
+    laneIds: await listActiveLaneDirIds(activeRoot),
+    rootDir,
+    purpose: 'plan docs updates for',
+    suppressLaneWarnings: laneContext.suppressLaneWarnings === true,
+  });
+  if (Array.isArray(laneContext.warnings)) {
+    laneContext.warnings.push(...selection.warnings);
   }
 
+  const sessionId = selection.sessionId;
   if (!sessionId) {
     return null;
   }
@@ -161,6 +227,10 @@ async function readActiveSession(rootDir, requestedSessionId) {
       repos: normalizeStringArray(data.repos),
       claimedPaths: normalizeStringArray(data.claimed_paths),
       featureSlugs: normalizeStringArray(data.feature_slugs),
+      startedAt: normalizeOptionalString(data.started_at),
+      worktrees: normalizeWorktreeMap(data.worktrees),
+      worktreeSources: normalizeWorktreeMap(data.worktree_sources),
+      baseRevisions: normalizeStringValueMap(data.base_revisions),
       decisionSnapshotHighestId: Number.isInteger(data.decision_snapshot?.highest_decision_id)
         ? data.decision_snapshot.highest_decision_id
         : null,
@@ -172,25 +242,370 @@ async function readActiveSession(rootDir, requestedSessionId) {
       repos: [],
       claimedPaths: [],
       featureSlugs: [],
+      startedAt: null,
+      worktrees: {},
+      worktreeSources: {},
+      baseRevisions: {},
       decisionSnapshotHighestId: null,
     };
   }
 }
 
+/** Other active lanes' scope fields, for the pre-close claim-overlap check. */
+async function listOtherActiveLanes(activeRoot, selectedId) {
+  const lanes = [];
+  for (const laneId of await listActiveLaneDirIds(activeRoot)) {
+    if (laneId === selectedId) {
+      continue;
+    }
+
+    try {
+      const sessionPath = path.join(activeRoot, laneId, 'session.yaml');
+      const data = parseSimpleYaml(await readFile(sessionPath, 'utf8'), { sourceName: sessionPath });
+      lanes.push({
+        id: laneId,
+        repos: normalizeStringArray(data.repos),
+        claimedPaths: normalizeStringArray(data.claimed_paths),
+      });
+    } catch {
+      // An unreadable sibling lane cannot contribute overlap detail; the lane
+      // lifecycle commands own reporting corrupt lane metadata.
+    }
+  }
+
+  return lanes;
+}
+
+function normalizeWorktreeMap(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    return {};
+  }
+
+  const result = {};
+  for (const [key, entry] of Object.entries(value)) {
+    const normalized = normalizeOptionalString(entry);
+    if (normalized) {
+      result[key] = path.resolve(normalized);
+    }
+  }
+
+  return result;
+}
+
+/** Plain string map (base_revisions) — values are revisions, not paths. */
+function normalizeStringValueMap(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    return {};
+  }
+
+  const result = {};
+  for (const [key, entry] of Object.entries(value)) {
+    const normalized = entry === null || entry === undefined ? null : String(entry).trim();
+    if (normalized) {
+      result[key] = normalized;
+    }
+  }
+
+  return result;
+}
+
+const SESSION_NOTE_FILENAME_PATTERN = /^\d{4}-\d{2}-\d{2}-\d+-[a-z0-9-]+\.md$/i;
+
+/**
+ * A:192 (D-281): the pre-close staleness set. Everything here is a warning
+ * surface — actionable and non-destructive; the closer chooses whether to
+ * reconcile, close anyway, or keep the lane active. Pieces that cannot be
+ * evaluated (no started_at, no decision snapshot) are named instead of being
+ * silently skipped.
+ */
+async function buildPreCloseStaleness(options) {
+  const activeSession = options.activeSession;
+  const entries = [];
+  const notEvaluated = [];
+
+  // 1. New canonical decisions appended after the lane's frozen start-of-lane
+  //    snapshot (D-266). Elevated from the informational decision-log summary:
+  //    the closer confirms each one is either this lane's own append or does
+  //    not change this lane's contracts.
+  const newDecisions = options.decisionStatus.newDecisions ?? [];
+  if (options.decisionStatus.decisionSnapshotHighestId === null) {
+    notEvaluated.push('decision staleness: the lane has no decision snapshot.');
+  } else {
+    for (const decision of newDecisions) {
+      entries.push(
+        `New decision D-${decision.id} since lane start (${decision.path}) — confirm it is this lane's own append or does not change this lane's contracts.`,
+      );
+    }
+  }
+
+  // 2. Base revisions stale relative to the current source repo heads. Bound
+  //    repos compare against the recorded source checkout, not the lane
+  //    worktree — the lane's own commits are not staleness. A repo that
+  //    RECORDED a base but whose current head is unreadable is named in
+  //    notEvaluated (something changed since capture); repos that never
+  //    captured a base (non-git sources) stay silent by design — git is
+  //    never required for lanes (D-265/D-279).
+  const staleBaseRevisions = [];
+  for (const [repoId, baseRevision] of Object.entries(activeSession.baseRevisions ?? {})) {
+    const sourceDir = activeSession.worktreeSources?.[repoId]
+      ?? resolveRepoSourceDir(options.workspaceDir, repoId, options.projectRepos);
+    const head = await readCurrentRepoHead(sourceDir);
+    if (head === null) {
+      notEvaluated.push(
+        `base-revision staleness for repo "${repoId}": the current head of ${sourceDir} could not be read (missing, non-git, nested, or unborn) even though the lane recorded base ${baseRevision.slice(0, 12)} there at start.`,
+      );
+      continue;
+    }
+    if (head !== baseRevision) {
+      staleBaseRevisions.push({ repoId, baseRevision, headRevision: head });
+      entries.push(
+        `Base revision for repo "${repoId}" is stale: lane base ${baseRevision.slice(0, 12)}, current source head ${head.slice(0, 12)} — review what landed since lane start.`,
+      );
+    }
+  }
+
+  // 3. Finalized session notes materialized after this lane started that
+  //    mention the lane's declared scope. mtime ordering is intentional: a
+  //    note that arrives in this root after lane start (local close, pull,
+  //    apply-export) is new to this lane regardless of its filename date.
+  const newSessionNotes = [];
+  const startedAtMs = activeSession.startedAt ? Date.parse(activeSession.startedAt) : Number.NaN;
+  if (Number.isNaN(startedAtMs)) {
+    notEvaluated.push('session-note staleness: the lane has no parseable started_at.');
+  } else {
+    for (const note of await listFinalizedSessionNotesSince(options.rootDir, startedAtMs)) {
+      const reasons = describeNoteScopeOverlap(note.content, activeSession);
+      if (reasons.length > 0) {
+        newSessionNotes.push({ path: note.relativePath, reasons });
+        entries.push(
+          `Finalized session note ${note.relativePath} was written after this lane started (${reasons.join('; ')}) — check it for overlap with this lane's scope.`,
+        );
+      }
+    }
+  }
+
+  // 4. Claimed-path overlap with other active lanes (recently closed lanes
+  //    surface through the finalized-note check above). Claims only overlap
+  //    when their repo scopes can intersect: an explicit `repo:` prefix pins
+  //    a claim to that repo, an unprefixed claim can live in any repo its
+  //    lane declares — `app:src/x` vs `lib:src/x` never cross-flag.
+  const laneOverlaps = [];
+  for (const lane of options.otherLanes ?? []) {
+    const sharedRepos = lane.repos.filter((repoId) => (activeSession.repos ?? []).includes(repoId));
+    if (sharedRepos.length === 0) {
+      continue;
+    }
+
+    const overlappingPaths = [];
+    for (const claim of activeSession.claimedPaths ?? []) {
+      const claimScope = claimRepoScope(claim, activeSession.repos ?? []);
+      for (const otherClaim of lane.claimedPaths) {
+        if (!repoScopesIntersect(claimScope, claimRepoScope(otherClaim, lane.repos))) {
+          continue;
+        }
+        if (pathsOverlap(normalizeClaimPath(claim), normalizeClaimPath(otherClaim))) {
+          overlappingPaths.push(normalizeClaimPath(claim));
+        }
+      }
+    }
+    if (overlappingPaths.length > 0) {
+      const uniquePaths = Array.from(new Set(overlappingPaths));
+      laneOverlaps.push({ laneId: lane.id, sharedRepos, overlappingPaths: uniquePaths });
+      entries.push(
+        `Active lane "${lane.id}" overlaps this lane's claimed path(s) ${uniquePaths.join(', ')} in shared repo(s) ${sharedRepos.join(', ')} — coordinate before closing.`,
+      );
+    }
+  }
+
+  return {
+    newDecisions,
+    staleBaseRevisions,
+    newSessionNotes,
+    laneOverlaps,
+    notEvaluated,
+    entries,
+  };
+}
+
+/**
+ * Notes newer than the lane start, stat-first: mature roots accumulate
+ * finalized notes forever, so content is read only for the (normally tiny)
+ * set that passes the mtime filter.
+ */
+async function listFinalizedSessionNotesSince(rootDir, sinceMs) {
+  const sessionsDir = path.join(rootDir, 'sessions');
+  let names;
+  try {
+    names = await readdir(sessionsDir);
+  } catch {
+    return [];
+  }
+
+  const candidates = await Promise.all(
+    names
+      .filter((name) => SESSION_NOTE_FILENAME_PATTERN.test(name))
+      .map(async (name) => {
+        const filePath = path.join(sessionsDir, name);
+        try {
+          const fileStat = await stat(filePath);
+          return fileStat.mtimeMs > sinceMs ? { name, filePath, mtimeMs: fileStat.mtimeMs } : null;
+        } catch {
+          return null;
+        }
+      }),
+  );
+
+  const notes = [];
+  for (const candidate of candidates.filter(Boolean).sort((left, right) => left.name.localeCompare(right.name))) {
+    try {
+      notes.push({
+        relativePath: `sessions/${candidate.name}`,
+        mtimeMs: candidate.mtimeMs,
+        content: await readFile(candidate.filePath, 'utf8'),
+      });
+    } catch {
+      // A note that disappears mid-scan is not staleness.
+    }
+  }
+
+  return notes;
+}
+
+/**
+ * Scope-overlap heuristics between a finalized note and the lane. Claimed
+ * paths match only against backticked path-like tokens in the note (session
+ * notes reference files in backticks by convention) with repo scoping — an
+ * unanchored substring scan would make directory claims like `src/` match
+ * virtually every note. Feature slugs match by mention; repos only via
+ * backticked `repo:path` references (a bare repo id matches too much prose
+ * to be a signal).
+ */
+function describeNoteScopeOverlap(content, activeSession) {
+  const reasons = [];
+  const lowerContent = content.toLowerCase();
+  const noteTokens = Array.from(content.matchAll(/`([^`\n]+)`/g))
+    .map((match) => match[1].trim())
+    .filter((token) => token.includes('/') || token.includes(':'));
+
+  for (const claim of activeSession.claimedPaths ?? []) {
+    const claimPath = normalizeClaimPath(claim);
+    if (!claimPath) {
+      continue;
+    }
+    const claimScope = claimRepoScope(claim, activeSession.repos ?? []);
+    const matched = noteTokens.some((token) => {
+      const tokenRepoMatch = token.match(/^([^:/\s]+):(.+)$/);
+      if (tokenRepoMatch && claimScope && !claimScope.includes(tokenRepoMatch[1])) {
+        return false;
+      }
+      const tokenPath = normalizePath(tokenRepoMatch ? tokenRepoMatch[2] : token).replace(/\/+$/, '');
+      return tokenPath !== '' && pathsOverlap(claimPath, tokenPath);
+    });
+    if (matched) {
+      reasons.push(`mentions claimed path ${claimPath}`);
+    }
+  }
+
+  for (const feature of activeSession.featureSlugs ?? []) {
+    if (feature && lowerContent.includes(feature.toLowerCase())) {
+      reasons.push(`mentions lane feature "${feature}"`);
+    }
+  }
+
+  for (const repoId of activeSession.repos ?? []) {
+    const referencePattern = new RegExp(`\`${escapeRegExp(repoId)}:[^\`\\n]+\``);
+    if (referencePattern.test(content)) {
+      reasons.push(`references repo "${repoId}" files`);
+    }
+  }
+
+  return reasons;
+}
+
+/**
+ * A claim's possible repo scope: an explicit `repo:` prefix pins it, an
+ * unprefixed claim can live in any repo its lane declares. null means the
+ * scope is unknowable and intersects everything (conservative for a warning
+ * surface).
+ */
+function claimRepoScope(claim, laneRepos) {
+  const match = String(claim).match(/^([^:/\s]+):/);
+  if (match) {
+    return [match[1]];
+  }
+
+  return Array.isArray(laneRepos) && laneRepos.length > 0 ? laneRepos : null;
+}
+
+function repoScopesIntersect(left, right) {
+  if (!left || !right) {
+    return true;
+  }
+
+  return left.some((repoId) => right.includes(repoId));
+}
+
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+/** Claims may carry a repo prefix and a trailing slash; neither survives into prefix matching. */
+function normalizeClaimPath(claim) {
+  return stripRepoPrefix(claim).replace(/\/+$/, '');
+}
+
+async function listActiveLaneDirIds(activeRoot) {
+  try {
+    const entries = await readdir(activeRoot, { withFileTypes: true });
+    return entries
+      .filter((entry) => entry.isDirectory())
+      .map((entry) => entry.name)
+      .sort();
+  } catch {
+    return [];
+  }
+}
+
 async function resolveChangedFiles(options) {
   if (options.explicitChangedFiles.length > 0) {
     return normalizeChangedFiles(options.explicitChangedFiles, options.repos);
   }
 
   const changedPaths = new Set();
-  for (const filePath of await readGitStatusPaths(options.cwd)) {
-    changedPaths.add(filePath);
+  const laneWorktrees = options.laneWorktrees ?? {};
+  // A cwd equal to or inside a recorded worktree is fully covered by that
+  // worktree's prefixed scan below; running the unprefixed cwd scan too would
+  // report the same files twice, once without a repo prefix.
+  const cwdInsideRecordedWorktree = Object.values(laneWorktrees).some((worktreePath) =>
+    isPathEqualOrInside(options.cwd, worktreePath));
+  if (!cwdInsideRecordedWorktree) {
+    for (const filePath of await readGitStatusPaths(options.cwd)) {
+      changedPaths.add(filePath);
+    }
   }
 
   const repoStatusResults = await Promise.all(
     options.repos.map(async (repo) => {
-      const repoDir = resolveRepoWorkingDirectory(options.cwd, repo);
-      if (!repo?.id || !repoDir || repoDir === options.cwd) {
+      if (!repo?.id) {
+        return [];
+      }
+
+      let laneWorktree = laneWorktrees[repo.id] ?? null;
+      if (laneWorktree && !(await directoryExists(laneWorktree))) {
+        // Recorded-but-missing is benign crash residue (D-281); fall back to
+        // the source checkout rather than silently zeroing this repo's delta.
+        options.warnings?.push(
+          `Recorded worktree ${laneWorktree} for repo "${repo.id}" does not exist; scanning the source checkout instead.`,
+        );
+        laneWorktree = null;
+      }
+      const repoDir = laneWorktree ?? resolveRepoWorkingDirectory(options.workspaceDir, repo);
+      // The cwd containment skip applies only to source dirs: a cwd at or
+      // inside an unbound repo's checkout is already covered by the
+      // unprefixed scan (git status paths are toplevel-relative, so a
+      // prefixed scan would double-report every file). A recorded worktree
+      // is scanned prefixed even when it is the cwd.
+      if (!repoDir || (!laneWorktree && isPathEqualOrInside(options.cwd, repoDir))) {
         return [];
       }
 
@@ -217,16 +632,30 @@ async function readGitStatusPaths(cwd) {
   }
 }
 
-function resolveRepoWorkingDirectory(cwd, repo) {
+function isPathEqualOrInside(candidate, parentDir) {
+  const relative = path.relative(path.resolve(parentDir), path.resolve(candidate));
+  return relative === '' || (!relative.startsWith('..') && !path.isAbsolute(relative));
+}
+
+async function directoryExists(target) {
+  try {
+    await readdir(target);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function resolveRepoWorkingDirectory(workspaceDir, repo) {
   if (!repo?.id) {
     return null;
   }
 
   if (repo.path) {
-    return path.resolve(cwd, repo.path);
+    return path.resolve(workspaceDir, repo.path);
   }
 
-  return path.resolve(cwd, repo.id);
+  return path.resolve(workspaceDir, repo.id);
 }
 
 function parseGitStatusPaths(stdout) {
@@ -453,17 +882,23 @@ function pathsOverlap(left, right) {
 }
 
 function summarizeDecisionStatus(scan, activeSession) {
-  const decisionIds = scan.documents
+  const decisionEntries = scan.documents
     .filter((document) => document.kind === 'decision')
-    .flatMap((document) => document.extracted?.decision_ids ?? [])
-    .sort((left, right) => left - right);
+    .flatMap((document) => (document.extracted?.decision_ids ?? []).map((id) => ({ id, path: document.path })))
+    .sort((left, right) => left.id - right.id);
+  const decisionIds = decisionEntries.map((entry) => entry.id);
   const highestDecisionId = decisionIds.length > 0 ? decisionIds[decisionIds.length - 1] : null;
   const snapshot = activeSession?.decisionSnapshotHighestId ?? null;
+  // A:192 staleness elevation: keep the id-with-source-file detail so the
+  // pre-close staleness set can name the domain file each new decision
+  // landed in.
+  const newDecisions = snapshot === null ? [] : decisionEntries.filter((entry) => entry.id > snapshot);
 
   return {
     highestDecisionId,
     decisionSnapshotHighestId: snapshot,
-    newDecisionIds: snapshot === null ? [] : decisionIds.filter((id) => id > snapshot),
+    newDecisionIds: newDecisions.map((entry) => entry.id),
+    newDecisions,
   };
 }