@vibecompass/vibecompass 0.10.8 → 0.11.1

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.
 
@@ -264,13 +270,13 @@ ${renderWorkflowDefaults(workflow)}
 ## 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
@@ -312,13 +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.
 
@@ -330,12 +337,12 @@ 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
@@ -529,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
 
@@ -563,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,244 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { randomUUID } from 'node:crypto';
+import { mkdir, readFile, realpath, 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 = await canonicalizeMemoryRootKey(rootDir);
+  const held = heldRoots.getStore();
+  if (await findHeldMemoryRootKey(held, 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 canonicalizeMemoryRootKey(rootDir) {
+  const resolved = path.resolve(rootDir);
+  try {
+    return await realpath(resolved);
+  } catch {
+    try {
+      return path.join(await realpath(path.dirname(resolved)), path.basename(resolved));
+    } catch {
+      return resolved;
+    }
+  }
+}
+
+async function findHeldMemoryRootKey(held, key) {
+  if (!held) {
+    return null;
+  }
+
+  if (held.has(key)) {
+    return key;
+  }
+
+  for (const heldKey of held) {
+    if (await memoryRootKeysReferToSamePath(heldKey, key)) {
+      return heldKey;
+    }
+  }
+
+  return null;
+}
+
+async function memoryRootKeysReferToSamePath(left, right) {
+  try {
+    return (await realpath(left)) === (await realpath(right));
+  } catch {
+    return false;
+  }
+}
+
+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);
+  });
+}