@mgiles/perk 1.0.1 → 2.0.0

package/extension/substrate/command.ts

@@ -0,0 +1,25 @@
+// The single chokepoint that gives every perk command a uniform, immediate "running…"
+// acknowledgement at entry. pi does not echo the invoked command and handlers only report() at the
+// end, so without this a command's async work (cold-door subprocess calls, GitHub round-trips) is
+// dead air between Enter and completion. registerPerkCommand wraps the handler to emit one transient
+// entry toast through the headless-safe report() seam (no cleanup state, headless-fail-safe for
+// free) before awaiting the original handler. The toast fires synchronously before the first await,
+// so it lands before any cold-door work, sendUserMessage drive, or gate transition; the wrapper does
+// not try/catch, so errors propagate exactly as before.
+
+import type { ExtensionAPI, RegisteredCommand } from "@earendil-works/pi-coding-agent";
+import { report } from "../surfaces/report.ts";
+
+export function registerPerkCommand(
+  pi: ExtensionAPI,
+  name: string,
+  options: Omit<RegisteredCommand, "name" | "sourceInfo">,
+): void {
+  pi.registerCommand(name, {
+    ...options,
+    handler: async (args, ctx) => {
+      report(ctx, name, "info", "running…");
+      await options.handler(args, ctx);
+    },
+  });
+}

package/extension/substrate/config.ts

@@ -1,23 +1,27 @@
 // The minimal TS config port. Mirrors `perk/substrate/config.py`'s overlay: read
-// `.pi/perk.toml` (committed) overlaid by `.pi/perk.local.toml` (gitignored, local wins). The only
+// `.perk/config.toml` (committed) overlaid by `.perk/local.toml` (gitignored, local wins). The only
 // setting consumed today is an optional `[workflow]` plan-authoring addendum, appended into the
 // `perk:plan-context` injection (extension/factories/planMode.ts) when present.
 //
 // Deliberately dependency-free: rather than pull a runtime TOML dependency into the published
-// extension for a single optional string, this reads the narrow TOML subset perk actually uses —
-// `[section]` headers + `key = "basic"` / `key = """multiline"""` string values + `#` comments.
+// extension, this reads the narrow TOML subset perk actually uses — `[section]` headers +
+// `[[name]]` array-of-tables + `key = "basic"` / `key = """multiline"""` strings + native
+// booleans/numbers + `#` comments.
 // Read-only, LBYL: a missing/unreadable file is `{}`; anything outside the subset is ignored.
 // Dynamic `resources_discover` skill/prompt contribution is a flagged follow-up, not built here.
 
 import { existsSync, readFileSync } from "node:fs";
-import { join } from "node:path";
 import { parseUserBindings, type SkillBinding } from "./bindings.ts";
+import { configFile, localConfigFile } from "./paths.ts";
 
-const CONFIG_FILENAME = "perk.toml";
-const LOCAL_CONFIG_FILENAME = "perk.local.toml";
+/**
+ * A TOML scalar the subset parser reads: quoted strings plus native booleans and numbers.
+ * Anything else (dates, arrays, inline tables) is still deliberately ignored.
+ */
+export type TomlScalar = string | boolean | number;
 
 /**
- * One configured CI check (a `[[ci]]` array-of-tables row). `name`/`command` are required
+ * One configured CI check (a `[[ci.checks]]` array-of-tables row). `name`/`command` are required
  * non-blank strings; an optional `glob` (a single comma-separated pattern string, e.g.
  * `"*.ts,*.tsx"`) declares which changed files the check is relevant to — the read-only CI
  * executor skips it on the run-all path when no changed file (vs trunk) matches.
@@ -32,18 +36,26 @@ export interface PerkConfig {
   /** Optional project-supplied plan-authoring addendum (`[workflow] plan_authoring = "..."`). */
   planAuthoring?: string;
   /**
-   * The `[[ci]]` checks (an ordered array-of-tables, each row name/command/optional glob); the
-   * read-only CI executor consumes it. Always-present ordered array (mirror of
-   * `bindings`/`providers`); absent/empty ⇒ `[]`.
+   * The `[ci]` verification namespace. `checks` is the `[[ci.checks]]` ordered array-of-tables
+   * (each row name/command/optional glob) the read-only CI executor consumes; absent/empty ⇒ `[]`.
+   * `trusted` (`[ci] trusted = true`, a native boolean) declares those project-supplied checks
+   * trusted, so the executor runs them WITHOUT a per-session confirm on every surface, including
+   * headless (it overrides the fail-closed refuse). Absent/`false`/non-boolean ⇒ untrusted
+   * (confirm with UI; refuse headless). Always present; defaults `{trusted: false, checks: []}`.
    */
