@vibecompass/vibecompass 0.10.7 → 0.11.0

package/src/project-memory.js

@@ -34,8 +34,12 @@ const KNOWN_PROJECT_FIELDS = new Set([
   'repos',
   'default_branch',
   'sync',
+  'runtime',
   'metadata',
 ]);
+// D-282 runtime-isolation settings; deep value validation (ranges, absolute
+// paths) lives at the consumption point in lane-runtime.js.
+const KNOWN_RUNTIME_FIELDS = new Set(['port_base', 'port_step', 'tmp_base']);
 const KNOWN_REPO_FIELDS = new Set(['id', 'source', 'remote', 'path', 'default_branch']);
 const KNOWN_SYNC_FIELDS = new Set([
   'provider',
@@ -97,7 +101,12 @@ export async function scanProjectMemory(rootDir) {
   const sessionDocuments = await parseMarkdownTree({
     rootDir,
     directoryName: 'sessions',
-    shouldInclude: (filename) => !NON_CANONICAL_SESSION_FILES.has(filename),
+    // D-278: everything under sessions/active/ is local-only lane scratch,
+    // never canonical — a stray lane-local file (e.g. a plan note) must not
+    // fail-close the whole scan as a malformed session note. The filename set
+    // still covers the legacy root-level wip.md/handoff.md.
+    shouldInclude: (filename, relativePath) =>
+      !NON_CANONICAL_SESSION_FILES.has(filename) && !relativePath.startsWith('sessions/active/'),
     parseDocument: (documentPath, relativePath, content) =>
       parseSessionDocument({
         content,
@@ -336,6 +345,23 @@ function validateProjectData(data, relativePath) {
     }
   }
 
+  if (data.runtime !== undefined) {
+    if (!isPlainObject(data.runtime)) {
+      warnings.push(
+        createWarning(
+          'project-runtime-invalid',
+          'project.yaml "runtime" must be a mapping of runtime-isolation settings (D-282); the defaults apply.',
+        ),
+      );
+    } else {
+      for (const key of Object.keys(data.runtime)) {
+        if (!KNOWN_RUNTIME_FIELDS.has(key)) {
+          warnings.push(createWarning('project-runtime-unknown-field', `Unknown project.yaml runtime field "${key}".`));
+        }
+      }
+    }
+  }
+
   if (data.metadata !== undefined && JSON.stringify(data.metadata).length > 500) {
     warnings.push(
       createWarning(

package/src/refresh-workflow.js

@@ -6,11 +6,19 @@ import { serializeProjectConfig } from './project-yaml.js';
 import { buildWorkflowScaffoldFiles } from './scaffold.js';
 import { parseSimpleYaml } from './simple-yaml.js';
 import { syncAgentInstructionFiles } from './generators/agent-files/index.js';
+import { withMemoryRootLock } from './serialization.js';
 import { PACKAGE_VERSION } from './version.js';
 
 export async function refreshWorkflow(options = {}) {
   const cwd = options.cwd ? path.resolve(options.cwd) : process.cwd();
   const rootDir = path.resolve(cwd, options.rootDir ?? '.compass');
+  if (!options.apply) {
+    return refreshWorkflowResolved(options, cwd, rootDir);
+  }
+  return withMemoryRootLock(rootDir, 'refresh-workflow', () => refreshWorkflowResolved(options, cwd, rootDir));
+}
+
+async function refreshWorkflowResolved(options, cwd, rootDir) {
   const toolingRootDir = options.toolingRootDir
     ? path.resolve(cwd, options.toolingRootDir)
     : cwd;

package/src/scaffold.js

@@ -222,16 +222,22 @@ This workspace uses VibeCompass project memory rooted at \`${rootRelativePath}\`
 ## Derived and scratch files
 - \`${rootRelativePath}/context.md\` — generated AI-facing workflow context
 - \`${rootRelativePath}/state/manifest.json\` — machine-owned local state; do not hand-edit
-- \`${rootRelativePath}/sessions/active/index.yaml\` — active session lane index and current lane pointer
-- \`${rootRelativePath}/sessions/active/<lane-id>/session.yaml\` — lane metadata
+- \`${rootRelativePath}/sessions/active/index.yaml\` — active session lane inventory and continuity pointer
+- \`${rootRelativePath}/sessions/active/<lane-id>/session.yaml\` — lane metadata (including the recorded \`lane_marker\` when one exists)
 - \`${rootRelativePath}/sessions/active/<lane-id>/wip.md\` — lane-local builder scratchpad
 - \`${rootRelativePath}/sessions/active/<lane-id>/handoff.md\` — lane-local builder/reviewer relay
+- \`.vibecompass-lane.yaml\` — worktree-local lane marker (D-280); lives outside the memory root, written only by \`vibecompass write-lane-marker\` or worktree provisioning, never synced
+- \`${rootRelativePath}/decisions/INDEX.md\` — derived grouped decision index; refresh with \`vibecompass refresh-decision-index\` (D-283, structure-preserving) instead of hand-editing rows
 
 ## Session model
 - VibeCompass active builder sessions are named lanes. Use one lane per active feature or workstream.
 - \`vibecompass start-session\` requires \`--id <lane-id>\` so each active lane has a meaningful feature or workstream name.
 - The active lane scratch files live under \`${rootRelativePath}/sessions/active/<lane-id>/\`.
-- \`${rootRelativePath}/sessions/active/index.yaml\` is the authoritative current lane pointer; the tool-specific Current session block is a human-readable continuity summary, not the lane-selection source of truth.
+- Lane selection follows D-277: an explicit \`--session\` wins, then the nearest worktree lane marker (\`.vibecompass-lane.yaml\`, walking up from cwd), then the single active lane. With two or more active lanes there is no implicit current-lane fallback.
+- \`${rootRelativePath}/sessions/active/index.yaml\` is the lane inventory; its \`current\` pointer and the tool-specific Current session block are human-readable continuity summaries, not the lane-selection source of truth.
+- Optional git binding (D-281): \`start-session --branch <name> --repo <id> [--worktree]\` creates or reuses the branch in every bound repo; \`--worktree\` additionally provisions per-repo worktrees under \`<workspace>/worktrees/<lane-id>/<repo-id>\` with the lane marker written into the container, so commands run from inside a worktree need neither \`--root\` nor \`--session\`. Binding is opt-in and git is never required for lanes.
+- At close, \`close-session\` removes a bound lane's recorded clean worktrees (guarded and never forced: dirty, in-use, or unverifiable worktrees survive with guidance, the lane marker is kept while any worktree survives, and branches are never deleted). Do not hand-remove provisioned worktrees; follow the printed guidance instead.
+- Every lane gets a per-lane runtime assignment at start (D-282): a lane port and temp dir recorded in \`session.yaml\` and exported with \`eval "$(vibecompass lane-env)"\` (includes conventional \`PORT\`/\`TMPDIR\` aliases), so parallel lanes never fight over dev-server ports or temp paths. Defaults are configurable under \`project.yaml\` \`runtime:\`; \`close-session\` removes the lane temp dir under guards.
 - Finalized sessions are append-only notes named \`${rootRelativePath}/sessions/YYYY-MM-DD-N-title.md\`; multiple sessions on the same day increment \`N\`.
 - Decisions remain append-only and independent from session notes. A session note may reference decisions, but the decision entry in \`${rootRelativePath}/decisions/\` is the durable decision record for this root.
 
@@ -256,20 +262,21 @@ ${renderWorkflowDefaults(workflow)}
 
 ## Documentation coverage
 - The architecture, decision, and session files created by init are an initial scaffold, not a comprehensive codebase review.
-- Before risky implementation work, inspect the relevant code and update the affected architecture docs.
+- Comprehensive \`docs review\` establishes a breadth-first baseline first: inventory the project, propose a coverage plan, create compact accepted docs, and leave deferred/missing areas visible before focused deepening.
+- Before implementation work on a specific feature, inspect the relevant architecture docs, decisions, coverage/documentation-plan state if present, and source files. If the area is missing, partial, or has never been deepened enough for the build, record that gap in the lane scratch and use \`docs update\`, a focused docs-review/deepening pass, or an explicit deferral before close-out.
 - Use \`vibecompass docs-update --session <lane-id>\` during a session for a targeted maintenance plan based on changed files, lane claims, session repos/features, and new decisions. This is a session-delta planner, not a broad architecture review.
 - Use the \`docs review\` prompt command when you want the current AI session to run a comprehensive documentation review. It may run \`vibecompass docs-review --guided\` as package mechanics to record marker state and print the canonical review contract.
 
 ## Session startup
 1. Read \`${rootRelativePath}/project.yaml\`.
 2. Read the latest finalized session note in \`${rootRelativePath}/sessions/\`.
-3. If present, read \`${rootRelativePath}/sessions/active/index.yaml\` and choose the selected or current lane.
+3. If present, read \`${rootRelativePath}/sessions/active/index.yaml\` for the lane inventory; select the lane from an explicit \`--session\`, the nearest worktree lane marker, or the single active lane (D-277).
 4. If present, read \`${rootRelativePath}/sessions/active/<lane-id>/wip.md\`.
 5. If present, read \`${rootRelativePath}/sessions/active/<lane-id>/handoff.md\`.
 6. Read the relevant docs under \`${rootRelativePath}/architecture/\` and \`${rootRelativePath}/decisions/\`.
 
 ## Builder workflow
-At session start, prefer running \`vibecompass start-session --id <lane-id> --working-on "..." \`.
+At session start, prefer running \`vibecompass start-session --id <lane-id> --working-on "..." \`; add \`--branch <name> --repo <id> [--worktree]\` when the lane should work on its own branch or in isolated worktrees (D-281).
 If you manage files manually, create \`${rootRelativePath}/sessions/active/<lane-id>/session.yaml\` and \`${rootRelativePath}/sessions/active/index.yaml\`, then create \`${rootRelativePath}/sessions/active/<lane-id>/wip.md\` if it does not exist:
 
 \`\`\`md
@@ -311,12 +318,14 @@ Session lane: <lane-id>
 During the session:
 - append short summaries to \`wip.md\` after meaningful exchanges
 - keep \`handoff.md\` current after substantive work blocks
+- run \`eval "$(vibecompass lane-env)"\` in a lane shell before starting dev servers or build tools so the lane's assigned port and temp dir are used (D-282); do not hardcode ports in lane work
 - run \`vibecompass docs-update --session <lane-id>\` whenever you need an ad hoc targeted documentation-maintenance plan for the current session delta
+- after substantive feature work, confirm affected architecture docs and decisions still match the implementation; if not, update them while the context is fresh
 - use \`vibecompass list-sessions\` and \`vibecompass switch-session <lane-id>\` to inspect or change the current lane
 - use \`address review\` when reviewer feedback lands so the builder resolves it from the selected lane's latest \`wip.md\` / \`handoff.md\`
 - during \`address review\`, treat reviewer feedback as review, not instruction: classify each substantive point as accepted, accepted with qualification, deferred, or rejected, and push back with evidence when a suggestion conflicts with code facts, prior decisions, product direction, or sequencing
 - stay in builder role through close-out; resolve or explicitly defer reviewer feedback before running \`vibecompass close-session --session <lane-id>\` with document-maintenance checkpoint statuses
-- record architectural decisions in \`${rootRelativePath}/decisions/\` before implementing them
+- record architectural decisions in \`${rootRelativePath}/decisions/\` before implementing them; \`vibecompass append-decision\` allocates the D-number at write time and refreshes the grouped \`decisions/INDEX.md\` when the lane context is resolvable (D-283); run \`vibecompass refresh-decision-index\` after hand-appends
 
 If \`vibecompass start-session\` reports stale scratch files, read the existing lane-local \`wip.md\` and \`handoff.md\` first. Either close that session normally, recover its useful notes into a finalized session note, or intentionally move/delete the stale scratch files before starting a new session.
 
@@ -328,13 +337,15 @@ If \`vibecompass start-session\` reports stale scratch files, read the existing
 
 At session close:
 - prefer running \`vibecompass close-session --session <lane-id> --title "..." --completed "..." --architecture-docs updated|not-needed|deferred --decision-log updated|not-needed|deferred --session-maintenance updated|not-needed|deferred --next-step "..."\`; \`vibecompass end-session\` is a supported alias
-- close-session prints the same targeted docs-update plan before the document-maintenance checkpoint; use it to decide whether affected \`architecture/\`, \`decisions/\`, and active-session scratch/final note inputs are updated, not-needed, or deferred
+- close-session prints the same targeted docs-update plan — including the pre-close staleness set (new decisions since lane start, stale base revisions, newer finalized notes touching this lane's scope, claim overlap with other active lanes) — before the document-maintenance checkpoint; use it to decide whether affected \`architecture/\`, \`decisions/\`, and active-session scratch/final note inputs are updated, not-needed, or deferred
 - document-maintenance checkpoint statuses are required before close-session writes the finalized note; the package validates the status values, while the closer owns semantic doc authorship
 - follow the stored close-session defaults from \`${rootRelativePath}/project.yaml\`
 - finalize the lane-local \`wip.md\` into \`${rootRelativePath}/sessions/YYYY-MM-DD-N-title.md\`; the permanent note distills decisions, completions, blockers, and next steps rather than preserving the full \`## Review log\`
 - if a granular reviewer trail must remain durable, summarize it explicitly in the session note inputs or create a separate finalized session note before close-session deletes lane scratch files
-- delete the closed lane directory under \`${rootRelativePath}/sessions/active/<lane-id>/\`
+- close-session deletes the closed lane directory under \`${rootRelativePath}/sessions/active/<lane-id>/\` and cleans up provisioned worktrees, the lane marker, the container, and the lane temp dir when they are safely removable; leftover pieces come with printed guidance
 - refresh any affected architecture/decision docs
+- for local-primary roots with hosted sync configured, run \`vibecompass push --root ${rootRelativePath}\` after canonical docs/session files are finalized when the hosted dashboard should reflect the session; pass \`--sync-target <name>\` when using a non-default or named target
+- for hosted-only projects, there is no local authoritative push; confirm hosted dashboard/proposal/Understanding state was updated or record the refresh/apply work as deferred
 
 ## Reviewer workflow
 - use \`review handoff\` when you want the reviewer to run the next review pass
@@ -525,8 +536,9 @@ Append-only decision log for ${projectConfig.name}.
 ## Conventions
 - store canonical decision entries in domain-grouped files such as \`cross-cutting.md\`
 - never edit or delete prior decision entries
-- use headings in the form \`### D-<number> — Title\`
+- use headings in the form \`### D-<number> — Title\` (em-dash; hyphen-only headings cannot be indexed)
 - include \`**Timestamp:**\`, \`**Decision:**\`, and \`**Rationale:**\`
+- \`INDEX.md\` is a derived grouped index: refresh it with \`vibecompass refresh-decision-index\` (structure-preserving, D-283) rather than hand-editing rows; \`vibecompass append-decision\` refreshes it automatically when it can label the session group
 
 ## Example
 
@@ -559,8 +571,8 @@ Finalized session notes for ${projectConfig.name} live here.
 - \`## Next session should start with\`
 
 ## Active-session scratch files
-- \`active/index.yaml\` — active lane index and current lane pointer
-- \`active/<lane-id>/session.yaml\` — lane metadata
+- \`active/index.yaml\` — active lane inventory and continuity pointer (not a resolver with 2+ lanes; D-277)
+- \`active/<lane-id>/session.yaml\` — lane metadata, including the recorded \`lane_marker\` when one exists
 - \`active/<lane-id>/wip.md\` — builder scratchpad during an active lane
 - \`active/<lane-id>/handoff.md\` — reviewer/builder baton-pass during an active lane
 

package/src/serialization.js

@@ -0,0 +1,205 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { randomUUID } from 'node:crypto';
+import { mkdir, readFile, rename, rm, stat, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+
+/**
+ * Single-machine serialization tier for shared project-memory writers (D-276).
+ *
+ * Three layers cooperate so every package-owned writer of shared memory runs
+ * one at a time per root:
+ * - an on-disk mkdir-as-mutex lock directory under `state/` serializes across
+ *   processes (mkdir without `recursive` is atomic on APFS/ext4)
+ * - an in-process promise queue serializes concurrent async callers inside one
+ *   process, where the disk lock alone cannot arbitrate
+ * - AsyncLocalStorage tracks held roots so nested calls inside a lock holder
+ *   re-enter instead of deadlocking (e.g. close-session refreshing the
+ *   manifest, which is itself lock-wrapped)
+ *
+ * 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.
+ */
+
+const LOCK_DIR_NAME = 'memory-root.lock';
+const OWNER_FILE_NAME = 'owner.json';
+const DEFAULT_STALE_MS = 30_000;
+const DEFAULT_ATTEMPTS = 120;
+const RETRY_BASE_DELAY_MS = 25;
+const RETRY_MAX_DELAY_MS = 100;
+
+const heldRoots = new AsyncLocalStorage();
+const processQueues = new Map();
+
+export class MemoryRootLockError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'MemoryRootLockError';
+  }
+}
+
+export function memoryRootLockPath(rootDir) {
+  return path.join(path.resolve(rootDir), 'state', LOCK_DIR_NAME);
+}
+
+/**
+ * Runs `fn` while holding the serialization lock for `rootDir`. Reentrant:
+ * a nested call from inside the lock holder runs immediately.
+ */
+export async function withMemoryRootLock(rootDir, label, fn, options = {}) {
+  const key = path.resolve(rootDir);
+  const held = heldRoots.getStore();
+  if (held?.has(key)) {
+    return fn();
+  }
+
+  const previous = processQueues.get(key) ?? Promise.resolve();
+  let releaseQueue;
+  const queueSlot = new Promise((resolve) => {
+    releaseQueue = resolve;
+  });
+  processQueues.set(key, previous.then(() => queueSlot));
+  await previous;
+
+  try {
+    const ownerToken = await acquireDiskLock(key, label, options);
+    try {
+      const nextHeld = new Set(held ?? []);
+      nextHeld.add(key);
+      return await heldRoots.run(nextHeld, fn);
+    } finally {
+      await releaseDiskLock(key, ownerToken);
+    }
+  } finally {
+    releaseQueue();
+    if (processQueues.get(key) === queueSlot) {
+      processQueues.delete(key);
+    }
+  }
+}
+
+async function acquireDiskLock(key, label, options) {
+  const lockDir = memoryRootLockPath(key);
+  const attempts = options.attempts ?? DEFAULT_ATTEMPTS;
+  const staleMs = options.staleMs ?? DEFAULT_STALE_MS;
+  await mkdir(path.dirname(lockDir), { recursive: true });
+
+  for (let attempt = 1; ; attempt += 1) {
+    const ownerToken = randomUUID();
+    try {
+      await mkdir(lockDir);
+      await writeFile(
+        path.join(lockDir, OWNER_FILE_NAME),
+        `${JSON.stringify({ pid: process.pid, token: ownerToken, label, acquired_at: new Date().toISOString() })}\n`,
+        'utf8',
+      );
+      return ownerToken;
+    } catch (error) {
+      if (error?.code !== 'EEXIST') {
+        throw error;
+      }
+    }
+
+    if (await isAbandonedLock(lockDir, staleMs)) {
+      await reclaimAbandonedLock(lockDir);
+      continue;
+    }
+
+    if (attempt >= attempts) {
+      const owner = await readLockOwner(lockDir);
+      const ownerText = owner
+        ? `held by live pid ${owner.pid ?? 'unknown'} (${owner.label ?? 'unknown command'}) since ${owner.acquired_at ?? 'unknown'}`
+        : 'owner unreadable';
+      throw new MemoryRootLockError(
+        `Timed out waiting for the project-memory lock at ${lockDir} — ${ownerText}. ` +
+          'Locks held by a live process are never stolen, however long they run. ' +
+          'If no other vibecompass command is running against this root, remove the lock directory and retry.',
+      );
+    }
+
+    await delay(RETRY_BASE_DELAY_MS + Math.floor(Math.random() * RETRY_MAX_DELAY_MS));
+  }
+}
+
+/**
+ * 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
+ * between mkdir and the owner write). A lock held by a live process is NEVER
+ * treated as stale, regardless of age — long-running holders time out waiters
+ * with an actionable error instead of being silently stolen.
+ */
+async function isAbandonedLock(lockDir, staleMs) {
+  const owner = await readLockOwner(lockDir);
+
+  if (owner && Number.isInteger(owner.pid)) {
+    return !isProcessAlive(owner.pid);
+  }
+
+  try {
+    const stats = await stat(lockDir);
+    return Date.now() - stats.mtimeMs > staleMs;
+  } catch (error) {
+    if (error?.code === 'ENOENT') {
+      return false;
+    }
+    throw error;
+  }
+}
+
+/**
+ * Reclaims an abandoned lock via atomic rename so racing waiters cannot
+ * double-free: exactly one contender wins the rename and deletes the moved
+ * directory; the others see ENOENT and simply retry the mkdir claim. This can
+ * never delete a freshly acquired lock, because a new claim creates a new
+ * directory at the original path rather than reusing the renamed one.
+ */
+async function reclaimAbandonedLock(lockDir) {
+  const reclaimPath = `${lockDir}.reclaim-${process.pid}-${randomUUID()}`;
+  try {
+    await rename(lockDir, reclaimPath);
+  } catch (error) {
+    if (error?.code === 'ENOENT') {
+      return;
+    }
+    throw error;
+  }
+  await rm(reclaimPath, { recursive: true, force: true });
+}
+
+/**
+ * Releases only a lock this caller still owns (token compare), so a holder
+ * whose lock was reclaimed after a crash-recovery cannot delete a successor's
+ * live lock.
+ */
+async function releaseDiskLock(key, ownerToken) {
+  const lockDir = memoryRootLockPath(key);
+  const owner = await readLockOwner(lockDir);
+  if (owner?.token !== ownerToken) {
+    return;
+  }
+  await rm(lockDir, { recursive: true, force: true });
+}
+
+async function readLockOwner(lockDir) {
+  try {
+    return JSON.parse(await readFile(path.join(lockDir, OWNER_FILE_NAME), 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function isProcessAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    // EPERM means the process exists but belongs to another user.
+    return error?.code === 'EPERM';
+  }
+}
+
+function delay(ms) {
+  return new Promise((resolve) => {
+    setTimeout(resolve, ms);
+  });
+}