@ulysses-ai/create-workspace 0.23.3-beta.0 → 0.24.0-beta.0

package/template/_claude/scripts/forges/github.mjs

@@ -16,7 +16,7 @@ import {
   MergeRejected,
 } from './interface.mjs';
 
-const PR_VIEW_FIELDS = 'number,url,state,title,mergeable,mergeStateStatus,reviewDecision,headRefName,baseRefName,isDraft,mergedAt';
+const PR_VIEW_FIELDS = 'number,url,state,title,mergeable,mergeStateStatus,reviewDecision,headRefName,baseRefName,isDraft,mergedAt,createdAt';
 
 export function createGithubAdapter(config, { spawnFn = nodeSpawnSync } = {}) {
   const defaultRepo = resolveRepo(config, spawnFn);
@@ -106,6 +106,7 @@ export function createGithubAdapter(config, { spawnFn = nodeSpawnSync } = {}) {
       baseRefName: raw.baseRefName,
       isDraft: raw.isDraft,
       mergedAt: raw.mergedAt,
+      createdAt: raw.createdAt,
       _raw: raw,
     };
   }
@@ -139,6 +140,54 @@ export function createGithubAdapter(config, { spawnFn = nodeSpawnSync } = {}) {
     }));
   }
 
+  // The PR's CI picture, from `gh pr checks` (which categorizes each check
+  // row into a `bucket`: pass, fail, pending, skipping, cancel — the
+  // aggregate state derives from those, not from `state`, whose vocabulary
+  // is wider and matters less). gh exits non-zero when any check fails or
+  // is pending, so the exit status carries nothing the JSON does not. A PR
+  // with no CI at all prints no JSON: gh 2.89 exits 1 with "no checks
+  // reported on the '<branch>' branch" on stderr — that absence is the
+  // answer, 'none', while any other prose (auth, network, not-found) is a
+  // real error. A cancelled check never passed and reads as failing; a
+  // skipped one is an expected matrix leg and counts as a pass.
+  async function prChecks({ id, repo }) {
+    if (!id) throw new Error('prChecks: id is required');
+    const { number, repo: parsedRepo } = parsePrId(id, repoFor(repo));
+    const result = gh(['pr', 'checks', String(number), '--repo', parsedRepo, '--json', 'name,state,bucket,link']);
+    let rows;
+    try {
+      rows = JSON.parse(result.stdout || '');
+    } catch {
+      const stderr = (result.stderr || result.stdout || '').trim();
+      if (/not\s+found|could\s+not\s+resolve/i.test(stderr)) {
+        throw new PrNotFound(id);
+      }
+      if (/no checks reported/i.test(stderr)) {
+        return {
+          state: 'none',
+          url: `https://github.com/${parsedRepo}/pull/${number}/checks`,
+          failing: [],
+        };
+      }
+      throw new Error(`gh pr checks ${number} failed: ${stderr}`);
+    }
+    if (!Array.isArray(rows)) {
+      throw new Error(`gh pr checks ${number} returned unparseable output: ${result.stdout}`);
+    }
+    const failing = rows
+      .filter((c) => c.bucket === 'fail' || c.bucket === 'cancel')
+      .map((c) => ({ name: c.name, url: c.link }));
+    const state = failing.length > 0 ? 'failure'
+      : rows.some((c) => c.bucket === 'pending') ? 'pending'
+      : rows.length === 0 ? 'none'
+      : 'success';
+    return {
+      state,
+      url: `https://github.com/${parsedRepo}/pull/${number}/checks`,
+      failing,
+    };
+  }
+
   async function releaseView({ tag, repo }) {
     if (!tag) throw new Error('releaseView: tag is required');
     const target = repoFor(repo);
@@ -226,6 +275,7 @@ export function createGithubAdapter(config, { spawnFn = nodeSpawnSync } = {}) {
     prMerge,
     prView,
     prList,
+    prChecks,
     releaseView,
     releaseCreate,
     workflowRunFind,

package/template/_claude/scripts/forges/gitlab.mjs

@@ -27,6 +27,12 @@
 //     Watching polls the pipeline until it reaches a status that cannot
 //     change on its own — a `manual` job keeps polling, since approving it
 //     resumes the pipeline.
+//   - `prChecks` reads the MR's `head_pipeline` through `glab api`. There
+//     is no `glab mr checks` (the command does not exist — it prints help
+//     and exits 0, a trap that would read as "no checks"), and commit
+//     statuses would mix external CI with pipeline jobs; head_pipeline is
+//     the pipeline for the MR's current head, which is exactly the CI the
+//     merge gates on. A `manual` pipeline reads as pending with a note.
 //   - `releaseCreate` has no forge-generated-notes equivalent on GitLab:
 //     `generateNotes: true` throws NOT_SUPPORTED — callers pass
 //     `generateNotes: false` plus explicit `notes`.
@@ -191,6 +197,7 @@ export function createGitlabAdapter(config, { spawnFn = nodeSpawnSync, pollMs =
       baseRefName: raw.target_branch,
       isDraft: !!raw.draft,
       mergedAt: raw.merged_at,
+      createdAt: raw.created_at,
       _raw: raw,
     };
   }
@@ -260,6 +267,67 @@ export function createGitlabAdapter(config, { spawnFn = nodeSpawnSync, pollMs =
     return list;
   }
 
+  // `glab api` prints the entity on success and prose on failure — a
+  // parse error means the call did not get what it asked for.
+  function parseApi(path, stdout) {
+    try {
+      return JSON.parse(String(stdout || '').trim() || 'null');
+    } catch (err) {
+      throw new Error(`glab api ${path} returned unparseable output: ${err.message}`);
+    }
+  }
+
+  // The MR's CI picture (gh:201). No `glab mr checks` exists and commit
+  // statuses would mix external CI with pipeline jobs (see the header
+  // notes), so the MR entity's head_pipeline is the source: the pipeline
+  // for the MR's current head. No pipeline → 'none'. `skipped` counts as
+  // success (an expected skip satisfies CI, like GitHub's skipping
+  // bucket); `failed`/`canceled` read the pipeline's failed jobs (a full
+  // page of them, per_page=100) so the failure names what broke — minus
+  // the allow_failure jobs, which are allowed to fail and so did not break
+  // it; everything still moving — running, pending, created, preparing,
+  // waiting_for_resource, scheduled — is pending, and `manual` is pending
+  // too, with a note: approving the manual job turns the pipeline running
+  // again.
+  async function prChecks({ id, repo }) {
+    if (!id) throw new Error('prChecks: id is required');
+    const { number, repo: parsedRepo } = parseMrId(id, repoFor(repo));
+    const enc = encodeURIComponent(parsedRepo);
+    const mrPath = `projects/${enc}/merge_requests/${number}`;
+    const result = glab(apiArgs(mrPath));
+    if (result.status !== 0) {
+      const stderr = (result.stderr || '').trim();
+      if (NOT_FOUND_RE.test(stderr)) {
+        throw new PrNotFound(id);
+      }
+      throw new Error(`glab api ${mrPath} failed: ${stderr}`);
+    }
+    const mr = parseApi(mrPath, result.stdout) ?? {};
+    const pipeline = mr.head_pipeline ?? null;
+    if (!pipeline || !pipeline.id) {
+      return { state: 'none', url: mr.web_url ?? webUrl(parsedRepo, 'merge_requests', number), failing: [] };
+    }
+    const url = pipeline.web_url ?? webUrl(parsedRepo, 'pipelines', pipeline.id);
+    const status = String(pipeline.status || '').toLowerCase();
+    if (status === 'success' || status === 'skipped') {
+      return { state: 'success', url, failing: [] };
+    }
+    if (status === 'failed' || status === 'canceled') {
+      const jobsPath = `projects/${enc}/pipelines/${pipeline.id}/jobs?scope[]=failed&per_page=100`;
+      const jobs = parseApi(jobsPath, glabOrThrow(apiArgs(jobsPath))) ?? [];
+      return {
+        state: 'failure',
+        url,
+        failing: jobs.filter((j) => !j.allow_failure).map((j) => ({ name: j.name, url: j.web_url })),
+      };
+    }
+    const checks = { state: 'pending', url, failing: [] };
+    if (status === 'manual') {
+      checks.note = 'pipeline waiting on a manual job — approve it in the pipeline UI';
+    }
+    return checks;
+  }
+
   async function releaseView({ tag, repo }) {
     if (!tag) throw new Error('releaseView: tag is required');
     const target = repoFor(repo);
@@ -353,6 +421,7 @@ export function createGitlabAdapter(config, { spawnFn = nodeSpawnSync, pollMs =
     prMerge,
     prView,
     prList,
+    prChecks,
     releaseView,
     releaseCreate,
     workflowRunFind,

package/template/_claude/scripts/forges/interface.mjs

@@ -15,8 +15,11 @@
 //     → { merged: true, url }
 //     strategy: 'merge' | 'squash' | 'rebase'
 //   prView({ id, repo?, json? })
-//     → { id, url, state, mergeable, mergeStateStatus, reviewDecision, title }
-//     json may name additional fields to pass through
+//     → { id, url, state, mergeable, mergeStateStatus, reviewDecision, title,
+//         createdAt }
+//     json may name additional fields to pass through. createdAt (an ISO
+//     timestamp) is when the PR opened — a caller judging whether a
+//     "no checks yet" read is a race needs it.
 //   prList({ state = 'merged', base?, head?, search?, limit = 100, repo? })
 //     → [{ id, number, title, url, headRefName, baseRefName, mergedAt, state }]
 //     `base`/`head` filter by target/source branch (e.g. the open PR for a
@@ -29,6 +32,20 @@
 //     older results may exist beyond it the returned array carries a
 //     non-enumerable `truncated: true` (callers that only map the list
 //     never see it).
+//   prChecks({ id, repo? })
+//     → { state: 'pending' | 'success' | 'failure' | 'none', url,
+//         failing: [{ name, url }], note? }
+//     The PR's CI picture: 'success' or 'failure' once its checks finished,
+//     'pending' while they run, 'none' when the PR has no checks at all.
+//     `failing` lists the failing check runs (name + url) when the state is
+//     'failure'; `url` points where a human looks — the PR's checks page
+//     (GitHub) or the head pipeline (GitLab). A GitLab pipeline on a
+//     `manual` job reads as pending with a `note` saying so (approving the
+//     job resumes the pipeline), and `skipped` counts as success, matching
+//     GitHub's skipping bucket. The read is conservative on both forges:
+//     GitHub weighs every check on the PR, required or not, and GitLab's
+//     `failing` excludes allow_failure jobs — allowed to fail, they do not
+//     fail the pipeline.
 //   releaseView({ tag, repo? })
 //     → { tag, url, name, publishedAt }
 //     throws ReleaseNotFound if the tag has no release

package/template/_claude/scripts/maintenance-audit.mjs

@@ -16,7 +16,12 @@
 //                         .indexignore excludes, anything under an archive/
 //                         directory) and closed-out lifecycles are skipped
 //   3. structure        — workspace.json and CLAUDE.md present and parseable,
-//                         manifest repos cloned, expected directories there
+//                         manifest repos cloned, expected directories there,
+//                         and the template-modification registry sane:
+//                         legacy workspace.json keys, keys that escape
+//                         .claude/, and registrations the workspace abandoned
+//                         are info, a registry that doesn't parse is a
+//                         warning (gh:194)
 //   4. git              — launcher on its default branch with a clean tracked
 //                         tree. Audited from a linked worktree (task or
 //                         session), the launcher-level questions — the
@@ -29,7 +34,16 @@
 //                         .claude/skills/workspace-update/ modification an
 //                         --upgrade leaves when its content equals the staged
 //                         payload's is the expected bootstrap, reported as
-//                         info, never a dirty-tree warning (gh:190)
+//                         info, never a dirty-tree warning (gh:190). Leftover
+//                         Claude Code agent worktrees (worktree-agent-*
+//                         branches, gh:205) are each listed as info with the
+//                         facts and a strict removable verdict that fails
+//                         closed — worktree integrity, clean, own-work
+//                         analysis against the default branch (merge
+//                         commits, git-cherry patch-id landing), locked,
+//                         idle over an hour, chat-record claims (unreadable
+//                         records block removal) — also exposed as
+//                         summary.agentWorktrees for --json
 //   5. auto-files       — workspace-context catalogs current (the same
 //                         semantics as build-workspace-context.mjs --check)
 //   6. budget           — always-loaded context within
@@ -86,7 +100,8 @@ import {
   readIgnorePrefixes,
   isIgnored,
 } from './build-workspace-context.mjs';
-import { hashBytes } from './template-baseline.mjs';
+import { hashBytes, readBaseline } from './template-baseline.mjs';
+import { readTemplateModifications } from './template-modifications.mjs';
 import { refreshIfStale } from '../lib/freshness.mjs';
 import { parseSessionContent } from '../lib/session-frontmatter.mjs';
 
@@ -279,6 +294,55 @@ export async function runAudit({
     }
   }
 
+  // Template-modification registry (gh:194), still under section 3 — it is
+  // workspace structure: which files the workspace owns outright and which
+  // template files it deliberately edits, and why. Legacy workspace.json
+  // keys awaiting migration, keys that escape .claude/ (the registry covers
+  // .claude/ paths only), and registrations the workspace has abandoned are
+  // info (all are /workspace-update offers, nothing is broken); a registry
+  // that doesn't parse silently disables its exclusions and reasons, which
+  // is worth a warning.
+  {
+    const mods = readTemplateModifications(absRoot);
+    if (mods.parseError !== null) {
+      add('structure', 'warning', '.claude/template-modifications.json',
+        `does not parse (${mods.parseError}) — localFiles exclusions and modification reasons are being ignored; fix the JSON`);
+    }
+    if (mods.legacyKeys.length > 0) {
+      add('structure', 'info', 'workspace.json',
+        `legacy template-modification key(s) still present: ${mods.legacyKeys.map((k) => `workspace.${k}`).join(', ')} — /workspace-update offers to migrate them into .claude/template-modifications.json`);
+    }
+    if (mods.ignoredKeys.length > 0) {
+      add('structure', 'info', '.claude/template-modifications.json',
+        `key(s) outside .claude/ are ignored: ${mods.ignoredKeys.join(', ')} — the registry covers .claude/ paths only (root files are handled by their own merge paths); drop or fix them`);
+    }
+    const entries = Object.entries(mods.modifications);
+    if (entries.length > 0) {
+      const baseline = readBaseline(absRoot);
+      if (baseline) {
+        for (const [key, reason] of entries) {
+          const rel = `.claude/${key}`;
+          const baselineHash = baseline.files[rel];
+          const installed = join(absRoot, rel);
+          // Stale = the installed file is back to exactly what the template
+          // last shipped (its baseline hash): the recorded edit is gone. A
+          // missing file is NOT stale — a deliberate deletion is a live
+          // decision the next update's deletedLocally ask will explain with
+          // this very reason — and neither is a key naming a directory:
+          // only regular files compare.
+          if (typeof baselineHash !== 'string') continue;
+          let st;
+          try { st = statSync(installed); } catch { continue; }
+          if (!st.isFile()) continue;
+          if (hashBytes(readFileSync(installed)) === baselineHash) {
+            add('structure', 'info', '.claude/template-modifications.json',
+              `entry for ${rel} is stale — the file matches the template baseline again, the recorded edit is gone (reason: ${reason}); drop the entry`);
+          }
+        }
+      }
+    }
+  }
+
   // ---------- 1. cross-reference ----------
 
   const claudeMdPath = join(absRoot, 'CLAUDE.md');
@@ -464,6 +528,7 @@ export async function runAudit({
 
   // ---------- 4. git state ----------
 
+  const agentWorktrees = [];
   if (!gitInfo.isRepo) {
     add('git', 'info', '.', 'not a git repository — git checks skipped');
   } else {
@@ -529,6 +594,262 @@ export async function runAudit({
     if (untracked.length > 0) {
       add('git', 'info', '.', `${untracked.length} untracked path(s) — gitignored content is not counted`);
     }
+
+    // Claude Code agent worktrees (gh:205): a subagent with worktree
+    // isolation gets {repo}/.claude/worktrees/agent-{id}/ on a
+    // worktree-agent-{id} branch, in the workspace repo and each project
+    // repo. Claude Code removes a clean one when the subagent finishes and
+    // sweeps the rest past cleanupPeriodDays — but the sweep keeps any
+    // worktree holding work, and a subagent that commits without pushing is
+    // exactly that, indefinitely. Each leftover is one info finding plus a
+    // summary.agentWorktrees entry, and the script decides removal: facts
+    // carry a strict removable verdict with the reasons behind it, and
+    // cleanup offers removal only for removable: true — safety rests on the
+    // script, not on prose re-deriving the facts. The branch prefix and the
+    // path shape together keep task worktrees (feature/bugfix/chore
+    // branches) and hand-added worktrees out of the list.
+    const gitIn = (dir, args) => spawnSync('git', ['-C', dir, ...args], { encoding: 'utf8' });
+    const inAgentSlot = (p) => {
+      const parts = p.split(sep).join('/').split('/');
+      for (let i = 1; i < parts.length - 1; i += 1) {
+        if (parts[i] === 'worktrees' && parts[i - 1] === '.claude' && parts[i + 1].startsWith('agent-')) {
+          return true;
+        }
+      }
+      return false;
+    };
+    const agentEntries = (repoDir) => {
+      const res = gitIn(repoDir, ['worktree', 'list', '--porcelain']);
+      if (res.status !== 0) return [];
+      const out = [];
+      let cur = null;
+      for (const line of String(res.stdout).split(/\r?\n/)) {
+        if (!line) { cur = null; continue; }
+        if (line.startsWith('worktree ')) {
+          cur = { path: line.slice('worktree '.length), branch: null, locked: false, lockReason: null, prunable: false };
+          out.push(cur);
+        } else if (cur && line.startsWith('branch ')) {
+          cur.branch = line.slice('branch '.length).replace(/^refs\/heads\//, '');
+        } else if (cur && line.startsWith('locked')) {
+          cur.locked = true;
+          cur.lockReason = line.slice('locked'.length).trim() || null;
+        } else if (cur && line.startsWith('prunable')) {
+          cur.prunable = true;
+        }
+      }
+      return out.filter((w) => typeof w.branch === 'string'
+        && w.branch.startsWith('worktree-agent-') && inAgentSlot(w.path));
+    };
+    // Native path resolution (Windows 8.3 short names) with a plain
+    // fallback. On win32 the filesystem is case-insensitive and git may
+    // spell a path with different casing than Node does, so real-path
+    // comparisons there are case-insensitive too.
+    const realPathNative = (p) => {
+      try { return realpathSync.native(p); } catch { /* fall through */ }
+      try { return realpathSync(p); } catch { /* fall through */ }
+      return resolve(p);
+    };
+    const sameRealPath = (a, b) => {
+      const x = realPathNative(a);
+      const y = realPathNative(b);
+      return process.platform === 'win32' ? x.toLowerCase() === y.toLowerCase() : x === y;
+    };
+    // Counts arrive from git stdout; anything but a plain integer is a null
+    // answer, never a coerced zero.
+    const parseCount = (stdout) => {
+      const t = String(stdout).trim();
+      return /^[0-9]+$/.test(t) ? Number(t) : null;
+    };
+    // A repos/{name}/ directory that is not a git toplevel of its own would
+    // make every git query walk up to the launcher and list the launcher's
+    // worktrees under that repo's name — skip such directories entirely.
+    const isOwnToplevel = (dir) => {
+      const res = gitIn(dir, ['rev-parse', '--show-toplevel']);
+      if (res.status !== 0) return false;
+      return sameRealPath(String(res.stdout).trim(), dir);
+    };
+    // A worktree-agent-* branch a chat record still lists as a task belongs
+    // to a chat, not to cleanup. The records are read directly (the same
+    // layout chat-record.mjs owns) rather than imported, so the audit keeps
+    // running from the upgrade payload, which stages only part of scripts/.
+    // Every way a record can fail to be read — an unreadable chats
+    // directory (anything but ENOENT), unparseable JSON, a tasks field
+    // present but not an array — makes claims UNKNOWN, and unknown fails
+    // closed: no agent worktree is removable while any record is unreadable.
+    const claimedBranches = new Set();
+    let claimsUnknown = false;
+    {
+      const chatsDir = join(reposRoot, 'workspace-scratchpad', 'chats');
+      let names = [];
+      try {
+        names = readdirSync(chatsDir);
+      } catch (err) {
+        if (err?.code !== 'ENOENT') claimsUnknown = true;
+      }
+      for (const name of names) {
+        if (!name.endsWith('.json')) continue;
+        let rec;
+        try {
+          rec = JSON.parse(readFileSync(join(chatsDir, name), 'utf8'));
+        } catch {
+          claimsUnknown = true;
+          continue;
+        }
+        if (rec && rec.tasks !== undefined && !Array.isArray(rec.tasks)) {
+          claimsUnknown = true;
+          continue;
+        }
+        for (const t of Array.isArray(rec?.tasks) ? rec.tasks : []) {
+          if (t && typeof t.branch === 'string') claimedBranches.add(t.branch);
+        }
+      }
+    }
+    const reposToScan = [
+      { repo: '.', repoDir: reposRoot },
+      ...Object.keys(reposManifest).map((name) => ({ repo: name, repoDir: join(reposRoot, 'repos', name) })),
+    ];
+    // git reports worktree paths as the filesystem spells them (a resolved
+    // /private/var on macOS where the root arrived as /var), so both sides
+    // are realpathed before relativizing — a gone directory falls back to
+    // its recorded spelling and reports as an absolute path rather than
+    // being skipped.
+    const reposAnchor = (() => { try { return realpathSync(reposRoot); } catch { return reposRoot; } })();
+    const asReal = (p) => { try { return realpathSync(p); } catch { return p; } };
+    // Idle gate: a worktree active within the last hour is not removable,
+    // guarding a just-started agent even though Claude Code locks running
+    // agent worktrees. Last activity is the newest of the directory's mtime
+    // and the HEAD reflog's latest entry — under --date=unix the %gd
+    // selector renders as HEAD@{<epoch-seconds>}, the entry's own time
+    // (the commit's dates are something else entirely).
+    const IDLE_MS = 60 * 60 * 1000;
+    const lastActivityMs = (dir) => {
+      let ms = NaN;
+      try { ms = statSync(dir).mtimeMs; } catch { /* the directory may already be gone */ }
+      const rl = gitIn(dir, ['reflog', 'show', '-1', '--date=unix', '--format=%gd', 'HEAD']);
+      if (rl.status === 0) {
+        const m = /@\{(\d+)\}/.exec(String(rl.stdout));
+        if (m) ms = Math.max(ms, Number(m[1]) * 1000);
+      }
+      return ms;
+    };
+    for (const { repo, repoDir } of reposToScan) {
+      if (!existsSync(repoDir)) continue; // an uncloned repo is section 3's finding
+      if (!isOwnToplevel(repoDir)) continue; // not a repo of its own — see isOwnToplevel
+      for (const w of agentEntries(repoDir)) {
+        const wtRealPath = asReal(w.path);
+        const facts = {
+          repo,
+          branch: w.branch,
+          path: toRootRelative(reposAnchor, wtRealPath),
+          absolutePath: wtRealPath,
+          clean: null,
+          commitsBeyond: null,
+          patchIdsOnDefault: null,
+          locked: w.locked,
+          ...(w.lockReason ? { lockReason: w.lockReason } : {}),
+        };
+        const reasons = [];
+        // Ref queries run from the repo, not the worktree, so the facts
+        // survive a prunable entry whose directory is already gone.
+        // Gate 1 — integrity: git must still map this directory to the
+        // recorded worktree. A deleted .git file leaves a plain directory
+        // whose git queries silently run against the owning repo (which may
+        // well be clean) — the toplevel check is what catches that, and a
+        // prunable record means the directory is already gone.
+        if (w.prunable) {
+          reasons.push('prunable worktree record — git no longer resolves this worktree');
+        } else {
+          const top = gitIn(w.path, ['rev-parse', '--show-toplevel']);
+          if (top.status !== 0 || !sameRealPath(String(top.stdout).trim(), w.path)) {
+            reasons.push('worktree integrity unverifiable — directory does not match its record');
+          }
+        }
+        // Gate 2 — clean, untracked files included.
+        const wtStatus = gitIn(w.path, ['status', '--porcelain']);
+        if (wtStatus.status === 0) facts.clean = String(wtStatus.stdout).trim() === '';
+        if (facts.clean === false) reasons.push('dirty worktree');
+        else if (facts.clean === null) reasons.push('cleanliness unknown');
+        // Gate 3 — no work of its own on the line. The base is the repo's
+        // configured default, origin's copy when it exists, else the local
+        // ref; with neither there is nothing to measure against.
+        const configured = repo === '.'
+          ? gitInfo.defaultBranch ?? 'main'
+          : (reposManifest[repo] && typeof reposManifest[repo].branch === 'string' && reposManifest[repo].branch
+            ? reposManifest[repo].branch
+            : 'main');
+        const base = [`origin/${configured}`, configured].find(
+          (ref) => gitIn(repoDir, ['rev-parse', '--verify', '--quiet', ref]).status === 0,
+        );
+        if (!base) {
+          reasons.push(`no ${configured} ref to measure the branch against`);
+        } else {
+          facts.base = base;
+          const cnt = gitIn(repoDir, ['rev-list', '--count', `${base}..${w.branch}`]);
+          if (cnt.status === 0) facts.commitsBeyond = parseCount(cnt.stdout);
+          if (facts.commitsBeyond === null) {
+            reasons.push(`commits beyond ${base} unknown`);
+          } else if (facts.commitsBeyond > 0) {
+            // git cherry marks each branch commit +/- by whether its
+            // patch-id is already on the base — all "-" means the branch
+            // holds nothing the base lacks, even when --merged sees none of
+            // it (rebase and cherry-pick landings). A squash merge leaves
+            // the branch's patch-ids unmatched, so it lands on the "+" side
+            // — not removable, the safe direction. Patch-ids do not apply
+            // to merge commits at all, and cherry must account for every
+            // non-merge commit before its verdict is trusted.
+            const merges = gitIn(repoDir, ['rev-list', '--merges', '--count', `${base}..${w.branch}`]);
+            const noMerges = gitIn(repoDir, ['rev-list', '--no-merges', '--count', `${base}..${w.branch}`]);
+            const mergeCount = merges.status === 0 ? parseCount(merges.stdout) : null;
+            const noMergeCount = noMerges.status === 0 ? parseCount(noMerges.stdout) : null;
+            const cherry = gitIn(repoDir, ['cherry', base, w.branch]);
+            const cherryLines = cherry.status === 0
+              ? String(cherry.stdout).split(/\r?\n/).map((l) => l.trim()).filter(Boolean)
+              : null;
+            if (mergeCount === null) {
+              reasons.push(`landing on ${base} unverifiable — merge count unreadable`);
+            } else if (mergeCount > 0) {
+              reasons.push(`${mergeCount} merge commit(s) beyond ${base} — patch-ids do not apply to merges`);
+            } else if (cherryLines === null || noMergeCount === null || cherryLines.length !== noMergeCount) {
+              reasons.push(`landing on ${base} unverifiable — git cherry could not account for every commit`);
+            } else if (!cherryLines.every((l) => l.startsWith('-'))) {
+              reasons.push(`commit(s) beyond ${base} not landed on it`);
+              facts.patchIdsOnDefault = false;
+            } else {
+              facts.patchIdsOnDefault = true;
+            }
+          } else {
+            facts.patchIdsOnDefault = true; // nothing beyond the base at all
+          }
+        }
+        // Gate 4 — locked. Claude Code locks a worktree while its agent
+        // runs; a stale lock still means removal needs a human decision.
+        if (facts.locked) reasons.push(`locked${facts.lockReason ? ` (${facts.lockReason})` : ''}`);
+        // Gate 5 — idle (see lastActivityMs above).
+        const activity = lastActivityMs(w.path);
+        if (Number.isNaN(activity)) reasons.push('last activity unknown');
+        else if (nowFn().getTime() - activity < IDLE_MS) reasons.push('active within the last hour');
+        // Gate 6 — not claimed (see claimedBranches above). Claims that
+        // could not be read fail closed: unknown is not none.
+        facts.claimed = !claimsUnknown && claimedBranches.has(w.branch);
+        if (claimsUnknown) reasons.push('chat records unreadable — claims unknown');
+        else if (facts.claimed) reasons.push('claimed by a chat record');
+        facts.removable = reasons.length === 0;
+        facts.reasons = reasons;
+        agentWorktrees.push(facts);
+        const state = facts.clean === null ? 'cleanliness unknown' : facts.clean ? 'clean' : 'dirty';
+        const beyond = facts.commitsBeyond === null
+          ? `commits beyond ${facts.base ?? 'the default branch'} unknown`
+          : facts.commitsBeyond === 0
+            ? `no commits beyond ${facts.base}`
+            : `${facts.commitsBeyond} commit(s) beyond ${facts.base}`;
+        const bits = [state, beyond];
+        if (facts.locked) bits.push(`locked${facts.lockReason ? ` (${facts.lockReason})` : ''}`);
+        if (facts.claimed) bits.push('claimed by a chat record');
+        add('git', 'info', facts.path,
+          `leftover Claude Code agent worktree (${w.branch}): ${bits.join(', ')} — `
+          + (facts.removable ? 'removable' : `not removable (${facts.reasons.join('; ')})`));
+      }
+    }
   }
 
   // ---------- 5. auto-files ----------
@@ -629,6 +950,7 @@ export async function runAudit({
         ? { status: canonicalSel.status, budget: canonicalSel.budgetBytes, current: canonicalSel.currentBytes }
         : null,
       freshness,
+      agentWorktrees,
       exitCode: count('issue') > 0 ? 1 : 0,
     },
   };

package/template/_claude/scripts/merge-mode.mjs

@@ -142,4 +142,25 @@ function mergeModeFor(root, repo, deps = {}) {
   return parseForgeRemote(String(res.stdout || '').trim(), { hosts: forgeHosts(ws) }) ? 'forge' : null;
 }
 
-export { WORKSPACE_REPO, repoDirFor, readWorkspace, parseForgeRemote, forgeHosts, perRepoForge, forgeConfigForRepo, mergeModeFor };
+/**
+ * Resolve who approves a task repo's merge (gh:202): "ask" — the default —
+ * /complete-work presents the summary and asks once before merging;
+ * "operator" — the skill stops after the PRs are created and their checks
+ * read, merging only when the operator says so in a later turn (or never:
+ * a merge done in the forge UI is detected by --merge's re-run). The
+ * setting is per repo — repos.{repo}.mergeApproval, or
+ * workspace.mergeApproval for the workspace repo — addressed exactly the
+ * way `merge` is (mergeModeFor above). An unrecognized value throws: a
+ * typo silently read as "ask" would change who merges without anyone
+ * noticing.
+ */
+function mergeApprovalFor(root, repo) {
+  const ws = readWorkspace(resolve(root));
+  const setting = repo === WORKSPACE_REPO ? 'workspace.mergeApproval' : `repos.${repo}.mergeApproval`;
+  const value = repo === WORKSPACE_REPO ? ws?.workspace?.mergeApproval : ws?.repos?.[repo]?.mergeApproval;
+  if (value === undefined || value === null) return 'ask';
+  if (value === 'ask' || value === 'operator') return value;
+  throw new Error(`unknown ${setting} "${value}" — expected "ask" or "operator"`);
+}
+
+export { WORKSPACE_REPO, repoDirFor, readWorkspace, parseForgeRemote, forgeHosts, perRepoForge, forgeConfigForRepo, mergeModeFor, mergeApprovalFor };