@vibecompass/vibecompass 0.1.0 → 0.2.0

package/README.md

@@ -14,7 +14,9 @@ Shipped today:
 - interactive guided init for placement, workflow bootstrap, and first-session setup
 - generated `context.md` plus opt-in workflow guide files
 - opt-in starter `CLAUDE.md` / `AGENTS.md` templates that are created once and never overwritten
-- `vibecompass start-session` / `vibecompass close-session` for the local builder workflow
+- `vibecompass start-session` / `vibecompass close-session` for lane-aware local builder workflow
+- `vibecompass list-sessions` / `vibecompass switch-session` for multiple active session lanes
+- `vibecompass end-session` as a discoverable alias for `close-session`
 - `vibecompass sync-agents` for generated `CLAUDE.md`, `AGENTS.md`, `.cursorrules`, and `.github/copilot-instructions.md` views
 - canonical file scanning and validation
 - `state/manifest.json` generation
@@ -26,6 +28,8 @@ Not shipped yet:
 
 The package is publishable now as the file-contract and read-model core. The
 broader local-primary sync workflow is still being built on top of it.
+The lane-aware session workflow is intended to publish as `0.2.0`; the local
+package may remain at `0.1.0` until the publish pass.
 
 ## Requirements
 
@@ -39,6 +43,9 @@ broader local-primary sync workflow is still being built on top of it.
 npx -y @vibecompass/vibecompass --help
 ```
 
+The npm package is scoped under the VibeCompass org, but the installed CLI
+command is intentionally unscoped: `vibecompass`.
+
 ### Library
 
 ```bash
@@ -98,6 +105,7 @@ If you do not chain straight into a first session from `init`, open one later:
 
 ```bash
 npx -y @vibecompass/vibecompass start-session \
+  --id mcp-dogfood \
   --working-on "Validate the MCP dogfood workflow against the docs repo"
 ```
 
@@ -105,29 +113,49 @@ Close the active builder session:
 
 ```bash
 npx -y @vibecompass/vibecompass close-session \
+  --session mcp-dogfood \
   --title "Workflow Parity Commands" \
   --completed "Added package-owned start-session and close-session commands" \
   --next-step "Run the package publish dry-run"
 ```
 
+`end-session` is accepted as an alias for the same lifecycle step and flags:
+`npx -y @vibecompass/vibecompass end-session ...`.
+
 The package CLI owns filesystem lifecycle only. The default scaffolded
 workflow also uses prompt commands inside your coding tool:
 
 ```text
 start session      # builder role trigger
 join as reviewer   # reviewer role trigger
-review handoff     # reviewer reads the latest note, wip.md, handoff.md, and diffs
-address review     # builder reads reviewer feedback, responds inline, and continues
+review handoff     # reviewer reads selected-lane wip.md, handoff.md, and diffs
+address review     # builder reads selected-lane feedback, responds inline, and continues
 ```
 
 Those prompt commands are documented in the generated `context.md`,
 `CLAUDE.md`, and `AGENTS.md` templates. They are not additional
 `vibecompass` CLI subcommands.
 Reviewer handback is explicit in the package-managed workflow: the reviewer
-ends the pass by updating `wip.md` + `handoff.md`, and the builder closes
-the session with `vibecompass close-session` using the defaults stored in
+ends the pass by updating the selected lane's `wip.md` + `handoff.md`, and
+the builder closes the session with `vibecompass close-session --session
+<lane-id>` using the defaults stored in
 `project.yaml.metadata.workflow.close_session`.
 
+Active builder sessions are named lanes under
+`sessions/active/<lane-id>/`. Use one lane per active feature or workstream.
+`start-session` without `--id` opens the compatibility `default` lane only
+when no other lanes are active; concurrent work should pass `--id`.
+Finalized sessions are append-only notes named
+`sessions/YYYY-MM-DD-N-title.md`, so multiple sessions on the same day
+increment `N`. Decisions remain append-only in `decisions/`; a session note
+can reference a decision, but the decision file is the durable source of truth.
+
+For higher-risk work, use planning mode as a prompt-level step inside the
+active session. Planning mode should read the same context, propose scope and
+tradeoffs, and record the agreed plan in the selected lane's `wip.md`; it
+should not create a separate lifecycle artifact or finalize decisions until
+you approve implementation.
+
 Generate agent-instruction files from project memory:
 
 ```bash
@@ -227,10 +255,31 @@ Options:
 - `--root <path>`: project-memory root; defaults to `.compass`
 - `--tooling-root <path>`: workspace root that contains `CLAUDE.md`; defaults to cwd
 - `--working-on <text>`: required active-session summary
+- `--id <lane-id>`: optional lane ID; defaults to `default` only when no lanes are active
+- `--feature <slug>`: repeatable feature slug for the lane
+- `--repo <id>`: repeatable repo ID for the lane
+- `--claim <path>`: repeatable path claim for overlap warnings
 - `--date <YYYY-MM-DD>`: optional explicit session date
 
 This command updates the `Current session` block in `CLAUDE.md` and creates
-`sessions/wip.md` plus `sessions/handoff.md` for the next session number.
+`sessions/active/<lane-id>/session.yaml`, `wip.md`, and `handoff.md` for the
+next session number. It also updates `sessions/active/index.yaml`.
+
+### `vibecompass list-sessions`
+
+```text
+vibecompass list-sessions [options]
+```
+
+Lists active session lanes and marks the current lane.
+
+### `vibecompass switch-session`
+
+```text
+vibecompass switch-session <lane-id> [options]
+```
+
+Changes the current lane in `sessions/active/index.yaml`.
 
 ### `vibecompass close-session`
 
@@ -238,12 +287,17 @@ This command updates the `Current session` block in `CLAUDE.md` and creates
 vibecompass close-session --title <text> --completed <text> --next-step <text> [options]
 ```
 
+`vibecompass end-session` accepts the same options and runs the same close
+path. `close-session` remains the canonical command name in generated workflow
+metadata and docs.
+
 Options:
 
 - `--root <path>`: project-memory root; defaults to `.compass`
 - `--tooling-root <path>`: workspace root that contains `CLAUDE.md`; defaults to cwd
 - `--title <text>`: required finalized session-note title
 - `--worked-on <text>`: optional override for the "What we worked on" section
+- `--session <lane-id>`: active lane to close; required when multiple lanes are active
 - `--completed <text>`: repeatable completed item
 - `--decision <text>`: repeatable decision reference or summary
 - `--model <text>`: optional repeatable model contribution entry
@@ -251,7 +305,8 @@ Options:
 - `--next-step <text>`: repeatable next-session instruction
 
 This command finalizes the active scratchpad into
