@vibecompass/vibecompass 0.10.8 → 0.11.1

package/src/session.js

@@ -1,4 +1,5 @@
-import { access, mkdir, readFile, readdir, rm, writeFile } from 'node:fs/promises';
+import { randomUUID } from 'node:crypto';
+import { access, mkdir, readFile, readdir, realpath, rm, rmdir, stat, writeFile } from 'node:fs/promises';
 import path from 'node:path';
 import { scanProjectMemory } from './project-memory.js';
 import { parseSimpleYaml } from './simple-yaml.js';
@@ -6,6 +7,34 @@ import { buildCloseSessionGuidance, resolveWorkflowSettings } from './workflow.j
 import { syncAgentInstructionFiles } from './generators/agent-files/index.js';
 import { START_MARKER } from './generators/agent-files/markers.js';
 import { planDocsUpdate } from './docs-update.js';
+import {
+  captureBaseRevisions,
+  normalizeBranchName,
+  preflightGitBinding,
+  provisionGitBinding,
+  removeLaneWorktreesAtClose,
+  rollbackGitBinding,
+} from './git-binding.js';
+import { withMemoryRootLock } from './serialization.js';
+import { findDuplicateDecisionIds, formatDecisionId } from './decisions.js';
+import {
+  assignLanePort,
+  buildLaneTmpDir,
+  computeLaneTmpRootKey,
+  removeLaneTmpDirAtClose,
+  resolveRuntimeSettings,
+} from './lane-runtime.js';
+import {
+  LANE_MARKER_FILENAME,
+  assertMarkerTargetDisjoint,
+  findEnclosingGitDir,
+  readLaneMarker,
+  renderLaneMarker,
+  resolveLaneMarkerContext,
+  resolveLaneSelection,
+  validateLaneId,
+} from './lane-marker.js';
+import { PACKAGE_VERSION } from './version.js';
 // This lazy-only cycle is intentional: manifest.js reads lane state from this
 // module, and session command handlers rewrite the derived manifest after
 // lane mutations. Keep both sides free of top-level calls into the other.
@@ -14,7 +43,6 @@ import { writeStateManifest } from './manifest.js';
 const CURRENT_SESSION_REQUIRED_FIELDS = ['Date:', 'Working on:', 'Last thing completed:', 'Blockers:', 'Next session should:'];
 const WIP_HEADER_PATTERN = /^# WIP — (\d{4}-\d{2}-\d{2}) \(session (\d+)\)$/m;
 const SESSION_FILENAME_PATTERN = /^(\d{4}-\d{2}-\d{2})-(\d+)-([a-z0-9-]+)\.md$/i;
-const LANE_ID_PATTERN = /^[a-z0-9][a-z0-9-]{1,62}[a-z0-9]$/;
 const DOCUMENT_MAINTENANCE_STATUSES = new Set(['updated', 'not-needed', 'deferred']);
 const DOCUMENT_MAINTENANCE_FIELDS = [
   {
@@ -33,27 +61,86 @@ const DOCUMENT_MAINTENANCE_FIELDS = [
     flag: '--session-maintenance',
   },
 ];
-const RESERVED_LANE_IDS = new Set([
-  'active',
-  'current',
-  'default',
-  'false',
-  'handoff',
-  'index',
-  'new',
-  'no',
-  'null',
-  'off',
-  'on',
-  'sessions',
-  'state',
-  'true',
-  'wip',
-  'yes',
-]);
-
 export async function startProjectSession(options) {
-  const normalized = normalizeSessionPaths(options);
+  const { normalized, markerContext } = await resolveSessionCommandContext(options);
+  return withMemoryRootLock(normalized.rootDir, 'start-session', () =>
+    startProjectSessionLocked(normalized, options, markerContext));
+}
+
+/**
+ * Pre-lock command context (D-280): an explicit --root always wins; otherwise
+ * lane-scoped commands adopt the nearest valid worktree lane marker's
+ * memory_root, and only when no marker resolves does the `cwd/.compass`
+ * default apply. Commands that never resolve a lane from the marker skip the
+ * marker walk entirely when --root is explicit, so internal callers that
+ * always pass rootDir (manifest/status refresh) keep their existing behavior.
+ */
+async function resolveSessionCommandContext(options, { needMarkerForLane = false } = {}) {
+  let markerContext;
+  if (options?.rootDir && !needMarkerForLane) {
+    const cwd = options?.cwd ? path.resolve(options.cwd) : process.cwd();
+    markerContext = { cwd, rootDir: path.resolve(cwd, options.rootDir), rootSource: 'flag', marker: null, warnings: [] };
+  } else {
+    markerContext = await resolveLaneMarkerContext({
+      cwd: options?.cwd,
+      explicitRootDir: options?.rootDir ?? null,
+      explicitSessionId: normalizeOptionalString(options?.sessionId),
+    });
+  }
+
+  const inferredToolingRootDir = await inferToolingRootDirForContext(options, markerContext);
+  const normalized = normalizeSessionPaths({
+    ...options,
+    cwd: markerContext.cwd,
+    rootDir: markerContext.rootDir,
+    ...(inferredToolingRootDir ? { toolingRootDir: inferredToolingRootDir } : {}),
+  });
+  return { normalized, markerContext };
+}
+
+/**
+ * The tooling root (CLAUDE.md home) defaults to cwd, but follows the memory
+ * root's placement in two cases: when the marker supplied the root (a
+ * worktree cwd must update the real Current-session block), and when an
+ * explicit --root is used from a cwd with no CLAUDE.md (e.g. the corrupt-
+ * marker bypass run from a worktree) — a case where the cwd default could
+ * only fail at readClaudeFile, so inferring is strictly recovery, never a
+ * behavior change for working flows.
+ */
+async function inferToolingRootDirForContext(options, markerContext) {
+  if (options?.toolingRootDir) {
+    return undefined;
+  }
+
+  if (markerContext.rootSource === 'marker') {
+    return inferToolingRootForMemoryRoot(markerContext.rootDir);
+  }
+
+  if (markerContext.rootSource === 'flag' && !(await fileExists(path.join(markerContext.cwd, 'CLAUDE.md')))) {
+    return inferToolingRootForMemoryRoot(markerContext.rootDir);
+  }
+
+  return undefined;
+}
+
+/**
+ * The `<owner>/.compass` placement keeps CLAUDE.md one level above the memory
+ * root; the dedicated-memory-repo placement keeps it inside the root itself.
+ * Prefer whichever directory actually holds a CLAUDE.md, falling back to the
+ * parent (the actionable readClaudeFile error and --tooling-root remain the
+ * escape hatch for layouts with no CLAUDE.md at either).
+ * Exported for read-only surfaces (status) that adopt a marker-supplied root
+ * and must follow the same placement rule for the tooling root.
+ */
+export async function inferToolingRootForMemoryRoot(rootDir) {
+  if (await fileExists(path.join(rootDir, 'CLAUDE.md'))) {
+    return rootDir;
+  }
+
+  return path.dirname(rootDir);
+}
+
+async function startProjectSessionLocked(normalized, options, markerContext) {
   const workingOn = requireNonEmptyString(options?.workingOn, 'start-session requires a non-empty workingOn value.');
   const sessionDate = normalizeSessionDate(options?.date);
 
@@ -71,8 +158,74 @@ export async function startProjectSession(options) {
     repos,
     claims,
     existingLanes,
+    hasWorktree: options?.worktree === true,
   });
   const highestDecisionId = await readHighestDecisionId(normalized.rootDir);
+  const projectConfig = await readProjectConfig(normalized.projectFilePath);
+  const baseRevisionCapture = await captureBaseRevisions({
+    workspaceDir: path.dirname(normalized.rootDir),
+    repoIds: repos,
+    projectRepos: Array.isArray(projectConfig?.repos) ? projectConfig.repos : [],
+  });
+
+  // D-282 per-lane runtime assignment, computed in preflight inside the
+  // memory-root lock so sibling lanes' recorded ports are stable while the
+  // lowest free slot is picked. Assignment is lane coordination on this root,
+  // not an OS-level reservation — no port is probed or bound here.
+  const runtimeSettings = resolveRuntimeSettings(projectConfig);
+  const laneRuntime = {
+    port: assignLanePort({
+      existingLanes,
+      portBase: runtimeSettings.portBase,
+      portStep: runtimeSettings.portStep,
+    }),
+    tmpDir: buildLaneTmpDir({
+      tmpBase: runtimeSettings.tmpBase,
+      rootKey: await computeLaneTmpRootKey(normalized.rootDir),
+      laneId: sessionId,
+    }),
+  };
+
+  // D-281 opt-in git binding: normalize + preflight before the first write so
+  // a refused binding leaves the root untouched.
+  if (options?.worktree && !options?.branch) {
+    throw new Error('--worktree requires --branch; a worktree checks out the lane branch.');
+  }
+  let gitBinding = null;
+  if (options?.branch) {
+    const branch = await normalizeBranchName(options.branch);
+    const workspaceDir = path.dirname(normalized.rootDir);
+    const containerDir = path.join(workspaceDir, 'worktrees', sessionId);
+    const useWorktree = options.worktree === true;
+    const preflight = await preflightGitBinding({
+      workspaceDir,
+      rootDir: normalized.rootDir,
+      branch,
+      worktree: useWorktree,
+      repoIds: repos,
+      projectRepos: Array.isArray(projectConfig?.repos) ? projectConfig.repos : [],
+      existingLanes,
+      containerDir,
+    });
+    gitBinding = {
+      branch,
+      containerDir: useWorktree ? containerDir : null,
+      repoPlans: preflight.repoPlans,
+      warnings: preflight.warnings,
+      marker: useWorktree
+        ? {
+            path: path.join(containerDir, LANE_MARKER_FILENAME),
+            token: randomUUID(),
+            createdAt: formatLocalDateTime(new Date()),
+          }
+        : null,
+    };
+    // Bound repos base on what the binding checks out (create: start point;
+    // reuse: existing branch tip), overriding the plain HEAD capture.
+    for (const plan of preflight.repoPlans) {
+      baseRevisionCapture.baseRevisions[plan.repoId] = plan.baseRevision;
+    }
+  }
 
   const nextSessionNumber = await getNextSessionNumber(normalized.sessionsDir, sessionDate);
   const currentSession = parseCurrentSessionBlock(claude.content, { optional: true });
@@ -87,6 +240,21 @@ export async function startProjectSession(options) {
     nextSessionShould:
       normalizeOptionalString(options?.nextSessionShould) ??
       'Finish the active session and close it with a finalized session note.',
+  }, {
+    lanes: [
+      ...existingLanes.map((lane) => ({ id: lane.id, workingOn: lane.workingOn })),
+      { id: sessionId, workingOn },
+    ],
+    selectedId: sessionId,
+  });
+
+  // D-282: the lane temp dir is created before the first root write, so a
+  // creation failure aborts start-session with the root untouched (empty
+  // parent namespace dirs left behind by a failure are benign).
+  await mkdir(laneRuntime.tmpDir, { recursive: true }).catch((error) => {
+    throw new Error(
+      `Could not create the lane temp directory ${laneRuntime.tmpDir}: ${error instanceof Error ? error.message : String(error)} (D-282). Configure project.yaml runtime.tmp_base if the default namespace is not writable.`,
+    );
   });
 
   await mkdir(normalized.activeSessionsDir, { recursive: true });
