@vibecompass/vibecompass 0.11.0 → 0.11.1

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 0.11.1 - 2026-07-06
+
+- Harden the per-root serialization lock for symlink-aliased memory roots: root keys now canonicalize through existing parent directories when the memory root itself does not yet exist, and nested lock holders compare held/requested roots by `realpath` before reacquiring the disk lock. This preserves reentrancy when an outer lock creates the root and an inner call reaches it through another spelling.
+- Make shared-checkout lane warnings honest about runnable isolation: unbound same-repo lanes now recommend `--branch <name> --worktree` for independent files or dev servers, including at `lane-env` where `PORT` is exported, while keeping `--claim` as the ownership-review fallback.
+- Suppress shared-checkout warnings when either the selected lane or the sibling lane is already worktree-bound, and add regression coverage for the symlink-root reentrancy and worktree-bound warning paths.
+
 ## 0.11.0 - 2026-07-03
 
 Phase 8 concurrent multi-session lanes (stages S1–S4). Highlights: a per-root

package/package.json

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

package/src/cli.js

@@ -151,7 +151,7 @@ export async function runCli(argv, io = createDefaultIo(), runtime = {}) {
     }
     if (result.runtime) {
       io.stdout.write(`Runtime: port ${result.runtime.port}, temp dir ${result.runtime.tmpDir}\n`);
-      io.stdout.write('Export into a shell with: eval "$(vibecompass lane-env)" (D-282; pass --session <lane-id> when multiple lanes are active).\n');
+      io.stdout.write('Export into a shell with: eval "$(vibecompass lane-env)" (D-282; pass --session <lane-id> when multiple lanes are active; use --worktree for independently runnable same-repo lanes).\n');
     }
     writeWarnings(io, result.warnings);
     writeAgentFileSyncResult(io, result.agentFileSync);
@@ -2290,7 +2290,7 @@ function usageText() {
     '  --session <lane-id>                  Lane to export. Omitted: nearest worktree lane marker, else the single active lane; 2+ active lanes require --session or a marker (D-277)',
     '  --json                               Print the runtime assignment as JSON instead of shell export lines',
     '  --no-conventional                    Omit the conventional PORT/TMPDIR alias exports',
-    '                                        Consume with: eval "$(vibecompass lane-env)"; defaults come from project.yaml runtime.{port_base,port_step,tmp_base}',
+    '                                        Consume with: eval "$(vibecompass lane-env)"; defaults come from project.yaml runtime.{port_base,port_step,tmp_base}; use --worktree for independent same-repo dev servers',
     '',
     'Decision-log options (append-decision / next-decision-id):',
     '  --root <path>                        Project-memory root. Defaults to .compass',

package/src/serialization.js

@@ -1,6 +1,6 @@
 import { AsyncLocalStorage } from 'node:async_hooks';
 import { randomUUID } from 'node:crypto';
-import { mkdir, readFile, rename, rm, stat, writeFile } from 'node:fs/promises';
+import { mkdir, readFile, realpath, rename, rm, stat, writeFile } from 'node:fs/promises';
 import path from 'node:path';
 
 /**
@@ -47,9 +47,9 @@ export function memoryRootLockPath(rootDir) {
  * a nested call from inside the lock holder runs immediately.
  */
 export async function withMemoryRootLock(rootDir, label, fn, options = {}) {
-  const key = path.resolve(rootDir);
+  const key = await canonicalizeMemoryRootKey(rootDir);
   const held = heldRoots.getStore();
-  if (held?.has(key)) {
+  if (await findHeldMemoryRootKey(held, key)) {
     return fn();
   }
 
@@ -78,6 +78,45 @@ export async function withMemoryRootLock(rootDir, label, fn, options = {}) {
   }
 }
 
+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;

package/src/session.js

@@ -158,6 +158,7 @@ async function startProjectSessionLocked(normalized, options, markerContext) {
     repos,
     claims,
     existingLanes,
+    hasWorktree: options?.worktree === true,
   });
   const highestDecisionId = await readHighestDecisionId(normalized.rootDir);
   const projectConfig = await readProjectConfig(normalized.projectFilePath);
@@ -850,7 +851,18 @@ export async function readLaneEnvironment(options = {}) {
     port: lane.runtime.port,
     tmpDir: lane.runtime.tmpDir,
     env,
-    warnings: [...markerContext.warnings, ...selection.warnings],
+    warnings: [
+      ...markerContext.warnings,
+      ...selection.warnings,
+      ...buildSharedCheckoutWarnings({
+        sessionId: selection.sessionId,
+        repos: lane.repos ?? [],
+        claims: lane.claims ?? [],
+        existingLanes: lanes.filter((item) => item.id !== selection.sessionId),
+        hasWorktree: Boolean(lane.worktreeContainer),
+        context: 'lane-env',
+      }),
+    ],
   };
 }
 
@@ -2017,7 +2029,21 @@ function buildOverlapWarnings(options) {
     }
 
     const sharedRepos = intersect(options.repos, lane.repos ?? []);
-    if (sharedRepos.length > 0 && options.claims.length === 0 && (lane.claims ?? []).length === 0) {
+    warnings.push(...buildSharedCheckoutWarnings({
+      sessionId: options.sessionId,
+      repos: options.repos,
+      claims: options.claims,
+      existingLanes: [lane],
+      hasWorktree: options.hasWorktree,
+      context: 'start-session',
+    }));
+
+    if (
+      sharedRepos.length > 0 &&
+      (options.hasWorktree || lane.worktreeContainer) &&
+      options.claims.length === 0 &&
+      (lane.claims ?? []).length === 0
+    ) {
       warnings.push(
         `Active session lane "${options.sessionId}" shares repo(s) ${sharedRepos.join(', ')} with "${lane.id}" without path claims; add --claim values to clarify ownership.`,
       );
@@ -2027,6 +2053,37 @@ function buildOverlapWarnings(options) {
   return warnings;
 }
 
+function buildSharedCheckoutWarnings(options) {
+  if (options.hasWorktree) {
+    return [];
+  }
+
+  const warnings = [];
+  for (const lane of options.existingLanes) {
+    if (lane.worktreeContainer) {
+      continue;
+    }
+
+    const sharedRepos = intersect(options.repos, lane.repos ?? []);
+    if (sharedRepos.length === 0) {
+      continue;
+    }
+
+    const ownershipHint = options.claims.length === 0 && (lane.claims ?? []).length === 0
+      ? ' Add --claim values when shared-checkout work is intentional so ownership is reviewable.'
+      : '';
+    const runtimeHint = options.context === 'lane-env'
+      ? ' The exported PORT is a runtime assignment, not an independently runnable dev server for a shared checkout.'
+      : '';
+    warnings.push(
+      `Active session lane "${options.sessionId}" shares repo(s) ${sharedRepos.join(', ')} with unbound lane "${lane.id}" in the same checkout. ` +
+        `Use --branch <name> --worktree when lanes need independent files or dev servers; worktrees are the isolation boundary.${runtimeHint}${ownershipHint}`,
+    );
+  }
+
+  return warnings;
+}
+
 function collectLaneMetadataWarnings(lanes) {
   return lanes.flatMap((lane) => lane.warnings ?? []);
 }