@gr8ful/spf 0.5.1 → 0.7.0

package/dist/core/fanout.js

@@ -0,0 +1,313 @@
+/**
+ * Best-of-N: run ONE prompt N times in parallel, then let CODE pick the winner.
+ *
+ * THE SHAPE IS NOT NEW, and that is the whole argument for it. `spf watch`
+ * already runs N chains CONCURRENTLY IN ONE PROCESS — each with its own git
+ * worktree, its own adw_id, its own `Run`, all sharing the main repo's WAL
+ * SQLite through a data-dir symlink (see `core/watch.ts`'s `runIssue`,
+ * `cli/commands/watch.ts`'s `runChain` closure and its `linkDataDir`). Fan-out
+ * is that proven mechanism pointed at one prompt instead of N issues: N
+ * sibling Runs with derived adw_ids over N worktrees, followed by a
+ * DETERMINISTIC `pickBest`. "Agent proposes, code disposes" — extended to
+ * SELECTION, which is the only new idea here.
+ *
+ * THE UNIT OF ISOLATION IS THE RUN, NEVER AN AGENT CALL. Every attempt gets a
+ * fresh worktree and a fresh Run whose `repo_root` is bound once, in the Run
+ * constructor. That is what keeps `gates.resolveClaim`,
+ * `permissions.snapshot/enforce`, the quality checks and `changes.capture`
+ * judging the tree their agents actually wrote in. A per-call cwd swap would
+ * point them at the wrong tree and hand out green gates on unverified work; a
+ * `SandboxHandle`/cwd-threading design was evaluated for exactly this and
+ * REJECTED. Do not reintroduce it.
+ *
+ * SELECTION READS SQLITE, NOT RETURN VALUES. Gate reports (`tracer.gateRow`)
+ * and per-run usage (`sessions.total_tokens`/`total_cost`) already land in the
+ * shared db keyed by adw_id, so the basis below is a SELECT away. Widening
+ * `steps.runSteps`' return contract to carry metrics back was evaluated and
+ * REJECTED as needless blast radius: every chain, every step, and the watch
+ * dispatch would change to serve one new caller. `runAttempt` still returns
+ * just an exit code, exactly like `runChainDef` does.
+ *
+ * WHY THE BUDGET SHIPS WITH THIS. An n-multiplier on spend without a ceiling
+ * is a footgun — the only budget-like constant before this changeset was
+ * `JSON_FIX_ATTEMPTS = 2`. `defaults.max_run_cost`/`max_run_tokens`
+ * (`core/agents.ts`'s `assertRunBudget`) are checked before each attempt's
+ * NEXT agent call, never after — so one attempt can still overshoot the
+ * ceiling by a whole call, and a chain with only ONE agent dispatch
+ * (`scout`, `prompt`, `build`) can never trip it at all. With that caveat, N
+ * attempts are bounded by roughly N × ceiling, and each one that DOES trip
+ * it fails its phase closed with a message naming the ceiling and the spend.
+ *
+ * WINNER HANDLING KEEPS THE HUMAN ACCOUNTABLE. Each attempt commits on its own
+ * branch in its own worktree. The winner's branch AND worktree are KEPT and
+ * reported (branch + adw_id + the selection basis); the losers' worktrees and
+ * branches are deleted. SPF DOES NOT MERGE THE WINNER — the operator does.
+ * Keeping the winner's worktree is deliberate, not laziness: a chain that
+ * doesn't commit (or that failed after writing) leaves work in the tree only,
+ * and `git worktree remove --force` would destroy it. `git merge`/
+ * `git cherry-pick` from the main repo work fine against a branch that is
+ * checked out elsewhere, so nothing is blocked by keeping it.
+ *
+ * ABORT GRANULARITY, stated plainly because it is a real limit — and, as of
+ * `deps.firstSuccess`, OPT-IN rather than the default. Best-of-N exists to
+ * COMPARE N candidates; the DEFAULT (`firstSuccess` unset/false) therefore
+ * dispatches every attempt regardless of how early one succeeds, so the
+ * gates/cost/tokens comparison in `pickBest` is over the whole field the
+ * operator actually asked for, not "whatever happened to still be queued."
+ * Passing `firstSuccess: true` restores first-past-the-post: once an attempt
+ * exits 0 the race is decided and no further attempt is STARTED —
+ * `deps.runAttempt` is never called for a queued attempt, which is where the
+ * saving actually is (with `concurrency` 2 and `--n 4`, half the attempts are
+ * typically never dispatched). Either way, attempts ALREADY IN FLIGHT run to
+ * completion: `steps.runSteps` has no cancellation seam, and adding one would
+ * mean changing the driver every chain shares for the benefit of this one
+ * caller. `AttemptDispatch.isAborted()` is threaded to the runner so a
+ * dispatch that CAN check between phases does when `firstSuccess` is on, and
+ * so a test can prove the flag is honored — cooperative by design, not by
+ * accident.
+ */
+import path from "node:path";
+import { removeRunWorktree, withRunWorktree } from "./git_helper.js";
+/** Sentinel exit code meaning "never dispatched — the race was already decided". Distinct from any real chain exit code. */
+export const ABORTED_EXIT = -1;
+export const ZERO_METRICS = { gate_passes: 0, gate_failures: 0, cost: 0, tokens: 0 };
+// ── naming (deterministic, so a killed run leaves cleanable debris) ──────────
+/** `<baseAdw>-<i>` — a derived, greppable sibling of the base id. */
+export function attemptAdwId(baseAdwId, index) {
+    return `${baseAdwId}-${index}`;
+}
+/**
+ * `spf/fanout/<baseAdw>-<i>` — namespaced so the winner is obvious in
+ * `git branch` and the losers are obviously disposable. Separate from
+ * `spf-watch/*`/`spf-refine/*` (see `core/watch.ts`) because these branches
+ * are never pushed by SPF: a human merges the winner from the local ref.
+ */
+export function attemptBranch(baseAdwId, index) {
+    return `spf/fanout/${attemptAdwId(baseAdwId, index)}`;
+}
+/** The worktree leaf name. Deterministic from the adw_id, like watch's `issue-<id>`. */
+export function attemptWorktreeName(baseAdwId, index) {
+    return `fanout-${attemptAdwId(baseAdwId, index)}`;
+}
+export function attemptWorktreePath(worktreesDir, baseAdwId, index) {
+    return path.join(worktreesDir, attemptWorktreeName(baseAdwId, index));
+}
+// ── selection: the deterministic disposer ───────────────────────────────────
+/**
+ * The selection basis, in order. Every criterion is read from the shared
+ * SQLite or measured by this module — never asked of an agent.
+ *
+ *  1. the run SUCCEEDED (exit 0). A failed attempt is not a candidate at all.
+ *  2. fewest gate FAILURES, then most gate PASSES. Failures first because zero
+ *     is the bar: an attempt that needed a correction round is worse than one
+ *     that never tripped a gate, regardless of how many gates each ran. Passes
+ *     break that tie in favour of the attempt that VERIFIED more.
+ *  3. lowest total cost.
+ *  4. fewest tokens.
+ *  5. lowest wall time — a LAST RESORT, deliberately below cost and tokens:
+ *     every code phase runs through `spawnSync` (`core/quality.ts`), which
+ *     blocks the shared event loop, so "concurrent" attempts partly serialize
+ *     on exactly the phases fan-out means to compare, and `wall_ms` ends up
+ *     favouring whichever attempt happened to run last by a scheduling
+ *     accident rather than anything about the candidate. Cost and tokens are
+ *     read from the trace and are not subject to that; wall time still
+ *     breaks a genuine tie between two runs identical on both.
+ *  6. lexicographic adw_id.
+ *
+ * (6) exists to make this a TOTAL order: adw_ids are unique per attempt, so
+ * the comparator can never return 0 for two different attempts, so the winner
+ * cannot depend on which attempt happened to finish first. That is what
+ * "deterministic" has to mean here — pinned by a permutation test in
+ * `src/test/fanout.test.ts`.
+ */
+export function compareAttempts(a, b) {
+    const rank = (attempt) => (attempt.status === "success" ? 0 : 1);
+    return (rank(a) - rank(b) ||
+        a.gate_failures - b.gate_failures ||
+        b.gate_passes - a.gate_passes ||
+        a.cost - b.cost ||
+        a.tokens - b.tokens ||
+        a.wall_ms - b.wall_ms ||
+        (a.adw_id < b.adw_id ? -1 : a.adw_id > b.adw_id ? 1 : 0));
+}
+/** Which criterion actually separated the winner from its closest rival — the honest half of a printed basis. */
+function decidingCriterion(winner, runnerUp) {
+    if (winner.gate_failures !== runnerUp.gate_failures) {
+        return `fewer gate failures (${winner.gate_failures} vs ${runnerUp.gate_failures})`;
+    }
+    if (winner.gate_passes !== runnerUp.gate_passes) {
+        return `more gate passes (${winner.gate_passes} vs ${runnerUp.gate_passes})`;
+    }
+    if (winner.cost !== runnerUp.cost) {
+        return `lower cost ($${winner.cost.toFixed(4)} vs $${runnerUp.cost.toFixed(4)})`;
+    }
+    if (winner.tokens !== runnerUp.tokens) {
+        return `fewer tokens (${winner.tokens.toLocaleString("en-US")} vs ${runnerUp.tokens.toLocaleString("en-US")})`;
+    }
+    if (winner.wall_ms !== runnerUp.wall_ms) {
+        // Named as contended, not a clean property of the candidate — see the
+        // criteria list above.
+        return `lower wall time (${(winner.wall_ms / 1000).toFixed(1)}s vs ${(runnerUp.wall_ms / 1000).toFixed(1)}s — contended under concurrency, a last resort)`;
+    }
+    return `lexicographic adw_id tiebreak (${winner.adw_id} before ${runnerUp.adw_id})`;
+}
+/**
+ * Pick the winner. PURE: no I/O, no clock, no filesystem — everything it
+ * needs is already on the attempts, which is what makes the selection
+ * testable and reproducible from a trace.
+ *
+ * Sorts a COPY: the caller's array keeps its index order for printing.
+ */
+export function pickBest(attempts) {
+    const succeeded = attempts.filter((a) => a.status === "success");
+    if (succeeded.length === 0) {
+        return { winner: null, basis: `no attempt succeeded (${attempts.length} tried) — nothing to select` };
+    }
+    const ranked = [...succeeded].sort(compareAttempts);
+    const winner = ranked[0];
+    const summary = `${winner.gate_failures} gate failure(s), ${winner.gate_passes} gate pass(es), ` +
+        `$${winner.cost.toFixed(4)}, ${(winner.wall_ms / 1000).toFixed(1)}s`;
+    if (ranked.length === 1) {
+        return {
+            winner,
+            basis: `the only attempt that succeeded of ${attempts.length} — ${summary}`,
+        };
+    }
+    return {
+        winner,
+        basis: `${decidingCriterion(winner, ranked[1])} over ${ranked[1].adw_id}; ${succeeded.length} of ${attempts.length} attempt(s) succeeded — ${summary}`,
+    };
+}
+/**
+ * Run `n` attempts of one prompt, select deterministically, clean up the
+ * losers, keep the winner.
+ *
+ * Concurrency is the same inflight-budget idea as `watch.claimNewWork`,
+ * expressed as a fixed worker pool over a shared queue: at most
+ * `concurrency` attempts are ever in flight, and a worker that finds the race
+ * already decided records the remaining attempts as `skipped` WITHOUT
+ * dispatching them. Attempts are returned in index order regardless of the
+ * order they finished — the printed table must not shuffle between runs.
+ */
+export async function runBestOf(deps) {
+    deps.log(`fanout: chain "${deps.chainName}" x${deps.n} off ${deps.baseBranch}, concurrency ${deps.concurrency}, ` +
+        `adw_id ${attemptAdwId(deps.baseAdwId, 1)}..${attemptAdwId(deps.baseAdwId, deps.n)}` +
+        (deps.firstSuccess ? ", first-success (stops dispatching once one attempt succeeds)" : ""));
+    const queue = Array.from({ length: deps.n }, (_, i) => i + 1);
+    const attempts = [];
+    /** Flipped exactly once, by the first attempt to exit 0. Never flipped back. */
+    let decided = false;
+    const runOne = async (index) => {
+        const adwId = attemptAdwId(deps.baseAdwId, index);
+        const branch = attemptBranch(deps.baseAdwId, index);
+        const worktree = attemptWorktreePath(deps.worktreesDir, deps.baseAdwId, index);
+        const started = performance.now();
+        let exitCode = null;
+        let error = null;
+        try {
+            exitCode = await withRunWorktree(deps.repoRoot, attemptWorktreeName(deps.baseAdwId, index), {
+                worktreesDir: deps.worktreesDir,
+                branch,
+                baseBranch: deps.baseBranch,
+                linkDataDir: deps.linkDataDir,
+                git: deps.git,
+                log: deps.log,
+            }, async (wt) => {
+                const code = await deps.runAttempt({
+                    index,
+                    adwId,
+                    cwd: wt.path,
+                    branch,
+                    prompt: deps.prompt,
+                    isAborted: () => decided,
+                });
+                // Only a successful attempt can be selected, so only a successful
+                // attempt's tree and branch are worth carrying past this scope.
+                // A failed one is cleaned up NOW rather than lingering while its
+                // siblings finish — its trace survives in the shared SQLite
+                // regardless, which is where a post-mortem looks anyway.
+                if (code === 0)
+                    wt.keep();
+                return code;
+            });
+        }
+        catch (caught) {
+            error = caught.message;
+            deps.log(`fanout: attempt ${index} (${adwId}) errored: ${error}`);
+        }
+        if (exitCode === 0 && deps.firstSuccess)
+            decided = true;
+        let metrics = ZERO_METRICS;
+        try {
+            metrics = deps.readMetrics(adwId);
+        }
+        catch (caught) {
+            // Metrics are for RANKING, never for correctness — an attempt whose
+            // rows can't be read ranks as a zero-gate, zero-cost run rather than
+            // failing the whole fan-out.
+            deps.log(`fanout: could not read metrics for ${adwId}: ${caught.message}`);
+        }
+        // `ABORTED_EXIT` is a runner saying "I declined to spend" — a sibling won
+        // between this attempt leaving the queue and its first agent call. That is
+        // a skip, not a failure: reporting it as `fail` would make a clean
+        // early-abort look like N-1 broken runs in the result table.
+        const status = exitCode === 0 ? "success" : exitCode === ABORTED_EXIT ? "skipped" : error !== null ? "error" : "fail";
+        return {
+            index,
+            adw_id: adwId,
+            branch,
+            worktree,
+            status,
+            exit_code: exitCode,
+            error,
+            wall_ms: performance.now() - started,
+            kept: false,
+            ...metrics,
+        };
+    };
+    const skipped = (index) => ({
+        index,
+        adw_id: attemptAdwId(deps.baseAdwId, index),
+        branch: attemptBranch(deps.baseAdwId, index),
+        worktree: attemptWorktreePath(deps.worktreesDir, deps.baseAdwId, index),
+        status: "skipped",
+        exit_code: ABORTED_EXIT,
+        error: null,
+        wall_ms: 0,
+        kept: false,
+        ...ZERO_METRICS,
+    });
+    const worker = async () => {
+        for (;;) {
+            const index = queue.shift();
+            if (index === undefined)
+                return;
+            if (decided) {
+                deps.log(`fanout: attempt ${index} skipped — an earlier attempt already succeeded`);
+                attempts.push(skipped(index));
+                continue;
+            }
+            attempts.push(await runOne(index));
+        }
+    };
+    const workers = Array.from({ length: Math.max(1, Math.min(deps.concurrency, deps.n)) }, () => worker());
+    await Promise.all(workers);
+    attempts.sort((a, b) => a.index - b.index);
+    const { winner, basis } = pickBest(attempts);
+    // Cleanup is the disposer's last act, and it runs AFTER selection because a
+    // loser is only knowable once every attempt has been ranked. Failed and
+    // skipped attempts own nothing by now (the scoped worktree helper already
+    // removed a failed one; a skipped one never had a tree), so this only ever
+    // touches attempts that SUCCEEDED and lost.
+    for (const attempt of attempts) {
+        if (attempt.status !== "success")
+            continue;
+        if (winner && attempt.adw_id === winner.adw_id) {
+            attempt.kept = true;
+            continue;
+        }
+        deps.log(`fanout: discarding attempt ${attempt.index} (${attempt.adw_id}) — branch ${attempt.branch}`);
+        removeRunWorktree(deps.repoRoot, { path: attempt.worktree, branch: attempt.branch }, { git: deps.git, log: deps.log });
+    }
+    return { winner, basis, attempts };
+}

