@gr8ful/spf 0.5.0 → 0.6.0

package/dist/cli/commands/fanout.js

@@ -0,0 +1,401 @@
+/**
+ * `spf fanout <chain> "<prompt>" --n 3` — best-of-N, disposed by code.
+ *
+ * The wiring half of `core/fanout.ts` (which holds the mechanism and the
+ * selection basis): config, the chain-dispatch callback, the data-dir symlink,
+ * the SQLite metrics read, and the result table. Same split as
+ * `core/watch.ts` / `cli/commands/watch.ts`, for the same reason — `core/`
+ * stays out of `src/chains/`'s dependency direction, so the fan-out mechanism
+ * is testable with no chains, no agents and no real git.
+ *
+ * A REAL SUBCOMMAND, NOT A `--best-of` FLAG ON `run`. Fan-out is a different
+ * verb: it creates N branches and N worktrees, keeps one, and deletes the
+ * rest. Hiding that behind a flag on `spf run` would make an ordinary run
+ * silently capable of deleting branches, and would have to answer what
+ * `--adw-id` even means when there are N of them. `run.ts` is untouched.
+ *
+ * SPF DOES NOT MERGE THE WINNER. It hands back a branch name, an adw_id and
+ * the basis on which that branch was chosen; a human merges or cherry-picks
+ * it. That is the accountability line this command must not cross — every
+ * other route (auto-merge, auto-push) removes the one human decision that
+ * makes N machine-written candidates safe to have produced at all.
+ */
+import { spawnSync } from "node:child_process";
+import { appendFileSync, existsSync, mkdirSync, readdirSync, readFileSync, symlinkSync } from "node:fs";
+import { homedir } from "node:os";
+import path from "node:path";
+import * as agents from "../../core/agents.js";
+import * as paths from "../../core/paths.js";
+import { isRepoAt, makeGit } from "../../core/git_helper.js";
+import { ABORTED_EXIT, attemptAdwId, runBestOf, ZERO_METRICS, } from "../../core/fanout.js";
+import { findChain, runChain as runChainDef } from "../../chains/index.js";
+import { SfDb } from "../../ui/server/db.js";
+import { newId, parseCli, resolvePrompt } from "../../core/utils.js";
+/**
+ * A ceiling on `--n`, not a recommendation. Each attempt is a full chain run
+ * with its own agents, so `--n` multiplies spend directly — and the machine
+ * also pays in worktrees, concurrent SQLite writers and disk. Anyone who
+ * genuinely wants more than this should be running a script that says so out
+ * loud, not typing a bigger number into an interactive command.
+ */
+const MAX_N = 8;
+const USAGE = `usage: spf fanout <chain> "<prompt or path/to/prompt.md>" [--n 3] [--concurrency N] ` +
+    `[--base <branch>] [--adw-id <id>] [--first-success] [--config <path>] [--cwd <dir>]\n` +
+    `       spf fanout --clean <base-adw-id> [--cwd <dir>]   # remove leftover worktrees/branches from a killed or discarded run`;
+/** Chains eligible to fan out: their derived phase string must show at least one commit step. See the check at dispatch time for why. */
+function hasCommitStep(phases) {
+    return phases.includes("git(commit");
+}
+/** `42.1s` / `3m 07s` — a wall time a human reads, not a millisecond count. */
+function formatDuration(ms) {
+    const seconds = ms / 1000;
+    if (seconds < 90)
+        return `${seconds.toFixed(1)}s`;
+    const minutes = Math.floor(seconds / 60);
+    return `${minutes}m ${String(Math.round(seconds - minutes * 60)).padStart(2, "0")}s`;
+}
+function formatGates(attempt) {
+    if (attempt.status === "skipped")
+        return "-";
+    return `${attempt.gate_passes}p/${attempt.gate_failures}f`;
+}
+/**
+ * The result table. Fixed column widths over a `console.table`: every other
+ * `spf` listing (`sessions`, `phases`) prints plain padded columns, and this
+ * output is read in a terminal beside them.
+ */
+function printTable(attempts) {
+    const widths = {
+        adw: Math.max(6, ...attempts.map((a) => a.adw_id.length)),
+        branch: Math.max(6, ...attempts.map((a) => a.branch.length)),
+    };
+    console.log(`  ${"#".padEnd(3)}${"adw_id".padEnd(widths.adw + 2)}${"branch".padEnd(widths.branch + 2)}` +
+        `${"status".padEnd(9)}${"gates".padEnd(9)}${"cost".padEnd(10)}time`);
+    for (const a of attempts) {
+        console.log(`  ${String(a.index).padEnd(3)}${a.adw_id.padEnd(widths.adw + 2)}${a.branch.padEnd(widths.branch + 2)}` +
+            `${a.status.padEnd(9)}${formatGates(a).padEnd(9)}${agents.formatUsd(a.cost).padEnd(10)}` +
+            `${a.status === "skipped" ? "-" : formatDuration(a.wall_ms)}` +
+            `${a.error ? `\n      error: ${a.error}` : ""}`);
+    }
+}
+/**
+ * Wire `<worktreePath>/.spf/data` to the main repo's `dataDir` — same
+ * purpose as `cli/commands/watch.ts`'s own `linkDataDir`: without it an
+ * attempt's chain resolves its session/trace data relative to `cwd` (its
+ * worktree) and writes into a fresh `.spf/data` that dies with the
+ * worktree — invisible in `spf ui`, and gone before `readMetrics` could even
+ * read the gate rows that DECIDE the winner. Symlinking it to the main
+ * repo's data dir is what makes the shared WAL SQLite the one place all N
+ * attempts report to (`tracer.ts`'s WAL + `busy_timeout=5000` is exactly
+ * what concurrent writers through this symlink already rely on under `spf
+ * watch`). Idempotent. A plain function of its two inputs (not a closure
+ * over `dataPaths`) so it can be exercised directly in a test, against a
+ * real filesystem and a real git worktree, without a real chain or agent.
+ *
+ * `mkdirSync(dataDir, ...)` BEFORE the symlink is not optional: a fresh
+ * clone with `.spf/` committed (`.spf/data` gitignored), or a repo straight
+ * out of `spf init` (which seeds `.spf/` and `.spf/chains/` but never
+ * `.spf/data` — nothing has traced a run there yet) has no `.spf/data` to
+ * point at. Without this, the symlink is dangling and every attempt's `Run`
+ * constructor fails its own `ensureDir` on first use — `spf fanout` would be
+ * broken on a repo's first ever run.
+ */
+export function linkFanoutDataDir(worktreePath, dataDir) {
+    const target = path.join(worktreePath, ".spf", "data");
+    if (!existsSync(target)) {
+        mkdirSync(dataDir, { recursive: true });
+        mkdirSync(path.dirname(target), { recursive: true });
+        symlinkSync(dataDir, target, "dir");
+    }
+    excludeSpfDataFromGit(worktreePath);
+}
+/**
+ * Keep the `.spf/data` symlink invisible to `git status`/`git add -A` in the
+ * attempt's own worktree. `.spf/data/` — a trailing-slash DIRECTORY pattern,
+ * the shape this repo's own gitignore uses — does NOT match a SYMLINK of
+ * the same name, so without this, `git status` shows `?? .spf/data` and a
+ * committing chain's `git_helper.commitAll` (`git add -A`) stages it.
+ * Following the printed `git merge <winner-branch>` instruction then
+ * fast-forwards the symlink straight into the MAIN repo, replacing its real
+ * `.spf/data` directory with a symlink pointing back at itself — destroying
+ * the trace db (`ls .spf/data` becomes `ELOOP`). `info/exclude` is
+ * per-worktree, local-only, and idempotent to append to — the opposite of
+ * adding a pattern to a tracked `.gitignore`, which would ship this
+ * workaround into every clone for a symlink only `spf fanout` itself ever
+ * creates.
+ */
+export function excludeSpfDataFromGit(worktreePath) {
+    const resolved = spawnSync("git", ["rev-parse", "--git-path", "info/exclude"], { cwd: worktreePath, encoding: "utf-8" });
+    if (resolved.status !== 0)
+        return; // best-effort: worst case is the pre-existing staging risk, not a crash
+    const excludePath = path.resolve(worktreePath, resolved.stdout.trim());
+    const line = ".spf/data";
+    const existing = existsSync(excludePath) ? readFileSync(excludePath, "utf-8") : "";
+    if (existing.split("\n").some((l) => l.trim() === line))
+        return;
+    mkdirSync(path.dirname(excludePath), { recursive: true });
+    appendFileSync(excludePath, `${existing && !existing.endsWith("\n") ? "\n" : ""}${line}\n`);
+}
+/**
+ * `spf fanout --clean <base-adw-id>` — the cleanup half of the deterministic
+ * naming, for the two cases nothing else reaches: a run killed before its
+ * own `finally`s ran (SIGINT swallowed by a synchronous `spawnSync` phase, or
+ * `process.exit()` racing worktree cleanup — see `core/fanout.ts`'s lack of
+ * a cancellation seam), and a winner an operator has since merged/rejected
+ * and now wants gone. Matches by PREFIX rather than an index range: `--n`
+ * varies run to run, and a killed run may have left an arbitrary subset.
+ * `--force` on the worktree removal is deliberate and irreversible — this is
+ * explicitly a "the trees are trash now" command, unlike a normal run's own
+ * cleanup, which never force-removes a dirty tree it didn't already decide
+ * to discard (see `git_helper.ts`'s `createRunWorktree`).
+ */
+function cleanFanoutAttempts(baseAdwId, cwdOpt) {
+    const anchor = paths.resolveAnchor(cwdOpt);
+    if (!isRepoAt(anchor.repo_root)) {
+        console.error(`${anchor.repo_root} is not a git repository`);
+        return 1;
+    }
+    const worktreesDir = path.join(homedir(), ".spf", "fanout", path.basename(anchor.repo_root), "worktrees");
+    const git = makeGit(anchor.repo_root);
+    let removed = 0;
+    if (existsSync(worktreesDir)) {
+        for (const entry of readdirSync(worktreesDir)) {
+            if (!entry.startsWith(`fanout-${baseAdwId}-`))
+                continue;
+            const worktreePath = path.join(worktreesDir, entry);
+            spawnSync("git", ["worktree", "remove", "--force", worktreePath], { cwd: anchor.repo_root, encoding: "utf-8" });
+            console.log(`[spf] fanout    removed worktree ${worktreePath}`);
+            removed++;
+        }
+    }
+    const branchList = spawnSync("git", ["branch", "--list", `spf/fanout/${baseAdwId}-*`], {
+        cwd: anchor.repo_root,
+        encoding: "utf-8",
+    });
+    for (const line of (branchList.stdout || "").split("\n")) {
+        const branch = line.replace(/^\*?\s+/, "").trim();
+        if (!branch)
+            continue;
+        git.deleteLocalBranch(branch);
+        console.log(`[spf] fanout    deleted branch ${branch}`);
+        removed++;
+    }
+    if (removed === 0) {
+        console.log(`[spf] fanout    nothing to clean for ${baseAdwId} — no worktree or branch under that base id`);
+    }
+    return 0;
+}
+export async function fanoutCommand(argv) {
+    const { positionals, options, flags } = parseCli(argv, ["cwd", "config", "n", "concurrency", "base", "adw-id", "clean"], ["first-success"]);
+    if (options["clean"]) {
+        return cleanFanoutAttempts(options["clean"], options["cwd"]);
+    }
+    if (positionals.length < 2) {
+        console.error(USAGE);
+        return 1;
+    }
+    const [chainName, promptArg] = positionals;
+    const chain = findChain(chainName);
+    if (!chain) {
+        console.error(`unknown chain: ${chainName} — run \`spf list\` to see every chain`);
+        return 1;
+    }
+    if (!hasCommitStep(chain.phases)) {
+        // A winner with no commit step leaves its payload ONLY as uncommitted
+        // edits in the kept worktree — the branch this command hands back would
+        // carry zero commits, so `git merge`/`git cherry-pick` would be a no-op,
+        // and the printed `git worktree remove` cleanup line would DESTROY the
+        // only copy of the work. Refuse up front rather than print a lie.
+        console.error(`spf fanout: "${chain.name}" has no commit phase (${chain.phases}) — its winner's branch would carry zero ` +
+            `commits, and the work would exist only as uncommitted edits in a worktree that "git worktree remove" ` +
+            `would then destroy. Use a chain that commits (e.g. plan-build, plan-build-test, ` +
+            `plan-build-test-quality, simple-sdlc), or a repo-local chain (.spf/chains/*.yaml) with a commit step.`);
+        return 1;
+    }
+    const n = options["n"] ? Number.parseInt(options["n"], 10) : 3;
+    if (!Number.isInteger(n) || n < 2 || n > MAX_N) {
+        console.error(`--n must be an integer between 2 and ${MAX_N} (got ${JSON.stringify(options["n"] ?? "3")}) — for a single run use \`spf run ${chainName}\``);
+        return 1;
+    }
+    const anchor = paths.resolveAnchor(options["cwd"]);
+    if (!isRepoAt(anchor.repo_root)) {
+        // Not a nicety: every attempt IS a git worktree off a base branch. Without
+        // a repo there is nothing to isolate runs from each other with, and the
+        // "winner is a branch a human merges" contract has nothing to hand back.
+        console.error(`${anchor.repo_root} is not a git repository — spf fanout runs each attempt in its own git worktree`);
+        return 1;
+    }
+    const configPaths = paths.resolveConfigPaths(anchor, options["config"]).paths;
+    const cfg = agents.loadConfig(configPaths);
+    const dataPaths = paths.resolveDataPaths(anchor, cfg.defaults.data_dir, cfg.observability.db);
+    const git = makeGit(anchor.repo_root);
+    // Reused rather than given a knob of its own: `watch.concurrency` (default
+    // 2) is already this repo's answer to "how many chains may run at once
+    // here", and it is the same machine, the same SQLite and the same agent
+    // quota either way. `--concurrency` overrides it for one invocation.
+    const concurrency = options["concurrency"] ? Number.parseInt(options["concurrency"], 10) : cfg.watch.concurrency;
+    if (!Number.isInteger(concurrency) || concurrency < 1) {
+        console.error(`--concurrency must be a positive integer (got ${JSON.stringify(options["concurrency"])})`);
+        return 1;
+    }
+    const baseBranch = options["base"] ?? cfg.watch.base_branch;
+    const baseAdwId = options["adw-id"] ?? newId(8);
+    const worktreesDir = path.join(homedir(), ".spf", "fanout", path.basename(anchor.repo_root), "worktrees");
+    // Fail fast on a `--adw-id` reused from a previous fanout invocation.
+    // `readMetrics` (below) keys purely on adw_id, and `tracer.sessionStart`
+    // upserts an EXISTING session row (`status='running'`) while
+    // `sessionAddUsage` ACCUMULATES onto it — so a collision would silently mix
+    // the previous run's cost/tokens/gate rows into this run's selection
+    // basis, and the human reading `basis:` would be told a wrong reason.
+    if (existsSync(dataPaths.db_path)) {
+        const preflight = new SfDb(dataPaths.db_path);
+        try {
+            const collisions = Array.from({ length: n }, (_, i) => attemptAdwId(baseAdwId, i + 1)).filter((id) => preflight.session(id) !== null);
+            if (collisions.length > 0) {
+                console.error(`--adw-id ${baseAdwId} already has session rows for ${collisions.join(", ")} from a previous fanout ` +
+                    `run — reusing it would mix that run's cost/tokens/gates into this one's selection basis. Use a ` +
+                    `fresh --adw-id (or omit the flag to get one generated), or \`spf fanout --clean ${baseAdwId}\` first ` +
+                    `if that previous run is done with.`);
+                return 1;
+            }
+        }
+        finally {
+            preflight.close();
+        }
+    }
+    if (cfg.defaults.max_run_cost === undefined && cfg.defaults.max_run_tokens === undefined) {
+        // Not an error — an unbounded run is the documented default. But `--n` is
+        // a spend multiplier, and this is the one moment the operator is asking
+        // for N times the bill, so it is the honest moment to mention the ceiling
+        // exists. See ConfigDefaultsSchema's budget block.
+        console.log(`[spf] fanout    no defaults.max_run_cost / defaults.max_run_tokens configured — ` +
+            `${n} attempts will run to completion unbounded`);
+    }
+    const linkDataDir = (worktreePath) => linkFanoutDataDir(worktreePath, dataPaths.data_dir);
+    /**
+     * The shared db, opened lazily and once: it does not exist until the first
+     * attempt's tracer creates it, and `SfDb`'s constructor throws on a missing
+     * file. Readonly + WAL, so reading one finished attempt's rows while its
+     * siblings are still writing is exactly the access pattern the tracer's
+     * PRAGMAs are set up for.
+     */
+    // A holder rather than a bare `let`: assigned only inside the closure below,
+    // a plain local narrows to `null` everywhere else and the `finally`'s
+    // `close()` stops typechecking.
+    const held = { db: null };
+    function readMetrics(adwId) {
+        if (!held.db) {
+            if (!existsSync(dataPaths.db_path))
+                return ZERO_METRICS;
+            held.db = new SfDb(dataPaths.db_path);
+        }
+        const gates = held.db.gates(adwId);
+        const session = held.db.session(adwId);
+        // `passed` is a SQLite integer boolean that CAN be NULL on a row an older
+        // tracer wrote. Counted explicitly in both directions, never as
+        // `!g.passed`: a NULL is unknown, and letting it read as a failure would
+        // let a garbled row decide which candidate a human is told to merge.
+        return {
+            gate_passes: gates.filter((g) => g.passed === 1).length,
+            gate_failures: gates.filter((g) => g.passed === 0).length,
+            cost: session?.total_cost ?? 0,
+            tokens: session?.total_tokens ?? 0,
+        };
+    }
+    const runAttempt = async (dispatch) => {
+        // Cooperative abort, checked at the last possible moment before spend
+        // begins — a sibling can win between this attempt being pulled off the
+        // queue and its first agent call. See core/fanout.ts's ABORT GRANULARITY
+        // note for what this does and does not cover.
+        if (dispatch.isAborted())
+            return ABORTED_EXIT;
+        const ctx = {
+            prompt: dispatch.prompt,
+            config_paths: configPaths,
+            adw_id: dispatch.adwId,
+            // The attempt's OWN worktree. This is the anchor `session.ensure` binds
+            // the Run's repo_root to, once — which is what puts the gates,
+            // permissions snapshot, quality checks and changes capture on the tree
+            // these agents actually wrote in.
+            cwd: dispatch.cwd,
+            // Kept resolvable on purpose: this is the name `findChain` answers to,
+            // and `session.ensure` records it as the session's `adw_name`. The
+            // fan-out provenance rides the derived adw_id (`<base>-<i>`) and the
+            // branch instead — `chain_source` is contractually the absolute path of
+            // a `.spf/chains/*.yaml` file (see ChainContext), and a marker string
+            // stuffed in there would lie to `spf ui` about where the chain came from.
+            chain_name: chain.name,
+            // Nobody is at a TTY for attempt 2 of 3 — a chain that would prompt
+            // (simple-sdlc's sign-off) must take its unattended path, or N-1
+            // attempts would block forever on a prompt only one of them can show.
+            unattended: true,
+            chain_source: chain.source,
+        };
+        return runChainDef(chain, ctx);
+    };
+    // Best-effort operator guidance on an abnormal exit — NOT a real
+    // cancellation. Every code phase runs through a synchronous `spawnSync`
+    // (`core/quality.ts`), which blocks the event loop while it runs, so a
+    // SIGINT delivered during one is not even observed until it returns; an
+    // attempt whose chain HAS reached an async agent phase may still finalize
+    // its own session via `process.exit()` (`core/session.ts`'s
+    // `finalizeWhenKilled`) before this handler's log line ever flushes. What
+    // this reliably buys, in the case it can't prevent, is telling the
+    // operator the one thing the trace can't: which base adw_id to hand to
+    // `--clean` afterwards.
+    let interrupted = false;
+    const onSignal = (signal) => {
+        if (interrupted)
+            return;
+        interrupted = true;
+        console.error(`\n[spf] fanout: ${signal} received — attempts already past their last checkpoint run to completion. ` +
+            `Once everything has settled, clean up anything left under this base id with:\n` +
+            `  spf fanout --clean ${baseAdwId}\n`);
+        process.exit(130);
+    };
+    process.on("SIGINT", onSignal);
+    process.on("SIGTERM", onSignal);
+    try {
+        const result = await runBestOf({
+            chainName: chain.name,
+            prompt: resolvePrompt(promptArg),
+            n,
+            concurrency,
+            baseAdwId,
+            baseBranch,
+            repoRoot: anchor.repo_root,
+            worktreesDir,
+            git,
+            linkDataDir,
+            runAttempt,
+            readMetrics,
+            firstSuccess: flags["first-success"],
+            log: (message) => console.log(`[spf] ${message}`),
+        });
+        console.log(`\nfanout ${chain.name} — ${n} attempt(s), base ${baseBranch}`);
+        printTable(result.attempts);
+        if (!result.winner) {
+            console.error(`\nno winner: ${result.basis}`);
+            console.error(`Any attempt whose chain got far enough to open a session has its trace in the shared db — ` +
+                `\`spf phases <adw_id>\` to check (an attempt that failed before then, e.g. a worktree collision, has none).`);
+            return 1;
+        }
+        console.log(`\nwinner:  ${result.winner.adw_id}  branch ${result.winner.branch}`);
+        console.log(`basis:   ${result.basis}`);
+        console.log(`         (selection basis: succeeded > fewest gate failures > most gate passes > lowest cost > ` +
+            `fewest tokens > lowest wall time (contended under concurrency, last resort) > adw_id)`);
+        console.log(`kept:    ${result.winner.worktree}`);
+        console.log(`\nSPF does not merge the winner — you do:`);
+        console.log(`  git merge ${result.winner.branch}          # or: git cherry-pick <sha> / git diff ${baseBranch}..${result.winner.branch}`);
+        console.log(`  git worktree remove --force ${result.winner.worktree} && git branch -d ${result.winner.branch}   ` +
+            `# when you're done with it — --force is required (the .spf/data symlink always makes the tree` +
+            ` "dirty" to git) and will discard anything you haven't committed or merged out of it first`);
+        console.log(`The other attempts' worktrees and branches were deleted; their traces remain in the db (\`spf phases <adw_id>\`).`);
+        return 0;
+    }
+    finally {
+        held.db?.close();
+        process.off("SIGINT", onSignal);
+        process.off("SIGTERM", onSignal);
+    }
+}