-`sessions/YYYY-MM-DD-N-display-title.md`, deletes `wip.md` / `handoff.md`, and
+`sessions/YYYY-MM-DD-N-display-title.md`, deletes the closed lane directory
+under `sessions/active/<lane-id>/`, updates `sessions/active/index.yaml`, and
 updates the `Current session` block in `CLAUDE.md`. If no `--model` flags are
 provided, the session note records `Not recorded.` under `Models used`.
 This is the final builder lifecycle step after the last `address review`
@@ -283,15 +338,15 @@ These are the default prompt commands used by the scaffolded workflow files:
 
 - `start session`: builder role trigger
 - `join as reviewer`: reviewer role trigger
-- `review handoff`: reviewer reads the latest finalized note, `wip.md`, `handoff.md`, and relevant diffs before appending findings
-- `address review`: builder reads the latest reviewer feedback in `wip.md` / `handoff.md`, responds inline, applies accepted changes, and refreshes the builder handoff
+- `review handoff`: reviewer reads the selected lane's latest `wip.md`, `handoff.md`, latest finalized note, and relevant diffs before appending findings
+- `address review`: builder reads the latest reviewer feedback in the selected lane's `wip.md` / `handoff.md`, responds inline, applies accepted changes, and refreshes the builder handoff
 
 They are prompt commands for AI-tool behavior, not package CLI commands.
-Reviewer handback ends when the reviewer has updated `wip.md` and
-`handoff.md`; there is no extra reviewer-exit step. The builder remains
-in builder role, uses `address review` until findings are resolved or
-explicitly deferred, and then runs `vibecompass close-session` using the
-workflow defaults recorded in `project.yaml`.
+Reviewer handback ends when the reviewer has updated the selected lane's
+`wip.md` and `handoff.md`; there is no extra reviewer-exit step. The builder
+remains in builder role, uses `address review` until findings are resolved or
+explicitly deferred, and then runs `vibecompass close-session --session
+<lane-id>` using the workflow defaults recorded in `project.yaml`.
 
 ## JavaScript API
 

package/package.json

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

package/src/cli.js

@@ -4,7 +4,7 @@ import { realpathSync } from 'node:fs';
 import { pathToFileURL } from 'node:url';
 import { initializeProjectMemory } from './init.js';
 import { resolveInitCliOptions } from './setup.js';