-  ci: CiCheck[];
+  ci: { trusted: boolean; checks: CiCheck[] };
   /**
-   * The agent-keyed `[subagents]` table: a per-agent model override for each perk-owned
-   * project agent (`pr-reviewer`, `review-classifier`, `objective-explorer`). Each configured
+   * The agent-keyed `[models.subagents]` table: a per-agent model override for each perk-owned
+   * project agent (`pr-reviewer`, `review-classifier`, `objective-explorer`, `conflict-resolver`,
+   * `learn-analyst`, `adversarial-reviewer`). Each configured
    * value is injected as a per-call inline `model` override on that agent's `subagent` spawn; when
    * a key is absent the agent's frontmatter `model` (in `.pi/agents/<name>.md`) is the default.
    * (`subagents.agentOverrides` does NOT reach project agents — `pi-subagents`'
    * `applyBuiltinOverrides` applies only to builtins — so this inline override is the mechanism.)
+   * A value may carry a `:thinking` suffix (`"anthropic/claude-sonnet-4-5:high"`) or be the
+   * `"inherit"` sentinel (child inherits the parent session's model) — both resolved by
+   * pi-subagents on the inline override (the last-colon segment counts as thinking only when it
+   * is a pi level, so ollama-style tags stay part of the model id).
    * Always-present object; absent keys omitted (mirror of `providers`).
    */
   subagents: {
@@ -51,11 +63,14 @@ export interface PerkConfig {
     "review-classifier"?: string;
     "objective-explorer"?: string;
     "conflict-resolver"?: string;
+    "learn-analyst"?: string;
+    "adversarial-reviewer"?: string;
   };
   /**
-   * Optional `[objective] compact_threshold` — the context-usage fraction (0,1] that triggers
-   * threshold compaction while an objective is active. Because the TOML subset reads only
-   * string values, it must be written as a quoted string (e.g. `compact_threshold = "0.8"`).
+   * Optional `[compaction] objective_threshold` — the context-usage fraction (0,1] that triggers
+   * threshold compaction while an objective is active. A native TOML float (e.g.
+   * `objective_threshold = 0.8`); string/out-of-range values are ignored. The Python plane
+   * deliberately ignores this key (it converges the rest of `[compaction]` into settings).
    */
   objectiveCompactThreshold?: number;
   /** The `[[bindings]]` user overlay, resolved against shipped defaults downstream. */
@@ -65,28 +80,25 @@ export interface PerkConfig {
    * `shared/providers.yaml`. Absent keys mean “use the seam default”; resolution against the
    * supported set is a downstream concern.
    */
-  providers: { plan?: string; todo?: string; askuser?: string; footer?: string; web?: string };
-  /**
-   * The `[trust]` per-repo trust table. `trust.ci === true` (written `ci = "true"` — the subset
-   * parser reads strings only) declares the project's `[ci]` checks trusted, so the read-only CI
-   * executor runs them WITHOUT a per-session confirm on every surface, including headless
-   * (it overrides the fail-closed refuse). Absent/"false" ⇒ unchanged (confirm with UI; refuse
-   * headless). Always-present object; absent keys omitted (mirror of `providers`). The table may
-   * grow further trust keys later.
-   */
-  trust: { ci?: boolean };
+  providers: {
+    plan?: string;
+    todo?: string;
+    askuser?: string;
+    footer?: string;
+    web?: string;
+  };
 }
 
-/** A nested string table: `{ section: { key: value } }` (the only shape perk reads today). */
-type StringTable = Record<string, Record<string, string>>;
+/** A nested scalar table: `{ section: { key: scalar } }` (dotted section names kept literal). */
+type ScalarTable = Record<string, Record<string, TomlScalar>>;
 
 /**
- * The narrow TOML subset perk reads: `[section]`/top-level string tables plus `[[name]]`
- * array-of-tables (each row a string table). Mirrors `tomllib`'s shape for the keys perk uses.
+ * The narrow TOML subset perk reads: `[section]`/top-level scalar tables plus `[[name]]`
+ * array-of-tables (each row a scalar table). Mirrors `tomllib`'s shape for the keys perk uses.
  */
 interface TomlSubset {
-  tables: StringTable;
-  arrays: Record<string, Array<Record<string, string>>>;
+  tables: ScalarTable;
+  arrays: Record<string, Array<Record<string, TomlScalar>>>;
 }
 
 function unescapeBasic(raw: string): string {
@@ -99,16 +111,17 @@ function unescapeBasic(raw: string): string {
 
 /**
  * Parse the narrow TOML subset perk consumes. Returns `{ tables, arrays }`: `tables` is a
- * `{ section: { key: stringValue } }` map (top-level keys under the `""` section); `arrays` is a
- * `{ name: [{ key: stringValue }, ...] }` map fed by `[[name]]` array-of-tables. Non-string values
- * and unknown syntax are skipped — this is intentionally NOT a full TOML parser.
+ * `{ section: { key: scalar } }` map (top-level keys under the `""` section); `arrays` is a
+ * `{ name: [{ key: scalar }, ...] }` map fed by `[[name]]` array-of-tables. Scalars are quoted
+ * strings, native `true`/`false` booleans, and numeric literals; anything else is skipped —
+ * this is intentionally NOT a full TOML parser.
  */
 export function parseTomlSubset(text: string): TomlSubset {
-  const root: Record<string, string> = {};
-  const tables: StringTable = { "": root };
-  const arrays: Record<string, Array<Record<string, string>>> = {};
+  const root: Record<string, TomlScalar> = {};
+  const tables: ScalarTable = { "": root };
+  const arrays: Record<string, Array<Record<string, TomlScalar>>> = {};
   // The current write target for `key = value` lines (a section table or an array-of-tables row).
-  let dest: Record<string, string> = root;
+  let dest: Record<string, TomlScalar> = root;
   const lines = text.split(/\r?\n/);
   for (let i = 0; i < lines.length; i++) {
     const line = (lines[i] ?? "").trim();
@@ -118,7 +131,7 @@ export function parseTomlSubset(text: string): TomlSubset {
     const arrayHeader = line.match(/^\[\[([^\]]+)\]\]$/);
     if (arrayHeader) {
       const name = (arrayHeader[1] ?? "").trim();
-      const row: Record<string, string> = {};
+      const row: Record<string, TomlScalar> = {};
       let rows = arrays[name];
       if (!rows) {
         rows = [];
@@ -174,8 +187,21 @@ export function parseTomlSubset(text: string): TomlSubset {
     const basic = value.match(/^"((?:[^"\\]|\\.)*)"/);
     if (basic) {
       dest[key] = unescapeBasic(basic[1] ?? "");
+      continue;
+    }
+
+    // Unquoted scalar: strip an inline `#` comment, then read native booleans and numbers.
+    const hash = value.indexOf("#");
+    const bare = (hash === -1 ? value : value.slice(0, hash)).trim();
+    if (bare === "true" || bare === "false") {
+      dest[key] = bare === "true";
+      continue;
     }
-    // Non-string scalars are intentionally ignored (perk reads only strings today).
+    if (/^[+-]?\d[\d_]*(\.[\d_]+)?([eE][+-]?\d+)?$/.test(bare)) {
+      const parsed = Number(bare.replace(/_/g, ""));
+      if (Number.isFinite(parsed)) dest[key] = parsed;
+    }
+    // Other value shapes (dates, arrays, inline tables) are intentionally ignored.
   }
   return { tables, arrays };
 }
@@ -200,49 +226,51 @@ function readTomlFile(path: string): TomlSubset {
  * replace as a whole array (mirror of perk/substrate/config.py's list-replaces-list overlay).
  */
 function overlay(base: TomlSubset, over: TomlSubset): TomlSubset {
-  const tables: StringTable = {};
+  const tables: ScalarTable = {};
   for (const [section, kv] of Object.entries(base.tables)) tables[section] = { ...kv };
   for (const [section, kv] of Object.entries(over.tables)) {
     tables[section] = { ...(tables[section] ?? {}), ...kv };
   }
-  const arrays: Record<string, Array<Record<string, string>>> = { ...base.arrays };
+  const arrays: Record<string, Array<Record<string, TomlScalar>>> = { ...base.arrays };
   for (const [name, rows] of Object.entries(over.arrays)) arrays[name] = rows;
   return { tables, arrays };
 }
 
-/** Load `.pi/perk.toml` overlaid by `.pi/perk.local.toml` from `cwd` (mirror of perk/substrate/config.py). */
+/** Load `.perk/config.toml` overlaid by `.perk/local.toml` from `cwd` (mirror of perk/substrate/config.py). */
 export function loadPerkConfig(cwd: string): PerkConfig {
-  const piDir = join(cwd, ".pi");
   let merged: TomlSubset = emptySubset();
-  for (const name of [CONFIG_FILENAME, LOCAL_CONFIG_FILENAME]) {
-    merged = overlay(merged, readTomlFile(join(piDir, name)));
+  for (const file of [configFile(cwd), localConfigFile(cwd)]) {
+    merged = overlay(merged, readTomlFile(file));
   }
 
   const planAuthoring = merged.tables.workflow?.plan_authoring;
-  const rawThreshold = merged.tables.objective?.compact_threshold;
-  const parsedThreshold = rawThreshold != null ? Number.parseFloat(rawThreshold) : Number.NaN;
+  // `[compaction] objective_threshold` is a native float in (0,1]; strings/out-of-range ignored.
+  const rawThreshold = merged.tables.compaction?.objective_threshold;
   const objectiveCompactThreshold =
-    Number.isFinite(parsedThreshold) && parsedThreshold > 0 && parsedThreshold <= 1
-      ? parsedThreshold
+    typeof rawThreshold === "number" && rawThreshold > 0 && rawThreshold <= 1
+      ? rawThreshold
       : undefined;
   return {
     planAuthoring:
       typeof planAuthoring === "string" && planAuthoring.trim() ? planAuthoring : undefined,
-    ci: parseCiChecks(merged.arrays.ci ?? []),
-    subagents: parseSubagentsSelection(merged.tables.subagents),
+    ci: {
+      trusted: merged.tables.ci?.trusted === true,
+      checks: parseCiChecks(merged.arrays["ci.checks"] ?? []),
+    },
+    subagents: parseSubagentsSelection(merged.tables["models.subagents"]),
     objectiveCompactThreshold,
     bindings: parseUserBindings(merged.arrays.bindings ?? []),
     providers: parseProvidersSelection(merged.tables.providers),
-    trust: parseTrustSelection(merged.tables.trust),
   };
 }
 
 /**
- * Read the `[[ci]]` array-of-tables into an ordered `CiCheck[]`. A row is kept only when both
- * `name` and `command` are non-blank strings; `glob` is kept only when a non-blank string. Declared
- * order is preserved; ill-typed rows are silently dropped (mirror of `parseProvidersSelection`).
+ * Read the `[[ci.checks]]` array-of-tables into an ordered `CiCheck[]`. A row is kept only when
+ * both `name` and `command` are non-blank strings; `glob` is kept only when a non-blank string.
+ * Declared order is preserved; ill-typed rows are silently dropped (mirror of
+ * `parseProvidersSelection`).
  */
-export function parseCiChecks(rows: Array<Record<string, string>>): CiCheck[] {
+export function parseCiChecks(rows: Array<Record<string, TomlScalar>>): CiCheck[] {
   const checks: CiCheck[] = [];
   for (const row of rows) {
     const name = row.name;
@@ -257,21 +285,23 @@ export function parseCiChecks(rows: Array<Record<string, string>>): CiCheck[] {
   return checks;
 }
 
-/** The perk-owned project agents configurable via the `[subagents]` table. */
+/** The perk-owned project agents configurable via the `[models.subagents]` table. */
 const SUBAGENT_KEYS = [
   "pr-reviewer",
   "review-classifier",
   "objective-explorer",
   "conflict-resolver",
+  "learn-analyst",
+  "adversarial-reviewer",
 ] as const;
 
 /**
- * Read the agent-keyed `[subagents]` table into a selection (string values only). For each known
- * agent key, the value is kept only when it is a non-blank string; absent/ill-typed/unknown keys
- * are omitted (mirror of `parseProvidersSelection`).
+ * Read the agent-keyed `[models.subagents]` table into a selection (string values only). For each
+ * known agent key, the value is kept only when it is a non-blank string; absent/ill-typed/unknown
+ * keys are omitted (mirror of `parseProvidersSelection`).
  */
 function parseSubagentsSelection(
-  table: Record<string, string> | undefined,
+  table: Record<string, TomlScalar> | undefined,
 ): PerkConfig["subagents"] {
   const selection: PerkConfig["subagents"] = {};
   for (const key of SUBAGENT_KEYS) {
@@ -281,16 +311,8 @@ function parseSubagentsSelection(
   return selection;
 }
 
-/** Read the `[trust]` table into a `{ci?}` selection. `ci` is true only for the string "true". */
-function parseTrustSelection(table: Record<string, string> | undefined): { ci?: boolean } {
-  const selection: { ci?: boolean } = {};
-  if (typeof table?.ci === "string" && table.ci.trim().toLowerCase() === "true")
-    selection.ci = true;
-  return selection;
-}
-
-/** Read the flat `[providers]` table into a `{plan?, todo?, askuser?, footer?, web?}` selection (string values only). */
-function parseProvidersSelection(table: Record<string, string> | undefined): {
+/** Read the flat `[providers]` table into a `{plan?, todo?, askuser?, footer?, web?}` selection (string values only). A retired `review` key is silently ignored (the TS fail-safe posture; the Python plane's tripwire is the loud surface). */
+function parseProvidersSelection(table: Record<string, TomlScalar> | undefined): {
   plan?: string;
   todo?: string;
   askuser?: string;
@@ -320,16 +342,16 @@ export const GITHUB_ISSUE_BACKEND_ID: IssueBackendId = "github";
 /**
  * The fail-safe TS mirror of the issue-backend selection.
  *
- * Reads ONLY committed `.pi/perk.toml` — deliberately not `loadPerkConfig`'s overlay, mirroring
+ * Reads ONLY committed `.perk/config.toml` — deliberately not `loadPerkConfig`'s overlay, mirroring
  * the Python committed-only read (the backend decides where canonical durable state is written;
- * a per-user `perk.local.toml` override would fragment the canonical store). Python
+ * a per-user `.perk/local.toml` override would fragment the canonical store). Python
  * (`perk/backends/issues.py::resolve_issue_backend_id`) is the AUTHORITATIVE validator and **raises** on
  * "linear"/unknown; this mirror is fail-safe (absence/unknown/any error → `"github"`) because
  * the TS plane only renders prompts — it never writes canonical issues.
  */
 export function resolveIssueBackendId(cwd: string): IssueBackendId {
   try {
-    const committed = readTomlFile(join(cwd, ".pi", CONFIG_FILENAME));
+    const committed = readTomlFile(configFile(cwd));
     const backend = committed.tables.issues?.backend;
     if (backend === "github" || backend === "linear") return backend;
     return GITHUB_ISSUE_BACKEND_ID;

package/extension/substrate/consoleCapture.ts

@@ -0,0 +1,90 @@
+// A small, pure swap of the global `console.error` so in-process chatter can be re-routed through a
+// TUI-safe sink while a background task runs. plannotator's browser code-review setup writes
+// progress straight to `process.stderr` via plain `console.error(...)` (fetching the PR, creating
+// the local checkout, …); those raw writes bypass pi's managed rendering and paint over the input
+// box. While the request is in flight we install a replacement that forwards each captured line to
+// an injected sink (perk routes it through `report()`), then restore the original.
+//
+// Restore is debounce-driven: setup emits a burst of lines then goes quiet once the browser is up,
+// so we restore after `quietMs` with no new line (self-adjusts to the variable several-second
+// setup, no fixed-duration guess). A `finally` backstop in the caller restores too; `restore()` is
+// idempotent and only reassigns `console.error` when our replacement is still installed, so an
+// accidental overlap with a newer patcher is safe rather than clobbering. The replacement is inert
+// once restored (a stale reference delegates to the original) and re-entrancy-safe (a console.error
+// from inside the sink delegates to the original instead of recursing).
+
+export type ConsoleErrorSink = (line: string) => void;
+
+export interface ConsoleErrorInterceptor {
+  restore(): void;
+}
+
+interface InterceptOptions {
+  quietMs: number;
+  /** Injectable purely so the unit test drives a deterministic fake clock. */
+  schedule?: (fn: () => void, ms: number) => unknown;
+  clearScheduled?: (handle: unknown) => void;
+}
+
+/**
+ * Swap `console.error` so captured lines reach `sink` (joined with a space for multi-arg calls,
+ * mirroring plannotator's occasional 2-arg `console.error`). Returns an interceptor whose
+ * `restore()` reinstates the original. The original is also restored automatically once no captured
+ * line has arrived for `quietMs`.
+ */
+export function interceptConsoleError(
+  sink: ConsoleErrorSink,
+  opts: InterceptOptions,
+): ConsoleErrorInterceptor {
+  const schedule = opts.schedule ?? ((fn, ms) => globalThis.setTimeout(fn, ms));
+  const clearScheduled =
+    opts.clearScheduled ??
+    ((handle) => globalThis.clearTimeout(handle as ReturnType<typeof setTimeout>));
+
+  const original = console.error;
+  let restored = false;
+  let active = false;
+  let handle: unknown;
+
+  const restore = (): void => {
+    if (handle !== undefined) {
+      clearScheduled(handle);
+      handle = undefined;
+    }
+    if (restored) return;
+    restored = true;
+    // Only reclaim the slot if it is still OUR replacement — never clobber a newer patcher.
+    if (console.error === replacement) console.error = original;
+  };
+
+  const resetQuietTimer = (): void => {
+    if (handle !== undefined) clearScheduled(handle);
+    handle = schedule(restore, opts.quietMs);
+    // Never keep the event loop alive on our account.
+    (handle as { unref?: () => void })?.unref?.();
+  };
+
+  const replacement = (...args: unknown[]): void => {
+    // Once restored, behave as the original — a stale reference still holding `replacement`
+    // (a module that cached console.error, or a wrapping patcher) never re-routes to the sink.
+    // And if the sink (or a downstream report()/ui.notify) ever writes to console.error while we
+    // are installed, delegate to the original instead of recursing into ourselves.
+    if (restored || active) {
+      original(...args);
+      return;
+    }
+    active = true;
+    try {
+      sink(args.map(String).join(" "));
+    } finally {
+      active = false;
+    }
+    resetQuietTimer();
+  };
+
+  console.error = replacement;
+  // Start the timer immediately so a zero-line case (no setup output) still restores after quietMs.
+  resetQuietTimer();
+
+  return { restore };
+}

package/extension/substrate/git.ts

@@ -0,0 +1,77 @@
+// A thin `git`-shelling seam for the extension interior — the TS twin of perk/substrate/git.py.
+//
+// Node builtins only (so it loads cleanly under `node --test`); shells `git` via `execFileSync`,
+// never with a shell. Fail-open by design: every failure degrades to the caller's `cwd` (or null
+// where stated) rather than throwing — the carriers that use this must never wedge a session.
+
+import { execFileSync } from "node:child_process";
+import { isAbsolute, resolve } from "node:path";
+
+/**
+ * The MAIN working tree's root, even when `cwd` is inside a linked worktree — the TS twin of
+ * `main_worktree_root`. Resolves `git rev-parse --git-common-dir` (the shared `.git` of the main
+ * checkout) and returns its parent (equal to the repo root in the main checkout). **Fail-open**:
+ * any failure (not a repo, git missing) returns `cwd`, so a session-pointer write always has a
+ * location — never throws. (Python returns `null` outside a repo; here the single caller wants
+ * `main_worktree_root(cwd) or cwd`, so we fold the fallback in.)
+ */
+export function mainCheckoutRoot(cwd: string): string {
+  let out: string;
+  try {
+    out = execFileSync("git", ["rev-parse", "--git-common-dir"], {
+      cwd,
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+    }).trim();
+  } catch {
+    return cwd;
+  }
+  if (out === "") return cwd;
+  // `--git-common-dir` may be relative (to `cwd`) or absolute; resolve then take the parent
+  // (the dir containing `.git` = the main checkout root).
+  const common = isAbsolute(out) ? out : resolve(cwd, out);
+  return resolve(common, "..");
+}
+
+/** Run one git command; trimmed stdout, or null on any failure (the module's fail-open style). */
+function git(cwd: string, args: string[], timeout?: number): string | null {
+  try {
+    const out = execFileSync("git", args, {
+      cwd,
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+      ...(timeout !== undefined ? { timeout } : {}),
+    }).trim();
+    return out === "" ? null : out;
+  } catch {
+    return null;
+  }
+}
+
+/** The bounded best-effort `git fetch` budget (ms) — see `sinceBaseSha` step 2. */
+const FETCH_TIMEOUT_MS = 15_000;
+
+/**
+ * The since-base merge-base of the working tree: `merge-base(HEAD, origin/<base>)` — the sha the
+ * terminal review door diffs the active worktree against. **Fail-open**: null on any failure
+ * (not a repo, no such ref, git missing), never throws.
+ *
+ * 1. Resolve the base branch name: `base` when given; else the repo default via
+ *    `git symbolic-ref --short refs/remotes/origin/HEAD` (`origin/main` → `main`).
+ * 2. Best-effort `git fetch origin <branch>` with a bounded timeout — a failure (offline, no
+ *    remote) is swallowed and the stale local ref is used, keeping the door usable offline (and
+ *    the test scaffold network-free).
+ * 3. `git merge-base HEAD origin/<branch>` → the full sha.
+ */
+export function sinceBaseSha(cwd: string, base: string | null | undefined): string | null {
+  let branch = base ?? null;
+  if (branch === null) {
+    const head = git(cwd, ["symbolic-ref", "--short", "refs/remotes/origin/HEAD"]);
+    if (head === null) return null;
+    // `origin/main` → `main` (keep anything after the first slash — branch names may carry `/`).
+    branch = head.includes("/") ? head.slice(head.indexOf("/") + 1) : head;
+  }
+  if (branch === "") return null;
+  git(cwd, ["fetch", "origin", branch], FETCH_TIMEOUT_MS);
+  return git(cwd, ["merge-base", "HEAD", `origin/${branch}`]);
+}