package/dist/cli/commands/init.js

@@ -126,6 +126,25 @@ const STARTER_CONFIG = `# .spf/spf.config.yaml — merged ON TOP of spf's packag
 # review:
 #   require_human_signoff: false   # true = an unattended simple-sdlc run fails closed instead of committing on the reviewer's verdict alone
 #   signoff_timeout_seconds: 300
+
+# Uncomment to route roles to cheaper/stronger models by a run-global risk
+# signal (chain kind + prompt length) — OFF by default, and absence/false is
+# a TOTAL no-op: every agent dispatches at exactly the model its roster
+# entry names. \`spf init --template ts-flue-ollama\` ships this ON with two
+# MEASURED local tags; this starter leaves it off and commented because no
+# tag below has been measured against YOUR roster. See
+# assets/skill/references/config.md's "tiering" section for the full
+# mechanism (the ladder walk, rule T, the availability probe) before turning
+# this on — \`spf doctor\` checks these rungs the same way it checks
+# cfg.agents[].model, but ONLY once enabled: true.
+# tiering:
+#   enabled: true
+#   tiers:
+#     - { name: cheap,  coding_agent: flue, model: google/gemini-3.6-flash }
+#     - { name: strong, coding_agent: flue, model: openai/gpt-5.6-terra }
+#   roles:
+#     builder: cheap
+#     reviewer: strong
 `;
 // .spf/spf.config.yaml and .spf/prompt_engineering/ stay tracked — they're
 // shared project config, same as package.json. Only runtime/generated