@@ -108,6 +276,25 @@ export async function startProjectSession(options) {
       features,
       repos,
       claims,
+      baseRevisions: baseRevisionCapture.baseRevisions,
+      runtime: laneRuntime,
+      // Record-before-create (D-281): the full binding plan — including the
+      // marker path/token — is in session.yaml before any git artifact or
+      // marker file exists, so a crash leaves only benign recorded-but-missing
+      // entries.
+      ...(gitBinding
+        ? {
+            branch: gitBinding.branch,
+            worktreeContainer: gitBinding.containerDir,
+            worktrees: gitBinding.containerDir
+              ? Object.fromEntries(gitBinding.repoPlans.map((plan) => [plan.repoId, plan.worktreePath]))
+              : null,
+            worktreeSources: gitBinding.containerDir
+              ? Object.fromEntries(gitBinding.repoPlans.map((plan) => [plan.repoId, plan.sourceDir]))
+              : null,
+            laneMarker: gitBinding.marker,
+          }
+        : {}),
       highestDecisionId,
     }),
     'utf8',
@@ -132,11 +319,57 @@ export async function startProjectSession(options) {
     }),
     'utf8',
   );
+  const priorIndexContent = await readFile(normalized.activeSessionsIndexPath, 'utf8').catch(() => null);
   await upsertActiveSessionIndex(normalized, {
     id: sessionId,
     status: 'active',
     workingOn,
   }, { current: sessionId });
+
+  if (gitBinding) {
+    const progress = { worktrees: [], createdBranches: [] };
+    try {
+      if (gitBinding.containerDir) {
+        await mkdir(gitBinding.containerDir, { recursive: true });
+        await writeFile(
+          gitBinding.marker.path,
+          renderLaneMarker({
+            laneId: sessionId,
+            memoryRoot: normalized.rootDir,
+            token: gitBinding.marker.token,
+            createdAt: gitBinding.marker.createdAt,
+            createdBy: PACKAGE_VERSION,
+          }),
+          'utf8',
+        );
+      }
+      await provisionGitBinding({ branch: gitBinding.branch, repoPlans: gitBinding.repoPlans }, progress);
+    } catch (error) {
+      // D-281: start-session is atomic — unwind git artifacts created this
+      // call, then the lane files, CLAUDE.md, and index this call wrote.
+      const rollbackNotes = await rollbackGitBinding(progress, gitBinding.branch);
+      if (gitBinding.containerDir) {
+        await rm(gitBinding.containerDir, { recursive: true, force: true }).catch(() => {});
+      }
+      await rm(lanePaths.laneDir, { recursive: true, force: true }).catch(() => {});
+      // D-282: the lane temp dir was created this call; unwind it with the rest.
+      await rm(laneRuntime.tmpDir, { recursive: true, force: true }).catch(() => {});
+      await writeFile(normalized.claudePath, claude.content, 'utf8').catch(() => {});
+      if (priorIndexContent === null) {
+        await rm(normalized.activeSessionsIndexPath, { force: true }).catch(() => {});
+      } else {
+        await writeFile(normalized.activeSessionsIndexPath, priorIndexContent, 'utf8').catch(() => {});
+      }
+      await refreshStateManifestSafely(normalized.rootDir);
+      const message = error instanceof Error ? error.message : String(error);
+      throw new Error(
+        `${message}\nGit binding failed; start-session was rolled back and lane "${sessionId}" was not created.` +
+          (rollbackNotes.length > 0 ? `\nRollback notes: ${rollbackNotes.join('; ')}` : '') +
+          '\nIf a crash interrupts this rollback, run `vibecompass rebuild-active-index` and close the lane normally.',
+      );
+    }
+  }
+
   const manifestRefresh = await refreshStateManifestSafely(normalized.rootDir);
   const auditWarnings = await buildDocsReviewWarnings(normalized);
   const metadataWarnings = collectLaneMetadataWarnings(existingLanes);
