@vibecompass/vibecompass 0.13.0 → 0.14.0

package/CHANGELOG.md

@@ -1,6 +1,47 @@
 # Changelog
 
-## Unreleased
+## 0.14.0 - 2026-09-23
+
+- Add `continue-session [<lane-id>]` (D-353): resume an already-open lane
+  through the D-277 resolver (explicit id → worktree marker → single lane).
+  The lane keeps its opening date and session number; the command records
+  `resumed_at` / `resume_count` in `session.yaml`, appends a dated `Resumed`
+  line to `wip.md ## Log`, moves the index `current` hint and the Current
+  session block to the lane (showing the resume date), optionally refreshes
+  `--working-on`, prints the wip/handoff/latest-note paths plus runtime and
+  git-binding reminders, re-emits the docs-update staleness set as
+  `Resume staleness` warnings, and supports `--json`. With two or more active
+  lanes and no selection, or with an unknown explicit id, it fails closed and
+  prints the lane inventory. All inputs are read and outputs prepared before
+  the first write, so a refusal (missing CLAUDE.md, unparseable scratch or
+  metadata) changes no bytes; `--working-on` text is written literally,
+  hand-spaced or CRLF metadata keys are replaced rather than duplicated, and
+  Current-session fields carry over only for the exact same lane id.
+- `list-sessions` renders the shared lane inventory (opened date/session
+  number, resume count, branch/worktrees, port, last log line, current hint)
+  and accepts `--json`; the header now says `current hint`.
+- `start-session --id <existing-lane>` fails closed before any preflight and
+  names `continue-session`; starting a lane while others are active warns with
+  the resume alternative.
+- Generated `context.md` gains an "Open, resume, or choose" protocol and a
+  `continue session` prompt command; the managed agent block gains the
+  matching hard rule (resume instead of re-start; with 2+ lanes inventory and
+  ask, never adopt the current hint silently).
+- Report byte-identical managed agent instruction files as `unchanged` from
+  `sync-agents`, `refresh-workflow`, and session lifecycle syncs instead of
+  reporting a no-op as `update` / `dry-run-update`; missing or incomplete
+  managed markers remain warning-only and are never overwritten.
+
+## 0.13.1 - 2026-09-11
+
+- Add strict backward compatibility for intentional legacy recovery checkpoints
+  at root `sessions/YYYY-MM-DD.md` paths with an exact
+  `# Recovery checkpoint — YYYY-MM-DD — <title>` H1; project them with their
+  matching `session_date`, title, and
+  `session_number: null` without inventing numbered-session chronology.
+- Preserve fail-closed behavior for malformed, mismatched, untitled, or nested
+  recovery checkpoints and all existing numbered-session behavior, with focused
+  parser, manifest, read-model, and session-lifecycle regression coverage.
 
 ## 0.13.0 - 2026-07-11
 

package/README.md

@@ -128,11 +128,21 @@ npx -y @vibecompass/vibecompass@latest status --root .compass
 
 # Session workflow
 npx -y @vibecompass/vibecompass@latest start-session --root .compass --id auth-flow --working-on "Auth flow"
-npx -y @vibecompass/vibecompass@latest list-sessions --root .compass
+npx -y @vibecompass/vibecompass@latest list-sessions --root .compass            # --json for the machine-readable lane inventory
+npx -y @vibecompass/vibecompass@latest continue-session --root .compass         # resume the open lane (D-353); name it with 2+ lanes: continue-session auth-flow
 npx -y @vibecompass/vibecompass@latest switch-session auth-flow --root .compass
 npx -y @vibecompass/vibecompass@latest docs-update --root .compass --session auth-flow
 npx -y @vibecompass/vibecompass@latest close-session --root .compass --session auth-flow --title "Auth Flow" --completed "Built auth" --architecture-docs updated --decision-log not-needed --session-maintenance updated --next-step "Review"
 
+# Resuming (D-353): an active lane is an open session, not a crash. continue-session
+# keeps the lane's opening date and session number, records resumed_at/resume_count
+# in session.yaml, appends a dated "Resumed" line to wip.md, moves the index current
+# hint and the Current session block to the lane, and prints the files to read next
+# plus resume-staleness warnings. With two or more active lanes and no worktree
+# marker it fails closed and prints the lane inventory instead of guessing;
+# start-session --id <existing-lane> fails closed and points at continue-session.
+npx -y @vibecompass/vibecompass@latest continue-session auth-flow --root .compass --working-on "Auth flow, phase 2"
+
 # Optional git binding for a lane (D-281): create/reuse a branch in each bound
 # repo; --worktree provisions per-repo worktrees under
 # <workspace>/worktrees/<lane-id>/<repo-id> with the lane marker in the

package/package.json

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

package/src/cli.js

@@ -8,7 +8,7 @@ import { planDocsUpdate, renderDocsUpdatePlan } from './docs-update.js';
 import { resolveConnectHostedCliOptions, resolveInitCliOptions } from './setup.js';
 import { readFile } from 'node:fs/promises';
 import path from 'node:path';
-import { closeProjectSession, listProjectSessions, readLaneEnvironment, rebuildActiveSessionIndex, startProjectSession, switchProjectSession, writeLaneMarkerForSession } from './session.js';
+import { closeProjectSession, continueProjectSession, listProjectSessions, readLaneEnvironment, rebuildActiveSessionIndex, renderLaneInventoryLines, startProjectSession, switchProjectSession, writeLaneMarkerForSession } from './session.js';
 import { appendDecisionEntry, formatDecisionId, readNextDecisionId } from './decisions.js';
 import { checkGroupedDecisionIndex, refreshGroupedDecisionIndex, resolveDefaultIndexGroupLabel } from './decision-index.js';
 import { resolveLaneMarkerContext, resolveLaneSelection } from './lane-marker.js';
@@ -298,20 +298,66 @@ export async function runCli(argv, io = createDefaultIo(), runtime = {}) {
     return 0;
   }
 