-import { closeProjectSession, startProjectSession } from './session.js';
+import { closeProjectSession, listProjectSessions, startProjectSession, switchProjectSession } from './session.js';
 import { syncAgentInstructionFiles } from './generators/agent-files/index.js';
 
 export async function runCli(argv, io = createDefaultIo(), runtime = {}) {
@@ -86,7 +86,7 @@ export async function runCli(argv, io = createDefaultIo(), runtime = {}) {
     return 0;
   }
 
-  if (parsed.command === 'close-session') {
+  if (parsed.command === 'close-session' || parsed.command === 'end-session') {
     const result = await closeProjectSession({
       ...parsed.options,
       ...(runtime.cwd ? { cwd: runtime.cwd } : {}),
@@ -104,6 +104,32 @@ export async function runCli(argv, io = createDefaultIo(), runtime = {}) {
     return 0;
   }
 
+  if (parsed.command === 'list-sessions') {
+    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`);
+      }
+    }
+    return 0;
+  }
+
+  if (parsed.command === 'switch-session') {
+    const result = await switchProjectSession({
+      ...parsed.options,
+      ...(runtime.cwd ? { cwd: runtime.cwd } : {}),
+    });
+    io.stdout.write(`Current session lane: ${result.current}\n`);
+    return 0;
+  }
+
   if (parsed.command === 'sync-agents') {
     const result = await syncAgentInstructionFiles({
       ...parsed.options,
@@ -128,10 +154,18 @@ export function parseCliArgs(argv) {
       return parseStartSessionArgs(rest);
     }
 
-    if (command === 'close-session') {
+    if (command === 'close-session' || command === 'end-session') {
       return parseCloseSessionArgs(rest);
     }
 
+    if (command === 'list-sessions') {
+      return parseListSessionsArgs(rest);
+    }
+
+    if (command === 'switch-session') {
+      return parseSwitchSessionArgs(rest);
+    }
+
     if (command === 'sync-agents') {
       return parseSyncAgentsArgs(rest);
     }
@@ -322,6 +356,18 @@ function parseStartSessionArgs(argv) {
       case '--working-on':
         parsed.workingOn = value;
         break;
+      case '--id':
+        parsed.sessionId = value;
+        break;
+      case '--feature':
+        parsed.features = [...(parsed.features ?? []), value];
+        break;
+      case '--repo':
+        parsed.repos = [...(parsed.repos ?? []), value];
+        break;
+      case '--claim':
+        parsed.claims = [...(parsed.claims ?? []), value];
+        break;
       case '--date':
         parsed.date = value;
         break;
@@ -381,6 +427,9 @@ function parseCloseSessionArgs(argv) {
       case '--worked-on':
         parsed.workedOn = value;
         break;
+      case '--session':
+        parsed.sessionId = value;
+        break;
       case '--completed':
         parsed.completed.push(value);
         break;
@@ -413,6 +462,80 @@ function parseCloseSessionArgs(argv) {
   };
 }
 
+function parseListSessionsArgs(argv) {
+  const parsed = {};
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index];
+    if (!token.startsWith('--')) {
+      throw new Error(`Unexpected argument "${token}".`);
+    }
+
+    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;
+      default:
+        throw new Error(`Unknown flag "${token}".`);
+    }
+  }
+
+  return {
+    command: 'list-sessions',
+    options: parsed,
+  };
+}
+
+function parseSwitchSessionArgs(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;
+    }
+
+    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 '--session':
+        parsed.sessionId = 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];
+  }
+
+  return {
+    command: 'switch-session',
+    options: parsed,
+  };
+}
+
 function parseSyncAgentsArgs(argv) {
   const parsed = {};
 
@@ -483,6 +606,9 @@ function usageText() {
     '  vibecompass init --name <project-name> --mode <local-only|local-primary|hosted-only> --repo <id=remote> [options]',
     '  vibecompass start-session --working-on <text> [options]',
     '  vibecompass close-session --title <text> --completed <text> --next-step <text> [options]',
+    '  vibecompass end-session --title <text> --completed <text> --next-step <text> [options]  # alias',
+    '  vibecompass list-sessions [options]',
+    '  vibecompass switch-session <id> [options]',
     '  vibecompass sync-agents [options]',
     '',
     'Init options:',
@@ -511,16 +637,21 @@ function usageText() {
     '  --root <path>                        Project-memory root. Defaults to .compass',
     '  --tooling-root <path>                Tooling root that contains CLAUDE.md. Defaults to cwd',
     '  --working-on <text>                  Required active-session summary',
+    '  --id <lane-id>                       Optional active session lane ID. Defaults to default when no lanes exist',
+    '  --feature <slug>                     Repeatable feature slug for the lane',
+    '  --repo <id>                          Repeatable repo ID for the lane',
+    '  --claim <path>                       Repeatable path claim for overlap warnings',
     '  --date <YYYY-MM-DD>                  Optional explicit session date',
     '  --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',
     '',
-    'Close-session options:',
+    'Close-session options (also accepted by end-session):',
     '  --root <path>                        Project-memory root. Defaults to .compass',
     '  --tooling-root <path>                Tooling root that contains CLAUDE.md. Defaults to cwd',
     '  --title <text>                       Required display title for the finalized session note',
     '  --worked-on <text>                   Optional override for "What we worked on"',
+    '  --session <lane-id>                  Active session lane to close',
     '  --completed <text>                   Repeatable completed item',
     '  --decision <text>                    Repeatable decision reference or summary',
     '  --model <text>                       Optional repeatable model contribution entry',
@@ -529,6 +660,10 @@ 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',
     '',
+    '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',
+    '',
     'Sync-agents options:',
     '  --root <path>                        Project-memory root. Defaults to .compass',
     '  --tooling-root <path>                Directory where agent files are written. Defaults to cwd',

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

@@ -26,16 +26,25 @@ export function renderSharedInstructionBody(context, options = {}) {
     `- Project memory root: \`${context.rootDir}\``,
     '- Read `project.yaml` for project identity, repos, mode, and workflow defaults.',
     '- Read the latest finalized session note under `sessions/` before resuming work.',
-    '- Read `sessions/wip.md` and `sessions/handoff.md` when they exist; they are the active builder/reviewer scratch files.',
+    '- Read `sessions/active/index.yaml` when it exists, then read the selected lane under `sessions/active/<lane-id>/`.',
+    '- Read the selected lane `wip.md` and `handoff.md` when they exist; they are the active builder/reviewer scratch files.',
     '- Read relevant `architecture/` and `decisions/` files before changing implementation.',
     '',
     '## Project Shape',
     ...renderProjectShape(context),
     '',
     '## Workflow Rules',
+    '- VibeCompass active builder sessions are named lanes. Use one lane per active feature or workstream; finalized session notes are append-only history under `sessions/YYYY-MM-DD-N-title.md`.',
     '- Use `start session` for builder work and `join as reviewer` for review work.',
+    '- Use `vibecompass start-session --id <lane-id>` for concurrent lanes. Omitting `--id` opens the compatibility `default` lane only when no other lanes are active.',
+    '- Use `vibecompass list-sessions` and `vibecompass switch-session <lane-id>` to inspect or change the current lane.',
+    '- Treat `sessions/active/index.yaml` as the current lane source of truth; tool-specific Current session blocks are continuity summaries.',
+    '- Use optional planning mode for risky or ambiguous work: read the same context, propose scope, and record the agreed plan in the selected lane `wip.md` before implementation.',
     '- Use `review handoff` to ask a reviewer to inspect the active handoff.',
-    '- Use `address review` to process reviewer feedback from `sessions/wip.md` and `sessions/handoff.md`.',
+    '- Use `address review` to process reviewer feedback from the selected lane `wip.md` and `handoff.md`.',
+    '- End the active builder session with `vibecompass close-session --session <lane-id>`; `vibecompass end-session` is an accepted alias.',
+    '- If stale scratch files block `start-session`, read them first, then close, recover, move, or delete them intentionally before retrying.',
+    '- Keep decisions append-only in `decisions/`. Session notes may reference decisions, but decisions are the durable source of truth.',
     '- Treat generated agent files as views. Update canonical VibeCompass project memory instead of editing managed regions.',
     '',
     '## Recent Decisions',

package/src/index.js

@@ -1,7 +1,12 @@
 export { STATE_VERSION, generateStateManifest, writeStateManifest } from './manifest.js';
 export { initializeProjectMemory } from './init.js';
 export { scanProjectMemory } from './project-memory.js';
-export { startProjectSession, closeProjectSession } from './session.js';
+export {
+  closeProjectSession,
+  listProjectSessions,
+  startProjectSession,
+  switchProjectSession,
+} from './session.js';
 export {
   syncAgentInstructionFiles,
   getSupportedAgentFormats,

package/src/scaffold.js

@@ -118,8 +118,18 @@ This workspace uses VibeCompass project memory rooted at \`${rootRelativePath}\`
 ## Derived and scratch files
 - \`${rootRelativePath}/context.md\` — generated AI-facing workflow context
 - \`${rootRelativePath}/state/manifest.json\` — machine-owned local state; do not hand-edit
-- \`${rootRelativePath}/sessions/wip.md\` — active builder scratchpad during a session
-- \`${rootRelativePath}/sessions/handoff.md\` — builder/reviewer relay during a session
+- \`${rootRelativePath}/sessions/active/index.yaml\` — active session lane index and current lane pointer
+- \`${rootRelativePath}/sessions/active/<lane-id>/session.yaml\` — lane metadata
+- \`${rootRelativePath}/sessions/active/<lane-id>/wip.md\` — lane-local builder scratchpad
+- \`${rootRelativePath}/sessions/active/<lane-id>/handoff.md\` — lane-local builder/reviewer relay
+
+## Session model
+- VibeCompass active builder sessions are named lanes. Use one lane per active feature or workstream.
+- \`vibecompass start-session\` without \`--id\` opens the compatibility \`default\` lane only when no other lanes are active; use \`--id <lane-id>\` for concurrent work.
+- The active lane scratch files live under \`${rootRelativePath}/sessions/active/<lane-id>/\`.
+- \`${rootRelativePath}/sessions/active/index.yaml\` is the authoritative current lane pointer; the tool-specific Current session block is a human-readable continuity summary, not the lane-selection source of truth.
+- Finalized sessions are append-only notes named \`${rootRelativePath}/sessions/YYYY-MM-DD-N-title.md\`; multiple sessions on the same day increment \`N\`.
+- Decisions remain append-only and independent from session notes. A session note may reference decisions, but the decision entry in \`${rootRelativePath}/decisions/\` is the durable source of truth.
 
 ## Repos in scope
 ${repos}
@@ -133,11 +143,13 @@ ${repos}
 ## Session prompt commands
 - \`start session\` — builder role trigger
 - \`join as reviewer\` — reviewer role trigger
-- \`review handoff\` — reviewer reads the latest finalized note, \`wip.md\`, \`handoff.md\`, and relevant diffs before appending findings
-- \`address review\` — builder reads reviewer feedback in \`wip.md\` / \`handoff.md\`, responds inline, applies accepted changes, and refreshes the builder handoff
+- \`planning mode\` — optional prompt-level mode for scoping work before implementation
+- \`review handoff\` — reviewer reads the selected lane's \`wip.md\`, \`handoff.md\`, latest finalized note, and relevant diffs before appending findings
+- \`address review\` — builder reads reviewer feedback in the selected lane's \`wip.md\` / \`handoff.md\`, responds inline, applies accepted changes, and refreshes the builder handoff
 
 These are prompt commands for agent behavior, not \`vibecompass\` CLI subcommands.
-Reviewer handback is explicit: the reviewer ends the pass by updating \`wip.md\` + \`handoff.md\` and then stopping. Builder close-out uses \`vibecompass close-session\`, which follows the workflow defaults recorded in \`${rootRelativePath}/project.yaml\`.
+Reviewer handback is explicit: the reviewer ends the pass by updating the selected lane's \`wip.md\` + \`handoff.md\` and then stopping. Builder close-out uses \`vibecompass close-session --session <lane-id>\`, which follows the workflow defaults recorded in \`${rootRelativePath}/project.yaml\`.
+\`vibecompass end-session\` is also accepted as an alias for \`vibecompass close-session\`; the canonical command name remains \`close-session\`.
 
 ## Workflow defaults
 ${renderWorkflowDefaults(workflow)}
@@ -145,17 +157,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/wip.md\`.
-4. If present, read \`${rootRelativePath}/sessions/handoff.md\`.
-5. Read the relevant docs under \`${rootRelativePath}/architecture/\` and \`${rootRelativePath}/decisions/\`.
+3. If present, read \`${rootRelativePath}/sessions/active/index.yaml\` and choose the selected or current lane.
+4. If present, read \`${rootRelativePath}/sessions/active/<lane-id>/wip.md\`.
+5. If present, read \`${rootRelativePath}/sessions/active/<lane-id>/handoff.md\`.
+6. Read the relevant docs under \`${rootRelativePath}/architecture/\` and \`${rootRelativePath}/decisions/\`.
 
 ## Builder workflow
-At session start, prefer running \`vibecompass start-session --working-on "..." \`.
-If you manage files manually, create \`${rootRelativePath}/sessions/wip.md\` if it does not exist:
+At session start, prefer running \`vibecompass start-session --id <lane-id> --working-on "..." \`. Omit \`--id\` only for the first/default lane in a project with no other active lanes.
+If you manage files manually, create \`${rootRelativePath}/sessions/active/<lane-id>/session.yaml\` and \`${rootRelativePath}/sessions/active/index.yaml\`, then create \`${rootRelativePath}/sessions/active/<lane-id>/wip.md\` if it does not exist:
 
 \`\`\`md
 # WIP — YYYY-MM-DD (session N)
 
+Session lane: <lane-id>
+
 ## Working on
 
 ## Log
@@ -165,11 +180,13 @@ If you manage files manually, create \`${rootRelativePath}/sessions/wip.md\` if
 ## Review log
 \`\`\`
 
-Also create \`${rootRelativePath}/sessions/handoff.md\` if it does not exist:
+Also create \`${rootRelativePath}/sessions/active/<lane-id>/handoff.md\` if it does not exist:
 
 \`\`\`md
 # Handoff — YYYY-MM-DD (session N)
 
+Session lane: <lane-id>
+
 ## Builder → Reviewer
 
 ### What changed
@@ -188,20 +205,29 @@ Also create \`${rootRelativePath}/sessions/handoff.md\` if it does not exist:
 During the session:
 - append short summaries to \`wip.md\` after meaningful exchanges
 - keep \`handoff.md\` current after substantive work blocks
-- use \`address review\` when reviewer feedback lands so the builder resolves it from the latest \`wip.md\` / \`handoff.md\`
-- stay in builder role through close-out; resolve or explicitly defer reviewer feedback before running \`vibecompass close-session\`
+- use \`vibecompass list-sessions\` and \`vibecompass switch-session <lane-id>\` to inspect or change the current lane
+- use \`address review\` when reviewer feedback lands so the builder resolves it from the selected lane's latest \`wip.md\` / \`handoff.md\`
+- stay in builder role through close-out; resolve or explicitly defer reviewer feedback before running \`vibecompass close-session --session <lane-id>\`
 - record architectural decisions in \`${rootRelativePath}/decisions/\` before implementing them
 
+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.
+
+## Optional planning mode
+- Use planning mode for risky, ambiguous, cross-file, or architectural work before implementation.
+- Planning mode reads the same startup context as builder mode and may update the selected lane's \`wip.md\` with agreed scope, constraints, and open questions.
+- Planning mode should not finalize session notes, mutate decisions, or make broad code changes until the user approves the plan.
+- If planning produces a real architectural decision, append it to \`${rootRelativePath}/decisions/\` before implementing.
+
 At session close:
-- prefer running \`vibecompass close-session --title "..." --completed "..." --model "..." --next-step "..."\`
+- prefer running \`vibecompass close-session --session <lane-id> --title "..." --completed "..." --model "..." --next-step "..."\`; \`vibecompass end-session\` is a supported alias
 - follow the stored close-session defaults from \`${rootRelativePath}/project.yaml\`
-- finalize \`wip.md\` into \`${rootRelativePath}/sessions/YYYY-MM-DD-N-title.md\`
-- delete \`wip.md\` and \`handoff.md\`
+- finalize the lane-local \`wip.md\` into \`${rootRelativePath}/sessions/YYYY-MM-DD-N-title.md\`
+- delete the closed lane directory under \`${rootRelativePath}/sessions/active/<lane-id>/\`
 - refresh any affected architecture/decision docs
 
 ## Reviewer workflow
 - use \`review handoff\` when you want the reviewer to run the next review pass
-- read the latest finalized session note, then \`wip.md\`, then \`handoff.md\`
+- read the latest finalized session note, then the selected lane's \`wip.md\`, then \`handoff.md\`
 - inspect the relevant code/docs diffs
 - append findings under \`## Review log\` in \`wip.md\`
 - write a concise baton-pass summary into \`handoff.md\`
@@ -284,8 +310,10 @@ Finalized session notes for ${projectConfig.name} live here.
 - \`## Next session should start with\`
 
 ## Active-session scratch files
-- \`wip.md\` — builder scratchpad during an active session
-- \`handoff.md\` — reviewer/builder baton-pass during an active session
+- \`active/index.yaml\` — active lane index and current lane pointer
+- \`active/<lane-id>/session.yaml\` — lane metadata
+- \`active/<lane-id>/wip.md\` — builder scratchpad during an active lane
+- \`active/<lane-id>/handoff.md\` — reviewer/builder baton-pass during an active lane
 
 Those scratch files are session-scoped working artifacts, not finalized history.
 `;
@@ -304,16 +332,19 @@ Read \`${options.contextRelativeToToolingRoot}\` before doing substantive work.
 |---|---|---|
 | "start session" | Builder | Yes |
 | "join as reviewer" | Reviewer | No |
+| "planning mode" | Planner | No — scopes work inside the selected active lane before implementation |
 
 ## Prompt commands
 
 - \`start session\` — builder role trigger
 - \`join as reviewer\` — reviewer role trigger
-- \`review handoff\` — reviewer reads the latest finalized note, \`wip.md\`, \`handoff.md\`, and relevant diffs before appending findings
-- \`address review\` — builder reads reviewer feedback in \`wip.md\` / \`handoff.md\`, responds inline, applies accepted changes, and refreshes the builder handoff
+- \`planning mode\` — optional prompt-level mode for scoping risky or ambiguous work before implementation
+- \`review handoff\` — reviewer reads the selected lane's \`wip.md\`, \`handoff.md\`, latest finalized note, and relevant diffs before appending findings
+- \`address review\` — builder reads reviewer feedback in the selected lane's \`wip.md\` / \`handoff.md\`, responds inline, applies accepted changes, and refreshes the builder handoff
 
 These are prompt commands for agent behavior, not \`vibecompass\` CLI subcommands.
-Reviewer handback is explicit: the reviewer ends the pass by updating \`${options.rootRelativePath}/sessions/wip.md\` + \`${options.rootRelativePath}/sessions/handoff.md\` and then stopping. Builder close-out uses \`vibecompass close-session\`, which follows the workflow defaults recorded in \`${options.rootRelativePath}/project.yaml\`.
+Reviewer handback is explicit: the reviewer ends the pass by updating the selected lane's \`wip.md\` + \`handoff.md\` and then stopping. Builder close-out uses \`vibecompass close-session --session <lane-id>\`, which follows the workflow defaults recorded in \`${options.rootRelativePath}/project.yaml\`.
+\`vibecompass end-session\` is accepted as an alias for \`vibecompass close-session\`; \`close-session\` remains the canonical command name.
 
 ## Current session
 
@@ -330,8 +361,11 @@ Next session should: Read \`${options.contextRelativeToToolingRoot}\`, then open
 ## Startup
 - Read \`${options.contextRelativeToToolingRoot}\`
 - Follow the builder/reviewer protocol defined there
-- Use \`vibecompass start-session\` and \`vibecompass close-session\` to manage the active-session files when possible
-- Keep \`${options.rootRelativePath}/sessions/wip.md\` and \`${options.rootRelativePath}/sessions/handoff.md\` current during an active session
+- Use \`vibecompass start-session --id <lane-id>\`, \`vibecompass list-sessions\`, \`vibecompass switch-session <lane-id>\`, and \`vibecompass close-session --session <lane-id>\` to manage active lanes when possible
+- Treat \`${options.rootRelativePath}/sessions/active/index.yaml\` as the current lane source of truth; this Current session block is only a continuity summary
+- Keep the selected lane's \`${options.rootRelativePath}/sessions/active/<lane-id>/wip.md\` and \`${options.rootRelativePath}/sessions/active/<lane-id>/handoff.md\` current during an active session
+- Use planning mode when scope is unclear; record the agreed plan in the selected lane's \`wip.md\` before implementing
+- If stale scratch files block \`start-session\`, read them first, then close, recover, move, or delete them intentionally before retrying
 - Workflow defaults:
 ${renderWorkflowDefaults(workflow)}
 `;
@@ -350,27 +384,33 @@ This workspace uses VibeCompass project memory rooted at \`${options.rootRelativ
 |---|---|---|
 | "start session" | Builder | Yes — opens and closes the session lifecycle |
 | "join as reviewer" | Reviewer | No — reviews the builder's work and updates the handoff |
+| "planning mode" | Planner | No — scopes work inside the selected active lane before implementation |
 
 ## Prompt commands
 
 - \`start session\` — builder role trigger
 - \`join as reviewer\` — reviewer role trigger
-- \`review handoff\` — reviewer reads the latest finalized note, \`wip.md\`, \`handoff.md\`, and relevant diffs before appending findings
-- \`address review\` — builder reads reviewer feedback in \`wip.md\` / \`handoff.md\`, responds inline, applies accepted changes, and refreshes the builder handoff
+- \`planning mode\` — optional prompt-level mode for scoping risky or ambiguous work before implementation
+- \`review handoff\` — reviewer reads the selected lane's \`wip.md\`, \`handoff.md\`, latest finalized note, and relevant diffs before appending findings
+- \`address review\` — builder reads reviewer feedback in the selected lane's \`wip.md\` / \`handoff.md\`, responds inline, applies accepted changes, and refreshes the builder handoff
 
 These are prompt commands for agent behavior, not \`vibecompass\` CLI subcommands.
-Reviewer handback is explicit: the reviewer ends the pass by updating \`${options.rootRelativePath}/sessions/wip.md\` + \`${options.rootRelativePath}/sessions/handoff.md\` and then stopping. Builder close-out uses \`vibecompass close-session\`, which follows the workflow defaults recorded in \`${options.rootRelativePath}/project.yaml\`.
+Reviewer handback is explicit: the reviewer ends the pass by updating the selected lane's \`wip.md\` + \`handoff.md\` and then stopping. Builder close-out uses \`vibecompass close-session --session <lane-id>\`, which follows the workflow defaults recorded in \`${options.rootRelativePath}/project.yaml\`.
+\`vibecompass end-session\` is accepted as an alias for \`vibecompass close-session\`; \`close-session\` remains the canonical command name.
 
 ## Startup
 Before doing substantive work:
 1. Read \`${options.contextRelativeToToolingRoot}\`.
 2. Read the latest finalized session note under \`${options.rootRelativePath}/sessions/\`.
-3. If present, read \`${options.rootRelativePath}/sessions/wip.md\`.
-4. If present, read \`${options.rootRelativePath}/sessions/handoff.md\`.
-5. Read the relevant docs under \`${options.rootRelativePath}/architecture/\` and \`${options.rootRelativePath}/decisions/\`.
+3. If present, read \`${options.rootRelativePath}/sessions/active/index.yaml\` and choose the selected or current lane.
+4. If present, read \`${options.rootRelativePath}/sessions/active/<lane-id>/wip.md\`.
+5. If present, read \`${options.rootRelativePath}/sessions/active/<lane-id>/handoff.md\`.
+6. Read the relevant docs under \`${options.rootRelativePath}/architecture/\` and \`${options.rootRelativePath}/decisions/\`.
 
 ## Working rule
 Treat \`${options.contextRelativeToToolingRoot}\` as the local workflow source of truth for the builder/reviewer protocol and session scratch-file structure. When the package provides \`start-session\` / \`close-session\`, prefer those commands over hand-editing boilerplate.
+Use planning mode when scope is unclear; record the agreed plan in the selected lane's \`wip.md\` before implementing.
+If stale scratch files block \`start-session\`, read them first, then close, recover, move, or delete them intentionally before retrying.
 - Workflow defaults:
 ${renderWorkflowDefaults(workflow)}
 `;
@@ -397,7 +437,7 @@ function renderWorkflowDefaults(workflow) {
 
 function describeReviewerHandback(workflow) {
   if (workflow.reviewerHandback === 'handoff-file') {
-    return 'update sessions/wip.md and sessions/handoff.md, then stop the review pass';
+    return 'update sessions/active/<lane-id>/wip.md and sessions/active/<lane-id>/handoff.md, then stop the review pass';
   }
 
   return workflow.reviewerHandback;

package/src/session.js

@@ -7,6 +7,25 @@ import { syncAgentInstructionFiles } from './generators/agent-files/index.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 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);
@@ -15,18 +34,14 @@ export async function startProjectSession(options) {
 
   await ensureInitializedProjectMemory(normalized.rootDir);
   const claude = await readClaudeFile(normalized.claudePath);
-
-  if ((await fileExists(normalized.wipFilePath)) || (await fileExists(normalized.handoffFilePath))) {
-    throw new Error(
-      `An active session scratch file already exists under ${normalized.sessionsDir}. Close or recover the existing session before starting a new one.`,
-    );
-  }
+  const sessionId = await resolveStartSessionId(normalized, options);
+  const lanePaths = getLanePaths(normalized, sessionId);
 
   const nextSessionNumber = await getNextSessionNumber(normalized.sessionsDir, sessionDate);
   const currentSession = parseCurrentSessionBlock(claude.content);
   const updatedClaude = replaceCurrentSessionBlock(claude.content, {
-    date: `${sessionDate} (session ${nextSessionNumber})`,
-    workingOn,
+    date: `${sessionDate} (session ${nextSessionNumber}, lane ${sessionId})`,
+    workingOn: `${workingOn} [${sessionId}]`,
     lastThingCompleted:
       normalizeOptionalString(options?.lastThingCompleted) ??
       currentSession.lastThingCompleted ??
@@ -37,33 +52,62 @@ export async function startProjectSession(options) {
       'Finish the active session and close it with a finalized session note.',
   });
 
-  await mkdir(normalized.sessionsDir, { recursive: true });
+  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 error;
+  });
   await writeFile(normalized.claudePath, updatedClaude, 'utf8');
   await writeFile(
-    normalized.wipFilePath,
+    lanePaths.sessionFilePath,
+    renderLaneMetadata({
+      sessionId,
+      sessionDate,
+      sessionNumber: nextSessionNumber,
+      workingOn,
+      features: normalizeStringArray(options?.features),
+      repos: normalizeStringArray(options?.repos),
+      claims: normalizeStringArray(options?.claims),
+    }),
+    'utf8',
+  );
+  await writeFile(
+    lanePaths.wipFilePath,
     renderWipTemplate({
       sessionDate,
       sessionNumber: nextSessionNumber,
       workingOn,
+      sessionId,
     }),
     'utf8',
   );
   await writeFile(
-    normalized.handoffFilePath,
+    lanePaths.handoffFilePath,
     renderHandoffTemplate({
       sessionDate,
       sessionNumber: nextSessionNumber,
       workingOn,
+      sessionId,
     }),
     'utf8',
   );
+  await upsertActiveSessionIndex(normalized, {
+    id: sessionId,
+    status: 'active',
+    workingOn,
+  }, { current: sessionId });
 
   return {
     rootDir: normalized.rootDir,
     toolingRootDir: normalized.toolingRootDir,
     claudePath: normalized.claudePath,
-    wipFilePath: normalized.wipFilePath,
-    handoffFilePath: normalized.handoffFilePath,
+    sessionId,
+    sessionFilePath: lanePaths.sessionFilePath,
+    wipFilePath: lanePaths.wipFilePath,
+    handoffFilePath: lanePaths.handoffFilePath,
     sessionDate,
     sessionNumber: nextSessionNumber,
   };
@@ -71,7 +115,7 @@ export async function startProjectSession(options) {
 
 export async function closeProjectSession(options) {
   const normalized = normalizeSessionPaths(options);
-  const title = requireNonEmptyString(options?.title, 'close-session requires a non-empty title.');
+  const title = requireNonEmptyString(options?.title, 'session close requires a non-empty title.');
   const completed = normalizeStringArray(options?.completed);
   const models = normalizeStringArray(options?.models);
   const nextSteps = normalizeStringArray(options?.nextSteps);
@@ -79,25 +123,27 @@ export async function closeProjectSession(options) {
   const blockers = normalizeStringArray(options?.blockers);
 
   if (completed.length === 0) {
-    throw new Error('close-session requires at least one completed item.');
+    throw new Error('session close requires at least one completed item.');
   }
 
   if (nextSteps.length === 0) {
-    throw new Error('close-session requires at least one next-step entry.');
+    throw new Error('session close requires at least one next-step entry.');
   }
 
   await ensureInitializedProjectMemory(normalized.rootDir, { allowMissingProjectFile: true });
   const claude = await readClaudeFile(normalized.claudePath);
   const workflowSettings = await readWorkflowSettings(normalized.projectFilePath);
+  const sessionId = await resolveExistingSessionId(normalized, options);
+  const lanePaths = sessionId ? getLanePaths(normalized, sessionId) : normalized;
 
-  if (!(await fileExists(normalized.wipFilePath))) {
+  if (!(await fileExists(lanePaths.wipFilePath))) {
     throw new Error(
-      `No active session scratchpad exists at ${normalized.wipFilePath}. Start a session before trying to close it.`,
+      `No active session scratchpad exists at ${lanePaths.wipFilePath}. Start a session before trying to close it.`,
     );
   }
 
-  const wipContent = await readFile(normalized.wipFilePath, 'utf8');
-  const activeSession = parseActiveSession(wipContent);
+  const wipContent = await readFile(lanePaths.wipFilePath, 'utf8');
+  const activeSession = parseActiveSession(wipContent, lanePaths.wipFilePath);
   const currentSession = parseCurrentSessionBlock(claude.content);
   const workedOn =
     normalizeOptionalString(options?.workedOn) ??
@@ -105,12 +151,12 @@ export async function closeProjectSession(options) {
     currentSession.workingOn;
 
   if (!workedOn) {
-    throw new Error('close-session could not determine what the session worked on. Pass workedOn explicitly.');
+    throw new Error('session close could not determine what the session worked on. Pass workedOn explicitly.');
   }
 
   const sessionSlug = slugifyTitle(title);
   if (!sessionSlug) {
-    throw new Error('close-session title must contain at least one letter or number.');
+    throw new Error('session close title must contain at least one letter or number.');
   }
 
   const sessionRelativePath = toPosix(
@@ -138,10 +184,15 @@ export async function closeProjectSession(options) {
     'utf8',
   );
 
-  const hadHandoff = await fileExists(normalized.handoffFilePath);
-  await rm(normalized.wipFilePath, { force: true });
-  if (hadHandoff) {
-    await rm(normalized.handoffFilePath, { force: true });
+  const hadHandoff = await fileExists(lanePaths.handoffFilePath);
+  if (sessionId) {
+    await rm(lanePaths.laneDir, { recursive: true, force: true });
+    await removeActiveSessionFromIndex(normalized, sessionId);
+  } else {
+    await rm(lanePaths.wipFilePath, { force: true });
+    if (hadHandoff) {
+      await rm(lanePaths.handoffFilePath, { force: true });
+    }
   }
 
   const updatedClaude = replaceCurrentSessionBlock(claude.content, {
@@ -166,6 +217,7 @@ export async function closeProjectSession(options) {
     toolingRootDir: normalized.toolingRootDir,
     claudePath: normalized.claudePath,
     projectFilePath: normalized.projectFilePath,
+    sessionId,
     sessionFilePath,
     sessionRelativePath,
     sessionDate: activeSession.sessionDate,
@@ -173,12 +225,43 @@ export async function closeProjectSession(options) {
     workflowGuidance: buildCloseSessionGuidance(workflowSettings),
     agentFileSync,
     removedScratchFiles: [
-      normalized.wipFilePath,
-      ...(hadHandoff ? [normalized.handoffFilePath] : []),
+      lanePaths.wipFilePath,
+      ...(hadHandoff ? [lanePaths.handoffFilePath] : []),
     ],
   };
 }
 
+export async function listProjectSessions(options = {}) {
+  const normalized = normalizeSessionPaths(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,
+    lanes,
+  };
+}
+
+export async function switchProjectSession(options = {}) {
+  const normalized = normalizeSessionPaths(options);
+  const sessionId = validateLaneId(requireNonEmptyString(options?.sessionId, 'switch-session requires a session ID.'));
+  const lanes = await listActiveSessionLanes(normalized);
+
+  if (!lanes.some((lane) => lane.id === sessionId)) {
+    throw new Error(`Active session lane "${sessionId}" does not exist.`);
+  }
+
+  await upsertActiveSessionIndex(normalized, null, { current: sessionId });
+
+  return {
+    rootDir: normalized.rootDir,
+    current: sessionId,
+    lanes,
+  };
+}
+
 async function syncAgentInstructionFilesSafely(options) {
   try {
     return await syncAgentInstructionFiles(options);
@@ -203,20 +286,32 @@ async function syncAgentInstructionFilesSafely(options) {
 
 function normalizeSessionPaths(options) {
   const cwd = options?.cwd ? path.resolve(options.cwd) : process.cwd();
+  const rootDir = path.resolve(cwd, options?.rootDir ?? '.compass');
+  const toolingRootDir = options?.toolingRootDir
+    ? path.resolve(cwd, options.toolingRootDir)
+    : cwd;
 
   return {
-    rootDir: path.resolve(cwd, options?.rootDir ?? '.compass'),
-    toolingRootDir: options?.toolingRootDir
-      ? path.resolve(cwd, options.toolingRootDir)
-      : cwd,
-    projectFilePath: path.resolve(path.resolve(cwd, options?.rootDir ?? '.compass'), 'project.yaml'),
-    claudePath: path.resolve(
-      options?.toolingRootDir ? path.resolve(cwd, options.toolingRootDir) : cwd,
-      'CLAUDE.md',
-    ),
-    sessionsDir: path.resolve(path.resolve(cwd, options?.rootDir ?? '.compass'), 'sessions'),
-    wipFilePath: path.resolve(path.resolve(cwd, options?.rootDir ?? '.compass'), 'sessions/wip.md'),
-    handoffFilePath: path.resolve(path.resolve(cwd, options?.rootDir ?? '.compass'), 'sessions/handoff.md'),
+    rootDir,
+    toolingRootDir,
+    projectFilePath: path.resolve(rootDir, 'project.yaml'),
+    claudePath: path.resolve(toolingRootDir, 'CLAUDE.md'),
+    sessionsDir: path.resolve(rootDir, 'sessions'),
+    activeSessionsDir: path.resolve(rootDir, 'sessions/active'),
+    activeSessionsIndexPath: path.resolve(rootDir, 'sessions/active/index.yaml'),
+    wipFilePath: path.resolve(rootDir, 'sessions/wip.md'),
+    handoffFilePath: path.resolve(rootDir, 'sessions/handoff.md'),
+  };
+}
+
+function getLanePaths(normalized, sessionId) {
+  const laneDir = path.resolve(normalized.activeSessionsDir, sessionId);
+
+  return {
+    laneDir,
+    sessionFilePath: path.resolve(laneDir, 'session.yaml'),
+    wipFilePath: path.resolve(laneDir, 'wip.md'),
+    handoffFilePath: path.resolve(laneDir, 'handoff.md'),
   };
 }
 
@@ -304,11 +399,166 @@ function replaceCurrentSessionBlock(content, fields) {
 
 async function getNextSessionNumber(sessionsDir, sessionDate) {
   const sessions = await listFinalizedSessions(sessionsDir);
-  const todaysSessions = sessions.filter((session) => session.sessionDate === sessionDate);
+  const activeSessions = await listActiveSessionLanes({ sessionsDir, activeSessionsDir: path.join(sessionsDir, 'active') });
+  const todaysSessions = [
+    ...sessions,
+    ...activeSessions,
+  ].filter((session) => session.sessionDate === sessionDate);
   const highestNumber = todaysSessions.reduce((max, session) => Math.max(max, session.sessionNumber), 0);
   return highestNumber + 1;
 }
 
+async function resolveStartSessionId(normalized, options) {
+  const explicitId = normalizeOptionalString(options?.sessionId);
+  if (explicitId) {
+    return validateLaneId(explicitId);
+  }
+
+  const lanes = await listActiveSessionLanes(normalized);
+  if (lanes.length > 0) {
+    throw new Error('Active session lanes already exist. Pass --id to start another lane explicitly.');
+  }
+
+  if ((await fileExists(normalized.wipFilePath)) || (await fileExists(normalized.handoffFilePath))) {
+    throw new Error(
+      `Legacy active session scratch files already exist under ${normalized.sessionsDir}. Close or recover that session before starting a lane.`,
+    );
+  }
+
+  return 'default';
+}
+
+async function resolveExistingSessionId(normalized, options) {
+  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;
+}
+
+async function listActiveSessionLanes(normalized) {
+  try {
+    const entries = await readdir(normalized.activeSessionsDir, { withFileTypes: true });
+    const lanes = [];
+    for (const entry of entries) {
+      if (!entry.isDirectory()) {
+        continue;
+      }
+
+      const sessionId = entry.name;
+      const lanePaths = getLanePaths(normalized, sessionId);
+      const metadata = await readLaneMetadata(lanePaths.sessionFilePath);
+      const wipSession = await readLaneWipSession(lanePaths.wipFilePath);
+      lanes.push({
+        id: sessionId,
+        status: metadata.status ?? 'active',
+        workingOn: metadata.workingOn ?? null,
+        features: metadata.features,
+        repos: metadata.repos,
+        claims: metadata.claims,
+        sessionDate: metadata.sessionDate ?? wipSession?.sessionDate ?? null,
+        sessionNumber: metadata.sessionNumber ?? wipSession?.sessionNumber ?? 0,
+      });
+    }
+
+    return lanes.sort((left, right) => left.id.localeCompare(right.id));
+  } catch (error) {
+    if (error && typeof error === 'object' && 'code' in error && error.code === 'ENOENT') {
+      return [];
+    }
+
+    throw error;
+  }
+}
+
+async function readLaneWipSession(wipFilePath) {
+  try {
+    return parseActiveSession(await readFile(wipFilePath, 'utf8'), wipFilePath);
+  } catch {
+    return null;
+  }
+}
+
+async function readLaneMetadata(sessionFilePath) {
+  try {
+    const content = await readFile(sessionFilePath, 'utf8');
+    const data = parseSimpleYaml(content, { sourceName: sessionFilePath });
+    return {
+      status: normalizeOptionalString(data.status),
+      workingOn: normalizeOptionalString(data.working_on),
+      features: normalizeStringArray(data.feature_slugs),
+      repos: normalizeStringArray(data.repos),
+      claims: normalizeStringArray(data.claimed_paths),
+      sessionDate: normalizeOptionalString(data.session_date),
+      sessionNumber: typeof data.session_number === 'number' ? data.session_number : Number(data.session_number) || null,
+    };
+  } catch {
+    return {
+      status: null,
+      workingOn: null,
+      features: [],
+      repos: [],
+      claims: [],
+      sessionDate: null,
+      sessionNumber: null,
+    };
+  }
+}
+
+async function readActiveSessionIndex(normalized) {
+  try {
+    const data = parseSimpleYaml(await readFile(normalized.activeSessionsIndexPath, 'utf8'), {
+      sourceName: normalized.activeSessionsIndexPath,
+    });
+    return {
+      current: normalizeOptionalString(data.current),
+    };
+  } catch {
+    return {
+      current: null,
+    };
+  }
+}
+
+async function upsertActiveSessionIndex(normalized, lane, options = {}) {
+  const currentIndex = await readActiveSessionIndex(normalized);
+  const lanes = await listActiveSessionLanes(normalized);
+  const laneMap = new Map(lanes.map((item) => [item.id, item]));
+  if (lane) {
+    laneMap.set(lane.id, {
+      id: lane.id,
+      status: lane.status,
+      workingOn: lane.workingOn,
+    });
+  }
+
+  const current = options.current ?? currentIndex.current ?? lane?.id ?? null;
+  await mkdir(normalized.activeSessionsDir, { recursive: true });
+  await writeFile(normalized.activeSessionsIndexPath, renderActiveSessionIndex(current, [...laneMap.values()]), 'utf8');
+}
+
+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;
+  if (lanes.length === 0) {
+    await rm(normalized.activeSessionsIndexPath, { force: true });
+    return;
+  }
+
+  await writeFile(normalized.activeSessionsIndexPath, renderActiveSessionIndex(current, lanes), 'utf8');
+}
+
 async function listFinalizedSessions(sessionsDir) {
   try {
     const entries = await readdir(sessionsDir, { withFileTypes: true });
@@ -337,10 +587,10 @@ async function listFinalizedSessions(sessionsDir) {
   }
 }
 
-function parseActiveSession(wipContent) {
+function parseActiveSession(wipContent, wipFilePath = 'sessions/active/<lane-id>/wip.md') {
   const match = wipContent.match(WIP_HEADER_PATTERN);
   if (!match) {
-    throw new Error('sessions/wip.md is missing the expected "# WIP — YYYY-MM-DD (session N)" header.');
+    throw new Error(`${wipFilePath} is missing the expected "# WIP — YYYY-MM-DD (session N)" header.`);
   }
 
   return {
@@ -349,6 +599,19 @@ function parseActiveSession(wipContent) {
   };
 }
 
+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');
@@ -407,6 +670,8 @@ function findCurrentSessionFence(content) {
 function renderWipTemplate(options) {
   return `# WIP — ${options.sessionDate} (session ${options.sessionNumber})
 
+Session lane: ${options.sessionId}
+
 ## Working on
 ${options.workingOn}
 
@@ -423,6 +688,8 @@ ${options.workingOn}
 function renderHandoffTemplate(options) {
   return `# Handoff — ${options.sessionDate} (session ${options.sessionNumber})
 
+Session lane: ${options.sessionId}
+
 ## Builder → Reviewer
 
 ### What changed
@@ -444,6 +711,53 @@ function renderHandoffTemplate(options) {
 `;
 }
 
+function renderLaneMetadata(options) {
+  return [
+    `id: ${options.sessionId}`,
+    'status: active',
+    `session_date: ${options.sessionDate}`,
+    `session_number: ${options.sessionNumber}`,
+    `working_on: ${quoteYamlString(options.workingOn)}`,
+    renderYamlArray('feature_slugs', options.features),
+    renderYamlArray('repos', options.repos),
+    renderYamlArray('claimed_paths', options.claims),
+    `started_at: ${new Date().toISOString()}`,
+    'decision_snapshot:',
+    '  highest_decision_id: null',
+    '',
+  ].join('\n');
+}
+
+function renderActiveSessionIndex(current, lanes) {
+  const lines = [
+    `current: ${current ?? 'null'}`,
+    'lanes:',
+  ];
+
+  for (const lane of lanes.sort((left, right) => left.id.localeCompare(right.id))) {
+    lines.push(`  - id: ${lane.id}`);
+    lines.push(`    status: ${lane.status ?? 'active'}`);
+    lines.push(`    working_on: ${quoteYamlString(lane.workingOn ?? '')}`);
+  }
+
+  return `${lines.join('\n')}\n`;
+}
+
+function renderYamlArray(key, values) {
+  if (!values || values.length === 0) {
+    return `${key}: []`;
+  }
+
+  return [
+    `${key}:`,
+    ...values.map((value) => `  - ${quoteYamlString(value)}`),
+  ].join('\n');
+}
+
+function quoteYamlString(value) {
+  return JSON.stringify(value);
+}
+
 function renderSessionNote(options) {
   return `# Session — ${options.sessionDate}-${options.sessionNumber} — ${options.title}
 

package/src/workflow.js

@@ -77,7 +77,7 @@ export function buildWorkflowMetadata(existingMetadata, overrides = {}) {
 export function buildCloseSessionGuidance(workflowSettings) {
   const guidance = [];
 
-  guidance.push('Reviewer handback stays in sessions/wip.md and sessions/handoff.md before close-session runs.');
+  guidance.push('Reviewer handback stays in the selected sessions/active/<lane-id>/wip.md and handoff.md before close-session runs.');
 
   if (workflowSettings.closeSession.refreshArchitectureDocs) {
     guidance.push('Refresh any relevant architecture docs before finalizing the session.');