atris 3.34.0 → 3.36.0

package/commands/worktree.js

@@ -3,6 +3,12 @@
 const fs = require('fs');
 const path = require('path');
 const { spawnSync } = require('child_process');
+const { stampLatestOpenBriefForWorktree } = require('../lib/brief-ledger');
+
+const REGEN_ADAPTER_FILES = ['AGENTS.md', 'CLAUDE.md', 'GEMINI.md'];
+const COMMAND_MAX_BUFFER_BYTES = 64 * 1024 * 1024;
+const GIT_OID_PATTERN = /^[0-9a-f]{40,64}$/;
+const ONE_LAP_PROOF_REF_PATTERN = /^refs\/atris\/one-lap\/([0-9a-f]{40,64})$/;
 
 function runGit(args, { cwd = process.cwd(), check = true } = {}) {
   const result = spawnSync('git', args, { cwd, encoding: 'utf8' });
@@ -14,7 +20,14 @@ function runGit(args, { cwd = process.cwd(), check = true } = {}) {
 }
 
 function runCommand(command, { cwd = process.cwd(), check = true } = {}) {
-  const result = spawnSync(command, { cwd, encoding: 'utf8', shell: true, stdio: 'pipe' });
+  const result = spawnSync(command, {
+    cwd,
+    encoding: 'utf8',
+    shell: true,
+    stdio: 'pipe',
+    maxBuffer: COMMAND_MAX_BUFFER_BYTES,
+  });
+  if (result.error) throw result.error;
   if (check && result.status !== 0) {
     const msg = (result.stderr || result.stdout || `${command} failed`).trim();
     throw new Error(msg);
@@ -22,6 +35,67 @@ function runCommand(command, { cwd = process.cwd(), check = true } = {}) {
   return result;
 }
 
+function statusSnapshot(root) {
+  const result = runGit(['status', '--porcelain=v1', '--untracked-files=all'], { cwd: root, check: false });
+  if (result.status !== 0) return [];
+  return result.stdout
+    .split(/\r?\n/)
+    .map((line) => line.trimEnd())
+    .filter(Boolean);
+}
+
+function newStatusRows(before, after) {
+  const seen = new Set(before);
+  return after.filter((row) => !seen.has(row));
+}
+
+function readOneLapProofBinding(root, branch) {
+  const sidecarPath = path.join(root, '.atris', 'agent-worktree.json');
+  let sidecar = null;
+  try {
+    sidecar = JSON.parse(fs.readFileSync(sidecarPath, 'utf8'));
+  } catch (error) {
+    if (error && error.code !== 'ENOENT') throw new Error('one-lap proof metadata is unreadable');
+  }
+  const metadata = sidecar && sidecar.one_lap_proof;
+  const configured = runGit(['config', '--get', `branch.${branch}.atris-proof-ref`], { cwd: root, check: false });
+  const configuredRef = configured.status === 0 ? String(configured.stdout || '').trim() : '';
+  if (!metadata && !configuredRef) return null;
+  if (!metadata || !configuredRef) throw new Error('one-lap proof binding is incomplete');
+
+  const proofRef = String(metadata.ref || '');
+  const sourceCommit = String(metadata.commit || '');
+  const sourceTree = String(metadata.tree || '');
+  const refMatch = proofRef.match(ONE_LAP_PROOF_REF_PATTERN);
+  if (!refMatch || proofRef !== configuredRef || !GIT_OID_PATTERN.test(sourceCommit) || !GIT_OID_PATTERN.test(sourceTree)) {
+    throw new Error('one-lap proof binding is invalid');
+  }
+  const resolvedCommit = runGit(['rev-parse', '--verify', `${proofRef}^{commit}`], { cwd: root, check: false });
+  const resolvedTree = runGit(['rev-parse', '--verify', `${proofRef}^{tree}`], { cwd: root, check: false });
+  if (resolvedCommit.status !== 0 || String(resolvedCommit.stdout || '').trim() !== sourceCommit || refMatch[1] !== sourceCommit) {
+    throw new Error('one-lap proof commit no longer matches its retained ref');
+  }
+  if (resolvedTree.status !== 0 || String(resolvedTree.stdout || '').trim() !== sourceTree) {
+    throw new Error('one-lap proof tree no longer matches its retained ref');
+  }
+  return { ref: proofRef, commit: sourceCommit, tree: sourceTree };
+}
+
+function worktreeTree(root, source) {
+  const result = runGit(source === 'index'
+    ? ['write-tree']
+    : ['rev-parse', '--verify', 'HEAD^{tree}'], { cwd: root, check: false });
+  if (result.status !== 0) throw new Error(`could not resolve the ${source} tree for one-lap proof`);
+  return String(result.stdout || '').trim();
+}
+
+function assertOneLapProofTree(root, binding, source) {
+  if (!binding) return;
+  if (worktreeTree(root, source) !== binding.tree) {
+    throw new Error(`one-lap ${source} tree differs from the independently verified proof tree`);
+  }
+}
+
 function repoRoot(cwd = process.cwd()) {
   return runGit(['rev-parse', '--show-toplevel'], { cwd }).stdout.trim();
 }
@@ -89,6 +163,25 @@ function currentBranch(root = repoRoot()) {
   return runGit(['branch', '--show-current'], { cwd: root, check: false }).stdout.trim();
 }
 
+function detachedShipBranch(root) {
+  return `codex/${path.basename(root)}`;
+}
+
+function createDetachedShipBranch(root, branch) {
+  if (refExists(root, `refs/heads/${branch}`) || refExists(root, `refs/remotes/origin/${branch}`)) {
+    console.error(`blocked: detached head branch already exists: ${branch}`);
+    return false;
+  }
+  const created = runGit(['switch', '-c', branch], { cwd: root, check: false });
+  if (created.status !== 0) {
+    console.error(`blocked: detached head branch create failed: ${branch}`);
+    console.error((created.stderr || created.stdout || '').trim());
+    return false;
+  }
+  console.log(`ship: detached head, created branch ${branch}`);
+  return true;
+}
+
 function currentUpstream(root) {
   const result = runGit(['rev-parse', '--abbrev-ref', '--symbolic-full-name', '@{u}'], { cwd: root, check: false });
   return result.status === 0 ? result.stdout.trim() : '';
@@ -118,9 +211,7 @@ function normalizeTargetRef(root, target) {
   return value;
 }
 
-function defaultStartBase(root) {
-  const upstream = currentUpstream(root);
-  if (upstream && refExists(root, upstream)) return upstream;
+function defaultMainlineBase(root) {
   const head = remoteHead(root);
   if (head && refExists(root, head)) return head;
   for (const candidate of ['origin/master', 'origin/main']) {
@@ -129,6 +220,23 @@ function defaultStartBase(root) {
   return 'HEAD';
 }
 
+function defaultStartBase(root) {
+  const upstream = currentUpstream(root);
+  const mainline = defaultMainlineBase(root);
+  // Always refresh before cutting a worktree: a stale origin/master base sent
+  // an engine off to rebuild work that had already landed (2026-07-09, packs
+  // one-click flight rebuilt the stars backend from a base two PRs behind).
+  refreshRemoteRef(root, mainline);
+  if (!upstream || !refExists(root, upstream)) return mainline;
+  if (mainline === 'HEAD' || mainline === upstream) return upstream;
+  // A launcher upstream that is behind the mainline is a stale cut point
+  // (2026-07-05: a stale origin/task branch sent two flights into rebase
+  // conflicts). Start from the mainline unless the upstream carries new work.
+  refreshRemoteRef(root, upstream);
+  const behind = runGit(['merge-base', '--is-ancestor', upstream, mainline], { cwd: root, check: false });
+  return behind.status === 0 ? mainline : upstream;
+}
+
 function defaultShipTarget(root) {
   const branch = currentBranch(root);
   if (branch) {
@@ -153,15 +261,21 @@ function baseBranchName(ref) {
   return String(ref || '').replace(/^refs\/heads\//, '').replace(/^origin\//, '');
 }
 
-function statusCounts(root) {
+function statusCounts(root, { ignoredUnstagedFiles = new Set(), ignoredUntrackedFiles = new Set() } = {}) {
   if (!fs.existsSync(root)) return null;
-  const result = runGit(['status', '--porcelain'], { cwd: root, check: false });
+  // -uall expands untracked directories to individual files so ignoredUntrackedFiles
+  // can match exact paths (plain porcelain collapses them to "?? dir/").
+  const statusArgs = ignoredUntrackedFiles.size ? ['status', '--porcelain', '-uall'] : ['status', '--porcelain'];
+  const result = runGit(statusArgs, { cwd: root, check: false });
   if (result.status !== 0) return null;
   let staged = 0;
   let unstaged = 0;
   let untracked = 0;
   for (const line of result.stdout.split(/\r?\n/).filter(Boolean)) {
+    const file = line.slice(3);
+    if (ignoredUnstagedFiles.has(file) && line[0] === ' ' && line[1] !== ' ') continue;
     if (line.startsWith('??')) {
+      if (ignoredUntrackedFiles.has(file)) continue;
       untracked += 1;
       continue;
     }
@@ -171,6 +285,25 @@ function statusCounts(root) {
   return { staged, unstaged, untracked };
 }
 
+function changedFiles(root, args) {
+  const result = runGit([...args, '--', ...REGEN_ADAPTER_FILES], { cwd: root, check: false });
+  if (result.status !== 0) return new Set();
+  return new Set(result.stdout.split(/\r?\n/).filter(Boolean));
+}
+
+function restoreRegeneratedAdapterChurn(root, message, { dryRun = false } = {}) {
+  const unstaged = changedFiles(root, ['diff', '--name-only']);
+  const staged = changedFiles(root, ['diff', '--cached', '--name-only']);
+  const commitMessage = String(message || '');
+  const skipped = REGEN_ADAPTER_FILES.filter(
+    (file) => unstaged.has(file) && !staged.has(file) && !commitMessage.includes(file)
+  );
+  if (!skipped.length) return [];
+  console.log(`ship: skipped regenerated adapter churn: ${skipped.join(', ')}`);
+  if (!dryRun) runGit(['checkout', '--', ...skipped], { cwd: root });
+  return skipped;
+}
+
 function readFlag(args, name, fallback = '') {
   const prefix = `${name}=`;
   for (let i = 0; i < args.length; i += 1) {
@@ -215,17 +348,34 @@ function printStatus() {
 // Programmatic core shared by `atris worktree start` and `atris mission start
 // --worktree`: creates the branch + isolated checkout + identity sidecar and
 // returns the facts. Throws on failure; callers own messaging and next steps.
+//
+// checkoutBase (what the branch is cut from) and shipBase (what `atris
+// worktree ship` targets, recorded as branch.<branch>.atris-base) are kept
+// separate on purpose. checkoutBase defaults to the launcher's own
+// upstream/default remote base, so the agent starts from current work.
+// shipBase defaults to origin/master for agent/member worktrees regardless of
+// what branch the launcher happened to have checked out. recording the
+// launcher's own feature branch as the ship target false-landed two PRs on
+// 2026-07-04 (ship merged into the launcher's branch, never reached master).
+// --base/--target still overrides both when the caller wants a different
+// checkout point and ship target on purpose.
 function createAgentWorktree({ root = repoRoot(), member = '', agent = '', task, branch: branchOverride, path: pathOverride, base: baseOverride, now = new Date() } = {}) {
   const owner = member || agent;
   if (!owner || !task) throw new Error('createAgentWorktree: owner (member/agent) and task required');
   const branch = branchOverride || branchName(owner, task, now);
   const target = path.resolve(pathOverride || defaultWorktreePath(root, owner, task, now));
-  const base = normalizeTargetRef(root, baseOverride || defaultStartBase(root));
+  const explicitBase = Boolean(baseOverride);
+  // Agent/member worktrees always cut from the mainline: honoring the
+  // launcher checkout's upstream let a dispatch inherit another session's
+  // in-progress feature branch (2026-07-09: an auth fix arrived carrying 13
+  // unpushed commits from a parallel session and could not merge).
+  const checkoutBase = normalizeTargetRef(root, baseOverride || defaultMainlineBase(root));
+  const shipBase = explicitBase ? checkoutBase : normalizeTargetRef(root, 'origin/master');
   if (fs.existsSync(target)) throw new Error(`worktree path already exists: ${target}`);
   fs.mkdirSync(path.dirname(target), { recursive: true });
-  refreshRemoteRef(root, base);
-  runGit(['worktree', 'add', '-b', branch, target, base], { cwd: root });
-  runGit(['config', `branch.${branch}.atris-base`, base], { cwd: target, check: false });
+  refreshRemoteRef(root, checkoutBase);
+  runGit(['worktree', 'add', '-b', branch, target, checkoutBase], { cwd: root });
+  runGit(['config', `branch.${branch}.atris-base`, shipBase], { cwd: target, check: false });
   runGit(['config', `branch.${branch}.atris-owner`, owner], { cwd: target, check: false });
   runGit(['config', `branch.${branch}.atris-task`, task], { cwd: target, check: false });
   fs.mkdirSync(path.join(target, '.atris'), { recursive: true });
@@ -237,13 +387,14 @@ function createAgentWorktree({ root = repoRoot(), member = '', agent = '', task,
       owner,
       task,
       branch,
-      base,
+      base: shipBase,
+      checkout_base: checkoutBase,
       workspace_root: root,
       created_at: now.toISOString(),
     }, null, 2) + '\n',
     'utf8'
   );
-  return { path: target, branch, base, owner };
+  return { path: target, branch, base: shipBase, checkoutBase, owner };
 }
 
 function startWorktree(args) {
@@ -298,12 +449,21 @@ function startWorktree(args) {
 
 function createOrFindPr(root, branch, targetRef, title, dryRun) {
   const targetBranch = baseBranchName(targetRef);
-  const existing = spawnSync('gh', ['pr', 'view', '--json', 'number,url', '--jq', '"\\(.number) \\(.url)"'], {
+  // `gh pr view` (no --state filter) returns ANY PR for this branch name,
+  // including one already MERGED or CLOSED. A worktree branch that ships
+  // more than once (this same branch, more commits, another `worktree ship`)
+  // would then reuse the dead PR number: `gh pr merge <dead pr> --merge`
+  // exits 0 with just a warning (never fails), so the new commits silently
+  // never land while the ship command still reports success. Only reuse a
+  // PR that is still OPEN; anything else gets a fresh one.
+  const existing = spawnSync('gh', ['pr', 'view', '--json', 'number,url,state', '--jq', '"\\(.number) \\(.url) \\(.state)"'], {
     cwd: root,
     encoding: 'utf8',
   });
   if (existing.status === 0 && existing.stdout.trim()) {
-    return existing.stdout.trim();
+    const parts = existing.stdout.trim().split(/\s+/);
+    const state = parts.pop();
+    if (state === 'OPEN') return parts.join(' ');
   }
   const body = [
     'Automated Atris worktree ship.',
@@ -329,19 +489,41 @@ function prMergeRef(prOutput) {
   return text.split(/\s+/)[0];
 }
 
+function shipHelp() {
+  console.log('Usage: atris worktree ship --message "<commit>" --verify "<cmd>" [--merge] [--target <ref>] [--local]');
+  console.log('');
+  console.log('  --target <ref>  override the default landing target (default: branch atris-base, else origin default branch)');
+  console.log('  --local         merge into the local primary checkout instead of pushing and opening a PR');
+  console.log('  unstaged regenerated adapter files are skipped unless staged first or named in --message');
+  console.log('  recommended flight verify: npm run test:fast && node --test <focused files>');
+}
+
 function shipWorktree(args) {
+  if (hasFlag(args, '--help') || hasFlag(args, '-h') || args[0] === 'help') {
+    shipHelp();
+    return 0;
+  }
   const root = repoRoot();
   const dryRun = hasFlag(args, '--dry-run');
   const noPr = hasFlag(args, '--no-pr');
+  const localMode = hasFlag(args, '--local') || hasFlag(args, '--local-merge');
   const merge = hasFlag(args, '--merge');
   const message = readFlag(args, '--message') || readFlag(args, '-m');
   const verify = readFlag(args, '--verify');
-  const branch = currentBranch(root);
+  let branch = currentBranch(root);
   const worktrees = listWorktrees(root);
   const primary = worktrees[0]?.path;
   const targetRef = normalizeTargetRef(root, readFlag(args, '--target') || defaultShipTarget(root));
 
-  if (!branch || branch === 'master' || branch === 'main') {
+  if (!branch && path.resolve(root) === path.resolve(primary)) {
+    console.error('blocked: detached head on the primary checkout');
+    return 2;
+  }
+  if (!branch) {
+    branch = detachedShipBranch(root);
+    if (!createDetachedShipBranch(root, branch)) return 2;
+  }
+  if (branch === 'master' || branch === 'main') {
     console.error('blocked: ship from a feature worktree branch, not master/main');
     return 2;
   }
@@ -350,8 +532,27 @@ function shipWorktree(args) {
     return 2;
   }
 
+  let oneLapProof = null;
+  try {
+    oneLapProof = readOneLapProofBinding(root, branch);
+  } catch (error) {
+    console.error(`blocked: ${error.message}`);
+    return 3;
+  }
+  const proofTreeMatches = (source) => {
+    try {
+      assertOneLapProofTree(root, oneLapProof, source);
+      return true;
+    } catch (error) {
+      console.error(`blocked: ${error.message}`);
+      return false;
+    }
+  };
+
   refreshRemoteRef(root, targetRef);
-  const counts = statusCounts(root) || { staged: 0, unstaged: 0, untracked: 0 };
+  const skippedAdapters = restoreRegeneratedAdapterChurn(root, message, { dryRun });
+  const ignoredUnstagedFiles = dryRun ? new Set(skippedAdapters) : new Set();
+  const counts = statusCounts(root, { ignoredUnstagedFiles }) || { staged: 0, unstaged: 0, untracked: 0 };
   const dirty = counts.staged || counts.unstaged || counts.untracked;
   if (dirty && !message) {
     console.error('blocked: --message is required when there are local changes to commit');
@@ -362,23 +563,33 @@ function shipWorktree(args) {
     console.log(`commit: ${message}`);
     if (!dryRun) {
       runGit(['add', '-A'], { cwd: root });
+      if (!proofTreeMatches('index')) return 3;
       runGit(['commit', '-m', message], { cwd: root });
+      if (!proofTreeMatches('head')) return 3;
     }
   } else {
     console.log('commit: skipped (no local changes)');
+    if (!dryRun && !proofTreeMatches('head')) return 3;
   }
 
   if (verify) {
+    const beforeVerify = dryRun ? [] : statusSnapshot(root);
     console.log(`verify: ${verify}`);
     if (!dryRun) runCommand(verify, { cwd: root });
+    const afterVerifyRows = dryRun ? [] : statusSnapshot(root);
+    const verifyDelta = newStatusRows(beforeVerify, afterVerifyRows);
     const afterVerify = dryRun ? { staged: 0, unstaged: 0, untracked: 0 } : statusCounts(root) || { staged: 0, unstaged: 0, untracked: 0 };
     if (!dryRun && (afterVerify.staged || afterVerify.unstaged || afterVerify.untracked)) {
       console.error(
         `blocked: verifier left checkout dirty staged=${afterVerify.staged} ` +
           `unstaged=${afterVerify.unstaged} untracked=${afterVerify.untracked}`
       );
+      if (verifyDelta.length) {
+        console.error(`new after verify: ${verifyDelta.slice(0, 8).join(', ')}`);
+      }
       return 3;
     }
+    if (!dryRun && !proofTreeMatches('head')) return 3;
   } else {
     console.log('verify: skipped (no --verify)');
   }
@@ -393,6 +604,35 @@ function shipWorktree(args) {
   }
   console.log(`merge_check: ${targetRef} clean`);
 
+  if (localMode) {
+    console.log('push: skipped (local mode)');
+    if (merge) {
+      console.log('merge: requested (local mode)');
+      if (!dryRun) {
+        const targetBranch = baseBranchName(targetRef);
+        const primaryBranch = currentBranch(primary);
+        if (primaryBranch !== targetBranch) {
+          const switched = runGit(['switch', targetBranch], { cwd: primary, check: false });
+          if (switched.status !== 0) {
+            throw new Error((switched.stderr || switched.stdout || `git switch ${targetBranch} failed`).trim());
+          }
+        }
+        const primaryCounts = statusCounts(primary) || { staged: 0, unstaged: 0, untracked: 0 };
+        if (primaryCounts.staged || primaryCounts.unstaged || primaryCounts.untracked) {
+          throw new Error(
+            `primary checkout dirty staged=${primaryCounts.staged} ` +
+            `unstaged=${primaryCounts.unstaged} untracked=${primaryCounts.untracked}`
+          );
+        }
+        runGit(['merge', '--no-ff', branch, '-m', `Merge ${branch}`], { cwd: primary });
+        console.log('merge: merged (local mode)');
+      }
+    }
+    console.log('pr: skipped (local mode)');
+    console.log('done: worktree shipped');
+    return 0;
+  }
+
   console.log(`push: origin ${branch}`);
   if (!dryRun) runGit(['push', '-u', 'origin', branch], { cwd: root });
 
@@ -409,6 +649,11 @@ function shipWorktree(args) {
         mergeArgs.push('--merge');
         const merged = spawnSync('gh', mergeArgs, { cwd: root, encoding: 'utf8' });
         if (merged.status !== 0) throw new Error((merged.stderr || merged.stdout || 'gh pr merge failed').trim());
+        // `gh pr merge` on an already-merged PR exits 0 with a warning
+        // instead of failing, which would otherwise report a false landing.
+        if (/already merged/i.test(`${merged.stdout}${merged.stderr}`)) {
+          throw new Error(`gh pr merge reported the PR was already merged (stale PR reused): ${(merged.stdout || merged.stderr).trim()}`);
+        }
         console.log('merge: merged');
         const deleted = runGit(['push', 'origin', '--delete', branch], { cwd: root, check: false });
         if (deleted.status === 0) {
@@ -423,6 +668,12 @@ function shipWorktree(args) {
     console.log('pr: skipped (--no-pr)');
   }
 
+  try {
+    stampLatestOpenBriefForWorktree(root, {
+      result: 'pass',
+      note: `worktree ship completed into ${targetRef}`,
+    }, { worktree: root });
+  } catch {}
   console.log('done: worktree shipped');
   return 0;
 }
@@ -436,7 +687,8 @@ function guard(args) {
     console.error('run: atris worktree start --member <member>|--agent <name> --task "<short task>" --claim');
     return 2;
   }
-  const counts = statusCounts(root);
+  // The CLI's own worktree metadata (written by `worktree start`) must not count as dirt.
+  const counts = statusCounts(root, { ignoredUntrackedFiles: new Set(['.atris/agent-worktree.json']) });
   if (counts && (counts.staged || counts.unstaged || counts.untracked) && !hasFlag(args, '--allow-dirty')) {
     console.error(`blocked: checkout is dirty staged=${counts.staged} unstaged=${counts.unstaged} untracked=${counts.untracked}`);
     return 3;
@@ -456,6 +708,19 @@ function prune(args) {
 
 const PROTECTED_BRANCHES = new Set(['main', 'master']);
 
+// A worktree fresh off `worktree start` is merged into base by definition
+// (zero commits yet), so without a grace window the janitor reaps it while
+// the engine that requested it is still booting inside.
+const WORKTREE_REAP_GRACE_MS = 60 * 60 * 1000;
+
+function worktreeWithinReapGrace(worktreePath, now = Date.now()) {
+  try {
+    return now - fs.statSync(worktreePath).mtimeMs < WORKTREE_REAP_GRACE_MS;
+  } catch {
+    return false;
+  }
+}
+
 function cleanupWorktrees({ root = repoRoot(), base: baseOverride = '', apply = false } = {}) {
   const worktrees = listWorktrees(root);
   const primary = worktrees[0]?.path ? path.resolve(worktrees[0].path) : '';
@@ -503,6 +768,10 @@ function cleanupWorktrees({ root = repoRoot(), base: baseOverride = '', apply =
       kept.push({ ...item, reason: 'unmerged' });
       continue;
     }
+    if (worktreeWithinReapGrace(wtPath)) {
+      kept.push({ ...item, reason: 'fresh_worktree_grace' });
+      continue;
+    }
     const candidate = { ...item, reason: 'merged_into_base' };
     candidates.push(candidate);
     if (!apply) continue;
@@ -560,7 +829,9 @@ function guide() {
   console.log('   atris mission tick <id> --verify --complete-on-pass');
   console.log('');
   console.log('4. Ship only from the isolated worktree:');
-  console.log('   atris worktree ship --message "<commit>" --verify "<cmd>" --merge');
+  console.log('   atris worktree ship --message "<commit>" --verify "<cmd>" --merge [--target <ref>]');
+  console.log('   --target <ref> overrides the default landing target (default: branch atris-base, else origin default branch)');
+  console.log('   recommended verify: npm run test:fast && node --test <focused files>');
   console.log('');
   console.log('5. Clean merged worktrees:');
   console.log('   atris worktree cleanup');
@@ -576,7 +847,10 @@ function help() {
   console.log('');
   console.log('  atris worktree guide');
   console.log('  atris worktree start --member <member>|--agent <name> --task "<task>" [--claim]');
-  console.log('  atris worktree ship --message "<commit>" --verify "<cmd>" [--merge]');
+  console.log('  atris worktree ship --message "<commit>" --verify "<cmd>" [--merge] [--target <ref>] [--local]');
+  console.log('    --target <ref>  override the default landing target (default: branch atris-base, else origin default branch)');
+  console.log('    --local         merge into the local primary checkout instead of pushing and opening a PR');
+  console.log('    recommended verify: npm run test:fast && node --test <focused files>');
   console.log('  atris worktree status');
   console.log('  atris worktree guard [--allow-primary] [--allow-dirty]');
   console.log('  atris worktree prune [--apply]');
@@ -606,14 +880,19 @@ function worktreeCommand(args = []) {
 
 module.exports = {
   branchName,
+  statusSnapshot,
+  newStatusRows,
   createAgentWorktree,
+  createOrFindPr,
   cleanupWorktrees,
   defaultShipTarget,
   defaultStartBase,
   defaultWorktreePath,
   listWorktrees,
   parseWorktrees,
+  REGEN_ADAPTER_FILES,
   normalizeTargetRef,
+  restoreRegeneratedAdapterChurn,
   prMergeRef,
   slugify,
   statusCounts,