wisp-agents 0.6.0 → 0.8.0

package/server/checkpoint.js

@@ -0,0 +1,348 @@
+// Per-turn git checkpoints, single-file revert, turn rollback, and action command execution.
+
+import { execFileSync, spawn as nodeSpawn } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { killTree } from './proc.js';
+import { MAX_SNAPSHOT, rel } from './adapters/common.js';
+
+const MAX_EXEC_OUTPUT = 32 * 1024;
+const EXEC_TIMEOUT_MS = 60_000;
+
+function git(cwd, args, opts = {}) {
+  return execFileSync('git', args, {
+    cwd,
+    stdio: ['ignore', 'pipe', 'ignore'],
+    timeout: 5000,
+    ...opts,
+  });
+}
+
+function tryGit(cwd, args, opts) {
+  try {
+    return git(cwd, args, opts).toString('utf8').trim();
+  } catch {
+    return null;
+  }
+}
+
+// Snapshot the working tree before a turn starts. `git stash create` writes a commit object
+// holding tracked working-tree and index changes without touching HEAD, the index, or the stash
+// reflog; if the tree is clean it prints nothing and HEAD is the snapshot. Pinning the SHA under
+// refs/wisp/checkpoints/<session>/<turn> keeps `git gc` from collecting it.
+export function captureCheckpoint(cwd, sessionId, turnId) {
+  if (!cwd || !fs.existsSync(cwd)) return null;
+  const head = tryGit(cwd, ['rev-parse', '--verify', 'HEAD']);
+  if (!head) return null;
+  const stash = tryGit(cwd, ['stash', 'create']);
+  const commit = stash || head;
+  if (sessionId && turnId) {
+    tryGit(cwd, ['update-ref', `refs/wisp/checkpoints/${sessionId}/${turnId}`, commit]);
+  }
+  const branch = tryGit(cwd, ['symbolic-ref', '--quiet', '--short', 'HEAD']) || '';
+  const untrackedRaw = tryGit(cwd, ['ls-files', '--others', '--exclude-standard'], { maxBuffer: 2 * 1024 * 1024 });
+  const untracked = untrackedRaw ? untrackedRaw.split('\n').filter(Boolean).slice(0, 500) : [];
+  return {
+    commit,
+    head,
+    dirty: !!stash,
+    branch,
+    untracked,
+    at: Date.now(),
+  };
+}
+
+// The first turn in a worktree made for it: clean, at its base commit, so the checkpoint is known
+// without asking git (captureCheckpoint's synchronous calls held up every launch, once per run).
+// The base commit stays reachable from the base branch, so it needs no pinning ref.
+export function freshCheckpoint(wt) {
+  return { commit: wt.head, head: wt.head, dirty: false, branch: wt.branch, untracked: [], at: Date.now() };
+}
+
+export function cleanupCheckpoints(cwd, sessionId) {
+  if (!cwd || !sessionId || !fs.existsSync(cwd)) return;
+  const refs = tryGit(cwd, ['for-each-ref', '--format=%(refname)', `refs/wisp/checkpoints/${sessionId}/`]);
+  if (!refs) return;
+  for (const ref of refs.split('\n').filter(Boolean)) {
+    tryGit(cwd, ['update-ref', '-d', ref]);
+  }
+}
+
+export function readGitFile(cwd, commit, file) {
+  if (!cwd || !commit || !file || path.isAbsolute(file)) return null;
+  const gitPath = `./${file.split(path.sep).join('/')}`;
+  try {
+    const out = git(cwd, ['show', `${commit}:${gitPath}`], { maxBuffer: 8 * MAX_SNAPSHOT });
+    return out.length <= MAX_SNAPSHOT ? out.toString('utf8') : '';
+  } catch {
+    return null;
+  }
+}
+
+function readDiskSnapshot(abs) {
+  try {
+    const st = fs.statSync(abs);
+    if (!st.isFile()) return null;
+    return st.size <= MAX_SNAPSHOT ? fs.readFileSync(abs, 'utf8') : null;
+  } catch {
+    return null;
+  }
+}
+
+function writeDiskSnapshot(abs, content) {
+  if (content === null || content === undefined) {
+    fs.rmSync(abs, { force: true });
+    return;
+  }
+  fs.mkdirSync(path.dirname(abs), { recursive: true });
+  fs.writeFileSync(abs, content, 'utf8');
+}
+
+function resolveInsideCwd(cwd, file) {
+  if (!file || typeof file !== 'string') {
+    throw Object.assign(new Error('file path required'), { status: 400 });
+  }
+  const abs = path.resolve(cwd, file);
+  const relPath = path.relative(cwd, abs);
+  if (!relPath || relPath.startsWith('..') || path.isAbsolute(relPath)) {
+    throw Object.assign(new Error(`File lies outside the project folder: ${file}`), { status: 400 });
+  }
+  return { abs, relPath: rel(file, cwd) || relPath };
+}
+
+function findChangeEntry(turn, file, cwd) {
+  if (!turn?.changes?.length) return null;
+  const r = rel(file, cwd);
+  return (
+    turn.changes.find((c) => c.file === file || c.file === r) ||
+    turn.changes.find((c) => c.file.endsWith('/' + file) || file.endsWith('/' + c.file))
+  );
+}
+
+const sessionDir = (session) => session.worktree?.cwd || session.cwd;
+
+// Revert (or re-apply when restore=true) a single file's changes from `turn`.
+export function revertFileChange(session, turn, file, { restore = false } = {}) {
+  const cwd = sessionDir(session);
+  const { abs, relPath } = resolveInsideCwd(cwd, file);
+  const entry = findChangeEntry(turn, file, cwd);
+  const commit = turn.checkpoint?.commit;
+  if (!entry && !commit) {
+    throw Object.assign(new Error(`No captured changes or checkpoint for ${relPath}`), { status: 404 });
+  }
+
+  if (restore) {
+    if (entry?.afterSnapshot !== undefined) {
+      writeDiskSnapshot(abs, entry.afterSnapshot);
+    } else if (entry?.edits?.length) {
+      if (entry.op === 'create' || entry.op === 'write') {
+        writeDiskSnapshot(abs, entry.edits.at(-1).after ?? '');
+      } else {
+        let cur = readDiskSnapshot(abs) ?? '';
+        for (const e of entry.edits) {
+          if (e.before && cur.includes(e.before)) cur = cur.replace(e.before, e.after ?? '');
+        }
+        writeDiskSnapshot(abs, cur);
+      }
+    } else {
+      throw Object.assign(new Error(`Nothing to re-apply for ${relPath}`), { status: 400 });
+    }
+    if (entry) entry.reverted = false;
+    if (turn.changes?.every((c) => !c.reverted)) delete turn.rolledBackAt;
+    return { file: entry?.file || relPath, reverted: false };
+  }
+
+  // Save what is currently on disk so the user can Undo / Re-apply in one click.
+  const currentOnDisk = readDiskSnapshot(abs);
+  if (entry) entry.afterSnapshot = currentOnDisk;
+
+  // 1. Prefer the exact pre-turn file content recorded when the turn first touched the file.
+  if (entry && entry.beforeFile !== undefined) {
+    writeDiskSnapshot(abs, entry.op === 'create' ? null : entry.beforeFile);
+  } else if (commit) {
+    // 2. Otherwise check the turn's git checkpoint commit.
+    const fromGit = readGitFile(cwd, commit, entry?.file || relPath);
+    if (fromGit !== null) {
+      writeDiskSnapshot(abs, fromGit);
+    } else if (entry?.op === 'create' || !(turn.checkpoint?.untracked || []).includes(entry?.file || relPath)) {
+      writeDiskSnapshot(abs, null);
+    } else if (entry?.edits?.length) {
+      reverseEditsOnDisk(abs, entry);
+    }
+  } else if (entry) {
+    // 3. Fallback for non-git folders or legacy turns.
+    if (entry.op === 'create') {
+      writeDiskSnapshot(abs, null);
+    } else if (entry.op === 'write' && entry.edits?.[0]?.before !== undefined) {
+      writeDiskSnapshot(abs, entry.edits[0].before);
+    } else {
+      reverseEditsOnDisk(abs, entry);
+    }
+  }
+
+  if (entry) entry.reverted = true;
+  return { file: entry?.file || relPath, reverted: true };
+}
+
+function reverseEditsOnDisk(abs, entry) {
+  const cur = readDiskSnapshot(abs);
+  if (cur === null) return;
+  let next = cur;
+  for (const e of [...(entry.edits || [])].reverse()) {
+    if (e.after && next.includes(e.after)) {
+      next = next.replace(e.after, e.before ?? '');
+    }
+  }
+  writeDiskSnapshot(abs, next);
+}
+
+// Restore the project working tree to the state before `turn` ran (or undo that rollback when restore=true).
+export function rollbackToTurn(session, turn, { restore = false } = {}) {
+  const cwd = sessionDir(session);
+  const idx = session.turns.indexOf(turn);
+  if (idx < 0) throw Object.assign(new Error('No such turn'), { status: 404 });
+  const affected = session.turns.slice(idx);
+  const touchedFiles = [...new Set(affected.flatMap((t) => (t.changes || []).map((c) => c.file)))];
+
+  if (restore) {
+    const pre = turn.preRollback;
+    if (!pre) {
+      for (const t of affected) {
+        for (const c of t.changes || []) {
+          revertFileChange(session, t, c.file, { restore: true });
+        }
+        delete t.rolledBackAt;
+      }
+      return { files: touchedFiles, rolledBack: false };
+    }
+    if (pre.commit) {
+      tryGit(cwd, ['checkout', pre.commit, '--', '.']);
+      tryGit(cwd, ['read-tree', 'HEAD']);
+    }
+    for (const [relFile, content] of Object.entries(pre.files || {})) {
+      const { abs } = resolveInsideCwd(cwd, relFile);
+      writeDiskSnapshot(abs, content);
+    }
+    for (const t of affected) {
+      delete t.rolledBackAt;
+      for (const c of t.changes || []) c.reverted = false;
+    }
+    return { files: Object.keys(pre.files || {}).length ? Object.keys(pre.files) : touchedFiles, rolledBack: false };
+  }
+
+  const cp = turn.checkpoint;
+  const preUntracked = new Set(cp?.untracked || []);
+  const curUntrackedRaw = cp?.commit ? tryGit(cwd, ['ls-files', '--others', '--exclude-standard'], { maxBuffer: 2 * 1024 * 1024 }) : null;
+  const curUntracked = curUntrackedRaw ? curUntrackedRaw.split('\n').filter(Boolean).slice(0, 500) : [];
+  const newUntracked = curUntracked.filter((f) => !preUntracked.has(f));
+
+  // Snapshot current state of all affected files + new untracked files + git tree before rolling back so Undo works.
+  const preFiles = {};
+  for (const f of [...new Set([...touchedFiles, ...newUntracked])]) {
+    try {
+      const { abs } = resolveInsideCwd(cwd, f);
+      preFiles[f] = readDiskSnapshot(abs);
+    } catch {}
+  }
+  const preCp = captureCheckpoint(cwd, session.id, `${turn.id}-undo`);
+  turn.preRollback = { commit: preCp?.commit || null, files: preFiles };
+
+  if (cp?.commit) {
+    // Find any tracked files added since the checkpoint commit so we can remove them too.
+    const addedRaw = tryGit(cwd, ['diff', '--name-only', '--diff-filter=D', 'HEAD', cp.commit]) || '';
+    const addedTracked = addedRaw.split('\n').filter(Boolean);
+
+    // Restore tracked files from the checkpoint commit.
+    tryGit(cwd, ['checkout', cp.commit, '--', '.']);
+    // Keep the git index aligned with HEAD rather than the stash commit's tree.
+    tryGit(cwd, ['read-tree', 'HEAD']);
+
+    for (const f of [...addedTracked, ...newUntracked]) {
+      try {
+        const { abs } = resolveInsideCwd(cwd, f);
+        fs.rmSync(abs, { force: true });
+      } catch {}
+    }
+
+    // Restore or remove untracked files touched in the affected turns.
+    for (const t of affected.slice().reverse()) {
+      for (const c of t.changes || []) {
+        try {
+          const { abs, relPath } = resolveInsideCwd(cwd, c.file);
+          const inGit = readGitFile(cwd, cp.commit, relPath) !== null;
+          if (!inGit) {
+            if (c.op === 'create' || (!preUntracked.has(relPath) && c.beforeFile === null)) {
+              fs.rmSync(abs, { force: true });
+            } else if (typeof c.beforeFile === 'string') {
+              writeDiskSnapshot(abs, c.beforeFile);
+            }
+          }
+        } catch {}
+      }
+    }
+  } else {
+    // Non-git folder or turn without a git checkpoint: revert each turn's captured file changes in reverse.
+    for (const t of affected.slice().reverse()) {
+      for (const c of [...(t.changes || [])].reverse()) {
+        revertFileChange(session, t, c.file, { restore: false });
+      }
+    }
+  }
+
+  const now = Date.now();
+  for (const t of affected) {
+    t.rolledBackAt = now;
+    for (const c of t.changes || []) c.reverted = true;
+  }
+  return { files: touchedFiles, rolledBack: true, commit: cp?.head || cp?.commit || null };
+}
+
+// Run a shell command from an actionable presentation block inside `cwd`.
+export function execCommand(cwd, command, { timeoutMs = EXEC_TIMEOUT_MS } = {}) {
+  const cmd = String(command || '').trim();
+  if (!cmd) return Promise.reject(Object.assign(new Error('command required'), { status: 400 }));
+  const t0 = Date.now();
+
+  return new Promise((resolve) => {
+    const child = nodeSpawn(cmd, {
+      cwd,
+      env: { ...process.env, PAGER: 'cat', GIT_TERMINAL_PROMPT: '0', CI: '1' },
+      shell: true,
+      windowsHide: true,
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    let out = '';
+    const append = (chunk) => {
+      if (out.length < MAX_EXEC_OUTPUT) out += chunk.toString('utf8').slice(0, MAX_EXEC_OUTPUT - out.length);
+    };
+    child.stdout.on('data', append);
+    child.stderr.on('data', append);
+
+    let timedOut = false;
+    const timer = setTimeout(() => {
+      timedOut = true;
+      killTree(child);
+    }, timeoutMs);
+
+    child.on('error', (err) => {
+      clearTimeout(timer);
+      resolve({
+        command: cmd,
+        output: (out ? `${out}\n` : '') + err.message,
+        exitCode: 1,
+        durationMs: Date.now() - t0,
+      });
+    });
+
+    child.on('close', (code) => {
+      clearTimeout(timer);
+      const suffix = timedOut ? `\n[timed out after ${Math.round(timeoutMs / 1000)}s]` : '';
+      resolve({
+        command: cmd,
+        output: (out.replace(/\s+$/, '') + suffix).trim(),
+        exitCode: timedOut ? 124 : (code ?? 1),
+        durationMs: Date.now() - t0,
+      });
+    });
+  });
+}

package/server/client.js

@@ -115,20 +115,44 @@ export class WispClient {
   remove = (id) => this.request('DELETE', `/sessions/${id}`);
   stop = (id) => this.request('POST', `/sessions/${id}/stop`, {});
   answer = (id, text) => this.request('POST', `/sessions/${id}/answer`, { text });
+  revert = (id, fileOrOpts, opts = {}) => {
+    const body = typeof fileOrOpts === 'string' ? { file: fileOrOpts, ...opts } : fileOrOpts || {};
+    return this.request('POST', `/sessions/${id}/revert`, body);
+  };
+  rollback = (id, { turnId, restore = false } = {}) => this.request('POST', `/sessions/${id}/rollback`, { turnId, restore });
+  exec = (id, cmdOrOpts, opts = {}) => {
+    const body = typeof cmdOrOpts === 'string' ? { command: cmdOrOpts, ...opts } : cmdOrOpts || {};
+    return this.request('POST', `/sessions/${id}/exec`, body);
+  };
   takeover = (id, { open = false } = {}) => this.request(open ? 'POST' : 'GET', `/sessions/${id}/takeover`, open ? {} : undefined);
 
   // { prompt, cwd, agent, mode, model, effort, attachments: [uploadId] }. Missing agent/mode/model
   // fall back to the launcher's remembered defaults, like `wisp "…"` does; effort only if given.
-  async launch({ prompt, cwd = process.cwd(), agent, mode, model, effort, attachments } = {}) {
+  // worktree: true/false overrides the default (on in git repos). compare: [{ agent, model, effort }]
+  // runs the same task on more harnesses at once, each in its own worktree. subagents:
+  // [{ name, agent, model, effort, use }] (or preset: a saved team's id) the lead can delegate to.
+  async launch({ prompt, cwd = process.cwd(), agent, mode, model, effort, attachments, worktree, compare, subagents, preset } = {}) {
     if (!agent || !mode || model === undefined) {
       const { defaults = {} } = await this.config();
       agent ||= defaults.agent || 'claude';
       mode ||= defaults.mode || 'edits';
       model ??= defaults.models?.[agent] ?? (agent === defaults.agent ? defaults.model || '' : '');
     }
-    return this.request('POST', '/sessions', { prompt, cwd: path.resolve(cwd), agent, mode, model, effort, attachments });
+    return this.request('POST', '/sessions', { prompt, cwd: path.resolve(cwd), agent, mode, model, effort, attachments, worktree, compare, subagents, preset });
   }
 
+  // Ship it: commit the session's worktree, push its branch, open (or update) the PR.
+  ship = (id, { title, body, draft } = {}) => this.request('POST', `/sessions/${id}/ship`, { title, body, draft });
+  merge = (id) => this.request('POST', `/sessions/${id}/merge`, {});
+
+  // Recipes: saved prompts with {params}. key is the id or the name.
+  recipes = () => this.request('GET', '/recipes');
+  saveRecipe = (recipe) => this.request(recipe.id ? 'PATCH' : 'POST', `/recipes${recipe.id ? `/${recipe.id}` : ''}`, recipe);
+  runRecipe = (key, { params, words, cwd = process.cwd(), agent, model, effort, mode } = {}) =>
+    this.request('POST', `/recipes/${encodeURIComponent(key)}/run`, { params, words, cwd: path.resolve(cwd), agent, model, effort, mode });
+  triggers = () => this.request('GET', '/triggers');
+  usage = ({ days } = {}) => this.request('GET', `/usage${days ? `?days=${days}` : ''}`);
+
   // A follow-up. If the agent is blocked on ask_user, this answers it. queue: wait for the
   // current run instead of interrupting it (default: the user's setting).
   reply = (id, text, { attachments, queue } = {}) => this.request('POST', `/sessions/${id}/reply`, { text, attachments, queue });

package/server/git.js

@@ -0,0 +1,199 @@
+// Git and GitHub plumbing for worktree sessions and Ship it. Everything shells out to `git` and
+// `gh`. The user's own checkout is only read, except for the fast-forward after a merge.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { execFile } from './proc.js';
+
+const GIT = () => process.env.WISP_GIT_BIN || 'git';
+const GH = () => process.env.WISP_GH_BIN || 'gh';
+// Never wait on a credential or confirmation prompt nobody can see.
+const QUIET_ENV = { GIT_TERMINAL_PROMPT: '0', GH_PROMPT_DISABLED: '1', GH_NO_UPDATE_NOTIFIER: '1', GIT_EDITOR: 'true' };
+
+export function run(bin, args, { cwd, timeout = 60_000 } = {}) {
+  return new Promise((resolve, reject) => {
+    execFile(bin, args, { cwd, timeout, maxBuffer: 16 * 1024 * 1024, env: { ...process.env, ...QUIET_ENV } }, (err, stdout, stderr) => {
+      if (!err) return resolve(String(stdout).trim());
+      // git and gh lead with "fatal:" / "error:"; otherwise the tail is the useful part.
+      const lines = String(stderr || '').trim().split('\n').filter(Boolean);
+      const why = lines.find((l) => /^(fatal|error)\b/i.test(l)) || lines.slice(-3).join(' ') || err.message;
+      reject(Object.assign(new Error(why), { code: err.code }));
+    });
+  });
+}
+export const git = (cwd, args, opts) => run(GIT(), args, { cwd, ...opts });
+export const gh = (cwd, args, opts) => run(GH(), args, { cwd, timeout: 120_000, ...opts });
+const quiet = (p) => p.catch(() => '');
+
+export async function repoRoot(cwd) {
+  const top = await quiet(git(cwd, ['rev-parse', '--show-toplevel']));
+  return top ? path.resolve(top) : null;
+}
+
+// What a worktree session branches from: the remote's default branch, freshly fetched, else HEAD.
+export async function baseRef(root) {
+  const remotes = (await quiet(git(root, ['remote']))).split('\n');
+  if (remotes.includes('origin')) {
+    await quiet(git(root, ['fetch', '--quiet', 'origin'], { timeout: 20_000 })); // offline: use what we have
+    const head = await quiet(git(root, ['symbolic-ref', '--quiet', '--short', 'refs/remotes/origin/HEAD']));
+    for (const ref of [head, 'origin/main', 'origin/master']) {
+      if (ref && (await quiet(git(root, ['rev-parse', '--verify', '--quiet', `${ref}^{commit}`])))) return { ref, branch: ref.replace(/^origin\//, ''), remote: 'origin' };
+    }
+  }
+  const sha = await quiet(git(root, ['rev-parse', '--verify', '--quiet', 'HEAD']));
+  if (!sha) return null; // a repo without commits has nothing to branch from
+  return { ref: sha, branch: await quiet(git(root, ['symbolic-ref', '--quiet', '--short', 'HEAD'])), remote: null };
+}
+
+export const slug = (s) =>
+  String(s || '')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 32)
+    .replace(/-+$/, '');
+
+const realpath = (p) => {
+  try {
+    return fs.realpathSync.native(p);
+  } catch {
+    return path.resolve(p);
+  }
+};
+
+// A fresh worktree + branch for one session, under <home>/worktrees. Returns null outside a repo.
+// Where a launch's worktrees come from: { root, base }, or null outside a repo with commits.
+// Resolved once per launch, so compare runs share one fetch.
+export async function worktreeSource(cwd) {
+  const root = await repoRoot(cwd);
+  const base = root && (await baseRef(root));
+  if (!base) return null;
+  base.sha = await quiet(git(root, ['rev-parse', '--verify', '--quiet', `${base.ref}^{commit}`]));
+  return { root, base };
+}
+
+export async function createWorktree({ cwd, home, id, title, source }) {
+  const { root, base } = source || (await worktreeSource(cwd)) || {};
+  if (!base) return null;
+  // Short and readable; the full id only if that name is taken (a leftover branch, a prefix clash).
+  let branch = `wisp/${slug(title) || 'task'}-${id.slice(0, 6)}`;
+  if (await quiet(git(root, ['rev-parse', '--verify', '--quiet', `refs/heads/${branch}`]))) branch = `wisp/${slug(title) || 'task'}-${id}`;
+  const dir = path.join(home, 'worktrees', `${path.basename(root)}-${id}`);
+  fs.mkdirSync(path.dirname(dir), { recursive: true });
+  await git(root, ['worktree', 'add', '--quiet', '--no-track', '-b', branch, dir, base.ref]);
+  // Launched from a subfolder of the repo: keep working in that subfolder.
+  const sub = path.relative(realpath(root), realpath(cwd));
+  return { path: dir, cwd: sub && !sub.startsWith('..') ? path.join(dir, sub) : dir, branch, base: base.branch, baseRef: base.ref, head: base.sha || null, remote: base.remote, root, createdAt: Date.now() };
+}
+
+// Archiving removes a clean worktree; a follow-up brings it back from its branch.
+export async function ensureWorktree(wt) {
+  if (!wt || fs.existsSync(wt.path)) return;
+  await quiet(git(wt.root, ['worktree', 'prune']));
+  await git(wt.root, ['worktree', 'add', '--quiet', wt.path, wt.branch]);
+}
+
+// { dirty: changed paths, ahead: commits past the base, exists }
+export async function worktreeStatus(wt) {
+  if (!wt || !fs.existsSync(wt.path)) return { exists: false, dirty: 0, ahead: 0 };
+  const porcelain = await quiet(git(wt.path, ['status', '--porcelain']));
+  const ahead = Number(await quiet(git(wt.path, ['rev-list', '--count', `${wt.baseRef}..HEAD`]))) || 0;
+  return { exists: true, dirty: porcelain ? porcelain.split('\n').length : 0, ahead };
+}
+
+// force: drop uncommitted work too. The branch goes only when nothing would be lost with it.
+export async function removeWorktree(wt, { force = false, branch = false } = {}) {
+  if (!wt) return { removed: false };
+  if (fs.existsSync(wt.path)) {
+    const st = await worktreeStatus(wt);
+    if (st.dirty && !force) return { removed: false, dirty: st.dirty };
+    await quiet(git(wt.root, ['worktree', 'remove', '--force', wt.path]));
+    fs.rmSync(wt.path, { recursive: true, force: true });
+    await quiet(git(wt.root, ['worktree', 'prune']));
+  }
+  let branchDeleted = false;
+  if (branch) {
+    const unique = Number(await quiet(git(wt.root, ['rev-list', '--count', `${wt.baseRef}..${wt.branch}`]))) || 0;
+    if (!unique || branch === 'force') branchDeleted = !!(await quiet(git(wt.root, ['branch', '-D', wt.branch]).then(() => 'ok')));
+  }
+  return { removed: true, branchDeleted };
+}
+
+// --- Ship it: commit, push, open a PR, follow it, merge it -----------------------------------
+
+const PR_FIELDS = 'number,url,title,state,isDraft,reviewDecision,mergeStateStatus,statusCheckRollup,headRefOid,baseRefName,mergedAt';
+const PASS = new Set(['SUCCESS', 'NEUTRAL', 'SKIPPED']);
+const FAIL = new Set(['FAILURE', 'ERROR', 'TIMED_OUT', 'CANCELLED', 'ACTION_REQUIRED', 'STARTUP_FAILURE', 'STALE']);
+
+export function prSummary(j) {
+  const checks = { pass: 0, fail: 0, pending: 0 };
+  for (const c of j.statusCheckRollup || []) {
+    const v = String(c.conclusion || c.state || '').toUpperCase();
+    if (PASS.has(v)) checks.pass++;
+    else if (FAIL.has(v)) checks.fail++;
+    else checks.pending++;
+  }
+  return {
+    number: j.number,
+    url: j.url,
+    title: j.title,
+    state: j.state, // OPEN | CLOSED | MERGED
+    draft: !!j.isDraft,
+    review: j.reviewDecision || '', // APPROVED | CHANGES_REQUESTED | REVIEW_REQUIRED | ''
+    mergeState: j.mergeStateStatus || '',
+    head: j.headRefOid,
+    base: j.baseRefName,
+    mergedAt: j.mergedAt || null,
+    checks,
+    checkedAt: Date.now(),
+  };
+}
+
+export async function prView(cwd, ref) {
+  return prSummary(JSON.parse(await gh(cwd, ['pr', 'view', String(ref), '--json', PR_FIELDS])));
+}
+
+// Commit whatever the session left uncommitted, push its branch and open (or update) its PR.
+export async function ship(wt, { title, body = '', draft = false, pr }) {
+  await ensureWorktree(wt);
+  const dir = wt.path;
+  if (await quiet(git(dir, ['status', '--porcelain']))) {
+    if (!String(title || '').trim()) throw Object.assign(new Error('A commit message is required.'), { status: 400 });
+    await git(dir, ['add', '-A']);
+    await git(dir, ['commit', '--quiet', '--no-verify', '-m', title.trim(), ...(body.trim() ? ['-m', body.trim()] : [])]);
+  }
+  const { ahead } = await worktreeStatus(wt);
+  if (!ahead) throw Object.assign(new Error('Nothing to ship: this branch has no changes.'), { status: 400 });
+  if (!wt.remote) throw Object.assign(new Error('This repo has no origin remote to push to.'), { status: 400 });
+  await git(dir, ['push', '--quiet', '-u', wt.remote, `HEAD:refs/heads/${wt.branch}`], { timeout: 120_000 });
+  if (pr?.state === 'OPEN') return prView(dir, pr.number);
+  const url = (await gh(dir, ['pr', 'create', '--base', wt.base, '--head', wt.branch, '--title', title.trim(), '--body', body.trim() || ' ', ...(draft ? ['--draft'] : [])])).split('\n').pop();
+  return prView(dir, url);
+}
+
+// Squash-merge the exact head that was reviewed, then tidy up and catch the user's checkout up.
+export async function merge(wt, number) {
+  const dir = fs.existsSync(wt.path) ? wt.path : wt.root;
+  let pr = await prView(dir, number);
+  if (pr.state !== 'OPEN') throw Object.assign(new Error(`PR #${number} is ${pr.state.toLowerCase()}.`), { status: 400 });
+  if (pr.draft) await gh(dir, ['pr', 'ready', String(number)]);
+  await gh(dir, ['pr', 'merge', String(number), '--squash', '--match-head-commit', pr.head]);
+  pr = await prView(dir, number);
+  const sync = await syncBase(wt.root, wt.base);
+  await removeWorktree(wt, { force: true, branch: 'force' });
+  await quiet(git(wt.root, ['push', '--quiet', wt.remote || 'origin', '--delete', wt.branch]));
+  return { pr, sync };
+}
+
+// Fast-forward the user's base branch to the remote, never anything more invasive.
+export async function syncBase(root, base) {
+  try {
+    await git(root, ['fetch', '--quiet', 'origin']);
+    const current = await quiet(git(root, ['symbolic-ref', '--quiet', '--short', 'HEAD']));
+    if (current === base) await git(root, ['merge', '--ff-only', '--quiet', `origin/${base}`]);
+    else await git(root, ['fetch', '--quiet', 'origin', `${base}:${base}`]); // not checked out: move the ref (ff only)
+    return { ok: true, text: `Local ${base} is up to date with origin/${base}.` };
+  } catch (err) {
+    return { ok: false, text: `Local ${base} was not updated: ${err.message}` };
+  }
+}