package/dist/core/gates.d.ts

@@ -40,6 +40,14 @@ export declare function verdictConsistent(envelope: EnvelopeBase, _run: RunConte
  *
  * "Container" and "leaf" are derived from the graph, not asserted by the
  * agent: a node is a container iff some other node names it as `parent`.
+ *
+ * `questions` (see `RefineQuestionSchema`'s doc comment) is the human-in-the-
+ * loop escalation path, and it is mutually exclusive with `issues`: a
+ * refinement that raises material ambiguity must publish NOTHING this round
+ * — a partial tree pinned to an unanswered question is worse than none.
+ * When `questions` is non-empty this gate checks only its own shape (unique,
+ * non-blank ids; non-blank question text) and skips every `issues` rule
+ * below, since there is no tree to validate.
  */
 export declare function refinementWellFormed(envelope: EnvelopeBase, _run: RunContext): GateReport;
 /** Gate factory: the given shell command must exit 0, run from run.repo_root. */

package/dist/core/gates.js

@@ -17,7 +17,7 @@
 import { spawnSync } from "node:child_process";
 import { existsSync, statSync, readFileSync } from "node:fs";
 import path from "node:path";
-import { GateReport } from "./data_types.js";
+import { GateReport, PRIORITY_RANK } from "./data_types.js";
 import { operatorEnv } from "./utils.js";
 const TAIL_CHARS = 1000; // command output kept as evidence on a failure
 /**
@@ -141,12 +141,35 @@ const LEAF_KINDS = new Set(["story", "bug", "task"]);
  *
  * "Container" and "leaf" are derived from the graph, not asserted by the
  * agent: a node is a container iff some other node names it as `parent`.
+ *
+ * `questions` (see `RefineQuestionSchema`'s doc comment) is the human-in-the-
+ * loop escalation path, and it is mutually exclusive with `issues`: a
+ * refinement that raises material ambiguity must publish NOTHING this round
+ * — a partial tree pinned to an unanswered question is worse than none.
+ * When `questions` is non-empty this gate checks only its own shape (unique,
+ * non-blank ids; non-blank question text) and skips every `issues` rule
+ * below, since there is no tree to validate.
  */
 export function refinementWellFormed(envelope, _run) {
     const report = new GateReport();
     const issues = envelope.issues ?? [];
+    const questions = envelope.questions ?? [];
+    if (questions.length > 0) {
+        report.check("issues empty while escalating", issues.length === 0, issues.length === 0
+            ? "no issues published alongside the questions"
+            : `${issues.length} issue(s) published alongside ${questions.length} question(s) — escalating means publishing nothing this round`);
+        const seenIds = new Set();
+        for (const q of questions) {
+            const blank = !q.id.trim();
+            const dup = !blank && seenIds.has(q.id);
+            seenIds.add(q.id);
+            report.check(`question ${JSON.stringify(q.id)}`, !blank && !dup, blank ? "question id is blank" : dup ? "duplicate question id — every question needs a unique id within this round" : "id ok");
+            report.check(`question ${JSON.stringify(q.id)}.question`, q.question.trim().length > 0, q.question.trim().length > 0 ? "has text" : "question text is blank");
+        }
+        return report;
+    }
     if (issues.length === 0) {
-        report.check("issues", false, "a refinement produced no issues at all — decompose the spec into at least one leaf");
+        report.check("issues", false, "a refinement produced no issues at all and raised no questions — decompose the spec into at least one leaf, or escalate what's ambiguous");
         return report;
     }
     const byKey = new Map();
@@ -229,6 +252,29 @@ export function refinementWellFormed(envelope, _run) {
     }
     const leafCount = issues.filter((i) => !childKeys.has(i.key)).length;
     report.check("has leaves", leafCount > 0, leafCount > 0 ? `${leafCount} leaf issue(s)` : "every node is a container — nothing here is independently workable");
+    // Monotonicity: no node may be MORE urgent than its own parent — p0 < p1 <
+    // p2 < p3, so "more urgent" is a lower rank. Only checked against `parent`
+    // (the containment edge), never `blocked_by` (a real dependency can easily
+    // be less urgent than the thing it blocks — a p3 prefactor gating a p0
+    // feature is normal, not a mistake). A violation here is a decomposition
+    // mistake worth a correction round-trip (this gate's `retries: 1` —
+    // steps.ts's `refine()`), not a hard block: a p0 story wearing a p3
+    // feature's parent almost always means the feature was mis-scored, not the
+    // story. The spec's OWN priority ceiling is enforced separately, in
+    // `core/refine.ts`'s `publish()` — this gate only knows about the tree,
+    // never the spec issue it came from.
+    for (const issue of issues) {
+        if (!issue.parent)
+            continue;
+        const parent = byKey.get(issue.parent);
+        if (!parent)
+            continue; // already reported above as an unresolved parent
+        const childRank = PRIORITY_RANK[issue.priority] ?? 2;
+        const parentRank = PRIORITY_RANK[parent.priority] ?? 2;
+        report.check(`${issue.key}.priority`, childRank >= parentRank, childRank >= parentRank
+            ? `${issue.priority} — no more urgent than parent ${JSON.stringify(issue.parent)} (${parent.priority})`
+            : `${issue.priority} is more urgent than parent ${JSON.stringify(issue.parent)}'s ${parent.priority} — a container's priority is a ceiling for everything under it`);
+    }
     return report;
 }
 /** Gate factory: the given shell command must exit 0, run from run.repo_root. */

package/dist/core/git_helper.d.ts

@@ -86,3 +86,101 @@ export interface GitHandle {
 }
 /** Every operation this returns is bound to `repoRoot` — never `process.cwd()`. */
 export declare function makeGit(repoRoot: string): GitHandle;
+export interface RunWorktreeSpec {
+    /** Absolute path of the worktree's working directory. */
+    path: string;
+    /** The branch created at `path`. Deleting it requires removing the worktree first. */
+    branch: string;
+}
+export interface RunWorktreeOptions {
+    /** Absolute. OUTSIDE the repo — a worktree inside it would be walked by the repo's own tooling. */
+    worktreesDir: string;
+    /** Created by `git worktree add -b`, so it must NOT already exist (see the cleanup-first note below). */
+    branch: string;
+    /** Branch name only (`"main"`), not a remote ref — the remote prefix is applied by `resolveStartPoint`. */
+    baseBranch: string;
+    /** Default "origin". */
+    remote?: string;
+    /**
+     * Default true: fetch `remote/baseBranch` before branching, so a long-lived
+     * process doesn't fork every run off a stale base. Unlike watch's inlined
+     * `git.fetch(...)`, a FAILED fetch here is not fatal — see `resolveStartPoint`.
+     */
+    fetchBase?: boolean;
+    /** Overrides the whole base resolution — an explicit ref (sha, tag, local branch) to branch from. */
+    startPoint?: string;
+    /** Wire `<worktree>/.spf/data` to the MAIN repo's data dir. Injected, never done here — see the section comment. */
+    linkDataDir?: (worktreePath: string) => void;
+    /** Bound to the MAIN repo root. Injected so a unit test needs no real repo; defaults to `makeGit(repoRoot)`. */
+    git?: GitHandle;
+    log?: (message: string) => void;
+}
+/**
+ * Create `<worktreesDir>/<name>` on a fresh `branch` off the resolved base,
+ * and wire its data dir. Returns the spec its caller must eventually hand to
+ * `removeRunWorktree`.
+ *
+ * CLEARS A STALE WORKTREE DIRECTORY FIRST, but only when it's safe to: the
+ * path is deterministic from `name`, so the only way it can already exist is
+ * a previous attempt that never reached its own cleanup (killed mid-run,
+ * crashed, machine restart) — OR a previous attempt whose kept payload lives
+ * only in that tree's uncommitted edits (see `cli/commands/fanout.ts`'s
+ * winner-handling note: a chain with no commit step leaves its work in the
+ * worktree, not on the branch). `git worktree remove --force` deletes
+ * modified/untracked files with no confirmation and exit 0, so blindly
+ * force-removing here would silently destroy a kept winner the moment a
+ * `--adw-id` retry reuses its deterministic name. Refuse instead, loudly,
+ * before touching anything. `worktreeRemove` is a no-op when there is
+ * nothing to remove, so a genuinely stale (clean) leftover is still cleared
+ * exactly as before. (Same reasoning as `core/watch.ts`'s `runIssue`, which
+ * clears its own worktree the same way — modulo this same guard.)
+ *
+ * ALSO REFUSES A PRE-EXISTING BRANCH up front, for the same reason and the
+ * same actionable-error idea: the fan-out winner's branch is handed to a
+ * human to merge and can share this exact deterministic name across separate
+ * invocations (an explicit `--adw-id` retry), so it is never deleted here —
+ * see `removeRunWorktree` for the only place that happens, once an attempt
+ * is known to be discarded. Checking first turns `git worktree add -b`'s raw
+ * `fatal: a branch named '...' already exists` (which every attempt would
+ * otherwise hit identically, for the least helpful reason) into one message
+ * naming the collision and the way out.
+ */
+export declare function createRunWorktree(repoRoot: string, name: string, opts: RunWorktreeOptions): RunWorktreeSpec;
+/**
+ * Remove a run worktree and delete its branch. NEVER throws — cleanup runs on
+ * the failure path too, and a cleanup error must not replace the real error
+ * that got us here.
+ *
+ * Order matters and is not cosmetic: git refuses to delete a branch that is
+ * checked out in a worktree, so the worktree goes first. A caller that wants
+ * to KEEP the branch (the fan-out winner) must simply not call this.
+ */
+export declare function removeRunWorktree(repoRoot: string, worktree: RunWorktreeSpec, opts?: {
+    git?: GitHandle;
+    log?: (message: string) => void;
+}): void;
+/** What the callback of `withRunWorktree` is handed. */
+export interface RunWorktreeHandle extends RunWorktreeSpec {
+    /**
+     * Make this worktree and its branch SURVIVE the scope.
+     *
+     * The whole point of the scoped form: a caller that cannot decide the fate
+     * of a tree until it sees the result (fan-out keeps a successful attempt's
+     * branch so it can still be selected and, if it wins, handed to a human;
+     * a failed attempt's tree is worthless the moment it fails) says so from
+     * inside, once it knows. Not calling it is the default, and the default is
+     * cleanup.
+     */
+    keep(): void;
+}
+/**
+ * Run `fn` against a fresh run worktree, cleaning it up afterwards unless
+ * `wt.keep()` was called — including when `fn` throws, which is the case a
+ * hand-rolled create/remove pair reliably gets wrong.
+ *
+ * `opts` sits BEFORE the callback (a small departure from the usual
+ * `(a, b, fn)` shape) so the required options can't be forgotten behind an
+ * optional trailing argument, and so the callback stays the last thing you
+ * read — the JS convention that matters here.
+ */
+export declare function withRunWorktree<T>(repoRoot: string, name: string, opts: RunWorktreeOptions, fn: (worktree: RunWorktreeHandle) => Promise<T>): Promise<T>;

package/dist/core/git_helper.js

@@ -10,6 +10,7 @@
  * and conflating them is exactly the anchor bug this factory exists to close.
  */
 import { spawnSync } from "node:child_process";
+import { existsSync, mkdirSync } from "node:fs";
 import path from "node:path";
 function git(args, cwd) {
     const result = spawnSync("git", args, { cwd, encoding: "utf-8" });
@@ -153,3 +154,129 @@ export function makeGit(repoRoot) {
         },
     };
 }
+/**
+ * Where the base of a new run worktree comes from.
+ *
+ * A fetch failure is logged, not thrown: `spf fanout` is a local, interactive
+ * command that must still work on a repo with no remote, offline, or behind a
+ * proxy — and `refExists` below then falls back to the LOCAL base branch,
+ * which is the honest answer in all three cases. (Watch differs on purpose:
+ * a daemon that silently starts branching off a stale local base for hours is
+ * worse than a loud failure, so it keeps its unguarded `git.fetch`.)
+ */
+function resolveStartPoint(git, opts) {
+    if (opts.startPoint)
+        return opts.startPoint;
+    const remote = opts.remote ?? "origin";
+    if (opts.fetchBase !== false) {
+        try {
+            git.fetch(remote, opts.baseBranch);
+        }
+        catch (error) {
+            // First line only: `git fetch`'s own error is the underlying command's
+            // full multiline stderr, and an offline/local-only repo hits this on
+            // EVERY attempt — five lines of "'origin' does not appear to be a git
+            // repository" repeated N times drowns out everything else fan-out prints.
+            const firstLine = error.message.split("\n")[0];
+            opts.log?.(`worktree: fetch ${remote} ${opts.baseBranch} failed (${firstLine}) — using the local base`);
+        }
+    }
+    const remoteRef = `${remote}/${opts.baseBranch}`;
+    return git.refExists(remoteRef) ? remoteRef : opts.baseBranch;
+}
+/**
+ * Create `<worktreesDir>/<name>` on a fresh `branch` off the resolved base,
+ * and wire its data dir. Returns the spec its caller must eventually hand to
+ * `removeRunWorktree`.
+ *
+ * CLEARS A STALE WORKTREE DIRECTORY FIRST, but only when it's safe to: the
+ * path is deterministic from `name`, so the only way it can already exist is
+ * a previous attempt that never reached its own cleanup (killed mid-run,
+ * crashed, machine restart) — OR a previous attempt whose kept payload lives
+ * only in that tree's uncommitted edits (see `cli/commands/fanout.ts`'s
+ * winner-handling note: a chain with no commit step leaves its work in the
+ * worktree, not on the branch). `git worktree remove --force` deletes
+ * modified/untracked files with no confirmation and exit 0, so blindly
+ * force-removing here would silently destroy a kept winner the moment a
+ * `--adw-id` retry reuses its deterministic name. Refuse instead, loudly,
+ * before touching anything. `worktreeRemove` is a no-op when there is
+ * nothing to remove, so a genuinely stale (clean) leftover is still cleared
+ * exactly as before. (Same reasoning as `core/watch.ts`'s `runIssue`, which
+ * clears its own worktree the same way — modulo this same guard.)
+ *
+ * ALSO REFUSES A PRE-EXISTING BRANCH up front, for the same reason and the
+ * same actionable-error idea: the fan-out winner's branch is handed to a
+ * human to merge and can share this exact deterministic name across separate
+ * invocations (an explicit `--adw-id` retry), so it is never deleted here —
+ * see `removeRunWorktree` for the only place that happens, once an attempt
+ * is known to be discarded. Checking first turns `git worktree add -b`'s raw
+ * `fatal: a branch named '...' already exists` (which every attempt would
+ * otherwise hit identically, for the least helpful reason) into one message
+ * naming the collision and the way out.
+ */
+export function createRunWorktree(repoRoot, name, opts) {
+    const git = opts.git ?? makeGit(repoRoot);
+    const worktreePath = path.join(opts.worktreesDir, name);
+    if (existsSync(worktreePath)) {
+        const status = spawnSync("git", ["status", "--porcelain"], { cwd: worktreePath, encoding: "utf-8" });
+        if (status.status === 0 && status.stdout.trim() !== "") {
+            throw new Error(`${worktreePath} already exists and has uncommitted changes — refusing to remove it (it may be a ` +
+                `previous run's kept winner). Inspect or move it by hand, then retry, or use a fresh --adw-id.`);
+        }
+    }
+    try {
+        git.worktreeRemove(worktreePath);
+    }
+    catch (error) {
+        opts.log?.(`worktree: cleanup warning for ${worktreePath}: ${error.message}`);
+    }
+    if (git.refExists(opts.branch)) {
+        throw new Error(`branch ${opts.branch} already exists — delete it (\`git branch -D ${opts.branch}\`) once you no longer ` +
+            `need it, or use a fresh --adw-id`);
+    }
+    mkdirSync(opts.worktreesDir, { recursive: true });
+    git.worktreeAdd(worktreePath, opts.branch, resolveStartPoint(git, opts));
+    opts.linkDataDir?.(worktreePath);
+    return { path: worktreePath, branch: opts.branch };
+}
+/**
+ * Remove a run worktree and delete its branch. NEVER throws — cleanup runs on
+ * the failure path too, and a cleanup error must not replace the real error
+ * that got us here.
+ *
+ * Order matters and is not cosmetic: git refuses to delete a branch that is
+ * checked out in a worktree, so the worktree goes first. A caller that wants
+ * to KEEP the branch (the fan-out winner) must simply not call this.
+ */
+export function removeRunWorktree(repoRoot, worktree, opts = {}) {
+    const git = opts.git ?? makeGit(repoRoot);
+    try {
+        git.worktreeRemove(worktree.path);
+        git.deleteLocalBranch(worktree.branch);
+    }
+    catch (error) {
+        opts.log?.(`worktree: cleanup warning for ${worktree.path}: ${error.message}`);
+    }
+}
+/**
+ * Run `fn` against a fresh run worktree, cleaning it up afterwards unless
+ * `wt.keep()` was called — including when `fn` throws, which is the case a
+ * hand-rolled create/remove pair reliably gets wrong.
+ *
+ * `opts` sits BEFORE the callback (a small departure from the usual
+ * `(a, b, fn)` shape) so the required options can't be forgotten behind an
+ * optional trailing argument, and so the callback stays the last thing you
+ * read — the JS convention that matters here.
+ */
+export async function withRunWorktree(repoRoot, name, opts, fn) {
+    const spec = createRunWorktree(repoRoot, name, opts);
+    let kept = false;
+    const handle = { ...spec, keep: () => void (kept = true) };
+    try {
+        return await fn(handle);
+    }
+    finally {
+        if (!kept)
+            removeRunWorktree(repoRoot, spec, { git: opts.git, log: opts.log });
+    }
+}