package/dist/cli/commands/trace.d.ts

@@ -1,8 +1,26 @@
 import * as paths from "../../core/paths.ts";
+import type { SFConfig } from "../../core/data_types.ts";
 import { SfDb } from "../../ui/server/db.ts";
 export interface TraceHandle {
     db: SfDb;
     anchor: paths.RepoAnchor;
     dataDir: string;
+    /** Already loaded by this same resolution — `spf estimate` needs it (ceilings, resolveTiering) and reusing it means one loadConfig, not two. */
+    cfg: SFConfig;
 }
 export declare function openTrace(options: Record<string, string>): TraceHandle;
+/**
+ * Like `openTrace`, but never throws on a missing db file: `db` is `null`
+ * in that one slot instead. `anchor`/`dataDir`/`cfg` still come from the
+ * SAME `resolveTrace` call either way — a cold start (no `spf.db` yet)
+ * still carries a real, loaded `cfg`, which is what lets `spf estimate`
+ * echo `defaults.max_run_tokens`/`max_run_cost` and resolve planned routing
+ * before it exits, rather than crashing with `SfDb`'s "point spf ui at a
+ * target repo" message (which is about `spf ui`, not `spf estimate`).
+ */
+export declare function openTraceIfExists(options: Record<string, string>): {
+    db: SfDb | null;
+    anchor: paths.RepoAnchor;
+    dataDir: string;
+    cfg: SFConfig;
+};

