@vibecompass/vibecompass 0.17.0 → 0.17.2

package/CHANGELOG.md

@@ -1,5 +1,89 @@
 # Changelog
 
+## 0.17.2 - 2026-10-12
+
+Lockstep release with the app's lineage port: section headings open a fence
+only where masking does, commands leave nothing behind on an uninitialized root,
+agent files show a repo's remote beside its local path, `init` ignores lane
+scratch, and the scanner's section warnings read headings fence-aware. The
+lane brief stays opt-in (D-368).
+
+- Lineage: section headings in architecture docs and session notes now open a
+  fence only where masking does. A backtick fence's info string holds no
+  backtick, so a prose line that starts with backticks, such as
+  ```` ```a`b ````, no longer hides every later heading of the file. Before,
+  the decisions listed under a later `## Decisions made` heading were missed as
+  `made` relations, and later citations were filed under the wrong section.
+  Tilde fences may still hold backticks in their info string. A shared golden
+  fixture pair (`note-fence-opener`, `doc-fence-opener`) pins the rule for the
+  app port.
+- Commands no longer leave directories behind on an uninitialized root. A
+  write command run against a missing root (or a folder holding no project
+  memory) left an empty `state/` directory, and the root folder itself, behind
+  before it failed. The cross-process lock still serializes every command
+  there, since `bootstrap` and `apply-export` from an external bundle can
+  create a root, but at release it removes the directories it made while they
+  are still empty. Session commands report the missing root instead of a
+  missing `project.yaml`.
+- Agent files and `context.md` show a Git repo's remote when `project.yaml` also
+  records its local `path:`, as `<remote> (local path <path>)`. Before, any repo
+  with a path read as a local folder. Local-folder sources and repos without a
+  path read as before; run `vibecompass sync-agents` to refresh managed blocks.
+- `init` adds `sessions/active/` to the root's `.gitignore` beside `state/`, so
+  a versioned memory root never commits local-only lane scratch (D-278). It
+  appends only the entries a `.gitignore` lacks. An existing root's
+  `.gitignore` is not changed; add the line yourself.
+- Scanner: the recommended-section warnings for architecture docs and session
+  notes ignore headings inside fenced code, with the read model's fence-aware
+  reader. A fenced example `## Description` no longer hides a missing real
+  section.
+
+## 0.17.1 - 2026-10-07
+
+Hardening release: decision lineage fails soft, the read model reads sections
+fence-aware, and close-session no longer leaves half-deleted worktrees. The lane
+brief stays opt-in (D-368).
+
+- Lineage fails soft (D-371): when the lineage parser throws on a file, the read
+  model still loads and `decision_lineage.status` is `unavailable`, listing the
+  file in `unavailable_sources` with a `lineage-extraction-failed` diagnostic
+  (the error's class and first line, at most 200 characters). Relations, counts,
+  and `getDecisionLineage`'s lists are null, never empty. `getProjectContext`
+  gains a `decision_lineage` status, so Local MCP's project context shows it.
+  Before, one parser exception failed the whole read model: the brief, every
+  Local MCP read, and agent-file sync. Available lineage is unchanged, with the
+  same relation records and contract version 1.
+- Brief: with lineage unavailable, the brief abstains. It is `incomplete`, shows
+  the lane only, and lists the file lineage could not be read from, the
+  overview, and `decisions/INDEX.md` as required reads. A lane `brief.md`
+  written then records a failed generation, so `continue-session` regenerates
+  it.
+- Read model (D-372): architecture component sections (Description, Details,
+  Next steps, Retrieval guidance, Review metadata, Involved files) are read
+  fence-aware, and the first section of a title wins. A heading inside a fenced
+  example no longer replaces the real section (for example a sample
+  `## Description` in a schema doc). It is the brief's reader, now shared.
+- Lineage: section headings in architecture docs and session notes now follow
+  the closing-fence rule that 0.17.0 gave masking. A fence closes only on a
+  line of its opener's own character, so a mixed line such as ```` ```~~~ ````
+  no longer ends an example early. In 0.17.0 a sample `## Decisions made`
+  heading after such a line could be taken as the note's listing, making a
+  false `made` relation and missing the real ones, and later real headings
+  could be read as fenced. A shared golden fixture pair
+  (`decisions-fence-closing`, `note-fence-closing`) pins the rule for the app
+  port.
+- close-session: git removes a lane's worktrees with no time limit. A removal
+  killed by the 120-second limit while deleting a full `node_modules` left a
+  half-deleted checkout that the next close counted as modified. Git still
+  refuses locked worktrees, worktrees with submodules, and modified ones before
+  it deletes anything.
+- Tests: the lane-runtime settings test passes inside a `lane-env` shell.
+
+Not listed in 0.17.0's notes, though it shipped there: masking and decision
+entry structure closed a fence only on a line of its opener's own character,
+so a sample `**Supersedes:**` line after a mixed ```` ```~~~ ```` line no longer
+declared false lineage.
+
 ## 0.17.0 - 2026-10-03
 
 Session brief retrieval and framing fixes (recall plan A7). The lane brief stays

package/README.md

@@ -162,7 +162,9 @@ npx -y @vibecompass/vibecompass@latest brief --root .compass --session auth-flow
 # (guarded, never forced; branches are never deleted); dirty or in-use
 # worktrees survive with guidance and the lane marker stays as a breadcrumb.
 # Gitignored files (e.g. .env) do not count as dirty and are deleted with a
-# clean worktree — copy ignored local files out before closing.
+# clean worktree — copy ignored local files out before closing. Git does the
+# removal with no time limit, so a large node_modules can take a while; it
+# keeps locked worktrees and worktrees with submodules.
 # close-session and docs-update also print a pre-close staleness set: new
 # decisions since lane start, stale base revisions, newer finalized notes
 # that mention the lane's scope, and claim overlap with other active lanes.
@@ -228,6 +230,9 @@ npx -y @vibecompass/vibecompass@latest docs-review --root .compass --rebuild --a
 
 Docs review writes derived state under `state/`, including scanned source
 inventory, accepted coverage, and the accepted documentation-plan projection.
+`init` adds `state/` and `sessions/active/` (local-only lane scratch) to the
+root's `.gitignore`. A command that fails in a folder that is not a project
+memory root yet leaves nothing behind there.
 
 Generated agent files can also include managed VibeCompass blocks:
 
@@ -268,7 +273,9 @@ own text explicitly declares that it replaces or amends it, and the brief never
 claims that a decision governs your task. It cannot spot a replacement that is
 only implied, so read the follow-up list too. When the task's distinctive words
 match nothing in memory, the status is `no-match`, with at most four nearby
-reads that share the task's other words.
+reads that share the task's other words. If decision lineage cannot be read
+from a file, the brief shows no decisions or docs: it is `incomplete` and lists
+that file, the overview, and the decision index to read first.
 
 The brief in a session lane is an experiment you turn on (D-368):
 
@@ -416,8 +423,13 @@ the parser cannot certify is `unknown`. Every relation carries its source
 path, section, line, and content hashes. `getDecisionLineage(readModel, id)`
 returns one decision's incoming and outgoing lineage and its declared
 successors, followed transitively. Nothing is ever reported as "governs" or
-"currently valid". Architecture components also carry `retrieval_guidance`
-and `retrieval_scope` when their docs define them.
+"currently valid". If the parser throws on any file, `decision_lineage.status`
+is `unavailable`, with the file in `unavailable_sources` and null relations
+and counts, never empty ones; the rest of the read model still loads, and
+`getProjectContext` reports the lineage status. Architecture components also
+carry `retrieval_guidance` and `retrieval_scope` when their docs define them;
+their sections are read fence-aware, so a heading inside a code example never
+replaces a real section.
 
 `buildSessionBrief({ rootDir, task, files, featureSlugs, claims, laneId, budget })`
 is the read-only engine behind `vibecompass brief`: it returns the selection

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vibecompass/vibecompass",
-  "version": "0.17.0",
+  "version": "0.17.2",
   "description": "Local-first project-memory core for VibeCompass",
   "type": "module",
   "bin": {

package/src/brief.js

@@ -6,6 +6,7 @@ import { compileBriefExclusions, readBriefSettingsForRoot, validateExcludePatter
 import { collectDeclaredSuccessors, parseDecisionEntries, scanDecisionReferences } from './decision-lineage.js';
 import { sha256Text, stableStringify } from './hash.js';
 import { resolveLaneMarkerContext, resolveLaneSelection, validateLaneId } from './lane-marker.js';
+import { extractSection, splitSections, stepFence } from './markdown-sections.js';
 import { loadProjectReadModelWithDocuments } from './read-model.js';
 import { parseSimpleYaml } from './simple-yaml.js';
 
@@ -119,6 +120,15 @@ export async function buildSessionBrief(options = {}) {
     }
   }
 
+  // D-371: with lineage unavailable no decision can be shown with its
+  // declared successors (D-359), so the brief abstains: the lane unit only,
+  // and the sources lineage could not be read from as required reads.
+  let lineageUnavailable = [];
+  if (!retrievalError && loaded.readModel.decision_lineage.status === 'unavailable') {
+    lineageUnavailable = loaded.readModel.decision_lineage.unavailable_sources;
+    retrievalError = `decision lineage is unavailable (D-371): it could not be extracted from ${describePaths(lineageUnavailable.map((source) => source.path))}, so no decision can be shown with its declared successors`;
+  }
+
   const overviewExcluded = exclusions?.matches(BRIEF_OVERVIEW_PATH) ?? false;
   const overviewExists = !overviewExcluded && (await pathExists(path.join(input.rootDir, BRIEF_OVERVIEW_PATH)));
   if (!overviewExists) {
@@ -149,7 +159,7 @@ export async function buildSessionBrief(options = {}) {
   };
 
   if (retrievalError) {
-    return finalizeRetrievalFailure(context, retrievalError);
+    return finalizeRetrievalFailure(context, retrievalError, lineageUnavailable);
   }
 
   const selection = selectCandidates(context, loaded, task);
@@ -1241,8 +1251,17 @@ function buildFollowUps(selection, context, included, omitted) {
   }
   entries.push(...requiredDecisions.sort((left, right) => right.decision_id - left.decision_id));
 
-  // A failed retrieval can still point at the fixed entry points.
+  // A failed retrieval can still point at the fixed entry points, after the
+  // sources lineage could not be read from (D-371).
   if (selection.retrievalError) {
+    for (const source of selection.lineageUnavailable ?? []) {
+      entries.push({
+        priority: 'required',
+        path: source.path,
+        heading: null,
+        reason: 'decision lineage could not be extracted from this file (D-371); read it directly',
+      });
+    }
     if (context.overview.exists) {
       entries.push({ priority: 'required', path: BRIEF_OVERVIEW_PATH, heading: null, reason: 'whole-project orientation' });
     }
@@ -1328,8 +1347,14 @@ function lineageReads(unit, priority) {
     }));
 }
 
-function finalizeRetrievalFailure(context, reason) {
-  return packBrief(context, { retrievalError: reason, terms: [], distinctive: [], relations: [], nearby: [] });
+function finalizeRetrievalFailure(context, reason, lineageUnavailable = []) {
+  return packBrief(context, { retrievalError: reason, lineageUnavailable, terms: [], distinctive: [], relations: [], nearby: [] });
+}
+
+/** Up to three paths, then "+N more". */
+function describePaths(paths) {
+  const shown = paths.slice(0, 3).map((value) => `\`${value}\``);
+  return paths.length > 3 ? `${shown.join(', ')} and ${paths.length - 3} more` : shown.join(', ');
 }
 
 /**
@@ -1379,31 +1404,6 @@ function buildDecisionAnchors(documents, decisionIds) {
   return new Map([...anchors].map(([id, sentences]) => [id, [...sentences].join('\n')]));
 }
 
-/**
- * One line of fenced-code tracking, with the rules of `findFencedRanges` in
- * `decision-lineage.js`. A fence opens on three or more backticks or tildes
- * indented at most three spaces; a backtick fence's info string has no
- * backtick. It closes only on a line holding the same character at least as
- * many times and nothing else (no other character, so ```~~~ never closes), so
- * a ``` line inside a ```` example stays code.
- */
-function stepFence(fence, line) {
-  const marker = line.match(/^ {0,3}(`{3,}|~{3,})/);
-  if (fence) {
-    const closes = marker && marker[1][0] === fence.char && marker[1].length >= fence.length && closingFence(fence.char).test(line);
-    return { fence: closes ? null : fence, delimiter: Boolean(closes) };
-  }
-  if (marker && !(marker[1][0] === '`' && line.slice(line.indexOf(marker[1]) + marker[1].length).includes('`'))) {
-    return { fence: { char: marker[1][0], length: marker[1].length }, delimiter: true };
-  }
-  return { fence: null, delimiter: false };
-}
-
-/** A closing fence line: only the opener's character (three or more), then whitespace — never mixed delimiters. */
-function closingFence(char) {
-  return char === '`' ? /^ {0,3}`{3,}\s*$/ : /^ {0,3}~{3,}\s*$/;
-}
-
 /** Paragraphs, list items, and table rows of a markdown body with their level-2 section, fence-aware. */
 function markdownBlocks(content) {
   const body = content.replace(/^---\r?\n[\s\S]*?\r?\n---[ \t]*(?:\r?\n|$)/, '');
@@ -1583,39 +1583,6 @@ function docSectionFields(content, component) {
   };
 }
 
-/**
- * Level-2 sections of a markdown body, fence-aware: headings inside fenced
- * code are content, and the first section with a given title wins (docs such
- * as `file-schema.md` show example `## Description` blocks in fences).
- */
-function splitSections(content, level = 2) {
-  const sections = new Map();
-  if (!content) return sections;
-  const lines = content.split(/\r?\n/);
-  const heading = new RegExp(`^#{1,${level}}\\s`);
-  const exact = new RegExp(`^#{${level}}\\s+(.+?)\\s*$`);
-  let fence = null;
-  let current = null;
-  for (const line of lines) {
-    const step = stepFence(fence, line);
-    const fenced = fence !== null || step.delimiter;
-    fence = step.fence;
-    if (!fenced && heading.test(line)) {
-      const match = line.match(exact);
-      current = match && !sections.has(match[1]) ? { title: match[1], lines: [] } : null;
-      if (current) sections.set(current.title, current);
-      continue;
-    }
-    if (current) current.lines.push(line);
-  }
-  return new Map([...sections].map(([title, section]) => [title, section.lines.join('\n').trim() || null]));
-}
-
-/** Body of a level-2 section (`## Title`), trimmed; null when absent. */
-export function extractSection(content, title) {
-  return splitSections(content, 2).get(title) ?? null;
-}
-
 /** Body of `### sub` inside `## section`; null when absent. */
 function extractSubsection(content, section, sub) {
   return splitSections(extractSection(content, section), 3).get(sub) ?? null;

package/src/cli.js

@@ -74,9 +74,9 @@ export async function runCli(argv, io = createDefaultIo(), runtime = {}) {
     }
     io.stdout.write(`Wrote ${result.projectFilePath}\n`);
     if (result.gitignoreUpdated) {
-      io.stdout.write(`Updated ${result.gitignorePath} to ignore state/\n`);
+      io.stdout.write(`Updated ${result.gitignorePath} to ignore state/ and sessions/active/\n`);
     } else {
-      io.stdout.write(`${result.gitignorePath} already ignored state/\n`);
+      io.stdout.write(`${result.gitignorePath} already ignored state/ and sessions/active/\n`);
     }
     io.stdout.write(
       `Generated ${result.manifestPath} (${result.manifest.canonical.document_count} canonical docs, ${result.manifest.canonical.warning_count} warnings)\n`,

package/src/decision-lineage.js

@@ -309,30 +309,37 @@ export function extractDecisionFileRelations({ path, content }) {
 /**
  * Builds the corpus-wide lineage view over scanned canonical documents
  * (`{ path, kind, content }`): every relation plus `target_exists`, the
- * diagnostics, and per-relation counts.
+ * diagnostics, and per-relation counts, with `status: 'available'`.
+ *
+ * D-371: each lineage source is extracted inside its own guard, which holds
+ * only that source's pure extraction (entry parse and relation extraction;
+ * no I/O). When any source throws, lineage is unavailable as a whole — a
+ * missing decision file can hide a declared successor of any decision — so
+ * the model carries `status: 'unavailable'`, the failed sources, and their
+ * `lineage-extraction-failed` diagnostics, with null relations and counts.
+ * Unavailable lineage is never returned as empty lineage.
  */
 export function buildDecisionLineageModel(documents) {
   const knownIds = new Set();
-  for (const document of documents) {
-    if (document.kind !== 'decision') continue;
-    for (const entry of parseDecisionEntries(document.content)) knownIds.add(entry.decision_id);
-  }
-
   const relations = [];
   const diagnostics = [];
+  const failures = [];
   for (const document of documents) {
-    const extractor =
-      document.kind === 'architecture'
-        ? extractArchitectureDocCitations
-        : document.kind === 'session'
-          ? extractSessionNoteRelations
-          : document.kind === 'decision'
-            ? extractDecisionFileRelations
-            : null;
-    if (!extractor) continue;
-    const result = extractor({ path: document.path, content: document.content });
-    relations.push(...result.relations);
-    diagnostics.push(...result.diagnostics);
+    if (!LINEAGE_SOURCE_KINDS.has(document.kind)) continue;
+    let extracted;
+    try {
+      extracted = extractLineageSource(document);
+    } catch (error) {
+      failures.push({ path: document.path, kind: document.kind, error: describeExtractionError(error) });
+      continue;
+    }
+    for (const id of extracted.decisionIds) knownIds.add(id);
+    relations.push(...extracted.relations);
+    diagnostics.push(...extracted.diagnostics);
+  }
+
+  if (failures.length > 0) {
+    return buildUnavailableLineageModel(failures);
   }
 
   const unresolved = new Set();
@@ -356,13 +363,101 @@ export function buildDecisionLineageModel(documents) {
 
   return {
     contract_version: DECISION_LINEAGE_CONTRACT_VERSION,
+    status: 'available',
     decision_count: knownIds.size,
     relation_counts: relationCounts,
     relations: sortRelations(withExistence),
+    unavailable_sources: [],
     diagnostics: sortDiagnostics(diagnostics),
   };
 }
 
+function buildUnavailableLineageModel(failures) {
+  const sources = [...failures].sort((left, right) => left.path.localeCompare(right.path));
+  return {
+    contract_version: DECISION_LINEAGE_CONTRACT_VERSION,
+    status: 'unavailable',
+    decision_count: null,
+    relation_counts: null,
+    relations: null,
+    unavailable_sources: sources.map(({ path, kind, error }) => ({ path, kind, error })),
+    diagnostics: sources.map(({ path, error }) => ({
+      code: 'lineage-extraction-failed',
+      path,
+      line: null,
+      message: `Decision lineage could not be extracted from this file (${error}), so lineage is unavailable for the whole root until the file changes or the extractor is fixed.`,
+    })),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Per-source extraction (D-371)
+// ---------------------------------------------------------------------------
+
+const LINEAGE_SOURCE_KINDS = new Set(['architecture', 'session', 'decision']);
+const EXTRACTION_ERROR_LIMIT = 200;
+
+/** The relations of one canonical document, by kind. */
+function extractDocumentRelations({ path, kind, content }) {
+  if (kind === 'architecture') return extractArchitectureDocCitations({ path, content });
+  if (kind === 'session') return extractSessionNoteRelations({ path, content });
+  return extractDecisionFileRelations({ path, content });
+}
+
+const DEFAULT_LINEAGE_PHASES = Object.freeze({
+  parseEntries: parseDecisionEntries,
+  extractRelations: extractDocumentRelations,
+});
+let lineagePhases = DEFAULT_LINEAGE_PHASES;
+
+/**
+ * Internal fault-injection seam for degraded-lineage tests (D-371): replaces
+ * the entry-parse and/or relation-extraction phase of per-source extraction
+ * and returns a function that restores the previous phases. It is not
+ * exported from `index.js`, so the package's `exports` map keeps it out of
+ * reach of consumers. Tests restore it in `finally`.
+ */
+export function setLineagePhasesForTesting(overrides = {}) {
+  const previous = lineagePhases;
+  lineagePhases = Object.freeze({ ...DEFAULT_LINEAGE_PHASES, ...overrides });
+  return () => {
+    lineagePhases = previous;
+  };
+}
+
+// One source's extraction: pure, synchronous, and the only code inside the
+// D-371 guard. A decision file contributes its entry IDs (known targets) and
+// its relations; a doc or note contributes relations.
+function extractLineageSource(document) {
+  const decisionIds =
+    document.kind === 'decision' ? lineagePhases.parseEntries(document.content).map((entry) => entry.decision_id) : [];
+  const result = lineagePhases.extractRelations({ path: document.path, kind: document.kind, content: document.content });
+  return { decisionIds, relations: result.relations, diagnostics: result.diagnostics };
+}
+
+/**
+ * The error class (or a thrown non-Error value's type) and the first line of
+ * its message, at most 200 code points; never a stack trace. The source path
+ * is recorded separately, so cutting this text never hides which source failed.
+ */
+function describeExtractionError(error) {
+  let text;
+  try {
+    if (error instanceof Error) {
+      const name = typeof error.name === 'string' && error.name ? error.name : 'Error';
+      const message = typeof error.message === 'string' ? error.message.split(/\r?\n/, 1)[0].trim() : '';
+      text = message ? `${name}: ${message}` : name;
+    } else {
+      const type = error === null ? 'null' : typeof error;
+      const value = typeof error === 'string' ? error.split(/\r?\n/, 1)[0].trim() : '';
+      text = value ? `thrown ${type}: ${value}` : `thrown ${type}`;
+    }
+  } catch {
+    text = 'unreadable thrown value';
+  }
+  return boundText(collapse(text), EXTRACTION_ERROR_LIMIT);
+}
+
 /**
  * Declared successors of a decision, transitively: later decisions whose own
  * text (or structured fields) declares `supersedes` or `amends` for it, and
@@ -1476,14 +1571,13 @@ export function findFencedRanges(text) {
     offset += line.length + 1;
     const marker = line.match(/^ {0,3}(`{3,}|~{3,})/);
     if (fence) {
-      // A closing fence holds only the opener's character, so ```~~~ never closes.
-      if (marker && marker[1][0] === fence.char && marker[1].length >= fence.length && (fence.char === '`' ? /^ {0,3}`+\s*$/ : /^ {0,3}~+\s*$/).test(line)) {
+      if (closesFence(fence, marker, line)) {
         ranges.push([fence.start, Math.min(offset - 1, text.length)]);
         fence = null;
       }
       continue;
     }
-    if (marker && !(marker[1][0] === '`' && line.slice(line.indexOf(marker[1]) + marker[1].length).includes('`'))) {
+    if (opensFence(marker, line)) {
       fence = { char: marker[1][0], length: marker[1].length, start: lineStart };
     }
   }
@@ -1491,6 +1585,20 @@ export function findFencedRanges(text) {
   return ranges;
 }
 
+// A fence opens on three or more backticks or tildes indented at most three
+// spaces; a backtick opener's info string holds no backtick, so ```a`b is
+// prose. Shared by masking and the section index.
+function opensFence(marker, line) {
+  return Boolean(marker) && !(marker[1][0] === '`' && line.slice(line.indexOf(marker[1]) + marker[1].length).includes('`'));
+}
+
+// A closing fence holds only the opener's character, at least as many times,
+// so ```~~~ never closes. Shared by masking and the section index.
+function closesFence(fence, marker, line) {
+  return Boolean(marker) && marker[1][0] === fence.char && marker[1].length >= fence.length &&
+    (fence.char === '`' ? /^ {0,3}`+\s*$/ : /^ {0,3}~+\s*$/).test(line);
+}
+
 function insideRanges(offset, ranges) {
   return ranges.some(([start, end]) => offset >= start && offset < end);
 }
@@ -1580,12 +1688,12 @@ function buildSectionIndex(content, bodyStart) {
 
     const fenceMatch = line.match(/^ {0,3}(`{3,}|~{3,})/);
     if (fence) {
-      if (fenceMatch && fenceMatch[1][0] === fence.char && fenceMatch[1].length >= fence.length && /^ {0,3}[`~]+\s*$/.test(line)) {
+      if (closesFence(fence, fenceMatch, line)) {
         fence = null;
       }
       continue;
     }
-    if (fenceMatch) {
+    if (opensFence(fenceMatch, line)) {
       fence = { char: fenceMatch[1][0], length: fenceMatch[1].length };
       continue;
     }

package/src/generators/agent-files/template.js

@@ -88,13 +88,15 @@ function renderProjectSnapshot(context) {
   return lines.length > 0 ? lines : ['- No project details recorded yet.'];
 }
 
+// A local-folder source shows its folder; a Git repo shows its remote, plus
+// the local path where one is recorded beside it (PC2).
 function formatRepoDescriptor(repo) {
-  if (repo?.source === 'local' || repo?.path) {
+  if (repo?.source === 'local' || (repo?.path && !repo?.remote)) {
     return `local folder ${repo.path ?? '.'}`;
   }
 
   if (repo?.remote) {
-    return repo.remote;
+    return repo.path ? `${repo.remote} (local path ${repo.path})` : repo.remote;
   }
 
   return 'source not recorded';

package/src/git-binding.js

@@ -15,6 +15,14 @@ const QUICK_GIT_TIMEOUT_MS = 5000;
 const WORKTREE_GIT_TIMEOUT_MS = 120000;
 const GIT_OUTPUT_MAX_BUFFER = 1024 * 1024;
 
+// H3: close-time removal has no kill timeout. Git is the only deleter, and it
+// makes every refusal (locked, submodules, modified or untracked files, not a
+// worktree of this repo) before it deletes anything; killing it while it
+// deletes a large tree (a full node_modules) left a half-deleted checkout that
+// the next close saw as modified. A filesystem that stalls makes close wait
+// until git finishes or the user interrupts it.
+export const WORKTREE_REMOVE_AT_CLOSE_EXEC_OPTIONS = Object.freeze({ maxBuffer: GIT_OUTPUT_MAX_BUFFER });
+
 /**
  * Repo working copies live as siblings of the memory root: the workspace is
  * `dirname(rootDir)` and a declared `repo.path` (else the repo id) resolves
@@ -396,6 +404,9 @@ export async function rollbackGitBinding(progress, branch) {
  *   container AND covered by a token-matched container marker are removable
  *   (D-279/D-280 guards — arbitrary path removal is refused)
  * - removal is never forced; a status failure counts as unknown, not clean
+ * - git is the only deleter and runs without a kill timeout (H3), so its own
+ *   refusals (lock, submodules, registration) come before any deletion and a
+ *   large ignored tree is never left half-deleted by a timer
  * - removal is skipped with guidance when the process cwd sits inside the
  *   target
  * - branches are never deleted at close
@@ -487,10 +498,16 @@ export async function removeLaneWorktreesAtClose(options) {
       await execFileAsync(
         'git',
         ['-C', sourceDir, 'worktree', 'remove', entry.worktreePath],
-        { timeout: WORKTREE_GIT_TIMEOUT_MS, maxBuffer: GIT_OUTPUT_MAX_BUFFER },
+        WORKTREE_REMOVE_AT_CLOSE_EXEC_OPTIONS,
       );
       removed.push({ repoId: entry.repoId, worktreePath: entry.worktreePath, sourceDir });
     } catch (error) {
+      if (error && typeof error === 'object' && error.signal) {
+        // No timer kills this call (H3), so a signal is an outside
+        // interruption, possibly mid-delete.
+        keep(entry, 'git-interrupted', `git was interrupted (${error.signal}) while removing it, so the checkout may be partly deleted. Inspect it before removing it.`);
+        continue;
+      }
       keep(entry, 'git-refused', `git refused the removal: ${describeGitError(error)}. Resolve that first.`);
     }
   }

package/src/init.js

@@ -34,7 +34,7 @@ export async function initializeProjectMemory(options) {
   const gitignorePath = path.join(normalized.rootDir, '.gitignore');
 
   await writeProjectFile(projectFilePath, normalized.projectConfig, normalized.force);
-  const gitignoreUpdated = await ensureStateIgnored(gitignorePath);
+  const gitignoreUpdated = await ensureLocalOnlyPathsIgnored(gitignorePath);
   const scaffoldResult = await scaffoldInitFiles(normalized.bootstrap);
   const manifestResult = await writeStateManifest(normalized.rootDir, {
     generatedAt: normalized.generatedAt,
@@ -461,22 +461,25 @@ async function writeProjectFile(projectFilePath, projectConfig, force) {
   await writeFile(projectFilePath, source, 'utf8');
 }
 
-async function ensureStateIgnored(gitignorePath) {
-  const stateEntry = 'state/';
+// Local-only paths a versioned memory root never commits: derived state, and
+// lane scratch under sessions/active/ (D-278; PC5).
+const LOCAL_ONLY_IGNORE_ENTRIES = ['state/', 'sessions/active/'];
 
+async function ensureLocalOnlyPathsIgnored(gitignorePath) {
   if (!(await fileExists(gitignorePath))) {
-    await writeFile(gitignorePath, `${stateEntry}\n`, 'utf8');
+    await writeFile(gitignorePath, `${LOCAL_ONLY_IGNORE_ENTRIES.join('\n')}\n`, 'utf8');
     return true;
   }
 
   const current = await readFile(gitignorePath, 'utf8');
   const entries = current.split(/\r?\n/).map((line) => line.trim());
-  if (entries.includes(stateEntry)) {
+  const missing = LOCAL_ONLY_IGNORE_ENTRIES.filter((entry) => !entries.includes(entry));
+  if (missing.length === 0) {
     return false;
   }
 
   const separator = current.length > 0 && !current.endsWith('\n') ? '\n' : '';
-  await writeFile(gitignorePath, `${current}${separator}${stateEntry}\n`, 'utf8');
+  await writeFile(gitignorePath, `${current}${separator}${missing.join('\n')}\n`, 'utf8');
   return true;
 }
 

package/src/markdown-sections.js

@@ -0,0 +1,65 @@
+/**
+ * The one markdown section reader shared by the read model's component fields
+ * (D-372) and the session brief (D-359): fence-aware, first section of a title
+ * wins. The lineage extractor keeps its own section index
+ * (`decision-lineage.js`), which follows the same opening and closing rules.
+ */
+
+/**
+ * One line of fenced-code tracking, with the rules of `findFencedRanges` in
+ * `decision-lineage.js`. A fence opens on three or more backticks or tildes
+ * indented at most three spaces; a backtick fence's info string has no
+ * backtick. It closes only on a line holding the same character at least as
+ * many times and nothing else (no other character, so ```~~~ never closes), so
+ * a ``` line inside a ```` example stays code.
+ */
+export function stepFence(fence, line) {
+  const marker = line.match(/^ {0,3}(`{3,}|~{3,})/);
+  if (fence) {
+    const closes = marker && marker[1][0] === fence.char && marker[1].length >= fence.length && closingFence(fence.char).test(line);
+    return { fence: closes ? null : fence, delimiter: Boolean(closes) };
+  }
+  if (marker && !(marker[1][0] === '`' && line.slice(line.indexOf(marker[1]) + marker[1].length).includes('`'))) {
+    return { fence: { char: marker[1][0], length: marker[1].length }, delimiter: true };
+  }
+  return { fence: null, delimiter: false };
+}
+
+/** A closing fence line: only the opener's character (three or more), then whitespace — never mixed delimiters. */
+function closingFence(char) {
+  return char === '`' ? /^ {0,3}`{3,}\s*$/ : /^ {0,3}~{3,}\s*$/;
+}
+
+/**
+ * Sections of a markdown body at `level` (default 2), fence-aware: headings
+ * inside fenced code are content, the first section with a given title wins
+ * (docs such as `file-schema.md` show example `## Description` blocks in
+ * fences), and a heading at that level or above ends the current section.
+ */
+export function splitSections(content, level = 2) {
+  const sections = new Map();
+  if (!content) return sections;
+  const lines = content.split(/\r?\n/);
+  const heading = new RegExp(`^#{1,${level}}\\s`);
+  const exact = new RegExp(`^#{${level}}\\s+(.+?)\\s*$`);
+  let fence = null;
+  let current = null;
+  for (const line of lines) {
+    const step = stepFence(fence, line);
+    const fenced = fence !== null || step.delimiter;
+    fence = step.fence;
+    if (!fenced && heading.test(line)) {
+      const match = line.match(exact);
+      current = match && !sections.has(match[1]) ? { title: match[1], lines: [] } : null;
+      if (current) sections.set(current.title, current);
+      continue;
+    }
+    if (current) current.lines.push(line);
+  }
+  return new Map([...sections].map(([title, section]) => [title, section.lines.join('\n').trim() || null]));
+}
+
+/** Body of a level-2 section (`## Title`), trimmed; null when absent. */
+export function extractSection(content, title) {
+  return splitSections(content, 2).get(title) ?? null;
+}

package/src/project-memory.js

@@ -3,6 +3,7 @@ import path from 'node:path';
 import { validateBriefSettings } from './brief-settings.js';
 import { parseFrontmatter } from './frontmatter.js';
 import { sha256Text } from './hash.js';
+import { splitSections } from './markdown-sections.js';
 import { parseSimpleYaml } from './simple-yaml.js';
 
 const PROJECT_FILE = 'project.yaml';
@@ -886,12 +887,11 @@ function findDuplicateDecisionErrors(documents) {
   return errors;
 }
 
+// Level-2 section titles, lowercased, read fence-aware with the section reader
+// the read model and the brief share (D-372; H10): a heading inside fenced
+// code is an example, so it never satisfies a recommended section.
 function extractLevelTwoSections(content) {
-  const sections = new Set();
-  for (const match of content.matchAll(/^##\s+(.+)$/gm)) {
-    sections.add(match[1].trim().toLowerCase());
-  }
-  return sections;
+  return new Set([...splitSections(content, 2).keys()].map((title) => title.trim().toLowerCase()));
 }
 
 // D-292 changelog-shape detector, shared by the scanner and the docs-review

package/src/read-model.js

@@ -3,9 +3,9 @@ import path from 'node:path';
 import { buildDecisionLineageModel, collectDeclaredSuccessors } from './decision-lineage.js';
 import { parseFrontmatter } from './frontmatter.js';
 import { generateStateManifest } from './manifest.js';
+import { splitSections } from './markdown-sections.js';
 import { scanProjectMemory } from './project-memory.js';
 
-const SECTION_PATTERN = /^##\s+(.+)$/gm;
 const DECISION_HEADING_PATTERN = /^###\s+D-(\d{3,})\s+—\s+(.+)$/gm;
 
 export async function loadProjectReadModel(rootDir) {
@@ -83,6 +83,12 @@ export function getProjectContext(readModel, options = {}) {
     domains: readModel.domains,
     recent_decisions: readModel.decisions.slice(0, decisionLimit),
     recent_sessions: readModel.sessions.slice(0, sessionLimit),
+    // D-371: whether decision lineage could be read, in every response, so a
+    // reader (Local MCP's project context) can tell unavailable from empty.
+    decision_lineage: {
+      status: readModel.decision_lineage.status,
+      unavailable_sources: readModel.decision_lineage.unavailable_sources,
+    },
   };
 }
 
@@ -113,7 +119,8 @@ export function getDecisionLog(readModel, options = {}) {
  * what later decisions declare about it, and `declared_successors` follows
  * declared `supersedes`/`amends` transitively. Mentions stay mentions: no
  * relation here certifies that a decision governs anything or is currently
- * valid.
+ * valid. When lineage is unavailable (D-371), `lineage_status` says so and
+ * every relation-derived value is null, never an empty list.
  */
 export function getDecisionLineage(readModel, decisionId, options = {}) {
   const id = typeof decisionId === 'number' ? decisionId : Number(String(decisionId ?? '').replace(/^D-/i, ''));
@@ -122,8 +129,27 @@ export function getDecisionLineage(readModel, decisionId, options = {}) {
   }
 
   const citationLimit = Math.max(1, Math.min(options.citationLimit ?? 50, 500));
-  const relations = readModel.decision_lineage.relations;
+  const lineage = readModel.decision_lineage;
   const decision = readModel.decisions.find((entry) => entry.decision_id === id) ?? null;
+  if (lineage.status === 'unavailable') {
+    return {
+      freshness: readModel.freshness,
+      decision_id: id,
+      exists: Boolean(decision),
+      title: decision?.title ?? null,
+      path: decision?.path ?? null,
+      lineage_status: 'unavailable',
+      unavailable_sources: lineage.unavailable_sources,
+      outgoing: null,
+      incoming: null,
+      declared_successors: null,
+      made_in: null,
+      cited_by: null,
+      cited_by_total: null,
+    };
+  }
+
+  const relations = lineage.relations;
   const lineageRelations = new Set(['supersedes', 'amends', 'preserves', 'unknown']);
   const outgoing = relations.filter(
     (relation) => relation.source_decision_id === id && lineageRelations.has(relation.relation),
@@ -142,6 +168,8 @@ export function getDecisionLineage(readModel, decisionId, options = {}) {
     exists: Boolean(decision),
     title: decision?.title ?? null,
     path: decision?.path ?? null,
+    lineage_status: 'available',
+    unavailable_sources: [],
     outgoing,
     incoming,
     declared_successors: collectDeclaredSuccessors(relations, id),
@@ -237,7 +265,9 @@ function buildFeatureMap(scanResult, repoAliases, projectRepos) {
 
 function buildComponentRecord(document, repoAliases, projectRepos) {
   const frontmatter = parseFrontmatter(document.content, { sourceName: document.path });
-  const sections = splitMarkdownSections(frontmatter.body);
+  // D-372: the brief's fence-aware reader, so a fenced example heading or a
+  // repeated title never replaces a real section.
+  const sections = splitSections(frontmatter.body, 2);
   const repoIds = uniqueSorted(document.extracted.repo_ids ?? []);
   const involvedFiles = parseInvolvedFiles({
     rawSection: sections.get('Involved files') ?? '',
@@ -418,19 +448,6 @@ function extractDecisionEntries(content, sourcePath) {
   });
 }
 
-function splitMarkdownSections(body) {
-  const sections = new Map();
-  const matches = [...body.matchAll(SECTION_PATTERN)];
-
-  for (const [index, match] of matches.entries()) {
-    const start = (match.index ?? 0) + match[0].length;
-    const end = matches[index + 1]?.index ?? body.length;
-    sections.set(match[1].trim(), body.slice(start, end).trim());
-  }
-
-  return sections;
-}
-
 function parseInvolvedFiles({ rawSection, defaultRepoIds, repoAliases, projectRepos }) {
   if (!rawSection) {
     return [];

package/src/scaffold.js

@@ -503,12 +503,18 @@ ${repoLines}
 `;
 }
 
+// A local-folder source shows its folder; a Git repo shows its remote, plus
+// the local path where one is recorded beside it (PC2).
 function formatRepoDescriptor(repo) {
-  if (repo.source === 'local' || repo.path) {
+  if (repo.source === 'local' || (repo.path && !repo.remote)) {
     return `local folder ${repo.path}`;
   }
 
-  return repo.remote ?? 'source not recorded';
+  if (repo.remote) {
+    return repo.path ? `${repo.remote} (local path ${repo.path})` : repo.remote;
+  }
+
+  return 'source not recorded';
 }
 
 function generateArchitectureGuide(projectConfig) {

package/src/serialization.js

@@ -1,6 +1,6 @@
 import { AsyncLocalStorage } from 'node:async_hooks';
 import { randomUUID } from 'node:crypto';
-import { mkdir, readFile, realpath, rename, rm, stat, writeFile } from 'node:fs/promises';
+import { mkdir, readdir, readFile, realpath, rename, rm, rmdir, stat, writeFile } from 'node:fs/promises';
 import path from 'node:path';
 
 /**
@@ -16,6 +16,15 @@ import path from 'node:path';
  *   re-enter instead of deadlocking (e.g. close-session refreshing the
  *   manifest, which is itself lock-wrapped)
  *
+ * Every command takes the disk lock, on an uninitialized root too: a locked
+ * command can create a root there (bootstrap, or apply-export from an external
+ * bundle), so skipping the lock would let two of them validate the same
+ * missing files and both write. The lock leaves nothing behind (PC1): at
+ * release it removes the directories it created to hold itself (state/, and
+ * the root when it was missing) while they are still empty, and a root the
+ * lock created still counts as missing to the command
+ * (`memoryRootCreatedByLock`).
+ *
  * This tier is intentionally local-only. Cross-machine serialization belongs
  * to git merge (local-primary teams) or the hosted database (hosted-only);
  * no distributed locking is ever built on top of this file.
@@ -28,6 +37,7 @@ const DEFAULT_ATTEMPTS = 120;
 const RETRY_BASE_DELAY_MS = 25;
 const RETRY_MAX_DELAY_MS = 100;
 
+// Held root key -> { createdRoot }: whether this lock made the root directory.
 const heldRoots = new AsyncLocalStorage();
 const processQueues = new Map();
 
@@ -88,13 +98,14 @@ export async function withMemoryRootLock(rootDir, label, fn, options = {}) {
   await previous;
 
   try {
-    const ownerToken = await acquireDiskLock(key, label, options);
+    const lock = await acquireDiskLock(key, label, options);
     try {
-      const nextHeld = new Set(held ?? []);
-      nextHeld.add(key);
+      const nextHeld = new Map(held ?? []);
+      nextHeld.set(key, { createdRoot: lock.createdRoot });
       return await heldRoots.run(nextHeld, fn);
     } finally {
-      await releaseDiskLock(key, ownerToken);
+      await releaseDiskLock(key, lock.ownerToken);
+      await removeLockCreatedDirectories(key, lock.created);
     }
   } finally {
     releaseQueue();
@@ -104,6 +115,57 @@ export async function withMemoryRootLock(rootDir, label, fn, options = {}) {
   }
 }
 
+/**
+ * Whether `rootDir` exists only because the lock this caller holds made it
+ * (PC1): the root was missing when the command started and still holds
+ * nothing but the lock, so a command that requires an existing root reports
+ * it missing instead of reading the lock's own directory as one. Once the
+ * command writes into it (bootstrap), it is a root in its own right. False
+ * outside a lock holder.
+ */
+export async function memoryRootCreatedByLock(rootDir) {
+  const held = heldRoots.getStore();
+  if (!held) {
+    return false;
+  }
+  const heldKey = await findHeldMemoryRootKey(held, await canonicalizeMemoryRootKey(rootDir));
+  if (!heldKey || !held.get(heldKey).createdRoot) {
+    return false;
+  }
+  try {
+    const rootEntries = await readdir(heldKey);
+    const stateEntries = await readdir(path.dirname(memoryRootLockPath(heldKey)));
+    return rootEntries.every((entry) => entry === 'state') && stateEntries.every((entry) => entry.startsWith(LOCK_DIR_NAME));
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Removes the directories acquisition created (state/, then the root and any
+ * missing parents up to `created`) while each is still empty (PC1). A command
+ * that wrote memory there, or another holder's lock, keeps a directory
+ * non-empty, so it stays. Two commands racing on the same missing root can
+ * leave an empty directory when the second found it already made; it never
+ * holds memory.
+ */
+async function removeLockCreatedDirectories(key, created) {
+  if (!created) {
+    return;
+  }
+  const top = path.resolve(created);
+  for (let dir = path.dirname(memoryRootLockPath(key)); ; dir = path.dirname(dir)) {
+    try {
+      await rmdir(dir);
+    } catch {
+      return;
+    }
+    if (dir === top || path.dirname(dir) === dir) {
+      return;
+    }
+  }
+}
+
 async function canonicalizeMemoryRootKey(rootDir) {
   const resolved = path.resolve(rootDir);
   try {
@@ -126,7 +188,7 @@ async function findHeldMemoryRootKey(held, key) {
     return key;
   }
 
-  for (const heldKey of held) {
+  for (const heldKey of held.keys()) {
     if (await memoryRootKeysReferToSamePath(heldKey, key)) {
       return heldKey;
     }
@@ -145,9 +207,11 @@ async function memoryRootKeysReferToSamePath(left, right) {
 
 async function acquireDiskLock(key, label, options) {
   const lockDir = memoryRootLockPath(key);
+  const stateDir = path.dirname(lockDir);
   const attempts = options.attempts ?? DEFAULT_ATTEMPTS;
   const staleMs = options.staleMs ?? DEFAULT_STALE_MS;
-  await mkdir(path.dirname(lockDir), { recursive: true });
+  // The topmost directory this acquisition created, if any (mkdir reports it).
+  let created = await mkdir(stateDir, { recursive: true });
 
   for (let attempt = 1; ; attempt += 1) {
     const ownerToken = randomUUID();
@@ -158,9 +222,17 @@ async function acquireDiskLock(key, label, options) {
         `${JSON.stringify({ pid: process.pid, token: ownerToken, label, acquired_at: new Date().toISOString() })}\n`,
         'utf8',
       );
-      return ownerToken;
+      return {
+        ownerToken,
+        created,
+        createdRoot: Boolean(created) && path.resolve(created) !== path.resolve(stateDir),
+      };
     } catch (error) {
-      if (error?.code !== 'EEXIST') {
+      if (error?.code === 'ENOENT') {
+        // A releasing holder removed the state/ (or root) it had created; make
+        // it again, and remove it at release in turn.
+        created = topmostDirectory(created, await mkdir(stateDir, { recursive: true }));
+      } else if (error?.code !== 'EEXIST') {
         throw error;
       }
     }
@@ -186,6 +258,13 @@ async function acquireDiskLock(key, label, options) {
   }
 }
 
+function topmostDirectory(left, right) {
+  if (!left || !right) {
+    return left ?? right;
+  }
+  return path.resolve(left).length <= path.resolve(right).length ? left : right;
+}
+
 /**
  * A lock is abandoned only when its owner process is provably gone (dead PID),
  * or the owner file never became readable within the grace window (a crash

package/src/session.js

@@ -16,7 +16,7 @@ import {
   removeLaneWorktreesAtClose,
   rollbackGitBinding,
 } from './git-binding.js';
-import { withMemoryRootLock } from './serialization.js';
+import { memoryRootCreatedByLock, withMemoryRootLock } from './serialization.js';
 import { findDuplicateDecisionIds, formatDecisionId } from './decisions.js';
 import {
   assignLanePort,
@@ -1782,7 +1782,9 @@ function getLanePaths(normalized, sessionId) {
 }
 
 async function ensureInitializedProjectMemory(rootDir, options = {}) {
-  if (!(await fileExists(rootDir))) {
+  // The lock makes a missing root to hold its state/ and removes it again at
+  // release (PC1), so a root it created is still missing here.
+  if (!(await fileExists(rootDir)) || (await memoryRootCreatedByLock(rootDir))) {
     throw new Error(
       `No project memory root was found at ${rootDir}. Run "vibecompass init" before using session commands.`,
     );