@vibecompass/vibecompass 0.13.1 → 0.15.0

package/src/docs-review.js

@@ -19,6 +19,7 @@ import {
   writeDocsReviewSourceInventory,
 } from './source-inventory.js';
 import { readSyncCursor, resolveSyncBinding } from './sync-binding.js';
+import { formatMissingCredentialError, resolveSyncCredential } from './credential-store.js';
 import { PACKAGE_VERSION } from './version.js';
 import { withMemoryRootLock } from './serialization.js';
 import { listDecisionFileNames, readNextDecisionId } from './decisions.js';
@@ -89,6 +90,7 @@ export async function preflightDocsReview(options = {}, environment = {}) {
       rootDir,
       statePath,
       env: environment.env ?? process.env,
+      credentialStore: environment.runtime?.credentialStore ?? null,
       fetch: environment.runtime?.fetch ?? globalThis.fetch,
     });
   }
@@ -137,6 +139,7 @@ export async function preflightDocsReview(options = {}, environment = {}) {
   const hosted = options.submitHosted
     ? await submitHostedDocsReview({
       env,
+      credentialStore: environment.runtime?.credentialStore ?? null,
       project,
       reviewConfig,
       reviewPrompt,
@@ -1588,9 +1591,20 @@ async function submitHostedDocsReview(options) {
     throw new Error('docs-review --submit-hosted requires sync.credential_env_var in project.yaml.');
   }
 
-  const credential = normalizeOptionalString(options.env?.[credentialEnvVar]);
+  // D-355: env override, then the local credential store.
+  const submitBinding = {
+    apiUrl: options.runtime.api_url,
+    projectId: options.runtime.project_id,
+    credentialEnvVar,
+    target: options.runtime.sync_target ?? null,
+  };
+  const submitResolution = await resolveSyncCredential(submitBinding, {
+    env: options.env ?? process.env,
+    ...(options.credentialStore ?? {}),
+  });
+  const credential = submitResolution.credential;
   if (!credential) {
-    throw new Error(`docs-review --submit-hosted requires ${credentialEnvVar}.`);
+    throw new Error(formatMissingCredentialError(submitBinding, { action: 'docs-review --submit-hosted', detail: submitResolution.detail }));
   }
 
   const endpoint = new URL(
@@ -1758,9 +1772,19 @@ async function pollHostedDocsReview(options) {
     throw new Error('docs-review --poll-hosted requires runtime.credential_env_var in state/docs-review.json.');
   }
 
-  const credential = normalizeOptionalString(options.env?.[credentialEnvVar]);
+  const pollBinding = {
+    apiUrl: runtime.api_url,
+    projectId: runtime.project_id,
+    credentialEnvVar,
+    target: runtime.sync_target ?? null,
+  };
+  const pollResolution = await resolveSyncCredential(pollBinding, {
+    env: options.env ?? process.env,
+    ...(options.credentialStore ?? {}),
+  });
+  const credential = pollResolution.credential;
   if (!credential) {
-    throw new Error(`docs-review --poll-hosted requires ${credentialEnvVar}.`);
+    throw new Error(formatMissingCredentialError(pollBinding, { action: 'docs-review --poll-hosted', detail: pollResolution.detail }));
   }
 
   const endpoint = new URL(

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

@@ -7,6 +7,16 @@ export { initializeProjectMemory } from './init.js';
 export { preflightDocsReview } from './docs-review.js';
 export { planDocsUpdate, renderDocsUpdatePlan } from './docs-update.js';
 export { demoteHosted, promoteHosted } from './mode-transition.js';
+export { loginHosted } from './login.js';
+export {
+  describeCredentialSource,
+  formatMissingCredentialError,
+  listSyncCredentials,
+  removeSyncCredential,
+  resolveCredentialStoreDir,
+  resolveSyncCredential,
+  storeSyncCredential,
+} from './credential-store.js';
 export {
   adoptRemoteHead,
   applyPullExport,
@@ -22,7 +32,9 @@ export {
 } from './project-memory.js';
 export {
   closeProjectSession,
+  continueProjectSession,
   listProjectSessions,
+  renderLaneInventoryLines,
   startProjectSession,
   switchProjectSession,
 } from './session.js';

package/src/login.js

@@ -0,0 +1,257 @@
+import { execFile as nodeExecFile } from 'node:child_process';
+import { readFile } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { connectHostedProjectMemory } from './init.js';
+import { parseSimpleYaml } from './simple-yaml.js';
+import { resolveSyncBinding } from './sync-binding.js';
+import {
+  credentialStoreOptionsFrom,
+  normalizeApiUrl,
+  storeSyncCredential,
+} from './credential-store.js';
+import { PACKAGE_VERSION } from './version.js';
+
+/**
+ * Browser device-code sign-in for hosted sync (D-355).
+ *
+ * The CLI asks the hosted app for a device code, shows (and opens) the
+ * verification link plus a short user code, and polls until the signed-in
+ * project owner approves the code in the dashboard. The claim response is the
+ * only place the plaintext token ever exists: the CLI stores it in the local
+ * credential store and, when the root has no sync binding yet, writes the
+ * non-secret binding into project.yaml exactly as `connect-hosted` would.
+ */
+
+export const DEFAULT_HOSTED_API_URL = 'https://vibecompass.dev';
+export const DEFAULT_SYNC_CREDENTIAL_ENV_VAR = 'VIBECOMPASS_SYNC_TOKEN';
+export const DEVICE_AUTH_START_ROUTE = 'api/cli/device-auth';
+export const DEVICE_AUTH_TOKEN_ROUTE = 'api/cli/device-auth/token';
+const DEFAULT_POLL_INTERVAL_SECONDS = 5;
+const DEFAULT_POLL_TIMEOUT_SECONDS = 600;
+const REQUEST_TIMEOUT_MS = 15_000;
+const VALID_MODES = new Set(['local-only', 'local-primary', 'hosted-only']);
+
+export async function loginHosted(options = {}, environment = {}) {
+  const cwd = environment.cwd ? path.resolve(environment.cwd) : process.cwd();
+  const rootDir = path.resolve(cwd, options.rootDir ?? '.compass');
+  const projectFilePath = path.join(rootDir, 'project.yaml');
+  const io = environment.io ?? {};
+  const write = (text) => (io.stdout ?? process.stdout).write(text);
+  const fetchImpl = environment.runtime?.fetch ?? globalThis.fetch;
+  if (typeof fetchImpl !== 'function') {
+    throw new Error('login requires a fetch implementation.');
+  }
+  const sleep = environment.runtime?.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+  const now = environment.runtime?.now ?? (() => Date.now());
+
+  let project;
+  try {
+    project = parseSimpleYaml(await readFile(projectFilePath, 'utf8'), { sourceName: projectFilePath });
+  } catch (error) {
+    if (error && typeof error === 'object' && error.code === 'ENOENT') {
+      throw new Error(`No project.yaml found in ${rootDir}. Run "vibecompass init" first, then "vibecompass login".`);
+    }
+    throw error;
+  }
+  if (!VALID_MODES.has(project.mode)) {
+    throw new Error('login requires project.yaml mode to be local-only, local-primary, or hosted-only.');
+  }
+
+  const binding = resolveLoginBinding(project, options);
+  const apiUrl = binding?.apiUrl ?? options.apiUrl ?? DEFAULT_HOSTED_API_URL;
+  if (binding && options.apiUrl && normalizeApiUrl(options.apiUrl) !== normalizeApiUrl(binding.apiUrl)) {
+    throw new Error(
+      `--api-url ${options.apiUrl} does not match the bound hosted URL ${binding.apiUrl}${binding.target ? ` for target ${binding.target}` : ''}. `
+      + 'Pass --sync-target <name> to sign in to a different environment, or rebind with connect-hosted.',
+    );
+  }
+  const projectHint = binding?.projectId ?? options.projectId ?? null;
+  const credentialEnvVar = binding?.credentialEnvVar ?? options.credentialEnvVar ?? DEFAULT_SYNC_CREDENTIAL_ENV_VAR;
+
+  // Every network wait (start, each poll, and body reads) is bounded by the
+  // overall deadline so a stalled server can never outlive --poll-timeout.
+  const requestedTimeoutSeconds = positiveNumber(options.pollTimeoutSeconds, DEFAULT_POLL_TIMEOUT_SECONDS);
+  let deadline = now() + requestedTimeoutSeconds * 1000;
+  const timing = { now, deadline: () => deadline };
+
+  const start = await postJson(fetchImpl, apiUrl, DEVICE_AUTH_START_ROUTE, {
+    ...(projectHint ? { project_id: projectHint } : {}),
+    label: options.label ?? os.hostname(),
+    package_version: PACKAGE_VERSION,
+  }, timing);
+  if (!start.ok) {
+    throw new Error(`Hosted sign-in could not start (HTTP ${start.status}${start.body?.error ? `: ${start.body.error}` : ''}). Check the hosted URL ${apiUrl} and try again.`);
+  }
+  const deviceCode = requireString(start.body, 'device_code');
+  const userCode = requireString(start.body, 'user_code');
+  const verificationUri = requireString(start.body, 'verification_uri_complete', 'verification_uri');
+  const expiresIn = positiveNumber(start.body.expires_in, DEFAULT_POLL_TIMEOUT_SECONDS);
+  let intervalMs = positiveNumber(start.body.interval, DEFAULT_POLL_INTERVAL_SECONDS) * 1000;
+
+  write('Sign in to VibeCompass\n');
+  write(`Open: ${verificationUri}\n`);
+  write(`Code: ${userCode}\n`);
+  if (!options.noBrowser) {
+    const opened = await openBrowser(verificationUri, environment);
+    write(opened ? 'Opening your browser…\n' : 'Could not open a browser automatically; paste the link into any browser.\n');
+  }
+  write(`Waiting for approval in the dashboard (expires in ${Math.round(expiresIn / 60)} minutes)…\n`);
+
+  deadline = Math.min(deadline, now() + expiresIn * 1000);
+  let claim = null;
+  while (!claim) {
+    const remaining = deadline - now();
+    if (remaining <= 0) {
+      throw new Error('Timed out waiting for the sign-in to be approved. Run "vibecompass login" again.');
+    }
+    await sleep(Math.min(intervalMs, remaining));
+    const poll = await postJson(fetchImpl, apiUrl, DEVICE_AUTH_TOKEN_ROUTE, { device_code: deviceCode }, timing);
+    if (poll.ok && poll.body?.status === 'approved') {
+      claim = poll.body;
+      break;
+    }
+    const code = typeof poll.body?.error === 'string' ? poll.body.error : null;
+    if (code === 'authorization_pending') {
+      continue;
+    }
+    if (code === 'slow_down') {
+      intervalMs += 5000;
+      continue;
+    }
+    if (code === 'expired_token') {
+      throw new Error('The sign-in code expired before it was approved. Run "vibecompass login" again.');
+    }
+    if (code === 'access_denied') {
+      throw new Error('The sign-in request was denied in the dashboard.');
+    }
+    throw new Error(`Hosted sign-in failed (HTTP ${poll.status}${code ? `: ${code}` : ''}).`);
+  }
+
+  const token = requireString(claim, 'token');
+  const approvedProject = claim.project && typeof claim.project === 'object' ? claim.project : {};
+  const projectId = requireString(approvedProject, 'id');
+  const projectName = typeof approvedProject.name === 'string' ? approvedProject.name : projectId;
+
+  const stored = await storeSyncCredential(
+    {
+      apiUrl,
+      projectId,
+      token,
+      label: `VibeCompass sync token (${projectName})`,
+      source: 'login',
+      backend: options.credentialStore,
+    },
+    credentialStoreOptionsFrom(environment),
+  );
+
+  const warnings = [];
+  let bindingWritten = null;
+  if (!binding) {
+    bindingWritten = await connectHostedProjectMemory({
+      cwd,
+      rootDir: options.rootDir ?? '.compass',
+      ...(options.syncTarget ? { targetName: options.syncTarget } : {}),
+      sync: { apiUrl, projectId, credentialEnvVar },
+    });
+  } else if (binding.projectId !== projectId) {
+    warnings.push(
+      `This root is bound to project ${binding.projectId}${binding.target ? ` (target ${binding.target})` : ''}, but you approved ${projectName} (${projectId}). `
+      + `The token is stored for the approved project; rebind with "vibecompass connect-hosted${binding.target ? ` --target ${binding.target}` : ''} --sync-api-url ${apiUrl} --sync-project-id ${projectId} --sync-credential-env-var ${credentialEnvVar}" if that was intended.`,
+    );
+  }
+
+  return {
+    apiUrl,
+    project: { id: projectId, name: projectName },
+    credential: claim.credential && typeof claim.credential === 'object' ? claim.credential : null,
+    stored,
+    binding: bindingWritten,
+    previousBinding: binding,
+    mode: bindingWritten?.mode ?? project.mode,
+    warnings,
+  };
+}
+
+function resolveLoginBinding(project, options) {
+  try {
+    return resolveSyncBinding(project, options.syncTarget ?? null);
+  } catch (error) {
+    // An unknown --sync-target may be created by login only when the caller
+    // is explicit about which hosted environment it points at (D-236: a typo
+    // must never silently land in another environment).
+    if (options.syncTarget && options.apiUrl) {
+      return null;
+    }
+    throw new Error(`${error.message} To create it through login, add --api-url <hosted url>.`);
+  }
+}
+
+async function postJson(fetchImpl, apiUrl, routeName, body, timing) {
+  const endpoint = new URL(routeName, apiUrl.endsWith('/') ? apiUrl : `${apiUrl}/`);
+  const remaining = timing ? timing.deadline() - timing.now() : REQUEST_TIMEOUT_MS;
+  if (remaining <= 0) {
+    throw new Error('Timed out waiting for the sign-in to be approved. Run "vibecompass login" again.');
+  }
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), Math.min(REQUEST_TIMEOUT_MS, remaining));
+  try {
+    let response;
+    try {
+      response = await fetchImpl(endpoint.href, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json', accept: 'application/json' },
+        body: JSON.stringify(body),
+        signal: controller.signal,
+      });
+    } catch (error) {
+      if (controller.signal.aborted) {
+        throw new Error(`Hosted sign-in request to ${endpoint.origin} timed out. Check the connection and run "vibecompass login" again.`);
+      }
+      throw new Error(`Could not reach ${endpoint.origin} (${error?.message ?? 'network error'}).`);
+    }
+    let parsed = null;
+    try {
+      parsed = typeof response.json === 'function' ? await response.json() : null;
+    } catch {
+      if (controller.signal.aborted) {
+        throw new Error(`Hosted sign-in response from ${endpoint.origin} stalled. Check the connection and run "vibecompass login" again.`);
+      }
+      parsed = null;
+    }
+    return { ok: Boolean(response.ok), status: response.status, body: parsed && typeof parsed === 'object' ? parsed : {} };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+async function openBrowser(url, environment) {
+  const platform = environment.runtime?.platform ?? process.platform;
+  const execFileImpl = environment.runtime?.execFile ?? nodeExecFile;
+  const [file, args] = platform === 'darwin'
+    ? ['open', [url]]
+    : platform === 'win32'
+      ? ['cmd', ['/c', 'start', '', url]]
+      : ['xdg-open', [url]];
+  return new Promise((resolve) => {
+    try {
+      execFileImpl(file, args, { windowsHide: true }, (error) => resolve(!error));
+    } catch {
+      resolve(false);
+    }
+  });
+}
+
+function requireString(source, ...keys) {
+  for (const key of keys) {
+    const value = source?.[key];
+    if (typeof value === 'string' && value.trim() !== '') {
+      return value.trim();
+    }
+  }
+  throw new Error(`Hosted sign-in response is missing ${keys[0]}.`);
+}
+
+function positiveNumber(value, fallback) {
+  return typeof value === 'number' && Number.isFinite(value) && value > 0 ? value : fallback;
+}

package/src/mode-transition.js

@@ -2,6 +2,11 @@ import { mkdir, readFile, rm, writeFile } from 'node:fs/promises';
 import path from 'node:path';
 import { parseSimpleYaml } from './simple-yaml.js';
 import { resolveSyncBinding } from './sync-binding.js';
+import {
+  credentialStoreOptionsFrom,
+  formatMissingCredentialError,
+  resolveSyncCredential,
+} from './credential-store.js';
 import { withMemoryRootLock } from './serialization.js';
 import { adoptRemoteHead, pushProjectMemory } from './sync.js';
 
@@ -186,9 +191,10 @@ async function loadModeAgnosticSyncContext(rootDir, options, environment) {
   if (!binding) {
     throw new Error('Mode transitions require a sync binding in project.yaml (run connect-hosted first).');
   }
-  const credential = ((environment.env ?? process.env)[binding.credentialEnvVar] ?? '').trim();
+  const resolution = await resolveSyncCredential(binding, credentialStoreOptionsFrom(environment));
+  const credential = resolution.credential;
   if (!credential) {
-    throw new Error(`Mode transitions require ${binding.credentialEnvVar} to be set.`);
+    throw new Error(formatMissingCredentialError(binding, { action: 'This mode transition', detail: resolution.detail }));
   }
   const fetchImpl = environment.runtime?.fetch ?? globalThis.fetch;
   if (typeof fetchImpl !== 'function') {

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/secret-prompt.js

@@ -0,0 +1,64 @@
+import { createInterface } from 'node:readline/promises';
+import { Writable } from 'node:stream';
+
+/**
+ * Hidden-input prompt for secrets (D-355). Typed characters are never echoed:
+ * readline runs in terminal mode against a muted output while the visible
+ * prompt text is written to the real stdout. A `runtime.prompt` adapter
+ * (tests, embedders) receives `{ type: 'password', message }` instead.
+ */
+export function canPromptSecret(io = {}, runtime = {}) {
+  if (typeof runtime.prompt === 'function') {
+    return true;
+  }
+  const input = runtime.stdin ?? io.stdin ?? process.stdin;
+  return Boolean(input?.isTTY);
+}
+
+export async function promptSecret(message, io = {}, runtime = {}) {
+  if (typeof runtime.prompt === 'function') {
+    return normalizeSecret(await runtime.prompt({ type: 'password', message }));
+  }
+
+  const input = runtime.stdin ?? io.stdin ?? process.stdin;
+  const output = io.stdout ?? process.stdout;
+  if (!input?.isTTY) {
+    throw new Error('Secret prompts require an interactive terminal. Pipe the value with --token-stdin instead.');
+  }
+
+  output.write(`${message}: `);
+  const muted = new Writable({
+    write(_chunk, _encoding, callback) {
+      callback();
+    },
+  });
+  const rl = createInterface({ input, output: muted, terminal: true });
+  try {
+    return normalizeSecret(await rl.question(''));
+  } finally {
+    rl.close();
+    output.write('\n');
+  }
+}
+
+/** Reads one secret from stdin: the first non-empty line, trimmed. */
+export async function readSecretFromStdin(io = {}, runtime = {}) {
+  const input = runtime.stdin ?? io.stdin ?? process.stdin;
+  if (typeof input?.setEncoding === 'function') {
+    input.setEncoding('utf8');
+  }
+  let data = '';
+  for await (const chunk of input) {
+    data += chunk;
+  }
+  const firstLine = data
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .find((line) => line !== '');
+  return firstLine ?? null;
+}
+
+function normalizeSecret(value) {
+  const trimmed = String(value ?? '').trim();
+  return trimmed === '' ? null : trimmed;
+}