@vibecompass/vibecompass 0.10.8 → 0.11.1

package/src/init.js

@@ -2,6 +2,7 @@ import { access, mkdir, readFile, readdir, writeFile } from 'node:fs/promises';
 import path from 'node:path';
 import { serializeProjectConfig } from './project-yaml.js';
 import { writeStateManifest } from './manifest.js';
+import { withMemoryRootLock } from './serialization.js';
 import { scaffoldInitFiles } from './scaffold.js';
 import { applyPlacementDefaults } from './setup.js';
 import { buildWorkflowMetadata } from './workflow.js';
@@ -57,6 +58,10 @@ export async function initializeProjectMemory(options) {
 export async function connectHostedProjectMemory(options) {
   const cwd = options?.cwd ? path.resolve(options.cwd) : process.cwd();
   const rootDir = path.resolve(cwd, options?.rootDir ?? '.compass');
+  return withMemoryRootLock(rootDir, 'connect-hosted', () => connectHostedProjectMemoryLocked(options, rootDir));
+}
+
+async function connectHostedProjectMemoryLocked(options, rootDir) {
   const projectFilePath = path.join(rootDir, 'project.yaml');
   let projectConfig;
   try {
@@ -171,6 +176,10 @@ async function updateManifestSyncState(rootDir, updater) {
 export async function setDefaultSyncTarget(options) {
   const cwd = options?.cwd ? path.resolve(options.cwd) : process.cwd();
   const rootDir = path.resolve(cwd, options?.rootDir ?? '.compass');
+  return withMemoryRootLock(rootDir, 'sync-target', () => setDefaultSyncTargetLocked(options, rootDir));
+}
+
+async function setDefaultSyncTargetLocked(options, rootDir) {
   const projectFilePath = path.join(rootDir, 'project.yaml');
   const projectConfig = parseSimpleYaml(await readFile(projectFilePath, 'utf8'), {
     sourceName: projectFilePath,

package/src/lane-marker.js

@@ -0,0 +1,339 @@
+import { access, readFile, realpath } from 'node:fs/promises';
+import path from 'node:path';
+import { parseSimpleYaml } from './simple-yaml.js';
+
+// D-280: the worktree-local lane marker is a single hand-inspectable YAML file
+// written and removed only by package commands. This module owns the marker
+// contract plus the shared lane-identity primitives (lane-ID validation and
+// the D-277 selection order) so session.js and docs-update.js cannot diverge.
+export const LANE_MARKER_FILENAME = '.vibecompass-lane.yaml';
+export const LANE_MARKER_FORMAT_VERSION = 1;
+
+export const LANE_ID_PATTERN = /^[a-z0-9][a-z0-9-]{1,62}[a-z0-9]$/;
+export const RESERVED_LANE_IDS = new Set([
+  'active',
+  'current',
+  'default',
+  'false',
+  'handoff',
+  'index',
+  'new',
+  'no',
+  'null',
+  'off',
+  'on',
+  'sessions',
+  'state',
+  'true',
+  'wip',
+  'yes',
+]);
+
+export function validateLaneId(value) {
+  const normalized = value.trim();
+  if (!LANE_ID_PATTERN.test(normalized)) {
+    throw new Error('Session lane ID must be a lowercase slug 3-64 characters long using letters, numbers, and hyphens.');
+  }
+
+  if (RESERVED_LANE_IDS.has(normalized)) {
+    throw new Error(`Session lane ID "${normalized}" is reserved.`);
+  }
+
+  return normalized;
+}
+
+/**
+ * Walks up from `startDir` to the filesystem root and returns the nearest
+ * directory containing a lane marker file, or null. Nearest-marker-wins keeps
+ * nested contexts coherent (D-280); no parsing happens here.
+ */
+export async function findNearestLaneMarker(startDir) {
+  let dir = path.resolve(startDir);
+
+  for (;;) {
+    const markerPath = path.join(dir, LANE_MARKER_FILENAME);
+    if (await fileExists(markerPath)) {
+      return { markerDir: dir, markerPath };
+    }
+
+    const parent = path.dirname(dir);
+    if (parent === dir) {
+      return null;
+    }
+
+    dir = parent;
+  }
+}
+
+/**
+ * Reads and validates a lane marker file. Corrupt or invalid markers fail
+ * closed with an actionable error naming the marker path — a marker that
+ * cannot be validated is broken session context, not something to guess past.
+ */
+export async function readLaneMarker(markerPath) {
+  let source;
+  try {
+    source = await readFile(markerPath, 'utf8');
+  } catch (error) {
+    throw new Error(
+      `Lane marker at ${markerPath} exists but cannot be read (${error instanceof Error ? error.message : String(error)}). ` +
+        'Fix the file permissions or remove the marker, or pass both --root and --session to bypass it.',
+    );
+  }
+
+  let data;
+  try {
+    data = parseSimpleYaml(source, { sourceName: markerPath });
+  } catch (error) {
+    throw new Error(
+      `Lane marker at ${markerPath} is not valid marker YAML (${error instanceof Error ? error.message : String(error)}). ` +
+        'Remove the marker or recreate it with `vibecompass write-lane-marker`, or pass both --root and --session to bypass it.',
+    );
+  }
+
+  const formatVersion = typeof data.format_version === 'number' ? data.format_version : Number(data.format_version);
+  if (formatVersion !== LANE_MARKER_FORMAT_VERSION) {
+    throw new Error(
+      `Lane marker at ${markerPath} has unsupported format_version ${data.format_version ?? '(missing)'}; this package understands version ${LANE_MARKER_FORMAT_VERSION}. ` +
+        'Recreate the marker with `vibecompass write-lane-marker`, upgrade the vibecompass package, or pass both --root and --session to bypass it.',
+    );
+  }
+
+  const laneId = typeof data.lane_id === 'string' ? data.lane_id.trim() : '';
+  if (!laneId || !LANE_ID_PATTERN.test(laneId) || RESERVED_LANE_IDS.has(laneId)) {
+    throw new Error(
+      `Lane marker at ${markerPath} has a missing or invalid lane_id. ` +
+        'Recreate the marker with `vibecompass write-lane-marker`, or pass both --root and --session to bypass it.',
+    );
+  }
+
+  const memoryRoot = typeof data.memory_root === 'string' ? data.memory_root.trim() : '';
+  if (!memoryRoot || !path.isAbsolute(memoryRoot)) {
+    throw new Error(
+      `Lane marker at ${markerPath} must record memory_root as an absolute path (found ${JSON.stringify(data.memory_root ?? null)}). ` +
+        'Recreate the marker with `vibecompass write-lane-marker`, or pass both --root and --session to bypass it.',
+    );
+  }
+
+  const token = typeof data.token === 'string' ? data.token.trim() : '';
+  if (!token) {
+    throw new Error(
+      `Lane marker at ${markerPath} is missing its token. ` +
+        'Recreate the marker with `vibecompass write-lane-marker`, or pass both --root and --session to bypass it.',
+    );
+  }
+
+  return {
+    markerPath,
+    markerDir: path.dirname(markerPath),
+    laneId,
+    memoryRoot,
+    token,
+    createdAt: typeof data.created_at === 'string' ? data.created_at : null,
+    createdBy: typeof data.created_by === 'string' ? data.created_by : null,
+  };
+}
+
+/**
+ * Pre-lock context resolution (D-280): finds the nearest marker from cwd,
+ * fail-closes on corrupt markers, applies root binding, and returns the
+ * memory root the command should target. An explicit --root always wins;
+ * otherwise a valid marker supplies the root; only when no marker resolves
+ * does the `cwd/.compass` default apply.
+ */
+export async function resolveLaneMarkerContext(options) {
+  const cwd = path.resolve(options.cwd ?? process.cwd());
+  const explicitRootDir = options.explicitRootDir ? path.resolve(cwd, options.explicitRootDir) : null;
+  const explicitSessionId = options.explicitSessionId ?? null;
+  const warnings = [];
+
+  const found = await findNearestLaneMarker(cwd);
+  let marker = null;
+  if (found) {
+    try {
+      marker = await readLaneMarker(found.markerPath);
+    } catch (error) {
+      // Corrupt markers fail closed unless the context is fully explicit:
+      // passing both --root and --session is the documented escape hatch,
+      // since the marker could then contribute nothing but warnings.
+      if (explicitRootDir && explicitSessionId) {
+        warnings.push(
+          `${error instanceof Error ? error.message : String(error)} Ignored because --root and --session were provided; fix or remove the marker.`,
+        );
+      } else {
+        throw error;
+      }
+    }
+  }
+
+  if (marker && explicitRootDir) {
+    const markerRoot = await canonicalizePath(marker.memoryRoot);
+    const explicitRoot = await canonicalizePath(explicitRootDir);
+    if (markerRoot !== explicitRoot) {
+      warnings.push(
+        `Lane marker at ${marker.markerPath} binds to memory root ${marker.memoryRoot}, not ${explicitRootDir}; ignoring the marker for this command.`,
+      );
+      marker = null;
+    }
+  }
+
+  const rootDir = explicitRootDir ?? marker?.memoryRoot ?? path.resolve(cwd, '.compass');
+
+  return {
+    cwd,
+    rootDir,
+    rootSource: explicitRootDir ? 'flag' : marker ? 'marker' : 'default',
+    marker,
+    warnings,
+  };
+}
+
+/**
+ * The D-277 lane selection order, shared by every lane-scoped resolver:
+ * explicit --session wins (warning when it contradicts a resolvable marker,
+ * naming both lanes) > marker lane (fail closed when stale, even if a
+ * single-lane fallback would have succeeded) > single active lane > null at
+ * zero lanes > actionable error at 2+ lanes. Pure function; the caller
+ * enumerates lanes (inside its lock for mutating commands).
+ */
+export function resolveLaneSelection(options) {
+  // Validating here (not only in callers) keeps the two resolvers from
+  // diverging on the explicit-flag contract.
+  const explicitSessionId = options.explicitSessionId ? validateLaneId(options.explicitSessionId) : null;
+  const marker = options.marker ?? null;
+  const laneIds = options.laneIds ?? [];
+  const purpose = options.purpose ?? 'use';
+  const warnings = [];
+
+  if (explicitSessionId) {
+    // An explicit selection still fails closed when it names a lane that is
+    // not active — otherwise a typo'd --session silently plans or writes
+    // against a lane that does not exist (the mis-selection D-277 removes).
+    if (!laneIds.includes(explicitSessionId)) {
+      throw new Error(
+        `Session lane "${explicitSessionId}" is not an active lane in ${options.rootDir ?? 'the project-memory root'}. ` +
+          'Run `vibecompass list-sessions` to see active lanes.',
+      );
+    }
+
+    if (marker && marker.laneId !== explicitSessionId && !options.suppressLaneWarnings) {
+      warnings.push(
+        `--session ${explicitSessionId} overrides the lane marker at ${marker.markerPath} (marker lane: ${marker.laneId}). ` +
+          'If that is unintentional, run the command from a directory bound to the intended lane.',
+      );
+    }
+
+    return { sessionId: explicitSessionId, source: 'flag', warnings };
+  }
+
+  if (marker) {
+    if (!laneIds.includes(marker.laneId)) {
+      throw new Error(
+        `Lane marker at ${marker.markerPath} names lane "${marker.laneId}", which is not an active lane in ${options.rootDir ?? 'the project-memory root'}. ` +
+          'Remove the stale marker or recreate it with `vibecompass write-lane-marker`, or pass --session explicitly (D-280: stale markers fail closed).',
+      );
+    }
+
+    return { sessionId: marker.laneId, source: 'marker', warnings };
+  }
+
+  if (laneIds.length === 1) {
+    return { sessionId: laneIds[0], source: 'single-lane', warnings };
+  }
+
+  if (laneIds.length > 1) {
+    throw new Error(
+      `Multiple active session lanes exist. Pass --session to choose which lane to ${purpose}, ` +
+        'or run the command from a directory with a worktree lane marker (`vibecompass write-lane-marker`).',
+    );
+  }
+
+  return { sessionId: null, source: 'none', warnings };
+}
+
+/**
+ * D-280 guard: a marker target must be path-disjoint from the memory root.
+ * An ancestor target would turn the shared workspace tree into a de facto
+ * global current pointer; an equal-or-descendant target would put marker
+ * state inside the memory root D-278 keeps local-only.
+ */
+export async function assertMarkerTargetDisjoint(targetDir, rootDir) {
+  const target = await canonicalizePath(path.resolve(targetDir));
+  const root = await canonicalizePath(path.resolve(rootDir));
+
+  if (target === root) {
+    throw new Error(
+      `write-lane-marker refuses ${targetDir}: the target equals the project-memory root. Markers must be path-disjoint from the memory root (D-280).`,
+    );
+  }
+
+  if (isPathInside(root, target)) {
+    throw new Error(
+      `write-lane-marker refuses ${targetDir}: the target contains the project-memory root, so the marker would govern the shared workspace tree (D-280).`,
+    );
+  }
+
+  if (isPathInside(target, root)) {
+    throw new Error(
+      `write-lane-marker refuses ${targetDir}: the target is inside the project-memory root; lane markers are local working state and never live in package memory (D-278/D-280).`,
+    );
+  }
+}
+
+/**
+ * Renders the marker file body. String fields that can hold arbitrary text
+ * are quoted with JSON.stringify to match the codebase's hand-rendered YAML
+ * convention; values needing escape sequences are out of contract for the
+ * parseSimpleYaml subset.
+ */
+export function renderLaneMarker(options) {
+  return [
+    `format_version: ${LANE_MARKER_FORMAT_VERSION}`,
+    `lane_id: ${options.laneId}`,
+    `memory_root: ${JSON.stringify(options.memoryRoot)}`,
+    `token: ${JSON.stringify(options.token)}`,
+    `created_at: ${options.createdAt}`,
+    `created_by: ${JSON.stringify(options.createdBy)}`,
+    '',
+  ].join('\n');
+}
+
+/** Walks up from `dir` looking for a `.git` entry (directory or file). */
+export async function findEnclosingGitDir(dir) {
+  let current = path.resolve(dir);
+
+  for (;;) {
+    if (await fileExists(path.join(current, '.git'))) {
+      return current;
+    }
+
+    const parent = path.dirname(current);
+    if (parent === current) {
+      return null;
+    }
+
+    current = parent;
+  }
+}
+
+function isPathInside(child, parent) {
+  const relative = path.relative(parent, child);
+  return relative.length > 0 && !relative.startsWith('..') && !path.isAbsolute(relative);
+}
+
+async function canonicalizePath(value) {
+  try {
+    return await realpath(value);
+  } catch {
+    return path.resolve(value);
+  }
+}
+
+async function fileExists(filePath) {
+  try {
+    await access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}

package/src/lane-runtime.js

@@ -0,0 +1,254 @@
+import { createHash } from 'node:crypto';
+import { lstat, realpath, rm } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+
+/**
+ * Per-lane runtime assignment (D-282).
+ *
+ * Every lane started on a package-managed root gets a lane port and a lane
+ * temp directory, computed during start-session preflight inside the D-276
+ * memory-root lock. Assignment is lane coordination on one root — the package
+ * never probes or binds the port and never supervises processes (the Phase 8
+ * scope fence). Consumption goes through `lane-env` config/env export.
+ */
+
+export const DEFAULT_LANE_PORT_BASE = 3100;
+export const DEFAULT_LANE_PORT_STEP = 1;
+export const LANE_PORT_MIN = 1024;
+export const LANE_PORT_MAX = 65535;
+const LANE_TMP_NAMESPACE = 'vibecompass-lanes';
+
+/**
+ * The default lane temp base is `<os.tmpdir()>/vibecompass-lanes`, but
+ * `os.tmpdir()` reads `TMPDIR` at call time and D-282's own `lane-env` export
+ * sets `TMPDIR=<laneTmpDir>` (the conventional alias). Starting a new lane from
+ * inside a `lane-env` shell would therefore place it *nested inside* the
+ * exporting lane's temp dir — a dangerous layout, because closing the outer
+ * lane recursively removes the inner lane's active temp dir. Strip any
+ * `vibecompass-lanes` segment out of the resolved temp root first, so a lane
+ * started from a `lane-env` shell is a sibling of the exporting lane under the
+ * real OS temp root, never nested (D-284).
+ */
+export function stripLaneTmpNamespace(dir) {
+  const segments = dir.split(path.sep);
+  const index = segments.indexOf(LANE_TMP_NAMESPACE);
+  if (index === -1) {
+    return dir;
+  }
+
+  const rootSegments = segments.slice(0, index);
+  return rootSegments.join(path.sep) || path.sep;
+}
+
+export function defaultLaneTmpBase() {
+  return path.join(stripLaneTmpNamespace(os.tmpdir()), LANE_TMP_NAMESPACE);
+}
+
+/**
+ * Resolves `project.yaml` `runtime:` overrides (`port_base`, `port_step`,
+ * `tmp_base`) against the D-282 defaults. Invalid values warn and fall back —
+ * a misconfigured runtime block must not stop a session from starting.
+ */
+export function resolveRuntimeSettings(projectConfig) {
+  const warnings = [];
+  const runtimeValue = projectConfig?.runtime;
+  const runtime = isPlainObject(runtimeValue) ? runtimeValue : {};
+  if (runtimeValue !== undefined && runtimeValue !== null && !isPlainObject(runtimeValue)) {
+    warnings.push('project.yaml "runtime" is not a mapping; the D-282 runtime defaults apply.');
+  }
+
+  for (const key of Object.keys(runtime)) {
+    if (!['port_base', 'port_step', 'tmp_base'].includes(key)) {
+      warnings.push(`Unknown project.yaml runtime field "${key}" (D-282 supports port_base, port_step, tmp_base).`);
+    }
+  }
+
+  let portBase = DEFAULT_LANE_PORT_BASE;
+  if (runtime.port_base !== undefined) {
+    if (Number.isInteger(runtime.port_base) && runtime.port_base >= LANE_PORT_MIN && runtime.port_base <= LANE_PORT_MAX) {
+      portBase = runtime.port_base;
+    } else {
+      warnings.push(
+        `project.yaml runtime.port_base must be an integer between ${LANE_PORT_MIN} and ${LANE_PORT_MAX}; using the default ${DEFAULT_LANE_PORT_BASE}.`,
+      );
+    }
+  }
+
+  let portStep = DEFAULT_LANE_PORT_STEP;
+  if (runtime.port_step !== undefined) {
+    if (Number.isInteger(runtime.port_step) && runtime.port_step >= 1) {
+      portStep = runtime.port_step;
+    } else {
+      warnings.push(`project.yaml runtime.port_step must be a positive integer; using the default ${DEFAULT_LANE_PORT_STEP}.`);
+    }
+  }
+
+  let tmpBase = defaultLaneTmpBase();
+  if (runtime.tmp_base !== undefined) {
+    const candidate = typeof runtime.tmp_base === 'string' ? runtime.tmp_base.trim() : '';
+    if (candidate && path.isAbsolute(candidate)) {
+      tmpBase = candidate;
+    } else {
+      warnings.push('project.yaml runtime.tmp_base must be an absolute path; using the OS temp namespace default.');
+    }
+  } else if (stripLaneTmpNamespace(os.tmpdir()) !== os.tmpdir()) {
+    // A lane-env-polluted TMPDIR was detected and un-nested (D-284). Surface it
+    // so the user knows this lane's temp dir sits beside — not inside — the
+    // lane whose lane-env they evaluated, and that it needs its own lane-env.
+    warnings.push(
+      'Detected a VibeCompass lane temp dir in TMPDIR (you are likely in a `lane-env` shell); placing this lane\'s temp dir as a sibling under the real OS temp root, not nested. Run `eval "$(vibecompass lane-env)"` for the new lane before using it.',
+    );
+  }
+
+  return { portBase, portStep, tmpBase, warnings };
+}
+
+/**
+ * Lowest `port_base + k * port_step` not recorded by any sibling lane.
+ * Unparseable sibling lanes contribute no port — their metadata warnings
+ * already surface at start — so assignment degrades to a possible collision
+ * warning path rather than blocking the start (D-282: coordination, not an
+ * OS-level reservation).
+ */
+export function assignLanePort(options) {
+  const portBase = options.portBase ?? DEFAULT_LANE_PORT_BASE;
+  const portStep = options.portStep ?? DEFAULT_LANE_PORT_STEP;
+  const used = new Set();
+  for (const lane of options.existingLanes ?? []) {
+    const port = lane?.runtime?.port;
+    if (Number.isInteger(port)) {
+      used.add(port);
+    }
+  }
+
+  for (let candidate = portBase; candidate <= LANE_PORT_MAX; candidate += portStep) {
+    if (!used.has(candidate)) {
+      return candidate;
+    }
+  }
+
+  throw new Error(
+    `No free lane port at or above ${portBase} (step ${portStep}, max ${LANE_PORT_MAX}); ` +
+      'close unused lanes or configure project.yaml runtime.port_base / runtime.port_step (D-282).',
+  );
+}
+
+/**
+ * Root key: first 12 hex chars of the SHA-256 of the memory root's canonical
+ * realpath. Disambiguates lane temp dirs across roots that share lane ids
+ * without leaking the full root path into the shared OS temp namespace.
+ */
+export async function computeLaneTmpRootKey(rootDir) {
+  const canonical = await realpath(rootDir).catch(() => path.resolve(rootDir));
+  return createHash('sha256').update(canonical).digest('hex').slice(0, 12);
+}
+
+export function buildLaneTmpDir(options) {
+  return path.join(options.tmpBase, options.rootKey, options.laneId);
+}
+
+/**
+ * D-282 guarded recursive removal at close, mirroring D-279/D-281
+ * conservatism: the recorded path must be absolute, its parent segment must be
+ * this root's `rootKey` (the package-owned lane temp namespace for this root),
+ * its final segment must be the closing lane's id, and the process cwd must
+ * not sit inside it. Any guard failure keeps the directory with guidance; a
+ * missing directory is benign crash residue.
+ *
+ * The namespace is verified from the recorded path's own `<root-key>/<lane-id>`
+ * tail rather than a close-time recomputation of `<tmp_base>/<root-key>`: the
+ * default `tmp_base` is `os.tmpdir()`, which reads `TMPDIR` at call time, and
+ * D-282's own documented consumption path (`eval "$(vibecompass lane-env)"`)
+ * exports `TMPDIR=<laneTmpDir>`. Recomputing the namespace from live env would
+ * falsely reject the lane's own recorded dir whenever close runs in a lane-env
+ * shell (or after `runtime.tmp_base` changed), stranding the temp dir.
+ * `rootKey` is the SHA of the memory root's realpath and is env-independent,
+ * so the recorded tail is a stable package signature.
+ */
+export async function removeLaneTmpDirAtClose(options) {
+  const { recordedTmpDir, laneId, rootKey, cwd } = options;
+  const base = { tmpDir: recordedTmpDir, removed: false };
+
+  if (!path.isAbsolute(recordedTmpDir)) {
+    return {
+      ...base,
+      reason: 'not-absolute',
+      warnings: [
+        `Lane temp dir ${recordedTmpDir} was left in place: the recorded path is not absolute (D-282 guarded removal). Inspect and delete it manually.`,
+      ],
+    };
+  }
+
+  if (!(await pathExists(recordedTmpDir))) {
+    // Benign crash residue, matching recorded-but-missing worktrees.
+    return { ...base, reason: 'missing', warnings: [] };
+  }
+
+  const realTmp = await canonicalizePathBestEffort(recordedTmpDir);
+  if (path.basename(path.dirname(realTmp)) !== rootKey) {
+    return {
+      ...base,
+      reason: 'outside-namespace',
+      warnings: [
+        `Lane temp dir ${recordedTmpDir} was left in place: it is not inside this root's lane temp namespace (its parent segment is not the root key ${rootKey}) (D-282 guarded removal). Inspect and delete it manually.`,
+      ],
+    };
+  }
+
+  if (path.basename(realTmp) !== laneId) {
+    return {
+      ...base,
+      reason: 'lane-id-mismatch',
+      warnings: [
+        `Lane temp dir ${recordedTmpDir} was left in place: it does not end in the closing lane's id "${laneId}" (D-282 guarded removal). Inspect and delete it manually.`,
+      ],
+    };
+  }
+
+  const realCwd = await canonicalizePathBestEffort(cwd ?? process.cwd());
+  const cwdRelative = path.relative(realTmp, realCwd);
+  if (cwdRelative === '' || (!cwdRelative.startsWith('..') && !path.isAbsolute(cwdRelative))) {
+    return {
+      ...base,
+      reason: 'cwd-inside',
+      warnings: [
+        `Lane temp dir ${recordedTmpDir} was left in place: the current working directory is inside it (D-282). cd out of the temp dir, then delete it manually.`,
+      ],
+    };
+  }
+
+  try {
+    await rm(recordedTmpDir, { recursive: true, force: true });
+    return { ...base, removed: true, reason: null, warnings: [] };
+  } catch (error) {
+    return {
+      ...base,
+      reason: 'remove-failed',
+      warnings: [
+        `Lane temp dir ${recordedTmpDir} could not be removed: ${error instanceof Error ? error.message : String(error)}. Inspect and delete it manually.`,
+      ],
+    };
+  }
+}
+
+async function pathExists(value) {
+  try {
+    await lstat(value);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function canonicalizePathBestEffort(value) {
+  try {
+    return await realpath(value);
+  } catch {
+    return path.resolve(value);
+  }
+}
+
+function isPlainObject(value) {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}

package/src/manifest.js

@@ -1,6 +1,7 @@
 import { mkdir, readFile, writeFile } from 'node:fs/promises';
 import path from 'node:path';
 import { localRevisionFromManifestHash, stableHash } from './hash.js';
+import { withMemoryRootLock } from './serialization.js';
 import { scanProjectMemory } from './project-memory.js';
 import { listProjectSessions } from './session.js';
 import { PACKAGE_VERSION } from './version.js';
@@ -83,6 +84,10 @@ export async function prepareStateManifest(rootDir, options = {}) {
 }
 
 export async function writeStateManifest(rootDir, options = {}) {
+  return withMemoryRootLock(rootDir, 'state-manifest-refresh', () => writeStateManifestLocked(rootDir, options));
+}
+
+async function writeStateManifestLocked(rootDir, options = {}) {
   const prepared = await prepareStateManifest(rootDir, options);
   const stateDir = path.dirname(prepared.manifestPath);
 
@@ -121,6 +126,20 @@ async function readActiveSessionsForManifest(rootDir) {
       repos: lane.repos ?? [],
       claimed_paths: lane.claims ?? [],
       started_at: lane.startedAt ?? null,
+      // D-281/D-278: git-binding presence projection — omitted for unbound
+      // lanes so pre-S3 manifest shapes are unchanged.
+      ...(lane.branch ? { branch: lane.branch } : {}),
+      ...(lane.worktreeContainer ? { worktree_container: lane.worktreeContainer } : {}),
+      // D-282: runtime assignment presence projection — omitted for pre-S4
+      // lanes so their manifest shapes are unchanged.
+      ...(lane.runtime && (Number.isInteger(lane.runtime.port) || lane.runtime.tmpDir)
+        ? {
+          runtime: {
+            ...(Number.isInteger(lane.runtime.port) ? { port: lane.runtime.port } : {}),
+            ...(lane.runtime.tmpDir ? { tmp_dir: lane.runtime.tmpDir } : {}),
+          },
+        }
+        : {}),
       ...(lane.decisionSnapshot
         ? {
           decision_snapshot: {