+  if (parsed.command === 'continue-session') {
+    await writeCompatibilityPreflightWarnings(io, parsed.options, runtime);
+    const result = await continueProjectSession({
+      ...parsed.options,
+      ...(runtime.cwd ? { cwd: runtime.cwd } : {}),
+    });
+    if (parsed.options.json) {
+      const { manifest: _manifest, docsUpdatePlan: _plan, agentFileSync, ...json } = result;
+      io.stdout.write(`${JSON.stringify({ ...json, agentFileSync: agentFileSync?.results ?? [] }, null, 2)}\n`);
+      writeWarnings(io, result.warnings);
+      return 0;
+    }
+    {
+      // Text mode.
+      io.stdout.write(`Continued lane ${result.sessionId} (session ${result.sessionDate}-${result.sessionNumber}, resume #${result.resumeCount}${result.laneAgeDays != null ? `, opened ${result.laneAgeDays} day${result.laneAgeDays === 1 ? '' : 's'} ago` : ''}; selected via ${result.selectionSource})\n`);
+      io.stdout.write(`Working on: ${result.workingOn}${result.workingOnUpdated ? ' (updated)' : ''}\n`);
+      io.stdout.write(`Updated ${result.claudePath}\n`);
+      io.stdout.write('Read next:\n');
+      io.stdout.write(`- ${result.wipFilePath}\n`);
+      io.stdout.write(`- ${result.handoffFilePath}\n`);
+      if (result.latestFinalizedSessionPath) {
+        io.stdout.write(`- ${result.latestFinalizedSessionPath} (latest finalized note)\n`);
+      }
+      if (result.gitBinding) {
+        const worktreeRepos = Object.keys(result.gitBinding.worktrees);
+        io.stdout.write(`Git binding: branch "${result.gitBinding.branch}"${worktreeRepos.length > 0 ? ` with worktrees for ${worktreeRepos.join(', ')} under ${result.gitBinding.worktreeContainer}` : ' (no worktrees)'}\n`);
+      }
+      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${result.otherLanes.length > 0 ? ` --session ${result.sessionId}` : ''})" (D-282).\n`);
+      }
+      if (result.otherLanes.length > 0) {
+        io.stdout.write(`Other active lanes (${result.otherLanes.length}) — pass --session ${result.sessionId} to lane-scoped commands, or run them from this lane's worktree:\n`);
+        for (const lane of result.otherLanes) {
+          io.stdout.write(`- ${lane.id}: ${lane.workingOn ?? 'No summary recorded'}\n`);
+        }
+      }
+    }
+    writeWarnings(io, result.warnings);
+    writeAgentFileSyncResult(io, result.agentFileSync);
+    return 0;
+  }
+
   if (parsed.command === 'list-sessions') {
     await writeCompatibilityPreflightWarnings(io, parsed.options, runtime);
     const result = await listProjectSessions({
       ...parsed.options,
       ...(runtime.cwd ? { cwd: runtime.cwd } : {}),
     });
-    io.stdout.write(`Active session lanes${result.current ? ` (current: ${result.current})` : ''}:\n`);
-    if (result.lanes.length === 0) {
-      io.stdout.write('- None\n');
-    } else {
-      for (const lane of result.lanes) {
-        const marker = lane.id === result.current ? '*' : '-';
-        io.stdout.write(`${marker} ${lane.id}: ${lane.workingOn ?? 'No summary recorded'}\n`);
-      }
+    if (parsed.options.json) {
+      io.stdout.write(`${JSON.stringify({ root_dir: result.rootDir, ...result.inventory }, null, 2)}\n`);
+      return 0;
+    }
+    for (const line of renderLaneInventoryLines(result.inventory)) {
+      io.stdout.write(`${line}\n`);
+    }
+    if (result.inventory.lanes.length > 1) {
+      io.stdout.write('Multiple lanes are active: resume one with `vibecompass continue-session <lane-id>`; the current hint is not a selection (D-277/D-353).\n');
+    } else if (result.inventory.lanes.length === 1) {
+      io.stdout.write(`Resume with \`vibecompass continue-session\` (single active lane resolves implicitly; D-353).\n`);
     }
     return 0;
   }
@@ -736,6 +782,10 @@ export function parseCliArgs(argv) {
       return parseListSessionsArgs(rest);
     }
 
+    if (command === 'continue-session') {
+      return parseContinueSessionArgs(rest);
+    }
+
     if (command === 'switch-session') {
       return parseSwitchSessionArgs(rest);
     }
@@ -1393,6 +1443,11 @@ function parseListSessionsArgs(argv) {
       throw new Error(`Unexpected argument "${token}".`);
     }
 
+    if (token === '--json') {
+      parsed.json = true;
+      continue;
+    }
+
     const value = argv[index + 1];
     if (value === undefined) {
       throw new Error(`Flag "${token}" requires a value.`);
@@ -1636,6 +1691,77 @@ function parseNextDecisionIdArgs(argv) {
   return { command: 'next-decision-id', options: parsed };
 }
 
+function parseContinueSessionArgs(argv) {
+  const parsed = {};
+  const positional = [];
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index];
+
+    if (!token.startsWith('--')) {
+      positional.push(token);
+      continue;
+    }
+
+    if (token === '--json') {
+      parsed.json = true;
+      continue;
+    }
+
+    const value = argv[index + 1];
+    if (value === undefined) {
+      throw new Error(`Flag "${token}" requires a value.`);
+    }
+    index += 1;
+
+    switch (token) {
+      case '--root':
+        parsed.rootDir = value;
+        break;
+      case '--tooling-root':
+        parsed.toolingRootDir = value;
+        break;
+      case '--session':
+        parsed.sessionId = value;
+        break;
+      case '--working-on':
+        parsed.workingOn = value;
+        break;
+      case '--date':
+        parsed.date = value;
+        break;
+      case '--last-thing-completed':
+        parsed.lastThingCompleted = value;
+        break;
+      case '--blockers':
+        parsed.blockers = value;
+        break;
+      case '--next-session-should':
+        parsed.nextSessionShould = value;
+        break;
+      default:
+        throw new Error(`Unknown flag "${token}".`);
+    }
+  }
+
+  if (positional.length > 1) {
+    throw new Error(`Unexpected argument "${positional[1]}".`);
+  }
+
+  if (parsed.sessionId && positional[0] && parsed.sessionId !== positional[0]) {
+    throw new Error(`Conflicting lane IDs: positional "${positional[0]}" and --session "${parsed.sessionId}".`);
+  }
+
+  if (!parsed.sessionId && positional[0]) {
+    parsed.sessionId = positional[0];
+  }
+
+  return {
+    command: 'continue-session',
+    options: parsed,
+  };
+}
+
 function parseSwitchSessionArgs(argv) {
   const parsed = {};
   const positional = [];
@@ -2369,7 +2495,8 @@ function usageText() {
     '  vibecompass start-session --id <lane-id> --working-on <text> [--branch <name> [--worktree]] [options]',
     '  vibecompass close-session --title <text> --completed <text> --architecture-docs <status> --decision-log <status> --session-maintenance <status> [options]',
     '  vibecompass end-session --title <text> --completed <text> --architecture-docs <status> --decision-log <status> --session-maintenance <status> [options]  # alias',
-    '  vibecompass list-sessions [options]',
+    '  vibecompass continue-session [<lane-id>] [--session <lane-id>] [--working-on <text>] [--json] [options]',
+    '  vibecompass list-sessions [--json] [options]',
     '  vibecompass switch-session <id> [options]',
     '  vibecompass rebuild-active-index [--current <lane-id>] [options]',
     '  vibecompass write-lane-marker --session <lane-id> [--dir <path>] [options]',
@@ -2481,9 +2608,21 @@ function usageText() {
     '  --last-thing-completed <text>        Optional override for the CLAUDE.md completed summary',
     '  --next-session-should <text>         Optional override for the CLAUDE.md next-session summary',
     '',
+    'Continue-session options (D-353):',
+    '  --root <path>                        Project-memory root. Explicit --root wins; otherwise the nearest worktree lane marker supplies it, else .compass',
+    '  --tooling-root <path>                Tooling root that contains CLAUDE.md. Defaults to cwd; follows the memory root placement when a marker supplies the root',
+    '  --session <lane-id>                  Lane to resume; positional ID is also accepted. Omitted: nearest worktree lane marker, else the single active lane; 2+ active lanes fail closed and print the lane inventory (D-277)',
+    '  --working-on <text>                  Optional refreshed lane scope; rewrites working_on in session.yaml, the index, wip.md, and CLAUDE.md',
+    '  --date <YYYY-MM-DD>                  Optional explicit resume date (the lane keeps its opening date and session number)',
+    '  --last-thing-completed <text>        Optional override for the CLAUDE.md current-session block',
+    '  --blockers <text>                    Optional current blockers summary',
+    '  --next-session-should <text>         Optional current-session handoff summary',
+    '  --json                               Print the resume result (lane, paths, runtime, other lanes, warnings) as JSON',
+    '',
     'List/switch-session options:',
     '  --root <path>                        Project-memory root. Defaults to .compass',
     '  --session <lane-id>                  Lane ID for switch-session; positional ID is also accepted',
+    '  --json                               list-sessions: print the lane inventory as JSON',
     '',
     'Rebuild-active-index options:',
     '  --root <path>                        Project-memory root. Defaults to .compass',

package/src/generators/agent-files/index.js

@@ -86,11 +86,19 @@ async function syncAgentInstructionFilesLocked(options, cwd, rootDir) {
     const applied = applyManagedBlock(existingContent, generatedContent, {
       adoptExisting,
     });
+    const changed = applied.warning === null && applied.content !== existingContent;
     const conflicts = applied.status === 'adopt'
       ? scanPotentialWorkflowConflicts(existingContent)
       : [];
+    let status = applied.status;
 
-    if (!dryRun && applied.warning === null && applied.content !== existingContent) {
+    if (applied.warning === null) {
+      status = changed
+        ? (dryRun ? `dry-run-${applied.status}` : applied.status)
+        : 'unchanged';
+    }
+
+    if (!dryRun && changed) {
       await mkdir(path.dirname(outputPath), { recursive: true });
       await writeFile(outputPath, applied.content, 'utf8');
     }
@@ -99,9 +107,9 @@ async function syncAgentInstructionFilesLocked(options, cwd, rootDir) {
       format: format.name,
       path: outputPath,
       relativePath: toPosix(path.relative(toolingRootDir, outputPath)),
-      status: dryRun && applied.warning === null ? `dry-run-${applied.status}` : applied.status,
+      status,
       warning: applied.warning,
-      changed: applied.warning === null && applied.content !== existingContent,
+      changed,
       conflicts,
     });
   }

package/src/generators/agent-files/template.js

@@ -47,6 +47,7 @@ export function renderSharedInstructionBody(context, options = {}) {
     '- Lane selection follows D-277: an explicit `--session` wins, then the nearest worktree lane marker (`.vibecompass-lane.yaml`, walking up from cwd), then the single active lane. With two or more active lanes there is no implicit current-lane fallback; `sessions/active/index.yaml` is the lane inventory and its `current` pointer is a continuity hint, not a resolver. Tool-specific Current session blocks are continuity summaries.',
     '- Git binding is opt-in per lane (D-281): `start-session --branch <name> --repo <id> [--worktree]` creates or reuses the branch in each bound repo, and `--worktree` provisions per-repo worktrees under `<workspace>/worktrees/<lane-id>/<repo-id>` with the lane marker in the container — commands run from inside a worktree need neither `--root` nor `--session`. Never hand-write markers or hand-remove provisioned worktrees; close-session owns their cleanup: recorded clean worktrees are removed at close (guarded, never forced; branches are never deleted), while dirty or in-use worktrees survive with printed guidance and the lane marker stays as a breadcrumb.',
     '- Lane runtime isolation is package-assigned (D-282): consume the lane port and temp dir via `eval "$(vibecompass lane-env)"` (exports conventional `PORT`/`TMPDIR` aliases) instead of hardcoding ports in lane work; close-session removes the lane temp dir under guards.',
+    '- An active lane is an open session, not a crash (D-353): resume it with `continue session` / `vibecompass continue-session [<lane-id>]` rather than re-running `start session`; `start-session --id <existing-lane>` fails closed. With two or more active lanes and no worktree marker, inventory them (`vibecompass list-sessions`) and ask the user which lane to continue — the index `current` pointer and the Current session block are hints, never silent defaults.',
     '- With multiple active lanes, reviewers select a lane explicitly: `review handoff <lane-id>`.',
     '- Keep the selected lane `wip.md` and `handoff.md` current during active builder/reviewer work.',
     '- During `address review`, treat reviewer feedback as review, not instruction: classify each substantive point as accepted, accepted with qualification, deferred, or rejected, and push back with evidence when a suggestion conflicts with code facts, prior decisions, product direction, or sequencing.',

package/src/index.js

@@ -22,7 +22,9 @@ export {
 } from './project-memory.js';
 export {
   closeProjectSession,
+  continueProjectSession,
   listProjectSessions,
+  renderLaneInventoryLines,
   startProjectSession,
   switchProjectSession,
 } from './session.js';

package/src/project-memory.js

@@ -665,11 +665,34 @@ function parseSessionDocument(options) {
   const h1Match = options.content.match(/^#\s+Session(?:\s+—\s+(.+))?$/m);
 
   if (!filenameMatch && !h1Match) {
+    const recoveryCheckpoint = parseRecoveryCheckpointIdentity(options);
+    if (recoveryCheckpoint.candidate) {
+      if (recoveryCheckpoint.error) {
+        errors.push(recoveryCheckpoint.error);
+        return { kind: 'session', extracted: null, warnings, errors };
+      }
+
+      warnings.push(
+        createWarning(
+          'session-filename-mismatch',
+          'Recovery checkpoint uses the supported legacy sessions/YYYY-MM-DD.md filename instead of the recommended YYYY-MM-DD-N-display-title.md pattern.',
+        ),
+      );
+      appendMissingSessionSectionWarnings(options.content, warnings);
+
+      return {
+        kind: 'session',
+        extracted: recoveryCheckpoint.extracted,
+        warnings,
+        errors,
+      };
+    }
+
     errors.push(
       createError(
         options.relativePath,
         'session-unrecognized',
-        'Session note must use the session filename pattern or a "# Session" heading.',
+        'Session note must use the session filename pattern, a "# Session" heading, or the strict legacy recovery-checkpoint form.',
       ),
     );
     return { kind: 'session', extracted: null, warnings, errors };
@@ -684,14 +707,7 @@ function parseSessionDocument(options) {
     );
   }
 
-  const sections = extractLevelTwoSections(options.content);
-  for (const section of RECOMMENDED_SESSION_SECTIONS) {
-    if (!sections.has(section.toLowerCase())) {
-      warnings.push(
-        createWarning('session-missing-section', `Session note is missing recommended section "## ${section}".`),
-      );
-    }
-  }
+  appendMissingSessionSectionWarnings(options.content, warnings);
 
   const title = extractSessionTitle(options.content, filenameMatch);
 
@@ -707,6 +723,98 @@ function parseSessionDocument(options) {
   };
 }
 
+function parseRecoveryCheckpointIdentity(options) {
+  const filenameMatch = options.relativePath.match(/^sessions\/(\d{4}-\d{2}-\d{2})\.md$/);
+  const firstLine = options.content.split(/\r?\n/, 1)[0];
+  const headingCandidate = /^# Recovery checkpoint(?:\s|$)/.test(firstLine);
+  const candidate = Boolean(filenameMatch) || headingCandidate;
+
+  if (!candidate) {
+    return { candidate: false, extracted: null, error: null };
+  }
+
+  if (!filenameMatch) {
+    return {
+      candidate: true,
+      extracted: null,
+      error: createError(
+        options.relativePath,
+        'session-recovery-checkpoint-path-invalid',
+        'Legacy recovery checkpoints must be root session files named sessions/YYYY-MM-DD.md.',
+      ),
+    };
+  }
+
+  const headingMatch = firstLine.match(
+    /^# Recovery checkpoint — (\d{4}-\d{2}-\d{2}) — (\S(?:.*\S)?)$/,
+  );
+  if (!headingMatch) {
+    return {
+      candidate: true,
+      extracted: null,
+      error: createError(
+        options.relativePath,
+        'session-recovery-checkpoint-heading-invalid',
+        'Legacy recovery checkpoints require "# Recovery checkpoint — YYYY-MM-DD — <nonempty title>".',
+      ),
+    };
+  }
+
+  const filenameDate = filenameMatch[1];
+  const headingDate = headingMatch[1];
+  if (!isValidIsoCalendarDate(filenameDate) || !isValidIsoCalendarDate(headingDate)) {
+    return {
+      candidate: true,
+      extracted: null,
+      error: createError(
+        options.relativePath,
+        'session-recovery-checkpoint-date-invalid',
+        'Legacy recovery checkpoint dates must be valid ISO calendar dates.',
+      ),
+    };
+  }
+
+  if (filenameDate !== headingDate) {
+    return {
+      candidate: true,
+      extracted: null,
+      error: createError(
+        options.relativePath,
+        'session-recovery-checkpoint-date-mismatch',
+        `Legacy recovery checkpoint filename date ${filenameDate} does not match heading date ${headingDate}.`,
+      ),
+    };
+  }
+
+  return {
+    candidate: true,
+    extracted: {
+      title: headingMatch[2].trim(),
+      session_date: filenameDate,
+      // A checkpoint records continuity inside an open lane; assigning a
+      // number would invent a close-session chronology that never occurred.
+      session_number: null,
+    },
+    error: null,
+  };
+}
+
+function appendMissingSessionSectionWarnings(content, warnings) {
+  const sections = extractLevelTwoSections(content);
+  for (const section of RECOMMENDED_SESSION_SECTIONS) {
+    if (!sections.has(section.toLowerCase())) {
+      warnings.push(
+        createWarning('session-missing-section', `Session note is missing recommended section "## ${section}".`),
+      );
+    }
+  }
+}
+
+function isValidIsoCalendarDate(value) {
+  const parsed = new Date(`${value}T00:00:00.000Z`);
+  return !Number.isNaN(parsed.getTime()) && parsed.toISOString().slice(0, 10) === value;
+}
+
 function extractDecisionEntries(content) {
   const matches = [...content.matchAll(/^###\s+D-(\d{3,})\b.*$/gm)];
 

package/src/scaffold.js

@@ -235,6 +235,7 @@ This workspace uses VibeCompass project memory rooted at \`${rootRelativePath}\`
 - The active lane scratch files live under \`${rootRelativePath}/sessions/active/<lane-id>/\`.
 - Lane selection follows D-277: an explicit \`--session\` wins, then the nearest worktree lane marker (\`.vibecompass-lane.yaml\`, walking up from cwd), then the single active lane. With two or more active lanes there is no implicit current-lane fallback.
 - \`${rootRelativePath}/sessions/active/index.yaml\` is the lane inventory; its \`current\` pointer and the tool-specific Current session block are human-readable continuity summaries, not the lane-selection source of truth.
+- An active lane directory is an open session, not an unclosed crash (D-353). Resume it with \`vibecompass continue-session [<lane-id>]\`: the lane keeps its opening date and session number; the command records \`resumed_at\`/\`resume_count\` in \`session.yaml\`, appends a dated \`Resumed\` line to \`wip.md\`, moves the index \`current\` hint and the Current session block to the lane, and re-emits runtime, git-binding, and staleness warnings. \`start-session --id <existing-lane>\` fails closed and names \`continue-session\`.
 - Optional git binding (D-281): \`start-session --branch <name> --repo <id> [--worktree]\` creates or reuses the branch in every bound repo; \`--worktree\` additionally provisions per-repo worktrees under \`<workspace>/worktrees/<lane-id>/<repo-id>\` with the lane marker written into the container, so commands run from inside a worktree need neither \`--root\` nor \`--session\`. Binding is opt-in and git is never required for lanes.
 - At close, \`close-session\` removes a bound lane's recorded clean worktrees (guarded and never forced: dirty, in-use, or unverifiable worktrees survive with guidance, the lane marker is kept while any worktree survives, and branches are never deleted). Do not hand-remove provisioned worktrees; follow the printed guidance instead.
 - Every lane gets a per-lane runtime assignment at start (D-282): a lane port and temp dir recorded in \`session.yaml\` and exported with \`eval "$(vibecompass lane-env)"\` (includes conventional \`PORT\`/\`TMPDIR\` aliases), so parallel lanes never fight over dev-server ports or temp paths. Defaults are configurable under \`project.yaml\` \`runtime:\`; \`close-session\` removes the lane temp dir under guards.
@@ -248,7 +249,8 @@ ${repos}
 ## Session roles
 | Entry trigger | Role | Owns session lifecycle? |
 |---|---|---|
-| "start session" | Builder | Yes — opens the session, keeps scratch files current, and writes the final session note |
+| "start session" | Builder | Yes — opens a new lane, keeps scratch files current, and writes the final session note |
+| "continue session" | Builder | Yes — resumes an already-open lane and owns its lifecycle from there |
 | "join as reviewer" | Reviewer | No — reviews the builder's work, appends findings, and updates handoff guidance |
 
 ## Session prompt commands
@@ -271,11 +273,20 @@ ${renderWorkflowDefaults(workflow)}
 ## Session startup
 1. Read \`${rootRelativePath}/project.yaml\`.
 2. Read the latest finalized session note in \`${rootRelativePath}/sessions/\`.
-3. If present, read \`${rootRelativePath}/sessions/active/index.yaml\` for the lane inventory; select the lane from an explicit \`--session\`, the nearest worktree lane marker, or the single active lane (D-277).
+3. Inventory active lanes with \`vibecompass list-sessions\` (or read \`${rootRelativePath}/sessions/active/index.yaml\`), then follow the "Open, resume, or choose" protocol below to decide between opening a new lane and resuming one; select a lane from an explicit \`--session\`, the nearest worktree lane marker, or the single active lane (D-277).
 4. If present, read \`${rootRelativePath}/sessions/active/<lane-id>/wip.md\`.
 5. If present, read \`${rootRelativePath}/sessions/active/<lane-id>/handoff.md\`.
 6. Read the relevant docs under \`${rootRelativePath}/architecture/\` and \`${rootRelativePath}/decisions/\`.
 
+## Open, resume, or choose (D-353)
+Both \`start session\` and \`continue session\` begin with the active-lane inventory. Then:
+- **No active lane:** open one with \`vibecompass start-session --id <lane-id> --working-on "..."\`. \`continue session\` with no lane reports that there is nothing to resume and hands off to \`start session\`.
+- **Exactly one active lane, or a cwd bound to a lane by a worktree marker:** resume it with \`vibecompass continue-session\` without asking. Open a second lane only when the user is clearly asking for separate new work; never re-open a lane that already exists.
+- **Two or more active lanes, no marker, no lane named by the user:** do not guess. Present the inventory (lane id, working-on, opened date, resume count, branch/worktree, last log line) and ask which lane to continue or whether to open a new one. The index \`current\` pointer and the Current session block are continuity hints to mention, never defaults to adopt silently. Resume with \`vibecompass continue-session <lane-id>\` once the user answers (\`continue session <lane-id>\`).
+- **Lane named by the user:** \`continue session <lane-id>\` resumes that lane; an unknown id fails closed with the inventory.
+- After resuming, read the lane's \`wip.md\` (latest \`## Log\` entries and \`## Reviewer input needed\`), \`handoff.md\`, and the latest finalized note; treat resume-staleness warnings (new decisions past the lane snapshot, stale base revisions, newer finalized notes touching the lane scope, claim overlap) as required reading before editing.
+- Run recovery (reconstruct a missing finalized note from git history) only when the Current session block date is in the past *and* no active lane exists *and* no finalized note covers that date. An active lane with a past date is simply resumable.
+
 ## Builder workflow
 At session start, prefer running \`vibecompass start-session --id <lane-id> --working-on "..." \`; add \`--feature\`, \`--repo\`, \`--claim\`, \`--architecture-doc\`, and \`--decision-domain-file\` values when the lane's scope is known so overlap warnings can be precise. Add \`--branch <name> --repo <id> [--worktree]\` when the lane should work on its own branch or in isolated worktrees (D-281).
 If you manage files manually, create \`${rootRelativePath}/sessions/active/<lane-id>/session.yaml\` and \`${rootRelativePath}/sessions/active/index.yaml\`, then create \`${rootRelativePath}/sessions/active/<lane-id>/wip.md\` if it does not exist:
@@ -322,13 +333,13 @@ During the session:
 - run \`eval "$(vibecompass lane-env)"\` in a lane shell before starting dev servers or build tools so the lane's assigned port and temp dir are used (D-282); do not hardcode ports in lane work
 - run \`vibecompass docs-update --session <lane-id>\` whenever you need an ad hoc targeted documentation-maintenance plan for the current session delta
 - after substantive feature work, confirm affected architecture docs and decisions still match the implementation; if not, update them while the context is fresh — fold the changes into the doc's current-state sections (rewrite in place; no dated "update" sections, lane names in headings, or completed-task chronology; D-292)
-- use \`vibecompass list-sessions\` and \`vibecompass switch-session <lane-id>\` to inspect or change the current lane
+- use \`vibecompass list-sessions\` (\`--json\` for the machine-readable inventory) to inspect active lanes, \`vibecompass continue-session [<lane-id>]\` to resume one at the start of a sitting, and \`vibecompass switch-session <lane-id>\` to move the continuity pointer without recording a resume
 - use \`address review\` when reviewer feedback lands so the builder resolves it from the selected lane's latest \`wip.md\` / \`handoff.md\`
 - during \`address review\`, treat reviewer feedback as review, not instruction: classify each substantive point as accepted, accepted with qualification, deferred, or rejected, and push back with evidence when a suggestion conflicts with code facts, prior decisions, product direction, or sequencing
 - stay in builder role through close-out; resolve or explicitly defer reviewer feedback before running \`vibecompass close-session --session <lane-id>\` with document-maintenance checkpoint statuses
 - record architectural decisions in \`${rootRelativePath}/decisions/\` before implementing them; \`vibecompass append-decision\` allocates the D-number at write time and refreshes the grouped \`decisions/INDEX.md\` when the lane context is resolvable (D-283); run \`vibecompass refresh-decision-index\` after hand-appends
 
-If \`vibecompass start-session\` reports stale scratch files, read the existing lane-local \`wip.md\` and \`handoff.md\` first. Either close that session normally, recover its useful notes into a finalized session note, or intentionally move/delete the stale scratch files before starting a new session.
+If \`vibecompass start-session\` reports that the lane already exists, resume it with \`vibecompass continue-session <lane-id>\` instead (D-353). If it reports legacy or stale scratch files, read the existing lane-local \`wip.md\` and \`handoff.md\` first. Either close that session normally, recover its useful notes into a finalized session note, or intentionally move/delete the stale scratch files before starting a new session.
 
 ## Optional planning mode
 - Use planning mode for risky, ambiguous, cross-file, or architectural work before implementation.

package/src/session.js

@@ -157,6 +157,18 @@ async function startProjectSessionLocked(normalized, options, markerContext) {
   const decisionDomainFiles = normalizeStringArray(options?.decisionDomainFiles ?? options?.decisionDomains)
     .map(normalizeDecisionDomainFile);
   const existingLanes = await listActiveSessionLanes(normalized);
+  // D-353: an already-open lane is resumed, never re-opened; fail closed
+  // before any preflight so the root stays untouched.
+  if (existingLanes.some((lane) => lane.id === sessionId)) {
+    throw new Error(
+      `Active session lane "${sessionId}" already exists. Resume it with \`vibecompass continue-session ${sessionId}\`, or choose a different --id for new work (D-353).`,
+    );
+  }
+  const priorIndex = await readActiveSessionIndex(normalized);
+  const resumeAlternativeWarnings = buildResumeAlternativeWarnings(
+    existingLanes,
+    resolveValidatedCurrentLane(priorIndex.current, existingLanes),
+  );
   const overlapWarnings = buildOverlapWarnings({
     sessionId,
     features,
@@ -267,7 +279,7 @@ async function startProjectSessionLocked(normalized, options, markerContext) {
   await mkdir(normalized.activeSessionsDir, { recursive: true });
   await mkdir(lanePaths.laneDir, { recursive: false }).catch((error) => {
     if (error && typeof error === 'object' && 'code' in error && error.code === 'EEXIST') {
-      throw new Error(`Active session lane "${sessionId}" already exists. Choose a different --id or close that lane first.`);
+      throw new Error(`Active session lane "${sessionId}" already exists. Resume it with \`vibecompass continue-session ${sessionId}\`, or choose a different --id for new work (D-353).`);
     }
 
     throw error;
@@ -401,6 +413,7 @@ async function startProjectSessionLocked(normalized, options, markerContext) {
     warnings: [
       ...markerContext.warnings,
       ...metadataWarnings,
+      ...resumeAlternativeWarnings,
       ...overlapWarnings,
       ...baseRevisionCapture.warnings,
       ...runtimeSettings.warnings,
@@ -767,13 +780,13 @@ async function canonicalizePathBestEffort(value) {
 }
 
 /** Flattens the docs-update pre-close staleness set into close warnings (A:192 re-emission). */
-function collectStalenessWarnings(plan) {
+function collectStalenessWarnings(plan, label = 'Pre-close staleness') {
   const staleness = plan?.staleness;
   if (!staleness) {
     return [];
   }
 
-  return (staleness.entries ?? []).map((entry) => `Pre-close staleness: ${entry}`);
+  return (staleness.entries ?? []).map((entry) => `${label}: ${entry}`);
 }
 
 function normalizeDocumentMaintenanceCheckpoint(value) {
@@ -893,10 +906,12 @@ export async function listProjectSessions(options = {}) {
   const index = await readActiveSessionIndex(normalized);
   const lanes = await listActiveSessionLanes(normalized);
 
+  const current = resolveValidatedCurrentLane(index.current, lanes);
   return {
     rootDir: normalized.rootDir,
-    current: resolveValidatedCurrentLane(index.current, lanes),
+    current,
     lanes,
+    inventory: buildLaneInventory(lanes, current),
   };
 }
 
@@ -970,6 +985,429 @@ async function switchProjectSessionLocked(normalized, options, markerContext) {
   };
 }
 
+/**
+ * D-353: resumes an already-open lane. Lane selection is the D-277 resolver
+ * (explicit id → worktree marker → single active lane); with two or more
+ * active lanes and no selection the command fails closed, but the error
+ * carries the rendered lane inventory so the caller can choose without a
+ * second command. Resuming never renumbers or re-dates the lane — the wip
+ * header, session number, and eventual finalized-note name stay anchored to
+ * the opening date; only the continuity surfaces (index pointer, Current
+ * session block, wip log, session.yaml resume bookkeeping) move.
+ */
+export async function continueProjectSession(options = {}) {
+  const { normalized, markerContext } = await resolveSessionCommandContext(options, { needMarkerForLane: true });
+  return withMemoryRootLock(normalized.rootDir, 'continue-session', () =>
+    continueProjectSessionLocked(normalized, options, markerContext));
+}
+
+async function continueProjectSessionLocked(normalized, options, markerContext) {
+  await assertLaneMarkerSnapshotCurrent(markerContext);
+  await ensureInitializedProjectMemory(normalized.rootDir, { allowMissingProjectFile: true });
+  const lanes = await listActiveSessionLanes(normalized);
+  const index = await readActiveSessionIndex(normalized);
+  const inventory = buildLaneInventory(lanes, resolveValidatedCurrentLane(index.current, lanes));
+
+  if (lanes.length === 0) {
+    throw new Error(
+      'No active session lane exists to continue. Open one with `vibecompass start-session --id <lane-id> --working-on "..."` (D-353).',
+    );
+  }
+
+  const explicitId = normalizeOptionalString(options?.sessionId);
+  if (!explicitId && !markerContext.marker && lanes.length > 1) {
+    throw new Error(
+      [
+        `Multiple active session lanes exist; continue-session will not guess which one to resume (D-277/D-353).`,
+        ...renderLaneInventoryLines(inventory),
+        'Choose explicitly: `vibecompass continue-session <lane-id>`, or run the command from a directory bound to the intended lane (worktree lane marker).',
+        'The `current` pointer above is a continuity hint, not a selection.',
+      ].join('\n'),
+    );
+  }
+  // An unknown explicit id fails closed with the same inventory the multi-lane
+  // refusal prints, so the caller can correct the id without a second command.
+  if (explicitId && !lanes.some((item) => item.id === validateLaneId(explicitId))) {
+    throw new Error(
+      [
+        `Session lane "${explicitId}" is not an active lane in ${normalized.rootDir}.`,
+        ...renderLaneInventoryLines(inventory),
+        'Resume one of the lanes above with `vibecompass continue-session <lane-id>`.',
+      ].join('\n'),
+    );
+  }
+
+  const selection = resolveLaneSelection({
+    explicitSessionId: explicitId ? validateLaneId(explicitId) : null,
+    marker: markerContext.marker,
+    laneIds: lanes.map((lane) => lane.id),
+    rootDir: normalized.rootDir,
+    purpose: 'continue',
+  });
+  const lane = lanes.find((item) => item.id === selection.sessionId);
+  if (lane.warnings.length > 0) {
+    throw new Error(
+      `Lane "${lane.id}"'s session.yaml could not be parsed (${lane.warnings[0]}); repair the lane metadata before continuing it, or close the lane.`,
+    );
+  }
+
+  const lanePaths = getLanePaths(normalized, lane.id);
+  const missingScratch = [];
+  if (!(await fileExists(lanePaths.wipFilePath))) {
+    missingScratch.push(lanePaths.wipFilePath);
+  }
+  if (!(await fileExists(lanePaths.handoffFilePath))) {
+    missingScratch.push(lanePaths.handoffFilePath);
+  }
+  if (missingScratch.length > 0) {
+    throw new Error(
+      `Lane "${lane.id}" is missing ${missingScratch.join(' and ')}. Recreate the scratch file(s) from the templates in context.md (or close the lane) before continuing it.`,
+    );
+  }
+
+  // Every required input is read and every output is prepared before the
+  // first write, so a deterministic refusal (missing CLAUDE.md, unparseable
+  // scratch, metadata that would not round-trip) leaves all lane, index, and
+  // tooling bytes untouched.
+  const wipContent = await readFile(lanePaths.wipFilePath, 'utf8');
+  const activeSession = parseActiveSession(wipContent, lanePaths.wipFilePath);
+  const sessionContent = await readFile(lanePaths.sessionFilePath, 'utf8');
+  const claude = await readClaudeFile(normalized.claudePath);
+  const currentSession = parseCurrentSessionBlock(claude.content, { optional: true });
+
+  const sessionDate = lane.sessionDate ?? activeSession.sessionDate;
+  const sessionNumber = lane.sessionNumber || activeSession.sessionNumber;
+  const resumeDate = normalizeSessionDate(options?.date);
+  const resumedAt = formatLocalDateTime(new Date());
+  const resumeCount = (lane.resumeCount ?? 0) + 1;
+  const workingOnUpdate = normalizeOptionalString(options?.workingOn);
+  const workingOn = workingOnUpdate ?? lane.workingOn ?? 'No summary recorded';
+  const otherLanes = lanes.filter((item) => item.id !== lane.id);
+
+  const updatedSessionContent = upsertTopLevelYamlScalars(
+    sessionContent,
+    {
+      ...(workingOnUpdate ? { working_on: quoteYamlString(workingOnUpdate) } : {}),
+      resumed_at: resumedAt,
+      resume_count: String(resumeCount),
+    },
+    lanePaths.sessionFilePath,
+  );
+  const otherLaneNote = otherLanes.length > 0
+    ? `; ${otherLanes.length} other active lane${otherLanes.length === 1 ? '' : 's'}: ${otherLanes.map((item) => item.id).join(', ')}`
+    : '';
+  const logLine = `- Resumed lane on ${resumeDate} (continue-session #${resumeCount}${otherLaneNote})${workingOnUpdate ? `. Working on updated: ${workingOnUpdate}` : ''}`;
+  const updatedWipContent = appendWipLogLine(
+    workingOnUpdate ? replaceWipSectionBody(wipContent, 'Working on', workingOnUpdate) : wipContent,
+    logLine,
+  );
+  // Continuity fields carry over only when the block already described this
+  // exact lane (a prefix match such as `billing` vs `billing-tax` must not).
+  const blockNamesThisLane = parseCurrentSessionLaneId(currentSession?.date) === lane.id;
+  const updatedClaudeContent = replaceCurrentSessionBlock(
+    claude.content,
+    {
+      date: `${sessionDate} (session ${sessionNumber}, lane ${lane.id}; resumed ${resumeDate})`,
+      workingOn: `${workingOn} [${lane.id}]`,
+      lastThingCompleted:
+        normalizeOptionalString(options?.lastThingCompleted) ??
+        (blockNamesThisLane ? currentSession.lastThingCompleted : null) ??
+        `Resumed lane ${lane.id} (continue-session #${resumeCount}).`,
+      blockers:
+        normalizeOptionalString(options?.blockers) ??
+        (blockNamesThisLane ? currentSession.blockers : null) ??
+        'No blocker recorded for the selected lane.',
+      nextSessionShould:
+        normalizeOptionalString(options?.nextSessionShould) ??
+        (blockNamesThisLane ? currentSession.nextSessionShould : null) ??
+        'Continue this lane from its wip.md/handoff.md and close it with a finalized session note.',
+    },
+    {
+      lanes: lanes.map((item) => ({ id: item.id, workingOn: item.id === lane.id ? workingOn : item.workingOn })),
+      selectedId: lane.id,
+    },
+  );
+
+  await writeFile(lanePaths.sessionFilePath, updatedSessionContent, 'utf8');
+  await writeFile(lanePaths.wipFilePath, updatedWipContent, 'utf8');
+  await upsertActiveSessionIndex(normalized, { id: lane.id, status: 'active', workingOn }, { current: lane.id });
+  await writeFile(normalized.claudePath, updatedClaudeContent, 'utf8');
+
+  const docsUpdate = await planDocsUpdateSafely({
+    rootDir: normalized.rootDir,
+    cwd: normalized.cwd,
+    sessionId: lane.id,
+    suppressLaneWarnings: true,
+    planner: options?.docsUpdatePlanner,
+  });
+  const manifestRefresh = await refreshStateManifestSafely(normalized.rootDir);
+  const agentFileSync = await syncAgentInstructionFilesSafely({
+    rootDir: normalized.rootDir,
+    toolingRootDir: normalized.toolingRootDir,
+  });
+  const finalizedSessions = await listFinalizedSessions(normalized.sessionsDir);
+  const latestFinalized = finalizedSessions.length > 0 ? finalizedSessions[finalizedSessions.length - 1] : null;
+  // The returned inventory is the post-resume state (what list-sessions shows
+  // now), not the pre-mutation snapshot used for the refusal messages.
+  const inventoryAfter = buildLaneInventory(await listActiveSessionLanes(normalized), lane.id);
+
+  return {
+    rootDir: normalized.rootDir,
+    toolingRootDir: normalized.toolingRootDir,
+    claudePath: normalized.claudePath,
+    sessionId: lane.id,
+    selectionSource: selection.source,
+    sessionFilePath: lanePaths.sessionFilePath,
+    wipFilePath: lanePaths.wipFilePath,
+    handoffFilePath: lanePaths.handoffFilePath,
+    latestFinalizedSessionPath: latestFinalized ? path.join(normalized.sessionsDir, latestFinalized.fileName) : null,
+    sessionDate,
+    sessionNumber,
+    resumeDate,
+    resumedAt,
+    resumeCount,
+    workingOn,
+    workingOnUpdated: Boolean(workingOnUpdate),
+    startedAt: lane.startedAt ?? null,
+    laneAgeDays: computeLaneAgeDays(sessionDate, resumeDate),
+    runtime: lane.runtime ?? null,
+    gitBinding: lane.branch
+      ? {
+          branch: lane.branch,
+          worktreeContainer: lane.worktreeContainer ?? null,
+          worktrees: lane.worktrees ?? {},
+        }
+      : null,
+    otherLanes: inventoryAfter.lanes.filter((item) => item.id !== lane.id),
+    inventory: inventoryAfter,
+    docsUpdatePlan: docsUpdate.plan,
+    warnings: [
+      ...markerContext.warnings,
+      ...selection.warnings,
+      ...collectLaneMetadataWarnings(otherLanes),
+      ...collectStalenessWarnings(docsUpdate.plan, 'Resume staleness'),
+      ...buildSharedCheckoutWarnings({
+        sessionId: lane.id,
+        repos: lane.repos ?? [],
+        claims: lane.claims ?? [],
+        existingLanes: otherLanes,
+        hasWorktree: Boolean(lane.worktreeContainer),
+        context: 'continue-session',
+      }),
+      ...docsUpdate.warnings,
+      ...manifestRefresh.warnings,
+    ],
+    manifest: manifestRefresh.manifest,
+    agentFileSync,
+  };
+}
+
+/**
+ * Lane inventory (D-353): the one summary shape shared by `list-sessions`,
+ * the continue-session multi-lane failure, and the start-session resume
+ * hint, so every surface an agent might read describes lanes the same way.
+ */
+function buildLaneInventory(lanes, current) {
+  return {
+    current: current ?? null,
+    lanes: [...lanes]
+      .sort((left, right) => left.id.localeCompare(right.id))
+      .map((lane) => ({
+        id: lane.id,
+        workingOn: lane.workingOn ?? null,
+        sessionDate: lane.sessionDate ?? null,
+        sessionNumber: lane.sessionNumber || null,
+        startedAt: lane.startedAt ?? null,
+        resumedAt: lane.resumedAt ?? null,
+        resumeCount: lane.resumeCount ?? 0,
+        branch: lane.branch ?? null,
+        worktreeContainer: lane.worktreeContainer ?? null,
+        worktreeRepos: Object.keys(lane.worktrees ?? {}),
+        runtimePort: lane.runtime?.port ?? null,
+        lastLogEntry: lane.lastLogEntry ?? null,
+        isCurrentHint: current != null && lane.id === current,
+        warnings: lane.warnings ?? [],
+      })),
+  };
+}
+
+export function renderLaneInventoryLines(inventory) {
+  const lines = [`Active session lanes${inventory.current ? ` (current hint: ${inventory.current})` : ''}:`];
+  if (inventory.lanes.length === 0) {
+    lines.push('- None');
+    return lines;
+  }
+
+  for (const lane of inventory.lanes) {
+    const marker = lane.isCurrentHint ? '*' : '-';
+    lines.push(`${marker} ${lane.id}: ${lane.workingOn ?? 'No summary recorded'}${lane.isCurrentHint ? ' [current hint]' : ''}`);
+    const facts = [];
+    if (lane.sessionDate) {
+      facts.push(`opened ${lane.sessionDate}${lane.sessionNumber ? ` (session ${lane.sessionNumber})` : ''}`);
+    }
+    if (lane.resumeCount > 0) {
+      facts.push(`resumed ${lane.resumeCount}×${lane.resumedAt ? ` (last ${lane.resumedAt})` : ''}`);
+    }
+    if (lane.branch) {
+      facts.push(`branch ${lane.branch}${lane.worktreeRepos.length > 0 ? ` (worktrees: ${lane.worktreeRepos.join(', ')})` : ''}`);
+    }
+    if (lane.runtimePort != null) {
+      facts.push(`port ${lane.runtimePort}`);
+    }
+    if (facts.length > 0) {
+      lines.push(`    ${facts.join('; ')}`);
+    }
+    if (lane.lastLogEntry) {
+      lines.push(`    last log: ${lane.lastLogEntry}`);
+    }
+    for (const warning of lane.warnings) {
+      lines.push(`    warning: ${warning}`);
+    }
+  }
+
+  return lines;
+}
+
+function buildResumeAlternativeWarnings(existingLanes, currentHint = null) {
+  if (existingLanes.length === 0) {
+    return [];
+  }
+
+  const ids = existingLanes.map((lane) => lane.id).sort((left, right) => left.localeCompare(right));
+  const inventoryLines = renderLaneInventoryLines(buildLaneInventory(existingLanes, currentHint)).map((line) => `  ${line}`);
+  return [
+    [
+      `${ids.length} lane${ids.length === 1 ? ' is' : 's are'} already active (${ids.join(', ')}). Opening a second lane is fine for new work; to resume existing work instead, run \`vibecompass continue-session <lane-id>\` (D-353).`,
+      ...inventoryLines,
+    ].join('\n'),
+  ];
+}
+
+/**
+ * Replaces or appends top-level scalar lines in a lane session.yaml without
+ * re-rendering the file, so keys this writer does not know about survive.
+ * Values are written verbatim through a function replacer (callers quote
+ * where needed; `$&`-style replacement tokens in user text are never
+ * interpreted). Key matching accepts the horizontal spacing parseSimpleYaml
+ * accepts (`key :`) and is CRLF-tolerant, so an existing spaced key is
+ * replaced rather than duplicated. The result is parsed before it is returned
+ * and an unparseable result is refused, so the caller never writes metadata
+ * that the next reader would null-degrade.
+ */
+function upsertTopLevelYamlScalars(content, scalars, sourceName = 'session.yaml') {
+  let next = content;
+  for (const [key, value] of Object.entries(scalars)) {
+    const pattern = new RegExp(`^${key}[ \\t]*:[^\\r\\n]*(\\r?\\n|$)`, 'm');
+    const line = `${key}: ${value}\n`;
+    if (pattern.test(next)) {
+      next = next.replace(pattern, () => line);
+    } else {
+      next = `${next.endsWith('\n') || next.length === 0 ? next : `${next}\n`}${line}`;
+    }
+  }
+
+  try {
+    parseSimpleYaml(next, { sourceName });
+  } catch (error) {
+    throw new Error(
+      `continue-session refused to write ${sourceName}: the updated lane metadata would not parse (${error instanceof Error ? error.message : String(error)}). Nothing was written.`,
+    );
+  }
+
+  return next;
+}
+
+/**
+ * Extracts the lane id recorded in a Current session block Date field
+ * (`YYYY-MM-DD (session N, lane <id>[; resumed YYYY-MM-DD])`). Returns null
+ * when the field has no lane clause, so callers compare full ids for
+ * equality instead of substring-matching.
+ */
+function parseCurrentSessionLaneId(dateField) {
+  if (typeof dateField !== 'string') {
+    return null;
+  }
+
+  const match = dateField.match(/\blane ([a-z0-9][a-z0-9-]*)(?=[;)\s]|$)/);
+  return match ? match[1] : null;
+}
+
+function findWipSection(content, sectionTitle) {
+  const lines = content.split('\n');
+  const heading = `## ${sectionTitle}`.toLowerCase();
+  const start = lines.findIndex((line) => line.trim().toLowerCase() === heading);
+  if (start < 0) {
+    return null;
+  }
+
+  let end = lines.length;
+  for (let index = start + 1; index < lines.length; index += 1) {
+    if (/^##\s+/.test(lines[index])) {
+      end = index;
+      break;
+    }
+  }
+
+  return { lines, start, end };
+}
+
+function appendWipLogLine(content, logLine) {
+  const section = findWipSection(content, 'Log');
+  if (!section) {
+    const base = content.endsWith('\n') ? content : `${content}\n`;
+    return `${base}\n## Log\n${logLine}\n`;
+  }
+
+  const { lines, start, end } = section;
+  let bodyEnd = end;
+  while (bodyEnd > start + 1 && lines[bodyEnd - 1].trim() === '') {
+    bodyEnd -= 1;
+  }
+  const body = lines.slice(start + 1, bodyEnd);
+  // A template placeholder ("- None yet.") is replaced by the first real entry.
+  const kept = body.length === 1 && /^-\s*none yet\.?$/i.test(body[0].trim()) ? [] : body;
+  const trailer = end < lines.length ? [''] : [];
+  return [...lines.slice(0, start + 1), ...kept, logLine, ...trailer, ...lines.slice(end)].join('\n');
+}
+
+function replaceWipSectionBody(content, sectionTitle, bodyText) {
+  const section = findWipSection(content, sectionTitle);
+  if (!section) {
+    return content;
+  }
+
+  const { lines, start, end } = section;
+  const trailer = end < lines.length ? [''] : [];
+  return [...lines.slice(0, start + 1), bodyText, ...trailer, ...lines.slice(end)].join('\n');
+}
+
+function extractLastLogEntry(content) {
+  const section = findWipSection(content, 'Log');
+  if (!section) {
+    return null;
+  }
+
+  const { lines, start, end } = section;
+  for (let index = end - 1; index > start; index -= 1) {
+    const trimmed = lines[index].trim();
+    if (trimmed.length > 0) {
+      return trimmed.length > 200 ? `${trimmed.slice(0, 197)}...` : trimmed;
+    }
+  }
+
+  return null;
+}
+
+function computeLaneAgeDays(openedDate, resumeDate) {
+  const opened = Date.parse(`${openedDate}T00:00:00Z`);
+  const resumed = Date.parse(`${resumeDate}T00:00:00Z`);
+  if (!Number.isFinite(opened) || !Number.isFinite(resumed)) {
+    return null;
+  }
+
+  return Math.max(0, Math.round((resumed - opened) / 86_400_000));
+}
+
 /**
  * Rebuilds `sessions/active/index.yaml` from the active lane directories plus
  * an explicit current-lane selection (D-266/D-277 recovery path). The current
@@ -1532,6 +1970,9 @@ async function listActiveSessionLanes(normalized) {
         architectureDocs: metadata.architectureDocs,
         decisionDomainFiles: metadata.decisionDomainFiles,
         startedAt: metadata.startedAt,
+        resumedAt: metadata.resumedAt ?? null,
+        resumeCount: metadata.resumeCount ?? 0,
+        lastLogEntry: wipSession?.lastLogEntry ?? null,
         decisionSnapshot: metadata.decisionSnapshot,
         branch: metadata.branch ?? null,
         worktreeContainer: metadata.worktreeContainer ?? null,
@@ -1557,7 +1998,11 @@ async function listActiveSessionLanes(normalized) {
 
 async function readLaneWipSession(wipFilePath) {
   try {
-    return parseActiveSession(await readFile(wipFilePath, 'utf8'), wipFilePath);
+    const content = await readFile(wipFilePath, 'utf8');
+    return {
+      ...parseActiveSession(content, wipFilePath),
+      lastLogEntry: extractLastLogEntry(content),
+    };
   } catch {
     return null;
   }
@@ -1576,6 +2021,9 @@ async function readLaneMetadata(sessionFilePath) {
       architectureDocs: normalizeStringArray(data.architecture_docs).map(normalizeArchitectureDocPath),
       decisionDomainFiles: normalizeStringArray(data.decision_domain_files).map(normalizeDecisionDomainFile),
       startedAt: normalizeOptionalString(data.started_at),
+      // D-353 resume bookkeeping; absent on lanes opened before continue-session existed.
+      resumedAt: normalizeOptionalString(data.resumed_at),
+      resumeCount: Math.max(0, Math.trunc(parseNullableNumber(data.resume_count) ?? 0)),
       decisionSnapshot: {
         highestDecisionId: parseNullableNumber(data.decision_snapshot?.highest_decision_id),
       },
@@ -1611,6 +2059,8 @@ async function readLaneMetadata(sessionFilePath) {
       architectureDocs: [],
       decisionDomainFiles: [],
       startedAt: null,
+      resumedAt: null,
+      resumeCount: 0,
       decisionSnapshot: {
         highestDecisionId: null,
       },
@@ -1727,6 +2177,7 @@ async function listFinalizedSessions(sessionsDir) {
       .map((entry) => entry.name.match(SESSION_FILENAME_PATTERN))
       .filter(Boolean)
       .map((match) => ({
+        fileName: match[0],
         sessionDate: match[1],
         sessionNumber: Number(match[2]),
         slug: match[3],

package/src/workflows/registry.js

@@ -7,7 +7,8 @@ export const WORKFLOW_REGISTRY = [
     detailPath: 'context.md',
     summary: 'Builder/reviewer lane lifecycle, handoffs, planning mode, and close-out.',
     promptCommands: [
-      { trigger: 'start session', summary: 'builder role trigger' },
+      { trigger: 'start session', summary: 'builder role trigger; opens a new named lane — if a lane is already active, resume it with `continue session` instead of opening a duplicate' },
+      { trigger: 'continue session', summary: 'builder resumes an already-open lane with `vibecompass continue-session [<lane-id>]` (D-353); with multiple active lanes name the lane explicitly: `continue session <lane-id>` — the agent presents the lane inventory and asks rather than guessing' },
       { trigger: 'join as reviewer', summary: 'reviewer role trigger' },
       { trigger: 'planning mode', summary: 'optional prompt-level mode for scoping work before implementation' },
       { trigger: 'review handoff', summary: 'reviewer reads the selected lane handoff and appends findings; with multiple active lanes name the lane explicitly: `review handoff <lane-id>`' },