@zuzuucodes/cli 1.2.3 → 1.3.1

package/zuzuu/commands/status.mjs

@@ -1,7 +1,9 @@
 // `zuzuu status` — detected hosts + recorded sessions (the git-native index).
 
 import { existsSync } from 'node:fs';
+import { dirname } from 'node:path';
 import { detected } from '../capture/adapters/registry.mjs';
+import { sessionStatus } from '../session-git.mjs';
 import { readIndex, paths } from '../store.mjs';
 import { FACULTIES } from '../faculty/contract.mjs';
 import { listProposals } from '../faculty/proposal.mjs';
@@ -10,8 +12,9 @@ import { detectDrift } from './doctor.mjs';
 
 const fmtDur = (ms) => (ms < 60_000 ? `${(ms / 1000).toFixed(0)}s` : `${(ms / 60_000).toFixed(1)}m`);
 
-/** Pure: structured status for a faculty home (the zuzuu-web /status source). Fail-soft per field. */
-export function statusData(agentDir, { hosts = detected().map((a) => ({ name: a.name })) } = {}) {
+/** Pure: structured status for a faculty home (the zuzuu-web /status source). Fail-soft per field.
+ *  `session` is injectable (like hosts) for hermetic tests; default = the repo above the home. */
+export function statusData(agentDir, { hosts = detected().map((a) => ({ name: a.name })), session } = {}) {
   let active = null, drift = { dirty: false, items: [] };
   const pending = {};
   try { active = activeGenerationFn(agentDir); } catch { active = null; }
@@ -23,7 +26,11 @@ export function statusData(agentDir, { hosts = detected().map((a) => ({ name: a.
     const items = Array.isArray(d?.drifted) ? d.drifted : [];
     drift = { dirty: items.length > 0, items };
   } catch { /* fail-soft */ }
-  return { home: existsSync(agentDir), activeGeneration: active, pending, drift, hosts };
+  let sess = session;
+  if (sess === undefined) {
+    try { sess = sessionStatus(dirname(agentDir)); } catch { sess = null; } // sessionStatus never throws — belt + braces
+  }
+  return { home: existsSync(agentDir), activeGeneration: active, pending, drift, hosts, session: sess };
 }
 
 /**

package/zuzuu/commands/web.mjs

@@ -11,14 +11,27 @@
 // the workbench, never the CLI. `--omit=optional` installs skip the deps; this
 // command then explains how to repair.
 //
+// Singleton-per-workspace (2026-06-12): the daemon records itself in
+// ~/.webcode/instances/<sha256(realpath-root).slice(0,16)>.json after listen
+// and removes it on clean shutdown (daemon src/instance-file.ts — the path
+// scheme here MUST stay in sync with it). Before spawning we check that file:
+// a live instance (pid alive + HTTP listener answering) is REUSED — same port,
+// same token, old browser tabs keep working; a stale file is deleted and we
+// spawn fresh. `--stop` / `--status` manage the running instance.
+// (The file carries the auth token: 0600, user's own machine, and the token
+// already appears in the daemon's stdout — acceptable.)
+//
 // Resolution order:
 //   1. the bundled web-app/dist next to this package (installed OR repo after build:web)
 //   2. the nested dev project's built daemon (web/packages/daemon, repo checkout)
 //   3. a standalone `zuzuu-web` on PATH (legacy/manual installs)
 //   4. none → repair hint (reinstall, or `npm run build:web` in a checkout)
 
-import { existsSync } from 'node:fs';
+import { existsSync, readFileSync, realpathSync, unlinkSync } from 'node:fs';
 import { resolve, dirname, join } from 'node:path';
+import { homedir } from 'node:os';
+import { createHash } from 'node:crypto';
+import http from 'node:http';
 import { spawn } from 'node:child_process';
 import { spawnSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
@@ -45,25 +58,108 @@ const realLaunch = ({ cwd, entryScript }) => {
   if (entryScript) spawn(process.execPath, [entryScript, cwd], { detached: true, stdio: 'ignore' }).unref();
   else spawn('zuzuu-web', [cwd], { detached: true, stdio: 'ignore' }).unref();
 };
+// Same scheme as the daemon's instance-file.ts: sha256 of the realpath'd root.
+const realInstancePathFor = (dir) => {
+  let real = dir;
+  try { real = realpathSync(dir); } catch { /* missing dir → daemon will refuse anyway */ }
+  const id = createHash('sha256').update(real).digest('hex').slice(0, 16);
+  return join(homedir(), '.webcode', 'instances', `${id}.json`);
+};
+const realReadInstance = (file) => {
+  try { return JSON.parse(readFileSync(file, 'utf8')); } catch { return null; }
+};
+const realRemoveFile = (file) => { try { unlinkSync(file); } catch { /* gone already */ } };
+const realPidAlive = (pid) => {
+  try { process.kill(pid, 0); return true; }
+  catch (err) { return err?.code === 'EPERM'; } // EPERM = alive, just not ours
+};
+const realKillPid = (pid, signal) => { try { process.kill(pid, signal); } catch { /* gone */ } };
+// Connectivity probe only — ANY HTTP answer (even 401) means a listener is there.
+const realProbe = (port) => new Promise((done) => {
+  const req = http.get({ host: '127.0.0.1', port, path: '/api/health', timeout: 1000 }, (res) => {
+    res.resume();
+    done(true);
+  });
+  req.on('timeout', () => { req.destroy(); done(false); });
+  req.on('error', () => done(false));
+});
+const realOpenBrowser = (url) => { // fail-soft: a missing opener never breaks the command
+  try {
+    const cmd = process.platform === 'darwin' ? 'open'
+      : process.platform === 'win32' ? 'start' : 'xdg-open';
+    spawn(cmd, [url], { stdio: 'ignore', detached: true, shell: process.platform === 'win32' }).unref();
+  } catch { /* ignore */ }
+};
+const realSleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+const urlOf = (inst) => `http://127.0.0.1:${inst.port}/?token=${inst.token}`;
 
 /**
- * `zuzuu web [dir]`
- * Launch the visual workbench for the given directory (default: cwd).
+ * `zuzuu web [dir] [--stop|--status]`
+ * Launch the visual workbench for the given directory (default: cwd) —
+ * reusing an already-running daemon for that workspace when there is one.
  * Bundled-first; never installs anything — the workbench ships in this package.
  */
-export function web(args = {}, deps = {}) {
+export async function web(args = {}, deps = {}) {
   const d = {
     resolveBundled: realResolveBundled,
     detectPath: realDetectPath,
     launch: realLaunch,
+    instancePathFor: realInstancePathFor,
+    readInstance: realReadInstance,
+    removeFile: realRemoveFile,
+    pidAlive: realPidAlive,
+    killPid: realKillPid,
+    probe: realProbe,
+    openBrowser: realOpenBrowser,
+    sleep: realSleep,
     log: (...m) => console.log(...m),
     ...deps,
   };
 
-  // 1. resolve the target directory
+  // 1. resolve the target directory + its instance state
   const dir = args._?.[0] ? resolve(String(args._[0])) : process.cwd();
+  const instanceFile = d.instancePathFor(dir);
+  const inst = d.readInstance(instanceFile);
+  const isAlive = async (i) =>
+    !!(i && Number.isInteger(i.pid) && d.pidAlive(i.pid) && await d.probe(i.port));
+
+  // --stop: terminate the running daemon for this workspace
+  if (args.stop) {
+    if (!inst) { d.log(`no workbench running for ${dir}`); return; }
+    if (d.pidAlive(inst.pid)) {
+      d.killPid(inst.pid, 'SIGTERM');
+      for (let i = 0; i < 15 && d.pidAlive(inst.pid); i++) await d.sleep(200); // ~3s grace
+      if (d.pidAlive(inst.pid)) d.log(`workbench (pid ${inst.pid}) hasn't exited yet — still shutting down.`);
+      else d.log(`stopped workbench for ${dir} (pid ${inst.pid})`);
+    } else {
+      d.log(`workbench for ${dir} was not running — cleaned up stale state.`);
+    }
+    d.removeFile(instanceFile); // daemon removes it itself on SIGTERM; this is belt-and-braces
+    return;
+  }
 
-  // 2. find the workbench: bundled → PATH → repair hint
+  // --status: report without side effects
+  if (args.status) {
+    if (await isAlive(inst)) {
+      d.log(`workbench running for ${dir}`);
+      d.log(`  pid ${inst.pid} → ${urlOf(inst)}`);
+    } else {
+      d.log(`no workbench running for ${dir}`);
+    }
+    return;
+  }
+
+  // 2. reuse a live instance: same port + token, old tabs stay valid
+  if (await isAlive(inst)) {
+    d.log(`workbench already running for ${dir}`);
+    d.log(`  → ${urlOf(inst)}`);
+    d.openBrowser(urlOf(inst));
+    return;
+  }
+  if (inst) d.removeFile(instanceFile); // stale (dead pid / no listener) → spawn fresh
+
+  // 3. find the workbench: bundled → PATH → repair hint
   const entryScript = d.resolveBundled();
   if (!entryScript && !d.detectPath()) {
     d.log('the workbench is not available in this install.');
@@ -72,8 +168,17 @@ export function web(args = {}, deps = {}) {
     return;
   }
 
-  // 3. launch — the workbench opens the browser and prints its URL
+  // 4. launch — the daemon opens the browser itself on fresh boot, so we only
+  // wait for its instance file to surface the URL here (don't double-open).
   d.log(`zuzuu web → launching visual workbench in ${dir} …`);
-  d.log('  it will open your browser and print its URL.');
   d.launch({ cwd: dir, entryScript });
+  for (let i = 0; i < 30; i++) { // ~6s
+    await d.sleep(200);
+    const fresh = d.readInstance(instanceFile);
+    if (fresh && d.pidAlive(fresh.pid)) {
+      d.log(`  → ${urlOf(fresh)}`);
+      return;
+    }
+  }
+  d.log('  it will open your browser and print its URL.');
 }

package/zuzuu/live/live-store.mjs

@@ -50,6 +50,13 @@ export function touchLive({ id, host, transcriptPath, now }, cwd = process.cwd()
   return write({ ...existing, lastSeen: now, transcriptPath: transcriptPath ?? existing.transcriptPath }, cwd);
 }
 
+/** Merge a patch into an existing live record (no-op when absent). */
+export function updateLive(id, patch, cwd = process.cwd()) {
+  const existing = read(id, cwd);
+  if (!existing) return null;
+  return write({ ...existing, ...patch }, cwd);
+}
+
 /** Remove a live record (its lifecycle has reached a terminal state). */
 export function closeLive(id, cwd = process.cwd()) {
   try {

package/zuzuu/session-git.mjs

@@ -0,0 +1,392 @@
+// zuzuu/session-git.mjs — invisible session-git: one agent session = one branch.
+//
+//   OPEN  → create `zz/session-<shortid>` (a branch, never a worktree)
+//   TURN  → checkpoint commit ON the session branch
+//   END   → squash-merge to main as ONE commit `session: <title>`, delete branch
+//
+// THE most safety-critical module in the codebase: it runs git mutations inside
+// USERS' repos, triggered from fail-open lifecycle hooks. Therefore:
+//   - every exported op is try-wrapped and returns { ok:false, reason } — NEVER throws
+//   - all git goes through spawnSync('git', [args], {cwd}) — no shell strings
+//   - non-repo / bare / detached HEAD / merge-rebase-in-progress / unborn HEAD → no-op
+//   - never push, never touch remotes, never auto-resolve conflicts (conflict →
+//     abort the squash, restore the branch, leave the repo exactly as before)
+//   - single-working-branch invariant: at most ONE `zz/session-*` branch; a
+//     leftover (crashed session) BLOCKS new session branches until continued,
+//     merged, or discarded — the next-session prompt is the recovery path.
+//   - secrets policy: checkpoints NEVER stage secret material (the same family
+//     the seeded no-secret-reads guardrail denies: .env/.env.* at any depth,
+//     *.pem, *.key, id_rsa*) — excluded files stay untracked in the worktree
+//     and are reported as `excludedSecrets`.
+//   - checkpoint history is never destroyed silently: an empty squash that
+//     still has checkpoints KEEPS the branch (explicit discard is the only
+//     way exploration history is dropped).
+
+import { spawnSync } from 'node:child_process';
+import { existsSync, readFileSync, rmSync } from 'node:fs';
+import { join, isAbsolute, resolve } from 'node:path';
+
+const PREFIX = 'zz/session-';
+
+/** One git call — argv array only (no shell), never throws. */
+function git(args, cwd, input) {
+  try {
+    const r = spawnSync('git', args, { cwd, encoding: 'utf8', input });
+    return { ok: r.status === 0 && !r.error, out: (r.stdout ?? '').trim(), err: (r.stderr ?? '').trim() };
+  } catch (e) {
+    return { ok: false, out: '', err: String(e) };
+  }
+}
+
+function gitDir(cwd) {
+  const r = git(['rev-parse', '--git-dir'], cwd);
+  if (!r.ok || !r.out) return null;
+  return isAbsolute(r.out) ? r.out : resolve(cwd, r.out);
+}
+
+/** Current branch name, or null when detached / not a repo. */
+function currentBranch(cwd) {
+  const r = git(['symbolic-ref', '--short', '-q', 'HEAD'], cwd);
+  return r.ok && r.out ? r.out : null;
+}
+
+const branchExists = (cwd, name) => git(['rev-parse', '-q', '--verify', `refs/heads/${name}`], cwd).ok;
+const isDirty = (cwd) => !!git(['status', '--porcelain'], cwd).out;
+
+/** Why git mutations are unsafe right now, or null when clear. */
+function unsafeReason(cwd) {
+  const inside = git(['rev-parse', '--is-inside-work-tree'], cwd);
+  if (!inside.ok || inside.out !== 'true') return 'not-a-git-repo';
+  if (!git(['rev-parse', '-q', '--verify', 'HEAD'], cwd).ok) return 'no-commits';
+  if (!currentBranch(cwd)) return 'detached-head';
+  const gd = gitDir(cwd);
+  if (gd) {
+    // An in-progress merge/rebase/cherry-pick/bisect belongs to the USER — a
+    // checkpoint commit here would conclude their operation. Hands off.
+    for (const f of ['MERGE_HEAD', 'CHERRY_PICK_HEAD', 'REVERT_HEAD', 'BISECT_LOG', 'rebase-merge', 'rebase-apply']) {
+      if (existsSync(join(gd, f))) return 'operation-in-progress';
+    }
+  }
+  return null;
+}
+
+/** Project opt-out: `.zuzuu/agent.json` carrying `"sessionGit": false`. */
+function optedOut(cwd) {
+  try {
+    const root = git(['rev-parse', '--show-toplevel'], cwd);
+    if (!root.ok || !root.out) return false;
+    const f = join(root.out, '.zuzuu', 'agent.json');
+    if (!existsSync(f)) return false;
+    return JSON.parse(readFileSync(f, 'utf8')).sessionGit === false;
+  } catch {
+    return false; // an unreadable manifest never *enables* danger — but opt-out is explicit
+  }
+}
+
+function disabledReason(cwd) {
+  const r = unsafeReason(cwd);
+  if (r) return r;
+  if (optedOut(cwd)) return 'opted-out';
+  return null;
+}
+
+/** True when session-git may act here: a usable git repo, not opted out. */
+export function sessionGitEnabled(cwd) {
+  try {
+    return !disabledReason(cwd);
+  } catch {
+    return false;
+  }
+}
+
+/** `zz/session-` + first 8 of the id, sanitized to [a-z0-9]. */
+export function sessionBranchName(sessionId) {
+  const short = String(sessionId ?? '').toLowerCase().replace(/[^a-z0-9]/g, '').slice(0, 8);
+  return PREFIX + (short || 'unknown');
+}
+
+/** All `zz/session-*` branches (there should be at most one — the invariant). */
+export function listSessionBranches(cwd) {
+  try {
+    const r = git(['for-each-ref', '--format=%(refname:short)', `refs/heads/${PREFIX}*`], cwd);
+    return r.ok && r.out ? r.out.split('\n').filter(Boolean) : [];
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * The branch sessions merge back into. Preference order:
+ *   1. the branch HEAD was on when the session opened (recorded as
+ *      `branch.<session>.zz-base` config at open — survives crashes)
+ *   2. origin/HEAD's branch, if it exists locally
+ *   3. local `main`, then `master`
+ *   4. the current branch, if it isn't itself a session branch
+ */
+export function mainBranch(cwd) {
+  try {
+    for (const b of listSessionBranches(cwd)) {
+      const base = git(['config', `branch.${b}.zz-base`], cwd);
+      if (base.ok && base.out && branchExists(cwd, base.out)) return base.out;
+    }
+    const oh = git(['symbolic-ref', 'refs/remotes/origin/HEAD'], cwd);
+    if (oh.ok && oh.out) {
+      const name = oh.out.replace('refs/remotes/origin/', '');
+      if (branchExists(cwd, name)) return name;
+    }
+    if (branchExists(cwd, 'main')) return 'main';
+    if (branchExists(cwd, 'master')) return 'master';
+    const cur = currentBranch(cwd);
+    return cur && !cur.startsWith(PREFIX) ? cur : null;
+  } catch {
+    return null;
+  }
+}
+
+/** Commits on the session branch beyond main (best-effort; 0 on any trouble). */
+function countCheckpoints(cwd, branch) {
+  const main = mainBranch(cwd);
+  if (!main || main === branch) return 0;
+  const r = git(['rev-list', '--count', `${main}..${branch}`], cwd);
+  const n = r.ok ? Number.parseInt(r.out, 10) : NaN;
+  return Number.isFinite(n) ? n : 0;
+}
+
+/**
+ * OPEN: create the session branch (dirty tree fine — changes ride along).
+ *   already on this session's branch (host restart) → { ok:true, resumed:true }
+ *   another session branch exists (leftover)        → { ok:false, blocked:true, existing }
+ */
+export function openSession(cwd, sessionId) {
+  try {
+    const reason = disabledReason(cwd);
+    if (reason) return { ok: false, reason };
+    const target = sessionBranchName(sessionId);
+    const cur = currentBranch(cwd);
+    if (cur === target) return { ok: true, resumed: true, branch: target };
+    const existing = listSessionBranches(cwd);
+    if (existing.length) return { ok: false, blocked: true, existing: existing[0] };
+    const r = git(['checkout', '-q', '-b', target], cwd);
+    if (!r.ok) return { ok: false, reason: r.err || 'checkout-failed' };
+    git(['config', `branch.${target}.zz-base`, cur], cwd); // remember where to merge back (best-effort)
+    return { ok: true, branch: target };
+  } catch (e) {
+    return { ok: false, reason: String(e) };
+  }
+}
+
+// The secret family checkpoints must never commit — mirrors the seeded
+// no-secret-reads guardrail (scaffold.mjs RULES_SEED: .env / id_rsa / .pem).
+const SECRET_GLOBS = ['.env', '.env.*', '**/.env', '**/.env.*', '**/*.pem', '**/*.key', '**/id_rsa*'];
+const SECRET_RE = /(^|\/)\.env(\.|$)|(^|\/)id_rsa[^/]*$|\.pem$|\.key$/;
+
+/** How many dirty/untracked paths are secret-family (and so were excluded). */
+function countExcludedSecrets(cwd) {
+  const out = git(['status', '--porcelain', '-uall'], cwd).out; // -uall: expand untracked dirs
+  if (!out) return 0;
+  let n = 0;
+  for (const line of out.split('\n')) {
+    const p = line.slice(3);
+    const path = (p.includes(' -> ') ? p.split(' -> ').pop() : p).replace(/^"|"$/g, '');
+    if (SECRET_RE.test(path)) n += 1;
+  }
+  return n;
+}
+
+/** TURN: checkpoint commit — only ON a session branch, only when dirty. NEVER commits on main.
+ *  Secret-family files are excluded from staging (left untracked/unstaged);
+ *  the count of excluded paths is returned as `excludedSecrets` when > 0. */
+export function checkpoint(cwd) {
+  try {
+    const blocked = unsafeReason(cwd);
+    if (blocked) return { ok: false, reason: blocked };
+    const cur = currentBranch(cwd);
+    if (!cur || !cur.startsWith(PREFIX)) return { ok: false, reason: 'not-on-session-branch' };
+    const base = countCheckpoints(cwd, cur);
+    if (!isDirty(cwd)) return { ok: true, committed: false, n: base };
+    const excludedSecrets = countExcludedSecrets(cwd);
+    const add = git(['add', '-A', '--', '.', ...SECRET_GLOBS.map((g) => `:(exclude,glob)${g}`)], cwd);
+    if (!add.ok) return { ok: false, reason: 'add-failed' };
+    if (git(['diff', '--cached', '--quiet'], cwd).ok) {
+      // everything dirty was secret material — never an empty commit
+      return { ok: true, committed: false, n: base, ...(excludedSecrets ? { excludedSecrets } : {}) };
+    }
+    const c = git(['commit', '-q', '-m', `zz: checkpoint ${base + 1}`], cwd);
+    if (!c.ok) return { ok: false, reason: c.err || 'commit-failed' };
+    return { ok: true, committed: true, n: base + 1, ...(excludedSecrets ? { excludedSecrets } : {}) };
+  } catch (e) {
+    return { ok: false, reason: String(e) };
+  }
+}
+
+/** The leftover detector: reflects any zz/session-* branch, checked out or not. */
+export function sessionStatus(cwd) {
+  try {
+    const enabled = sessionGitEnabled(cwd);
+    const main = mainBranch(cwd);
+    const cur = currentBranch(cwd);
+    const onSessionBranch = !!cur && cur.startsWith(PREFIX);
+    const branches = listSessionBranches(cwd);
+    let active = null;
+    if (branches.length) {
+      const branch = branches[0];
+      const checkpoints = countCheckpoints(cwd, branch);
+      active = {
+        branch,
+        checkpoints,
+        dirty: cur === branch && isDirty(cwd),
+        // exploration-only session: checkpoints exist but the tree equals main
+        // (the empty-squash-with-checkpoints case doctor/status render specially)
+        noNetChanges: checkpoints > 0 && !!main && main !== branch && git(['diff', '--quiet', main, branch], cwd).ok,
+      };
+    }
+    return { enabled, mainBranch: main, active, onSessionBranch };
+  } catch {
+    return { enabled: false, mainBranch: null, active: null, onSessionBranch: false };
+  }
+}
+
+const defaultTitle = (branch) => `${branch} · ${new Date().toISOString().slice(0, 10)}`;
+
+/** Best-effort: drop squash leftovers so they can't leak into the user's next commit. */
+function cleanupSquashState(cwd) {
+  const gd = gitDir(cwd);
+  if (!gd) return;
+  for (const f of ['SQUASH_MSG', 'MERGE_MSG']) {
+    try {
+      rmSync(join(gd, f), { force: true });
+    } catch {
+      /* best-effort */
+    }
+  }
+}
+
+/**
+ * END: squash-merge the session branch into main as ONE commit
+ * `session: <title>`, then delete the branch. Every ok:true return carries
+ * `mergedTo` (the branch actually merged into); when the recorded zz-base
+ * branch no longer exists, `warning:'base-branch-missing'` flags the fallback.
+ *   conflict        → abort (reset --merge), restore the prior checkout,
+ *                     { ok:false, conflict:true, branch, restoredTo } —
+ *                     restoredTo:null means the checkout back failed (stranded on main)
+ *   empty squash    → 0 checkpoints: no commit, still cleans up ({ mergedAs:null });
+ *                     WITH checkpoints: the branch is KEPT (history is never
+ *                     destroyed silently) → { ok:false,
+ *                     reason:'empty-squash-with-checkpoints', commits, branch }
+ */
+export function closeSession(cwd, { title } = {}) {
+  try {
+    const blocked = unsafeReason(cwd);
+    if (blocked) return { ok: false, reason: blocked };
+    const branches = listSessionBranches(cwd);
+    if (!branches.length) return { ok: false, reason: 'no-session-branch' };
+    const branch = branches[0];
+    const cur = currentBranch(cwd);
+    const baseCfg = git(['config', `branch.${branch}.zz-base`], cwd).out;
+    const main = mainBranch(cwd);
+    if (!main || main === branch) return { ok: false, reason: 'no-main-branch' };
+    // honesty: the branch we recorded at open is gone → we merge to a fallback
+    const baseMissing = !!baseCfg && !branchExists(cwd, baseCfg);
+
+    let excludedSecrets = 0;
+    if (cur === branch) {
+      const cp = checkpoint(cwd); // fold any uncommitted work into the squash
+      if (!cp.ok) return { ok: false, reason: cp.reason };
+      excludedSecrets = cp.excludedSecrets ?? 0;
+    } else if (isDirty(cwd)) {
+      // Loose changes on another branch are the USER's — never mix them into the squash.
+      return { ok: false, reason: 'dirty-worktree' };
+    }
+
+    const commits = countCheckpoints(cwd, branch);
+    /** Undo a failed merge and put the user back where they were. Returns the
+     *  branch we actually landed on — null = the checkout back failed and the
+     *  user is STRANDED ON MAIN (report it, never pretend otherwise). */
+    const restore = () => {
+      git(['reset', '--merge'], cwd);
+      cleanupSquashState(cwd);
+      if (!cur || cur === main) return cur ?? null;
+      return git(['checkout', '-q', cur], cwd).ok ? cur : null;
+    };
+
+    const co = git(['checkout', '-q', main], cwd);
+    if (!co.ok) return { ok: false, reason: co.err || 'checkout-main-failed' };
+    const merge = git(['merge', '--squash', branch], cwd);
+    if (!merge.ok) {
+      // conflict (or any squash failure): leave the repo exactly as before
+      return { ok: false, conflict: true, branch, restoredTo: restore() };
+    }
+
+    const extras = {
+      ...(excludedSecrets ? { excludedSecrets } : {}),
+      ...(baseMissing ? { warning: 'base-branch-missing' } : {}),
+    };
+
+    let mergedAs = null;
+    const nothingStaged = git(['diff', '--cached', '--quiet'], cwd).ok; // exit 1 = staged changes
+    if (nothingStaged) {
+      cleanupSquashState(cwd); // a stale SQUASH_MSG would hijack the user's next commit
+      if (commits > 0) {
+        // Exploration-only session: the squash is empty but real checkpoints
+        // exist. NEVER delete that history silently — keep the branch, put the
+        // user back, and report; `zuzuu session discard --yes` is the drop path.
+        if (cur && cur !== main) git(['checkout', '-q', cur], cwd);
+        return { ok: false, reason: 'empty-squash-with-checkpoints', commits, branch, ...extras };
+      }
+    } else {
+      const c = git(['commit', '-q', '-m', `session: ${title || defaultTitle(branch)}`], cwd);
+      if (!c.ok) {
+        return { ok: false, reason: c.err || 'commit-failed', restoredTo: restore() };
+      }
+      mergedAs = git(['rev-parse', 'HEAD'], cwd).out || null;
+    }
+
+    git(['config', '--unset', `branch.${branch}.zz-base`], cwd); // best-effort
+    const del = git(['branch', '-D', branch], cwd);
+    if (!del.ok) {
+      const warning = extras.warning ? `${extras.warning},branch-delete-failed` : 'branch-delete-failed';
+      return { ok: true, mergedAs, mergedTo: main, commits, ...extras, warning };
+    }
+    return { ok: true, mergedAs, mergedTo: main, commits, ...extras };
+  } catch (e) {
+    return { ok: false, reason: String(e) };
+  }
+}
+
+/** Recovery: check the leftover session branch back out and keep working. */
+export function continueSession(cwd) {
+  try {
+    const blocked = unsafeReason(cwd);
+    if (blocked) return { ok: false, reason: blocked };
+    const branches = listSessionBranches(cwd);
+    if (!branches.length) return { ok: false, reason: 'no-session-branch' };
+    const branch = branches[0];
+    if (currentBranch(cwd) === branch) return { ok: true, branch };
+    const r = git(['checkout', '-q', branch], cwd);
+    return r.ok ? { ok: true, branch } : { ok: false, reason: r.err || 'checkout-failed' };
+  } catch (e) {
+    return { ok: false, reason: String(e) };
+  }
+}
+
+/** Recovery: drop the session branch and its checkpoints. The CALLER gates confirmation. */
+export function discardSession(cwd) {
+  try {
+    const blocked = unsafeReason(cwd);
+    if (blocked) return { ok: false, reason: blocked };
+    const branches = listSessionBranches(cwd);
+    if (!branches.length) return { ok: false, reason: 'no-session-branch' };
+    const branch = branches[0];
+    const main = mainBranch(cwd);
+    if (!main || main === branch) return { ok: false, reason: 'no-main-branch' };
+    if (currentBranch(cwd) === branch) {
+      const co = git(['checkout', '-q', main], cwd);
+      if (!co.ok) return { ok: false, reason: co.err || 'checkout-main-failed' };
+    }
+    git(['config', '--unset', `branch.${branch}.zz-base`], cwd); // best-effort
+    const del = git(['branch', '-D', branch], cwd);
+    return del.ok ? { ok: true, branch } : { ok: false, reason: del.err || 'branch-delete-failed' };
+  } catch (e) {
+    return { ok: false, reason: String(e) };
+  }
+}