@tt-a1i/openpi 0.1.0

package/extensions/shared/subagent-roles.ts

@@ -0,0 +1,22 @@
+/** Built-in subagent role names shared by configuration and spawning. */
+export const SUBAGENT_ROLE_NAMES = [
+  "explorer",
+  "implementer",
+  "reviewer",
+  "advisor",
+] as const;
+
+export type SubagentRoleName = (typeof SUBAGENT_ROLE_NAMES)[number];
+
+export interface SubagentRoleModel {
+  readonly provider: string;
+  readonly model: string;
+}
+
+export type SubagentRoleModels = Partial<
+  Record<SubagentRoleName, SubagentRoleModel>
+>;
+
+export function isSubagentRoleName(value: string): value is SubagentRoleName {
+  return SUBAGENT_ROLE_NAMES.includes(value as SubagentRoleName);
+}

package/extensions/shared/terminal-text.ts

@@ -0,0 +1,38 @@
+// OSC may end in BEL or ST. DCS/SOS/PM/APC end only in ST; treating BEL as
+// their terminator would expose the rest of a still-hidden payload. Both
+// patterns consume an unterminated string through the bounded input's end.
+// eslint-disable-next-line no-control-regex
+const OSC_PATTERN =
+  /(?:\u001b\]|\u009d)(?:[^\u0007\u001b\u009c]|\u001b(?!\\))*(?:\u0007|\u001b\\|\u009c|$)/g;
+// eslint-disable-next-line no-control-regex
+const ST_STRING_PATTERN =
+  /(?:\u001b[PX^_]|[\u0090\u0098\u009e\u009f])(?:[^\u001b\u009c]|\u001b(?!\\))*(?:\u001b\\|\u009c|$)/g;
+// eslint-disable-next-line no-control-regex
+const CSI_PATTERN = /(?:\u001b\[|\u009b)[0-?]*[ -/]*[@-~]/g;
+// Remaining two-byte/charset escape forms (for example ESC ( 0).
+// eslint-disable-next-line no-control-regex
+const ESCAPE_PATTERN = /\u001b(?:[()][0-2A-Z]|[ -/]*[@-~])/g;
+// Invisible Unicode format controls can reorder or disguise untrusted text.
+// Keep only ZWNJ/ZWJ (U+200C/U+200D), which carry legitimate shaping and emoji
+// semantics; variation selectors are marks rather than Cf and remain intact.
+const UNSAFE_FORMAT_PATTERN = /(?![\u200c\u200d])\p{Cf}/gu;
+// eslint-disable-next-line no-control-regex
+const TERMINAL_CONTROL_PATTERN =
+  /[\u0000-\u001f\u007f-\u009f]|(?:(?![\u200c\u200d])\p{Cf})/u;
+
+/** Strip terminal control sequences and direction-spoofing format controls. */
+export function sanitizeTerminalText(text: string) {
+  return text
+    .replace(OSC_PATTERN, "")
+    .replace(ST_STRING_PATTERN, "")
+    .replace(CSI_PATTERN, "")
+    .replace(ESCAPE_PATTERN, "")
+    .replace(UNSAFE_FORMAT_PATTERN, "")
+    .replaceAll("\t", "  ")
+    .replace(/[\u0000-\u0008\u000b-\u001f\u007f-\u009f]/g, "");
+}
+
+/** Reject raw terminal or direction-spoofing controls in display patterns. */
+export function hasTerminalControls(text: string) {
+  return TERMINAL_CONTROL_PATTERN.test(text);
+}

package/extensions/shared/tool-call-timeout.ts

@@ -0,0 +1,104 @@
+import type { ToolDefinition } from "@earendil-works/pi-coding-agent";
+
+export const CHILD_TOOL_CALL_TIMEOUT_MS = 3 * 60 * 1_000;
+
+interface ToolRegistry {
+  getAllTools(): Array<{ name: string }>;
+  getToolDefinition(name: string): ToolDefinition | undefined;
+}
+
+function formatTimeout(timeoutMs: number) {
+  if (timeoutMs % 60_000 === 0) {
+    const minutes = timeoutMs / 60_000;
+    return `${minutes} minute${minutes === 1 ? "" : "s"}`;
+  }
+  if (timeoutMs % 1_000 === 0) {
+    const seconds = timeoutMs / 1_000;
+    return `${seconds} second${seconds === 1 ? "" : "s"}`;
+  }
+  return `${timeoutMs} ms`;
+}
+
+export class ToolCallTimeoutError extends Error {
+  constructor(toolName: string, timeoutMs: number) {
+    super(
+      `Tool call "${toolName}" timed out after ${formatTimeout(timeoutMs)}.`,
+    );
+    this.name = "ToolCallTimeoutError";
+  }
+}
+
+export async function runWithToolCallTimeout<T>(
+  toolName: string,
+  timeoutMs: number,
+  signal: AbortSignal | undefined,
+  execute: (signal: AbortSignal) => Promise<T>,
+) {
+  const timeoutController = new AbortController();
+  const executionSignal = signal
+    ? AbortSignal.any([signal, timeoutController.signal])
+    : timeoutController.signal;
+  const timeoutError = new ToolCallTimeoutError(toolName, timeoutMs);
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const timeout = new Promise<never>((_resolve, reject) => {
+    timer = setTimeout(() => {
+      reject(timeoutError);
+      timeoutController.abort(timeoutError);
+    }, timeoutMs);
+  });
+
+  let removeAbortListener: (() => void) | undefined;
+  const aborted = new Promise<never>((_resolve, reject) => {
+    if (!signal) return;
+    const onAbort = () => {
+      reject(
+        signal.reason instanceof Error
+          ? signal.reason
+          : new Error(`Tool call "${toolName}" was aborted.`),
+      );
+    };
+    if (signal.aborted) {
+      onAbort();
+      return;
+    }
+    signal.addEventListener("abort", onAbort, { once: true });
+    removeAbortListener = () => signal.removeEventListener("abort", onAbort);
+  });
+
+  try {
+    return await Promise.race([execute(executionSignal), timeout, aborted]);
+  } finally {
+    if (timer) clearTimeout(timer);
+    removeAbortListener?.();
+  }
+}
+
+/**
+ * Wrap every currently registered child tool with an independent execution
+ * timeout. Calling apply() again is safe and picks up tools registered later.
+ */
+export function createToolCallTimeoutGuard(
+  timeoutMs = CHILD_TOOL_CALL_TIMEOUT_MS,
+) {
+  const wrapped = new WeakSet<ToolDefinition>();
+
+  const wrap = (definition: ToolDefinition) => {
+    if (wrapped.has(definition)) return;
+    wrapped.add(definition);
+
+    const execute = definition.execute;
+    definition.execute = async (toolCallId, params, signal, onUpdate, ctx) =>
+      runWithToolCallTimeout(definition.name, timeoutMs, signal, (signal) =>
+        execute.call(definition, toolCallId, params, signal, onUpdate, ctx),
+      );
+  };
+
+  return {
+    apply(session: ToolRegistry) {
+      for (const { name } of session.getAllTools()) {
+        const definition = session.getToolDefinition(name);
+        if (definition) wrap(definition);
+      }
+    },
+  };
+}

package/extensions/shared/worktree.ts

@@ -0,0 +1,526 @@
+/**
+ * Git worktree isolation for child agents.
+ *
+ * Parallel children that share one working copy share a git index and a file
+ * tree: two agents editing the same file, or staging at the same time, silently
+ * clobber each other. A worktree gives each child its own checkout on its own
+ * branch, so their edits are separable and the parent decides what to merge.
+ *
+ * Design decisions, each forced by measured git behavior:
+ *
+ * - **Worktrees live under `.git/pi-worktrees/`,** not in the project tree.
+ *   Anything inside the working copy shows up as an untracked entry in the
+ *   parent's `git status` (verified: `?? .pi/`), which would corrupt the very
+ *   signal a coding agent reads to see what it changed. `.git/` is already
+ *   outside every status walk, and `git worktree` is perfectly happy there.
+ *
+ * - **Trust is inherited by path.** Pi resolves project trust by walking
+ *   parents (`findNearestTrustEntry`), so a worktree under the repo inherits
+ *   the repo's trust decision and the child keeps its project skills and
+ *   AGENTS.md. A worktree in `/tmp` would resolve to "untrusted" and silently
+ *   strip those, which is why an out-of-repo location is not an option.
+ *
+ * - **`node_modules` is linked from the PARENT of the checkout, not into it.**
+ *   A fresh checkout has no dependencies, so an isolated child cannot build or
+ *   test its own work (verified: `ERR_MODULE_NOT_FOUND: Cannot find package
+ *   'effect'`). Node resolves `node_modules` by walking ancestor directories,
+ *   so a link at `.git/pi-worktrees/node_modules` serves every worktree under
+ *   it while git never sees the entry at all.
+ *
+ *   Putting it INSIDE the checkout was the original design and was wrong in a
+ *   way worth recording. A `.gitignore` line of `node_modules/` — with the
+ *   trailing slash almost every project uses — matches a directory only, not a
+ *   symlink. So the link showed as `?? node_modules` for the child's whole
+ *   life, `git add -A` committed it as a `120000` blob, teardown was then
+ *   permanently blocked ("contains modified or untracked files"), and merging
+ *   the child's branch REPLACED the parent's real `node_modules` directory
+ *   with a self-referential symlink — destroying the dependencies of the very
+ *   repo the session was working in.
+ *
+ * - **Teardown never uses `--force`.** Git refuses to remove a worktree with
+ *   modified or untracked files, and that refusal is exactly the policy we
+ *   want: an isolated child that produced nothing is reclaimed automatically,
+ *   and one that produced work keeps its directory and branch for the parent
+ *   to inspect. Committed work is safe either way — the branch outlives the
+ *   worktree — but uncommitted work would not be, so we let git veto.
+ */
+
+import { execFile } from "node:child_process";
+import { randomBytes } from "node:crypto";
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+/** A hung git call must not stall a spawn or a session teardown. */
+export const WORKTREE_GIT_TIMEOUT_MS = 10_000;
+
+/** Kept inside `.git/` so the parent's `git status` never sees these. */
+export const WORKTREE_DIR_SEGMENTS = ["pi-worktrees"] as const;
+
+/** Branch/directory prefix, so these are recognizable in `git worktree list`. */
+export const WORKTREE_NAME_PREFIX = "pi/";
+
+export interface Worktree {
+  /** Absolute path to the isolated checkout; use as the child's cwd. */
+  readonly path: string;
+  /** Branch created for this worktree. Survives teardown. */
+  readonly branch: string;
+  /**
+   * Commit the worktree was created at. "Did the child produce anything" is
+   * measured against THIS, never against the parent's HEAD: the parent moves
+   * (it can commit, or merge the child's own branch) while the child works, and
+   * a moving baseline makes a productive child look empty and get its branch
+   * deleted.
+   */
+  readonly baseSha?: string;
+}
+
+export interface WorktreeFailure {
+  readonly reason: string;
+}
+
+export type WorktreeResult =
+  | { readonly ok: true; readonly worktree: Worktree }
+  | { readonly ok: false; readonly reason: string };
+
+interface GitResult {
+  readonly code: number;
+  readonly stdout: string;
+  readonly stderr: string;
+  /** Spawn/timeout failure rather than a normal numeric Git exit status. */
+  readonly exception: boolean;
+}
+
+function runGit(
+  args: readonly string[],
+  cwd: string,
+  timeoutMs = WORKTREE_GIT_TIMEOUT_MS,
+): Promise<GitResult> {
+  if (timeoutMs <= 0) {
+    return Promise.resolve({
+      code: 1,
+      stdout: "",
+      stderr: "git operation deadline exceeded",
+      exception: true,
+    });
+  }
+  return new Promise((resolve) => {
+    execFile(
+      "git",
+      ["-c", "core.fsmonitor=false", ...args],
+      {
+        cwd,
+        encoding: "utf8",
+        timeout: Math.min(timeoutMs, WORKTREE_GIT_TIMEOUT_MS),
+      },
+      (error, stdout, stderr) => {
+        const code =
+          error && typeof (error as { code?: unknown }).code === "number"
+            ? (error as unknown as { code: number }).code
+            : error
+              ? 1
+              : 0;
+        resolve({
+          code,
+          stdout: stdout ?? "",
+          stderr: (stderr ?? "") || (error ? error.message : ""),
+          exception:
+            !!error && typeof (error as { code?: unknown }).code !== "number",
+        });
+      },
+    );
+  });
+}
+
+function firstLine(text: string) {
+  return text.trim().split("\n")[0]?.trim() ?? "";
+}
+
+/**
+ * Sanitize a caller-supplied label into one path/ref segment.
+ *
+ * The label reaches us from a model-authored tool argument, so it is untrusted
+ * input on a path and a ref: `..`, a slash, or a leading dash would let it
+ * escape `.git/pi-worktrees/` or be read by git as an option. Only a
+ * conservative character set survives, and the result is never empty.
+ *
+ * The result is NOT unique and must never be the only thing distinguishing two
+ * worktrees. It cannot be: a non-Latin label ("中文标签", "🚀") has no surviving
+ * characters and collapses to the fallback, and two labels sharing a long
+ * prefix collide once `maxLength` cuts them. Uniqueness comes from the random
+ * suffix in `createWorktree`.
+ */
+export function worktreeSlug(label: string, fallback: string, maxLength = 32) {
+  const slug = label
+    .toLowerCase()
+    .replace(/[^a-z0-9._-]+/g, "-")
+    // `a..b` sanitizes fine as a path but is not a legal ref: git rejects any
+    // name containing `..`, which would fail the spawn rather than escape it.
+    .replace(/\.{2,}/g, ".")
+    .replace(/^[-.]+|[-.]+$/g, "")
+    .slice(0, maxLength)
+    .replace(/[-.]+$/g, "");
+  return slug || fallback;
+}
+
+/**
+ * Common git dir for `cwd`, or undefined when it is not a repository.
+ *
+ * `--git-common-dir` rather than `--git-dir`: inside an existing worktree the
+ * latter points at `.git/worktrees/<name>`, and nesting new worktrees there
+ * would bury them. The common dir is the same `.git` for the main checkout and
+ * every worktree of it, so isolation composes.
+ */
+export async function resolveGitCommonDir(cwd: string) {
+  const result = await runGit(["rev-parse", "--git-common-dir"], cwd);
+  if (result.code !== 0) return undefined;
+  const value = firstLine(result.stdout);
+  if (!value) return undefined;
+  return path.resolve(cwd, value);
+}
+
+/**
+ * Create an isolated worktree for `cwd`'s repository, branched from HEAD.
+ *
+ * Never throws and never falls back silently: a non-repository, a git failure,
+ * or a name collision comes back as `{ ok: false, reason }` so the caller can
+ * decide between reporting it and continuing in the shared directory.
+ */
+export async function createWorktree(options: {
+  cwd: string;
+  /** Human-ish label (agent title); sanitized into the branch/dir name. */
+  label: string;
+  /** Disambiguator appended to the slug; must be unique per live worktree. */
+  id: string;
+  /** Link the repo's node_modules in, so the child can build and test. */
+  linkNodeModules?: boolean;
+}): Promise<WorktreeResult> {
+  const gitDir = await resolveGitCommonDir(options.cwd);
+  if (!gitDir) {
+    return { ok: false, reason: `not a git repository: ${options.cwd}` };
+  }
+
+  /*
+   * The random suffix is what makes the name unique, and it is not optional.
+   * A committed branch deliberately OUTLIVES its worktree, so any name derived
+   * only from label+id is already taken the next time the same agent title
+   * runs — `git worktree add` then fails with "a branch named … already
+   * exists" and isolation, which is requested rather than best-effort, turns
+   * into a hard spawn failure that tells the model to go run unisolated.
+   * Deriving it from a label cannot work: every non-Latin title slugs to the
+   * same fallback.
+   */
+  const name = [
+    worktreeSlug(options.label, "agent"),
+    worktreeSlug(options.id, "0", 24),
+    randomBytes(3).toString("hex"),
+  ].join("-");
+  const worktreePath = path.join(gitDir, ...WORKTREE_DIR_SEGMENTS, name);
+  const branch = `${WORKTREE_NAME_PREFIX}${name}`;
+
+  // Read before creating: this is the baseline teardown measures against.
+  const base = await runGit(["rev-parse", "HEAD"], options.cwd);
+  const baseSha = base.code === 0 ? firstLine(base.stdout) : undefined;
+
+  const added = await runGit(
+    ["worktree", "add", "--quiet", "-b", branch, worktreePath, "HEAD"],
+    options.cwd,
+  );
+  if (added.code !== 0) {
+    return {
+      ok: false,
+      reason: firstLine(added.stderr) || "git worktree add failed",
+    };
+  }
+
+  if (options.linkNodeModules !== false)
+    linkNodeModules(options.cwd, worktreePath);
+
+  return {
+    ok: true,
+    worktree: { path: worktreePath, branch, ...(baseSha ? { baseSha } : {}) },
+  };
+}
+
+/**
+ * Link the repository's node_modules NEXT TO the worktrees, best effort.
+ *
+ * The link lives at `.git/pi-worktrees/node_modules`, one level above every
+ * checkout, because Node resolves bare imports by walking ancestor
+ * directories: a child at `.git/pi-worktrees/impl-1` finds it, and git never
+ * sees an entry inside the tree it reports on. See the header for what putting
+ * it inside the checkout actually did.
+ *
+ * The target is absolute so it resolves regardless of depth, and one link
+ * serves every worktree, so this is idempotent across concurrent creates. A
+ * failure here is not fatal — the child just cannot run builds — so it is
+ * swallowed rather than turned into a spawn failure.
+ */
+function linkNodeModules(repoCwd: string, worktreePath: string) {
+  const source = path.join(repoCwd, "node_modules");
+  const target = path.join(path.dirname(worktreePath), "node_modules");
+  try {
+    if (!fs.existsSync(source)) return;
+    if (
+      fs.existsSync(target) ||
+      fs.lstatSync(target, { throwIfNoEntry: false })
+    )
+      return;
+    fs.symlinkSync(source, target, "junction");
+  } catch {
+    // The worktree is still usable for reading and editing without deps.
+  }
+}
+
+export interface WorktreeCleanup {
+  /** True when the worktree directory is gone. */
+  readonly removed: boolean;
+  /** True when the branch was deleted too, because it held no commits. */
+  readonly branchDeleted: boolean;
+  /** Why it was kept, or why a final cleanup step failed. */
+  readonly reason?: string;
+  /** Branch observed in the checkout, or the branch created for it. */
+  readonly branch: string;
+  /** Creation-time baseline used to judge whether the child committed work. */
+  readonly baseSha?: string;
+  /** HEAD observed before cleanup. */
+  readonly headSha?: string;
+  /** Commits reachable from HEAD but not from baseSha. */
+  readonly commits?: number;
+  readonly detached: boolean;
+  readonly dirty?: boolean;
+  readonly untracked?: boolean;
+  readonly ignored?: boolean;
+}
+
+export interface WorktreeCommitCount {
+  readonly ok: boolean;
+  readonly count?: number;
+  readonly reason?: string;
+}
+
+/**
+ * Reclaim a worktree, keeping anything the child actually produced.
+ *
+ * Deliberately no `--force`: git's own refusal on a dirty tree is the policy
+ * we want. A child that changed nothing costs nothing to discard; a child with
+ * uncommitted work keeps its directory so the parent can look at it. The
+ * branch is deleted only when it holds no commits, so a child that committed
+ * always leaves something to merge, and a child that did nothing leaves no
+ * litter behind.
+ *
+ * "Produced nothing" is measured against the worktree's OWN head and its
+ * creation-time base, never against the parent's current HEAD. Both matter:
+ * a child is free to `checkout -b` and commit somewhere else, and the parent
+ * is free to move on (or merge the child's branch) before teardown runs.
+ * Getting either wrong deletes a branch that holds real work.
+ */
+export async function reclaimWorktree(
+  repoCwd: string,
+  worktree: Worktree,
+  options: { timeoutMs?: number } = {},
+): Promise<WorktreeCleanup> {
+  const deadline = Date.now() + (options.timeoutMs ?? WORKTREE_GIT_TIMEOUT_MS);
+  const run = (args: readonly string[]) =>
+    runGit(args, repoCwd, deadline - Date.now());
+  const base = {
+    removed: false,
+    branchDeleted: false,
+    branch: worktree.branch,
+    ...(worktree.baseSha ? { baseSha: worktree.baseSha } : {}),
+    detached: false,
+  };
+  const preserve = (
+    reason: string,
+    observed: Partial<WorktreeCleanup> = {},
+  ): WorktreeCleanup => ({ ...base, ...observed, reason });
+
+  // Inspect everything that automatic removal could destroy before asking Git
+  // to remove anything. An unknown state is productive until proven otherwise.
+  const head = await run([
+    "-C",
+    worktree.path,
+    "rev-parse",
+    "--verify",
+    "HEAD",
+  ]);
+  const headSha = head.code === 0 ? firstLine(head.stdout) : "";
+  if (!headSha) {
+    return preserve(
+      firstLine(head.stderr) || "could not inspect worktree HEAD",
+    );
+  }
+
+  const symbolic = await run([
+    "-C",
+    worktree.path,
+    "symbolic-ref",
+    "--quiet",
+    "--short",
+    "HEAD",
+  ]);
+  if (symbolic.code !== 0 && (symbolic.code !== 1 || symbolic.exception)) {
+    return preserve(
+      firstLine(symbolic.stderr) || "could not inspect worktree branch",
+      { headSha },
+    );
+  }
+  const headBranch = symbolic.code === 0 ? firstLine(symbolic.stdout) : "";
+  const detached = !headBranch;
+  const branch = headBranch || worktree.branch;
+  const observed = { branch, headSha, detached };
+
+  const status = await run([
+    "-C",
+    worktree.path,
+    "status",
+    "--porcelain=v1",
+    "--untracked-files=all",
+  ]);
+  if (status.code !== 0) {
+    return preserve(
+      firstLine(status.stderr) || "could not inspect worktree status",
+      observed,
+    );
+  }
+  const statusLines = status.stdout.split("\n").filter(Boolean);
+  const untracked = statusLines.some((line) => line.startsWith("??"));
+  const dirty = statusLines.length > 0;
+
+  const ignoredFiles = await run([
+    "-C",
+    worktree.path,
+    "ls-files",
+    "--others",
+    "--ignored",
+    "--exclude-standard",
+    "-z",
+  ]);
+  if (ignoredFiles.code !== 0) {
+    return preserve(
+      firstLine(ignoredFiles.stderr) || "could not inspect ignored files",
+      { ...observed, dirty, untracked },
+    );
+  }
+  const ignored = ignoredFiles.stdout.length > 0;
+
+  if (!worktree.baseSha) {
+    return preserve("worktree creation baseline is unknown", {
+      ...observed,
+      dirty,
+      untracked,
+      ignored,
+    });
+  }
+  const mergeBase = await run(["merge-base", worktree.baseSha, headSha]);
+  if (mergeBase.code !== 0) {
+    return preserve(
+      firstLine(mergeBase.stderr) || "could not compare HEAD with its baseline",
+      { ...observed, dirty, untracked, ignored },
+    );
+  }
+  if (firstLine(mergeBase.stdout) !== worktree.baseSha) {
+    return preserve("worktree HEAD no longer descends from its baseline", {
+      ...observed,
+      dirty,
+      untracked,
+      ignored,
+    });
+  }
+  const commitCount = await worktreeCommitCount(
+    repoCwd,
+    headSha,
+    worktree.baseSha,
+    deadline - Date.now(),
+  );
+  if (!commitCount.ok || commitCount.count === undefined) {
+    return preserve(
+      commitCount.reason ?? "could not inspect worktree commits",
+      {
+        ...observed,
+        dirty,
+        untracked,
+        ignored,
+      },
+    );
+  }
+  const inspected = {
+    ...observed,
+    commits: commitCount.count,
+    dirty,
+    untracked,
+    ignored,
+  };
+
+  if (dirty || ignored) {
+    const contents = [
+      dirty ? "modified or untracked files" : undefined,
+      ignored ? "ignored files" : undefined,
+    ].filter(Boolean);
+    return preserve(`worktree contains ${contents.join(" and ")}`, inspected);
+  }
+  // Detachment is itself an intentional checkout-state change, and productive
+  // detached commits have no surviving ref. Preserve all detached checkouts
+  // rather than guessing that a clean one is disposable.
+  if (detached) {
+    return preserve(
+      commitCount.count > 0
+        ? "detached HEAD contains commits not reachable from its base"
+        : "worktree HEAD is detached",
+      {
+        ...inspected,
+        branch: worktree.branch,
+      },
+    );
+  }
+
+  const removed = await run(["worktree", "remove", worktree.path]);
+  if (removed.code !== 0) {
+    return preserve(
+      firstLine(removed.stderr) || "git declined to remove the worktree",
+      inspected,
+    );
+  }
+  if (commitCount.count > 0 || branch !== worktree.branch) {
+    return { ...base, ...inspected, removed: true };
+  }
+
+  // Only delete the branch this module created, after proving it is clean and
+  // has no commits beyond its immutable creation baseline.
+  const deleted = await run(["branch", "-D", worktree.branch]);
+  return {
+    ...base,
+    ...inspected,
+    removed: true,
+    branchDeleted: deleted.code === 0,
+    ...(deleted.code === 0
+      ? {}
+      : {
+          reason: firstLine(deleted.stderr) || "could not delete empty branch",
+        }),
+  };
+}
+
+/** Commits on `head` that the immutable creation `base` does not have. */
+export async function worktreeCommitCount(
+  repoCwd: string,
+  head: string,
+  base: string,
+  timeoutMs = WORKTREE_GIT_TIMEOUT_MS,
+): Promise<WorktreeCommitCount> {
+  const result = await runGit(
+    ["rev-list", "--count", `${base}..${head}`],
+    repoCwd,
+    timeoutMs,
+  );
+  if (result.code !== 0) {
+    return {
+      ok: false,
+      reason: firstLine(result.stderr) || "git rev-list failed",
+    };
+  }
+  const count = Number.parseInt(firstLine(result.stdout), 10);
+  if (!Number.isFinite(count) || count < 0) {
+    return { ok: false, reason: "git rev-list returned an invalid count" };
+  }
+  return { ok: true, count };
+}