package/dist/cli/commands/trace.js

@@ -1,10 +1,29 @@
-/** Shared by sessions/phases/events/abort — resolve the workspace and open its trace db. */
+/** Shared by sessions/phases/events/abort/estimate — resolve the workspace and open its trace db. */
+import { existsSync } from "node:fs";
 import * as agents from "../../core/agents.js";
 import * as paths from "../../core/paths.js";
 import { SfDb } from "../../ui/server/db.js";
-export function openTrace(options) {
+/** The one place anchor/config/data-path resolution happens, so `openTrace` and `openTraceIfExists` cannot diverge on it. */
+function resolveTrace(options) {
     const anchor = paths.resolveAnchor(options["cwd"]);
     const cfg = agents.loadConfig(paths.resolveConfigPaths(anchor, options["config"]).paths);
     const dataPaths = paths.resolveDataPaths(anchor, cfg.defaults.data_dir, cfg.observability.db);
-    return { db: new SfDb(dataPaths.db_path), anchor, dataDir: dataPaths.data_dir };
+    return { dbPath: dataPaths.db_path, anchor, dataDir: dataPaths.data_dir, cfg };
+}
+export function openTrace(options) {
+    const { dbPath, anchor, dataDir, cfg } = resolveTrace(options);
+    return { db: new SfDb(dbPath), anchor, dataDir, cfg };
+}
+/**
+ * Like `openTrace`, but never throws on a missing db file: `db` is `null`
+ * in that one slot instead. `anchor`/`dataDir`/`cfg` still come from the
+ * SAME `resolveTrace` call either way — a cold start (no `spf.db` yet)
+ * still carries a real, loaded `cfg`, which is what lets `spf estimate`
+ * echo `defaults.max_run_tokens`/`max_run_cost` and resolve planned routing
+ * before it exits, rather than crashing with `SfDb`'s "point spf ui at a
+ * target repo" message (which is about `spf ui`, not `spf estimate`).
+ */
+export function openTraceIfExists(options) {
+    const { dbPath, anchor, dataDir, cfg } = resolveTrace(options);
+    return { db: existsSync(dbPath) ? new SfDb(dbPath) : null, anchor, dataDir, cfg };
 }

package/dist/cli/commands/watch.js

@@ -260,6 +260,17 @@ export async function watchCommand(argv) {
      */
     function linkDataDir(worktreePath) {
         const target = path.join(worktreePath, ".spf", "data");
+        // Hard guard, independent of however `worktreePath` got resolved: a real
+        // self-referential .spf/data symlink was observed live once already
+        // (points at itself — every later `mkdirSync` through it throws ELOOP;
+        // see `paths.healBrokenDataDir` for the recovery side of this same bug).
+        // The exact trigger was never pinned down, but `worktreePath` resolving
+        // to the main repo's own `data_dir` can never be correct regardless of
+        // how it got there, so refuse outright rather than create it again.
+        if (path.resolve(target) === path.resolve(dataPaths.data_dir)) {
+            console.error(`watch: refusing to link ${target} to itself — worktree path resolved to the main repo's own data_dir`);
+            return;
+        }
         if (existsSync(target))
             return;
         mkdirSync(path.dirname(target), { recursive: true });
@@ -341,17 +352,19 @@ export async function watchCommand(argv) {
             unattended: true,
             chain_source: chainDef.source,
         };
-        // KNOWN LIMITATION (not fixed here): runChainDef is called below with no
-        // third `options` argument, so nothing --suite-shaped ever reaches this
-        // dispatch — `resolveRequiredSuites`/`resolveRequiredAgents` below both
-        // fall back to each chain's compiled-in/YAML-declared default. An
-        // unattended watch run therefore can't override a chain's suite the way
-        // an interactive `spf <chain> --suite <name>` can.
-        const code = await runChainDef(chainDef, ctx);
-        // Static for every chain but "prompt" (whose --agent flag `spf watch`
-        // never passes) — resolved with no options, exactly like `runChainDef`
-        // above ran it.
-        const reviewRequired = resolveRequiredAgents(chainDef, {}).includes("reviewer");
+        // `opts.chainOptions` is `watch.chain_options` (see WatchConfigSchema's
+        // doc comment), threaded down from `deps.chainOptions` by
+        // `core/watch.ts`'s `runIssue` — the same options-map shape an
+        // interactive `spf <chain> --suite <name>` builds in
+        // `cli/commands/run.ts`'s `dispatchChain`. This closes the KNOWN
+        // LIMITATION from PR #20: an unattended watch dispatch used to call
+        // `runChainDef` with no options at all, so nothing --suite-shaped could
+        // ever reach it.
+        const code = await runChainDef(chainDef, ctx, opts.chainOptions);
+        // Resolved with the SAME options `runChainDef` just ran the chain with,
+        // so a `chain_options` override that swaps a "reviewer" step in or out
+        // is reflected here too, not just each chain's static/YAML default.
+        const reviewRequired = resolveRequiredAgents(chainDef, opts.chainOptions).includes("reviewer");
         if (code === 0) {
             return { accepted: true, adwId: opts.adwId, detail: "", reviewRequired, reviewSummary: reviewSummaryFor(opts.cwd, opts.adwId) };
         }
@@ -360,11 +373,15 @@ export async function watchCommand(argv) {
     };
     /**
      * Same shape as `runChain`, for the refine lane — with one extra step on
-     * success: a chain's return value is just an exit code, so the created-
-     * issues list `steps.publishIssues()` actually produced has to come back
-     * through the side channel it wrote (`refine_publish.json`, under the
-     * SAME symlinked session dir `linkDataDir` already wires up), not through
-     * `runChainDef`'s return value.
+     * success: a chain's return value is just an exit code, so what
+     * `steps.publishIssues()` actually did — published a tree, OR escalated a
+     * question set instead — has to come back through the side channel it
+     * wrote (`refine_publish.json` or `refine_questions.json`, under the SAME
+     * symlinked session dir `linkDataDir` already wires up), not through
+     * `runChainDef`'s return value. The two are read independently and both
+     * default to `[]`: `gates.refinementWellFormed` guarantees a chain never
+     * writes both files in the same run, so exactly one of `created`/
+     * `questions` is ever non-empty on an accepted run.
      */
     const runRefine = async (opts) => {
         const chainDef = findChain(cfg.watch.refine.chain); // checked above
@@ -375,28 +392,35 @@ export async function watchCommand(argv) {
             cwd: opts.cwd,
             chain_name: chainDef.name,
             issue_id: opts.issueId,
-            // Same reasoning as runChain's ctx above — an unattended dispatch,
-            // with no --suite-shaped options reaching it either (same KNOWN
-            // LIMITATION).
+            // Same reasoning as runChain's ctx above — an unattended dispatch.
             unattended: true,
             chain_source: chainDef.source,
         };
-        const code = await runChainDef(chainDef, ctx);
+        // Same `watch.chain_options` threading as runChain above — see its
+        // comment for the KNOWN LIMITATION this fixes.
+        const code = await runChainDef(chainDef, ctx, opts.chainOptions);
         if (code !== 0) {
             const detail = detailFromFailedPhase(opts.cwd, opts.adwId, `Refine chain "${cfg.watch.refine.chain}" (adw_id ${opts.adwId}) did not complete successfully. Run \`spf phases ${opts.adwId} --cwd ${opts.cwd}\` for detail.`);
-            return { accepted: false, adwId: opts.adwId, detail, created: [] };
+            return { accepted: false, adwId: opts.adwId, detail, created: [], questions: [] };
         }
+        const wtAnchor = paths.resolveAnchor(opts.cwd);
+        const wtDataPaths = paths.resolveDataPaths(wtAnchor, cfg.defaults.data_dir, cfg.observability.db);
+        const handoffDir = path.join(wtDataPaths.data_dir, "sessions", opts.adwId, "context_handoff");
         let created = [];
         try {
-            const wtAnchor = paths.resolveAnchor(opts.cwd);
-            const wtDataPaths = paths.resolveDataPaths(wtAnchor, cfg.defaults.data_dir, cfg.observability.db);
-            const summaryPath = path.join(wtDataPaths.data_dir, "sessions", opts.adwId, "context_handoff", "refine_publish.json");
-            created = JSON.parse(readFileSync(summaryPath, "utf-8"));
+            created = JSON.parse(readFileSync(path.join(handoffDir, "refine_publish.json"), "utf-8"));
         }
         catch {
             // best-effort — an empty list still lets runSpec finish cleanly, just with no per-issue summary
         }
-        return { accepted: true, adwId: opts.adwId, detail: "", created };
+        let questions = [];
+        try {
+            questions = JSON.parse(readFileSync(path.join(handoffDir, "refine_questions.json"), "utf-8"));
+        }
+        catch {
+            // best-effort, same as above — no questions file means this run wasn't an escalation
+        }
+        return { accepted: true, adwId: opts.adwId, detail: "", created, questions };
     };
     const deps = {
         provider,
@@ -407,6 +431,7 @@ export async function watchCommand(argv) {
         chain: cfg.watch.chain,
         baseBranch: cfg.watch.base_branch,
         concurrency: cfg.watch.concurrency,
+        chainOptions: cfg.watch.chain_options,
         refineEnabled: cfg.watch.refine.enabled,
         refineConcurrency: cfg.watch.refine.concurrency,
         refineChain: cfg.watch.refine.chain,