@@ -155,19 +388,44 @@ export async function startProjectSession(options) {
     handoffFilePath: lanePaths.handoffFilePath,
     sessionDate,
     sessionNumber: nextSessionNumber,
+    runtime: laneRuntime,
     warnings: [
+      ...markerContext.warnings,
       ...metadataWarnings,
       ...overlapWarnings,
+      ...baseRevisionCapture.warnings,
+      ...runtimeSettings.warnings,
+      ...(gitBinding?.warnings ?? []),
       ...manifestRefresh.warnings,
       ...auditWarnings,
     ],
+    ...(gitBinding
+      ? {
+          gitBinding: {
+            branch: gitBinding.branch,
+            worktreeContainer: gitBinding.containerDir,
+            markerPath: gitBinding.marker?.path ?? null,
+            repos: gitBinding.repoPlans.map((plan) => ({
+              repoId: plan.repoId,
+              mode: plan.mode,
+              baseRevision: plan.baseRevision,
+              worktreePath: plan.worktreePath,
+            })),
+          },
+        }
+      : {}),
     manifest: manifestRefresh.manifest,
     agentFileSync,
   };
 }
 
 export async function closeProjectSession(options) {
-  const normalized = normalizeSessionPaths(options);
+  const { normalized, markerContext } = await resolveSessionCommandContext(options, { needMarkerForLane: true });
+  return withMemoryRootLock(normalized.rootDir, 'close-session', () =>
+    closeProjectSessionLocked(normalized, options, markerContext));
+}
+
+async function closeProjectSessionLocked(normalized, options, markerContext) {
   const title = requireNonEmptyString(options?.title, 'session close requires a non-empty title.');
   const completed = normalizeStringArray(options?.completed);
   const models = normalizeStringArray(options?.models);
@@ -184,16 +442,42 @@ export async function closeProjectSession(options) {
   }
 
   await ensureInitializedProjectMemory(normalized.rootDir, { allowMissingProjectFile: true });
+
+  const duplicateDecisionIds = await findDuplicateDecisionIds(normalized.rootDir);
+  if (duplicateDecisionIds.length > 0) {
+    throw new Error(
+      `close-session is blocked: duplicate decision IDs detected — ${duplicateDecisionIds
+        .map((duplicate) => `${formatDecisionId(duplicate.id)} (${duplicate.occurrences.join(', ')})`)
+        .join('; ')}. Repair the canonical decision files by hand before closing (D-276); duplicates are never auto-renumbered.`,
+    );
+  }
+
   const claude = await readClaudeFile(normalized.claudePath);
   const projectConfig = await readProjectConfig(normalized.projectFilePath);
   const workflowSettings = resolveWorkflowSettings(projectConfig);
-  const sessionId = await resolveExistingSessionId(normalized, options);
+  const laneSelection = await resolveExistingSessionId(normalized, options, markerContext, 'close');
+  const sessionId = laneSelection.sessionId;
   const lanePaths = sessionId ? getLanePaths(normalized, sessionId) : normalized;
+  const closingLaneMetadata = sessionId ? await readLaneMetadata(lanePaths.sessionFilePath) : null;
+  // Fail closed on a null-degraded lane parse, mirroring the write-lane-marker
+  // rebind guard: a degraded parse reads as "no worktrees recorded", so
+  // closing would destroy session.yaml — the only record of the worktree
+  // paths, sources, container, and marker token — while the worktrees (and
+  // any uncommitted work in them) survive unmanaged behind a permanently
+  // stale marker (D-281).
+  if (closingLaneMetadata && closingLaneMetadata.warnings.length > 0) {
+    throw new Error(
+      `Lane "${sessionId}"'s session.yaml could not be parsed (${closingLaneMetadata.warnings[0]}); refusing to close — a null-degraded parse would hide recorded worktrees and closing would destroy the removal-guard records while the worktrees survive (D-281). Repair the lane metadata first, then rerun close-session.`,
+    );
+  }
   const documentMaintenance = normalizeDocumentMaintenanceCheckpoint(options?.documentMaintenance);
   const docsUpdate = await planDocsUpdateSafely({
     rootDir: normalized.rootDir,
     cwd: normalized.cwd,
     sessionId,
+    // close-session already resolved (and warned about) the lane selection;
+    // the embedded plan must not repeat the flag-vs-marker warning.
+    suppressLaneWarnings: true,
     // Test injection seam; production callers should let close-session use the default planner.
     planner: options?.docsUpdatePlanner,
   });
@@ -227,7 +511,9 @@ export async function closeProjectSession(options) {
   const sessionFilePath = path.join(normalized.rootDir, sessionRelativePath);
 
   if (await fileExists(sessionFilePath)) {
-    throw new Error(`Session note already exists at ${sessionFilePath}.`);
+    throw new Error(
+      `Session note already exists at ${sessionFilePath}. If a previous close-session was interrupted after writing the note (for example during worktree removal), move or delete that file and rerun close-session — recorded-but-missing worktrees from the interrupted run are benign.`,
+    );
   }
 
   await writeFile(
@@ -248,8 +534,86 @@ export async function closeProjectSession(options) {
   );
 
   const hadHandoff = await fileExists(lanePaths.handoffFilePath);
+  const markerCleanupWarnings = [];
   let activeSessionIndex = null;
+  let worktreeCleanup = null;
+  let runtimeCleanup = null;
   if (sessionId) {
+    // D-281 close-side guarded removal (S3-3): runs after the session note is
+    // written (a failed note write leaves everything intact) and before the
+    // lane records are destroyed. A crash between removal and the lane-dir
+    // delete leaves only benign recorded-but-missing entries.
+    const removal = closingLaneMetadata
+      ? await removeLaneWorktreesAtClose({
+          laneId: sessionId,
+          worktrees: closingLaneMetadata.worktrees,
+          worktreeSources: closingLaneMetadata.worktreeSources,
+          worktreeContainer: closingLaneMetadata.worktreeContainer,
+          recordedMarker: closingLaneMetadata.laneMarker,
+          cwd: normalized.cwd,
+        })
+      : { attempted: false, removed: [], surviving: [], warnings: [] };
+    markerCleanupWarnings.push(...removal.warnings);
+
+    let markerRemoved = false;
+    let markerKept = false;
+    let containerRemoved = false;
+    if (removal.surviving.length > 0) {
+      // D-281: keep the marker while any recorded worktree survives, so the
+      // leftover worktrees keep an actionable fail-closed breadcrumb instead
+      // of a silent wrong-root fallback. Only claim the marker "was kept"
+      // when it actually exists — removal may have been refused precisely
+      // because the marker is missing.
+      if (closingLaneMetadata?.laneMarker?.path && (await fileExists(closingLaneMetadata.laneMarker.path))) {
+        markerKept = true;
+        markerCleanupWarnings.push(
+          `Lane "${sessionId}" closed with ${removal.surviving.length} surviving worktree(s); the container marker at ${closingLaneMetadata.laneMarker.path} was kept as a breadcrumb (D-281). After removing the worktrees, delete the marker and the container directory manually.`,
+        );
+      }
+    } else {
+      if (closingLaneMetadata?.laneMarker?.path) {
+        const cleanup = await removeRecordedLaneMarker(closingLaneMetadata.laneMarker);
+        markerRemoved = cleanup.removed;
+        markerCleanupWarnings.push(...cleanup.warnings);
+      }
+      if (removal.attempted && closingLaneMetadata?.worktreeContainer) {
+        // rmdir-if-empty: never recursive — a stray user file in the
+        // container keeps it in place with a note rather than being deleted.
+        const containerCleanup = await removeEmptyWorktreeContainer(closingLaneMetadata.worktreeContainer, normalized.cwd);
+        containerRemoved = containerCleanup.removed;
+        markerCleanupWarnings.push(...containerCleanup.warnings);
+      }
+    }
+    if (removal.attempted) {
+      worktreeCleanup = {
+        branch: closingLaneMetadata?.branch ?? null,
+        removed: removal.removed,
+        surviving: removal.surviving,
+        markerRemoved,
+        // Explicit kept status (reviewer pass): "kept" requires the marker
+        // file to exist — surviving worktrees with a missing marker must not
+        // render a phantom breadcrumb line.
+        markerKept,
+        containerRemoved,
+      };
+    }
+
+    // D-282 guarded lane temp-dir removal: runs before the lane record —
+    // the only pointer to the temp dir — is destroyed. The namespace is
+    // verified from the recorded path's own <root-key>/<lane-id> tail against
+    // the env-independent rootKey, never a close-time recompute of tmp_base
+    // (os.tmpdir() reads TMPDIR, which lane-env pollutes). Lanes without a
+    // recorded runtime block (pre-S4) close exactly as before.
+    if (closingLaneMetadata?.runtime?.tmpDir) {
+      runtimeCleanup = await removeLaneTmpDirAtClose({
+        recordedTmpDir: closingLaneMetadata.runtime.tmpDir,
+        laneId: sessionId,
+        rootKey: await computeLaneTmpRootKey(normalized.rootDir),
+        cwd: normalized.cwd,
+      });
+      markerCleanupWarnings.push(...runtimeCleanup.warnings);
+    }
+
     await rm(lanePaths.laneDir, { recursive: true, force: true });
     activeSessionIndex = await removeActiveSessionFromIndex(normalized, sessionId);
   } else {
@@ -260,20 +624,34 @@ export async function closeProjectSession(options) {
   }
 
   const closedSummary = `Closed session ${activeSession.sessionNumber} and wrote \`${sessionRelativePath}\`.`;
+  const survivingLanes = activeSessionIndex?.lanes ?? [];
+  const survivorListing = { lanes: survivingLanes.map((lane) => ({ id: lane.id, workingOn: lane.workingOn })), selectedId: activeSessionIndex?.current ?? null };
   const updatedClaude = replaceCurrentSessionBlock(
     claude.content,
     activeSessionIndex?.current
-      ? buildCurrentSessionFieldsForLane(activeSessionIndex.lanes.find((lane) => lane.id === activeSessionIndex.current), {
+      ? buildCurrentSessionFieldsForLane(survivingLanes.find((lane) => lane.id === activeSessionIndex.current), {
           lastThingCompleted: normalizeOptionalString(options?.lastThingCompleted) ?? closedSummary,
         })
-      : {
-          date: `${activeSession.sessionDate} (session ${activeSession.sessionNumber})`,
-          workingOn: 'Session closed. Ready for the next builder session.',
-          lastThingCompleted: normalizeOptionalString(options?.lastThingCompleted) ?? closedSummary,
-          blockers: blockers.length > 0 ? summarizeList(blockers) : 'No blocker remains.',
-          nextSessionShould:
-            normalizeOptionalString(options?.nextSessionShould) ?? summarizeOrderedList(nextSteps),
-        },
+      : survivingLanes.length >= 2
+        ? {
+            date: `${activeSession.sessionDate} (session ${activeSession.sessionNumber})`,
+            workingOn:
+              'Multiple lanes remain active. Select one explicitly with `vibecompass switch-session <lane-id>`, --session, or a worktree lane marker.',
+            lastThingCompleted: normalizeOptionalString(options?.lastThingCompleted) ?? closedSummary,
+            blockers: blockers.length > 0 ? summarizeList(blockers) : 'No blocker remains.',
+            nextSessionShould:
+              normalizeOptionalString(options?.nextSessionShould) ??
+              'Pick the next lane explicitly (D-277: no implicit current-lane fallback while multiple lanes are active).',
+          }
+        : {
+            date: `${activeSession.sessionDate} (session ${activeSession.sessionNumber})`,
+            workingOn: 'Session closed. Ready for the next builder session.',
+            lastThingCompleted: normalizeOptionalString(options?.lastThingCompleted) ?? closedSummary,
+            blockers: blockers.length > 0 ? summarizeList(blockers) : 'No blocker remains.',
+            nextSessionShould:
+              normalizeOptionalString(options?.nextSessionShould) ?? summarizeOrderedList(nextSteps),
+          },
+    survivorListing,
   );
 
   await writeFile(normalized.claudePath, updatedClaude, 'utf8');
@@ -299,7 +677,16 @@ export async function closeProjectSession(options) {
       projectConfig,
       rootFlag: buildRootFlagForGuidance(normalized),
     }),
+    worktreeCleanup,
+    runtimeCleanup,
     warnings: [
+      ...markerContext.warnings,
+      ...laneSelection.warnings,
+      ...markerCleanupWarnings,
+      // A:192 (D-281): the pre-close staleness set computed by docs-update is
+      // re-emitted at close as warnings, so the closer sees it even when the
+      // embedded plan scrolls past.
+      ...collectStalenessWarnings(docsUpdate.plan),
       ...docsUpdate.warnings,
       ...manifestRefresh.warnings,
     ],
@@ -312,6 +699,62 @@ export async function closeProjectSession(options) {
   };
 }
 
+/**
+ * D-281 rmdir-if-empty: after the worktrees and the container marker are
+ * gone, an empty container is removed non-recursively. Anything left inside
+ * (stray user files) keeps the container in place with a note — close-out
+ * never deletes content it did not create. The D-281 cwd clause applies here
+ * too: POSIX happily rmdirs the invoking process's own working directory,
+ * which would strand the caller's shell in a deleted path.
+ */
+async function removeEmptyWorktreeContainer(containerDir, cwd) {
+  const realContainer = await canonicalizePathBestEffort(containerDir);
+  const realCwd = await canonicalizePathBestEffort(cwd ?? process.cwd());
+  const cwdRelative = path.relative(realContainer, realCwd);
+  if (cwdRelative === '' || (!cwdRelative.startsWith('..') && !path.isAbsolute(cwdRelative))) {
+    return {
+      removed: false,
+      warnings: [
+        `Worktree container ${containerDir} was left in place: the current working directory is inside it (D-281). cd out of the container, then delete it manually.`,
+      ],
+    };
+  }
+
+  try {
+    await rmdir(containerDir);
+    return { removed: true, warnings: [] };
+  } catch (error) {
+    if (error && typeof error === 'object' && 'code' in error && error.code === 'ENOENT') {
+      return { removed: false, warnings: [] };
+    }
+
+    return {
+      removed: false,
+      warnings: [
+        `Worktree container ${containerDir} was left in place: it is not empty (close-session only removes an empty container; D-281). Inspect and delete it manually.`,
+      ],
+    };
+  }
+}
+
+async function canonicalizePathBestEffort(value) {
+  try {
+    return await realpath(value);
+  } catch {
+    return path.resolve(value);
+  }
+}
+
+/** Flattens the docs-update pre-close staleness set into close warnings (A:192 re-emission). */
+function collectStalenessWarnings(plan) {
+  const staleness = plan?.staleness;
+  if (!staleness) {
+    return [];
+  }
+
+  return (staleness.entries ?? []).map((entry) => `Pre-close staleness: ${entry}`);
+}
+
 function normalizeDocumentMaintenanceCheckpoint(value) {
   const source = value && typeof value === 'object' && !Array.isArray(value)
     ? value
@@ -352,21 +795,111 @@ function normalizeDocumentMaintenanceCheckpoint(value) {
   return checkpoint;
 }
 
+/**
+ * Read-only lane runtime export (D-282): resolves the lane per D-277/D-280
+ * (explicit --session, else nearest worktree marker, else single active lane)
+ * and returns the recorded runtime assignment plus a ready-to-export env map.
+ * The conventional PORT/TMPDIR aliases let unmodified dev servers and tools
+ * pick the assignment up; pass conventionalAliases: false to omit them.
+ */
+export async function readLaneEnvironment(options = {}) {
+  const { normalized, markerContext } = await resolveSessionCommandContext(options, { needMarkerForLane: true });
+  await ensureInitializedProjectMemory(normalized.rootDir, { allowMissingProjectFile: true });
+  const lanes = await listActiveSessionLanes(normalized);
+  const explicitId = normalizeOptionalString(options?.sessionId);
+  const selection = resolveLaneSelection({
+    explicitSessionId: explicitId ? validateLaneId(explicitId) : null,
+    marker: markerContext.marker,
+    laneIds: lanes.map((lane) => lane.id),
+    rootDir: normalized.rootDir,
+    purpose: 'export runtime env for',
+  });
+
+  if (!selection.sessionId) {
+    throw new Error('No active session lane exists. Run `vibecompass start-session` first (D-282: runtime assignments are per-lane).');
+  }
+
+  const lane = lanes.find((item) => item.id === selection.sessionId);
+  if (lane.warnings.length > 0) {
+    throw new Error(
+      `Lane "${selection.sessionId}"'s session.yaml could not be parsed (${lane.warnings[0]}); repair the lane metadata before exporting its runtime env.`,
+    );
+  }
+
+  if (!lane.runtime || !Number.isInteger(lane.runtime.port) || !lane.runtime.tmpDir) {
+    throw new Error(
+      `Lane "${selection.sessionId}" has no recorded runtime assignment (lanes started before D-282 have none). Close and re-open the lane to assign one.`,
+    );
+  }
+
+  const conventionalAliases = options.conventionalAliases !== false;
+  const env = {
+    VIBECOMPASS_LANE_ID: selection.sessionId,
+    VIBECOMPASS_LANE_PORT: String(lane.runtime.port),
+    VIBECOMPASS_LANE_TMPDIR: lane.runtime.tmpDir,
+    ...(conventionalAliases
+      ? {
+          PORT: String(lane.runtime.port),
+          TMPDIR: lane.runtime.tmpDir,
+        }
+      : {}),
+  };
+
+  return {
+    rootDir: normalized.rootDir,
+    sessionId: selection.sessionId,
+    port: lane.runtime.port,
+    tmpDir: lane.runtime.tmpDir,
+    env,
+    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',
+      }),
+    ],
+  };
+}
+
 export async function listProjectSessions(options = {}) {
-  const normalized = normalizeSessionPaths(options);
+  const { normalized } = await resolveSessionCommandContext(options);
   await ensureInitializedProjectMemory(normalized.rootDir, { allowMissingProjectFile: true });
   const index = await readActiveSessionIndex(normalized);
   const lanes = await listActiveSessionLanes(normalized);
 
   return {
     rootDir: normalized.rootDir,
-    current: index.current ?? lanes[0]?.id ?? null,
+    current: resolveValidatedCurrentLane(index.current, lanes),
     lanes,
   };
 }
 
+/**
+ * D-277: the index pointer is only reported as current when it names an
+ * existing active lane; a single active lane may be current implicitly, but
+ * with two or more lanes an invalid/missing pointer is never repaired by
+ * picking one — current becomes null until an explicit selection.
+ */
+function resolveValidatedCurrentLane(pointer, lanes) {
+  if (pointer && lanes.some((lane) => lane.id === pointer)) {
+    return pointer;
+  }
+
+  return lanes.length === 1 ? lanes[0].id : null;
+}
+
 export async function switchProjectSession(options = {}) {
-  const normalized = normalizeSessionPaths(options);
+  const { normalized, markerContext } = await resolveSessionCommandContext(options);
+  return withMemoryRootLock(normalized.rootDir, 'switch-session', () =>
+    switchProjectSessionLocked(normalized, options, markerContext));
+}
+
+async function switchProjectSessionLocked(normalized, options, markerContext) {
   const sessionId = validateLaneId(requireNonEmptyString(options?.sessionId, 'switch-session requires a session ID.'));
   const lanes = await listActiveSessionLanes(normalized);
   const lane = lanes.find((item) => item.id === sessionId);
@@ -375,6 +908,16 @@ export async function switchProjectSession(options = {}) {
     throw new Error(`Active session lane "${sessionId}" does not exist.`);
   }
 
+  // D-280 disagreement warning: switching to a lane other than the one the
+  // enclosing marker binds proceeds, but names both lanes.
+  const selection = resolveLaneSelection({
+    explicitSessionId: sessionId,
+    marker: markerContext?.marker ?? null,
+    laneIds: lanes.map((item) => item.id),
+    rootDir: normalized.rootDir,
+    purpose: 'switch to',
+  });
+
   await upsertActiveSessionIndex(normalized, null, { current: sessionId });
   const claude = await readClaudeFile(normalized.claudePath);
   await writeFile(
@@ -384,6 +927,7 @@ export async function switchProjectSession(options = {}) {
       buildCurrentSessionFieldsForLane(lane, {
         lastThingCompleted: `Switched current lane to ${sessionId}.`,
       }),
+      { lanes: lanes.map((item) => ({ id: item.id, workingOn: item.workingOn })), selectedId: sessionId },
     ),
     'utf8',
   );
@@ -398,12 +942,244 @@ export async function switchProjectSession(options = {}) {
     claudePath: normalized.claudePath,
     current: sessionId,
     lanes,
-    warnings: manifestRefresh.warnings,
+    warnings: [...markerContext.warnings, ...selection.warnings, ...manifestRefresh.warnings],
     manifest: manifestRefresh.manifest,
     agentFileSync,
   };
 }
 
+/**
+ * Rebuilds `sessions/active/index.yaml` from the active lane directories plus
+ * an explicit current-lane selection (D-266/D-277 recovery path). The current
+ * pointer is never derived from enumeration alone: an explicit `current` wins,
+ * a still-valid existing pointer is preserved, and only a single surviving
+ * lane may become current implicitly.
+ */
+export async function rebuildActiveSessionIndex(options = {}) {
+  const { normalized } = await resolveSessionCommandContext(options);
+  return withMemoryRootLock(normalized.rootDir, 'rebuild-active-index', async () => {
+    await ensureInitializedProjectMemory(normalized.rootDir, { allowMissingProjectFile: true });
+    const lanes = await listActiveSessionLanes(normalized);
+    const requested = options?.current == null || options.current === ''
+      ? null
+      : validateLaneId(requireNonEmptyString(options.current, 'rebuild-active-index requires a non-empty --current lane ID when provided.'));
+
+    if (requested && !lanes.some((lane) => lane.id === requested)) {
+      throw new Error(`Active session lane "${requested}" does not exist; cannot set it as the current lane.`);
+    }
+
+    if (lanes.length === 0) {
+      await rm(normalized.activeSessionsIndexPath, { force: true });
+      return {
+        rootDir: normalized.rootDir,
+        indexPath: normalized.activeSessionsIndexPath,
+        current: null,
+        lanes,
+        removed: true,
+      };
+    }
+
+    const existing = await readActiveSessionIndex(normalized);
+    const current =
+      requested ??
+      (lanes.some((lane) => lane.id === existing.current) ? existing.current : null) ??
+      (lanes.length === 1 ? lanes[0].id : null);
+
+    if (!current) {
+      throw new Error(
+        'rebuild-active-index needs an explicit --current <lane-id> because more than one lane is active and the existing pointer is not valid (D-277: the current lane is an explicit selection, not a derived default).',
+      );
+    }
+
+    await mkdir(normalized.activeSessionsDir, { recursive: true });
+    await writeFile(normalized.activeSessionsIndexPath, renderActiveSessionIndex(current, lanes), 'utf8');
+    return {
+      rootDir: normalized.rootDir,
+      indexPath: normalized.activeSessionsIndexPath,
+      current,
+      lanes,
+      removed: false,
+    };
+  });
+}
+
+/**
+ * Writes the worktree lane marker for an active lane (D-280). Markers are
+ * never written implicitly: this explicit command and S3 worktree
+ * provisioning are the only producers. The target must be path-disjoint from
+ * the memory root, and the lane's session.yaml records the marker under a
+ * `lane_marker:` block map so close-session and S3 removal can token-match.
+ */
+export async function writeLaneMarkerForSession(options) {
+  // needMarkerForLane: the enclosing marker is consulted even under an
+  // explicit --root so the D-280 flag-vs-marker disagreement warning fires
+  // when this command binds a different lane than the invoking context.
+  const { normalized, markerContext } = await resolveSessionCommandContext(options, { needMarkerForLane: true });
+  return withMemoryRootLock(normalized.rootDir, 'write-lane-marker', () =>
+    writeLaneMarkerForSessionLocked(normalized, options, markerContext));
+}
+
+async function writeLaneMarkerForSessionLocked(normalized, options, markerContext) {
+  const sessionId = validateLaneId(
+    requireNonEmptyString(options?.sessionId, 'write-lane-marker requires --session <lane-id> so the marker binds to an explicit lane.'),
+  );
+  await ensureInitializedProjectMemory(normalized.rootDir, { allowMissingProjectFile: true });
+  const warnings = [...markerContext.warnings];
+  const lanes = await listActiveSessionLanes(normalized);
+  // Shared D-277/D-280 selection: validates the explicit lane is active and
+  // emits the disagreement warning when an enclosing marker names another lane.
+  const selection = resolveLaneSelection({
+    explicitSessionId: sessionId,
+    marker: markerContext.marker,
+    laneIds: lanes.map((lane) => lane.id),
+    rootDir: normalized.rootDir,
+    purpose: 'bind the marker to',
+  });
+  warnings.push(...selection.warnings);
+
+  const lanePaths = getLanePaths(normalized, sessionId);
+  if (!(await fileExists(lanePaths.sessionFilePath))) {
+    throw new Error(
+      `Lane "${sessionId}" has no session.yaml at ${lanePaths.sessionFilePath}; the marker cannot be recorded. Repair the lane (rebuild-active-index) before writing a marker.`,
+    );
+  }
+
+  const targetDir = path.resolve(normalized.cwd, options?.dir ?? '.');
+  const targetStat = await stat(targetDir).catch(() => null);
+  if (!targetStat) {
+    throw new Error(
+      `write-lane-marker target directory ${targetDir} does not exist. Create it first; markers are never provisioned implicitly (D-280).`,
+    );
+  }
+  if (!targetStat.isDirectory()) {
+    throw new Error(`write-lane-marker target ${targetDir} is not a directory.`);
+  }
+
+  await assertMarkerTargetDisjoint(targetDir, normalized.rootDir);
+  const gitDir = await findEnclosingGitDir(targetDir);
+  if (gitDir) {
+    warnings.push(
+      `Marker target ${targetDir} sits inside a git work tree (${gitDir}); lane markers are local-only (D-278) — make sure ${LANE_MARKER_FILENAME} is git-ignored there.`,
+    );
+  }
+
+  const markerPath = path.join(targetDir, LANE_MARKER_FILENAME);
+  if (await fileExists(markerPath)) {
+    try {
+      const existing = await readLaneMarker(markerPath);
+      if (existing.laneId !== sessionId) {
+        warnings.push(`Replaced the marker at ${markerPath} previously bound to lane "${existing.laneId}".`);
+      }
+    } catch {
+      warnings.push(`Replaced an unreadable marker at ${markerPath}.`);
+    }
+  }
+
+  const laneMetadata = await readLaneMetadata(lanePaths.sessionFilePath);
+  // Fail closed when the lane metadata is unreadable: a null-degraded parse
+  // would hide a recorded worktree container and let a rebind orphan the
+  // removal guard (D-281).
+  if (laneMetadata.warnings.length > 0) {
+    throw new Error(
+      `Lane "${sessionId}"'s session.yaml could not be parsed (${laneMetadata.warnings[0]}); refusing to rebind its marker — a provisioned worktree container would be undetectable (D-281). Repair the lane metadata first.`,
+    );
+  }
+  // D-281: a provisioned lane's container marker is what authorizes guarded
+  // worktree removal at close; rebinding would token-delete it and orphan
+  // the worktrees permanently.
+  if (laneMetadata.worktreeContainer) {
+    throw new Error(
+      `Lane "${sessionId}" has a provisioned worktree container at ${laneMetadata.worktreeContainer}; its marker is managed by start/close-session and rebinding it would orphan the worktree-removal guard (D-281). Close the lane to remove the worktrees instead.`,
+    );
+  }
+  if (laneMetadata.laneMarker?.path && path.resolve(laneMetadata.laneMarker.path) !== markerPath) {
+    const cleanup = await removeRecordedLaneMarker(laneMetadata.laneMarker);
+    warnings.push(...cleanup.warnings);
+  }
+
+  const token = randomUUID();
+  const createdAt = formatLocalDateTime(new Date());
+  const sessionYaml = await readFile(lanePaths.sessionFilePath, 'utf8');
+  // Record before writing the marker file: a crash between the two leaves the
+  // benign recorded-but-missing state (cleanup is a no-op) instead of an
+  // unrecorded on-disk marker that nothing can remove or report.
+  await writeFile(
+    lanePaths.sessionFilePath,
+    upsertLaneMarkerBlock(sessionYaml, { path: markerPath, token, createdAt }),
+    'utf8',
+  );
+  await writeFile(
+    markerPath,
+    renderLaneMarker({
+      laneId: sessionId,
+      memoryRoot: normalized.rootDir,
+      token,
+      createdAt,
+      createdBy: PACKAGE_VERSION,
+    }),
+    'utf8',
+  );
+
+  return {
+    rootDir: normalized.rootDir,
+    sessionId,
+    markerPath,
+    token,
+    warnings,
+  };
+}
+
+/**
+ * Removes a lane's recorded marker file only when the on-disk token still
+ * matches the recorded token (D-280 guarded removal); anything else is
+ * reported and left in place.
+ */
+async function removeRecordedLaneMarker(recorded) {
+  const warnings = [];
+  if (!recorded?.path) {
+    return { removed: false, warnings };
+  }
+
+  if (!(await fileExists(recorded.path))) {
+    return { removed: false, warnings };
+  }
+
+  try {
+    const marker = await readLaneMarker(recorded.path);
+    if (recorded.token && marker.token === recorded.token) {
+      await rm(recorded.path, { force: true });
+      return { removed: true, warnings };
+    }
+
+    warnings.push(
+      `Lane marker at ${recorded.path} left in place: its token does not match the lane's recorded marker (D-280: only token-matched markers are removed).`,
+    );
+  } catch (error) {
+    warnings.push(
+      `Lane marker at ${recorded.path} left in place: ${error instanceof Error ? error.message : String(error)}`,
+    );
+  }
+
+  return { removed: false, warnings };
+}
+
+/** Replaces (or appends) the `lane_marker:` block map in a session.yaml body. */
+function upsertLaneMarkerBlock(content, marker) {
+  // CRLF-tolerant to match parseSimpleYaml's /\r?\n/ splitting; a missed
+  // strip here would append a duplicate key and void the whole lane metadata.
+  const stripped = content.replace(/^lane_marker:\r?\n(?:[ \t]+.*\r?\n?)*/m, '');
+  const base = stripped.endsWith('\n') ? stripped : `${stripped}\n`;
+  const block = [
+    'lane_marker:',
+    `  path: ${quoteYamlString(marker.path)}`,
+    `  token: ${quoteYamlString(marker.token)}`,
+    `  created_at: ${marker.createdAt}`,
+    '',
+  ].join('\n');
+
+  return `${base}${block}`;
+}
+
 async function refreshStateManifestSafely(rootDir) {
   try {
     const manifest = await writeStateManifest(rootDir);
@@ -429,6 +1205,7 @@ async function planDocsUpdateSafely(options) {
         rootDir: options.rootDir,
         cwd: options.cwd,
         sessionId: options.sessionId,
+        suppressLaneWarnings: options.suppressLaneWarnings === true,
       }),
       warnings: [],
     };
@@ -588,9 +1365,9 @@ function parseCurrentSessionBlock(content, options = {}) {
   };
 }
 
-function replaceCurrentSessionBlock(content, fields) {
+function replaceCurrentSessionBlock(content, fields, laneListing = null) {
   const sessionFence = findCurrentSessionFence(content);
-  const blockBody = renderCurrentSessionBlockBody(fields);
+  const blockBody = renderCurrentSessionBlockBody(fields, laneListing);
 
   if (!sessionFence) {
     return insertCurrentSessionBlock(content, blockBody);
@@ -599,14 +1376,32 @@ function replaceCurrentSessionBlock(content, fields) {
   return `${content.slice(0, sessionFence.bodyStart)}${blockBody}${content.slice(sessionFence.bodyEnd)}`;
 }
 
-function renderCurrentSessionBlockBody(fields) {
-  return [
-    `Date: ${fields.date}`,
+/**
+ * D-277: with two or more active lanes the block becomes a derived multi-lane
+ * listing (one line per active lane plus the selected lane); with at most one
+ * lane it keeps the exact legacy five-field shape. The five field labels stay
+ * present in both shapes so parseCurrentSessionBlock/findCurrentSessionFence
+ * keep working on either.
+ */
+function renderCurrentSessionBlockBody(fields, laneListing = null) {
+  const lines = [`Date: ${fields.date}`];
+
+  if (laneListing && Array.isArray(laneListing.lanes) && laneListing.lanes.length >= 2) {
+    lines.push('Active lanes:');
+    for (const lane of [...laneListing.lanes].sort((left, right) => left.id.localeCompare(right.id))) {
+      const selectedSuffix = laneListing.selectedId === lane.id ? ' [selected]' : '';
+      lines.push(`- ${lane.id} — ${lane.workingOn ?? 'No summary recorded'}${selectedSuffix}`);
+    }
+  }
+
+  lines.push(
     `Working on: ${fields.workingOn}`,
     `Last thing completed: ${fields.lastThingCompleted}`,
     `Blockers: ${fields.blockers}`,
     `Next session should: ${fields.nextSessionShould}`,
-  ].join('\n');
+  );
+
+  return lines.join('\n');
 }
 
 function insertCurrentSessionBlock(content, blockBody) {
@@ -678,22 +1473,17 @@ async function resolveStartSessionId(normalized, options) {
   throw new Error('start-session requires --id <lane-id> so each active lane has a meaningful name.');
 }
 
-async function resolveExistingSessionId(normalized, options) {
+async function resolveExistingSessionId(normalized, options, markerContext, purpose) {
   const explicitId = normalizeOptionalString(options?.sessionId);
-  if (explicitId) {
-    return validateLaneId(explicitId);
-  }
-
   const lanes = await listActiveSessionLanes(normalized);
-  if (lanes.length === 1) {
-    return lanes[0].id;
-  }
-
-  if (lanes.length > 1) {
-    throw new Error('Multiple active session lanes exist. Pass --session to choose which lane to close.');
-  }
 
-  return null;
+  return resolveLaneSelection({
+    explicitSessionId: explicitId ? validateLaneId(explicitId) : null,
+    marker: markerContext?.marker ?? null,
+    laneIds: lanes.map((lane) => lane.id),
+    rootDir: normalized.rootDir,
+    purpose,
+  });
 }
 
 async function listActiveSessionLanes(normalized) {
@@ -718,6 +1508,12 @@ async function listActiveSessionLanes(normalized) {
         claims: metadata.claims,
         startedAt: metadata.startedAt,
         decisionSnapshot: metadata.decisionSnapshot,
+        branch: metadata.branch ?? null,
+        worktreeContainer: metadata.worktreeContainer ?? null,
+        worktrees: metadata.worktrees ?? {},
+        worktreeSources: metadata.worktreeSources ?? {},
+        baseRevisions: metadata.baseRevisions ?? {},
+        runtime: metadata.runtime ?? null,
         warnings: metadata.warnings,
         sessionDate: metadata.sessionDate ?? wipSession?.sessionDate ?? null,
         sessionNumber: metadata.sessionNumber ?? wipSession?.sessionNumber ?? 0,
@@ -756,6 +1552,24 @@ async function readLaneMetadata(sessionFilePath) {
       decisionSnapshot: {
         highestDecisionId: parseNullableNumber(data.decision_snapshot?.highest_decision_id),
       },
+      laneMarker: data.lane_marker && typeof data.lane_marker === 'object'
+        ? {
+            path: normalizeOptionalString(data.lane_marker.path),
+            token: normalizeOptionalString(data.lane_marker.token),
+            createdAt: normalizeOptionalString(data.lane_marker.created_at),
+          }
+        : null,
+      branch: normalizeOptionalString(data.branch),
+      worktreeContainer: normalizeOptionalString(data.worktree_container),
+      worktrees: normalizeStringMap(data.worktrees),
+      worktreeSources: normalizeStringMap(data.worktree_sources),
+      baseRevisions: normalizeStringMap(data.base_revisions),
+      runtime: data.runtime && typeof data.runtime === 'object' && !Array.isArray(data.runtime)
+        ? {
+            port: parseNullableNumber(data.runtime.port),
+            tmpDir: normalizeOptionalString(data.runtime.tmp_dir),
+          }
+        : null,
       sessionDate: normalizeOptionalString(data.session_date),
       sessionNumber: typeof data.session_number === 'number' ? data.session_number : Number(data.session_number) || null,
       warnings: [],
@@ -771,6 +1585,13 @@ async function readLaneMetadata(sessionFilePath) {
       decisionSnapshot: {
         highestDecisionId: null,
       },
+      laneMarker: null,
+      branch: null,
+      worktreeContainer: null,
+      worktrees: {},
+      worktreeSources: {},
+      baseRevisions: {},
+      runtime: null,
       sessionDate: null,
       sessionNumber: null,
       warnings: [
@@ -780,6 +1601,27 @@ async function readLaneMetadata(sessionFilePath) {
   }
 }
 
+/**
+ * One-level block map of string values (worktrees, worktree_sources,
+ * base_revisions). Unquoted all-digit values come back numerically coerced
+ * from parseScalar — normalize them back to strings.
+ */
+function normalizeStringMap(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    return {};
+  }
+
+  const result = {};
+  for (const [key, entry] of Object.entries(value)) {
+    const normalized = normalizeOptionalString(typeof entry === 'number' ? String(entry) : entry);
+    if (normalized) {
+      result[key] = normalized;
+    }
+  }
+
+  return result;
+}
+
 async function readActiveSessionIndex(normalized) {
   try {
     const data = parseSimpleYaml(await readFile(normalized.activeSessionsIndexPath, 'utf8'), {
@@ -796,7 +1638,12 @@ async function readActiveSessionIndex(normalized) {
 }
 
 async function upsertActiveSessionIndex(normalized, lane, options = {}) {
-  const currentIndex = await readActiveSessionIndex(normalized);
+  // D-277: callers must select `current` explicitly; the upsert never derives
+  // a current lane from the lane being written or a stale existing pointer.
+  if (!('current' in options)) {
+    throw new Error('upsertActiveSessionIndex requires an explicit current-lane selection.');
+  }
+
   const lanes = await listActiveSessionLanes(normalized);
   const laneMap = new Map(lanes.map((item) => [item.id, item]));
   if (lane) {
@@ -807,9 +1654,8 @@ async function upsertActiveSessionIndex(normalized, lane, options = {}) {
     });
   }
 
-  const current = options.current ?? currentIndex.current ?? lane?.id ?? null;
   await mkdir(normalized.activeSessionsDir, { recursive: true });
-  await writeFile(normalized.activeSessionsIndexPath, renderActiveSessionIndex(current, [...laneMap.values()]), 'utf8');
+  await writeFile(normalized.activeSessionsIndexPath, renderActiveSessionIndex(options.current, [...laneMap.values()]), 'utf8');
 }
 
 /**
@@ -820,7 +1666,15 @@ async function upsertActiveSessionIndex(normalized, lane, options = {}) {
 async function removeActiveSessionFromIndex(normalized, sessionId) {
   const index = await readActiveSessionIndex(normalized);
   const lanes = (await listActiveSessionLanes(normalized)).filter((lane) => lane.id !== sessionId);
-  const current = index.current === sessionId ? lanes[0]?.id ?? null : index.current;
+  // D-277: a surviving pointer is kept only when it names a surviving lane; a
+  // sole survivor may become current implicitly, but with 2+ survivors the
+  // pointer goes null until an explicit switch-session / marker selection.
+  // This also repairs stale pointers that named an already-missing lane.
+  const keptPointer =
+    index.current && index.current !== sessionId && lanes.some((lane) => lane.id === index.current)
+      ? index.current
+      : null;
+  const current = keptPointer ?? (lanes.length === 1 ? lanes[0].id : null);
   if (lanes.length === 0) {
     await rm(normalized.activeSessionsIndexPath, { force: true });
     return {
@@ -876,19 +1730,6 @@ function parseActiveSession(wipContent, wipFilePath = 'sessions/active/<lane-id>
   };
 }
 
-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;
-}
-
 function extractSectionBody(content, sectionTitle) {
   const heading = `## ${sectionTitle}`.toLowerCase();
   const lines = content.split('\n');
@@ -999,12 +1840,51 @@ function renderLaneMetadata(options) {
     renderYamlArray('repos', options.repos),
     renderYamlArray('claimed_paths', options.claims),
     `started_at: ${formatLocalDateTime(new Date())}`,
+    // D-282: the runtime assignment travels with the lane record (local-only
+    // per D-278) so lane-env and close-time cleanup read it back.
+    ...(options.runtime
+      ? [
+          'runtime:',
+          `  port: ${options.runtime.port}`,
+          `  tmp_dir: ${quoteYamlString(options.runtime.tmpDir)}`,
+        ]
+      : []),
+    ...(options.branch ? [`branch: ${quoteYamlString(options.branch)}`] : []),
+    ...(options.worktreeContainer ? [`worktree_container: ${quoteYamlString(options.worktreeContainer)}`] : []),
+    ...renderYamlBlockMapLines('worktrees', options.worktrees),
+    ...renderYamlBlockMapLines('worktree_sources', options.worktreeSources),
+    ...renderYamlBlockMapLines('base_revisions', options.baseRevisions),
+    ...(options.laneMarker
+      ? [
+          'lane_marker:',
+          `  path: ${quoteYamlString(options.laneMarker.path)}`,
+          `  token: ${quoteYamlString(options.laneMarker.token)}`,
+          `  created_at: ${options.laneMarker.createdAt}`,
+        ]
+      : []),
     'decision_snapshot:',
     `  highest_decision_id: ${options.highestDecisionId ?? 'null'}`,
     '',
   ].join('\n');
 }
 
+/**
+ * One-level block map of id keys to quoted string values, omitted entirely
+ * when empty. Writers validate keys with isSimpleYamlKeySafe before recording
+ * them — an unparseable key would null-degrade the whole lane for readers.
+ */
+function renderYamlBlockMapLines(key, map) {
+  const entries = map ? Object.entries(map).filter(([, value]) => value !== null && value !== undefined) : [];
+  if (entries.length === 0) {
+    return [];
+  }
+
+  return [
+    `${key}:`,
+    ...entries.map(([mapKey, value]) => `  ${mapKey}: ${quoteYamlString(String(value))}`),
+  ];
+}
+
 function renderActiveSessionIndex(current, lanes) {
   const lines = [
     `current: ${current ?? 'null'}`,
@@ -1149,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.`,
       );
@@ -1159,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 ?? []);
 }