npm - @gr8ful/spf - Versions diffs - 0.9.1 → 0.10.0 - Mend

@gr8ful/spf 0.9.1 → 0.10.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (38) hide show

package/README.md +56 -0
package/assets/defaults/spf.config.yaml +75 -0
package/assets/skill/references/config.md +98 -4
package/dist/chains/index.d.ts +2 -0
package/dist/chains/index.js +4 -0
package/dist/cli/commands/doctor.js +339 -2
package/dist/cli/commands/fanout.d.ts +7 -14
package/dist/cli/commands/fanout.js +45 -39
package/dist/cli/commands/loop.d.ts +2 -0
package/dist/cli/commands/loop.js +198 -0
package/dist/cli/commands/run.js +14 -4
package/dist/cli/commands/watch.d.ts +29 -1
package/dist/cli/commands/watch.js +219 -64
package/dist/cli/index.js +14 -0
package/dist/cli/interview.js +40 -16
package/dist/core/agent_cc.d.ts +11 -0
package/dist/core/agent_cc.js +25 -2
package/dist/core/agent_flue.js +14 -5
package/dist/core/agents.d.ts +61 -1
package/dist/core/agents.js +363 -6
package/dist/core/data_types.d.ts +316 -0
package/dist/core/data_types.js +143 -0
package/dist/core/loop.d.ts +230 -0
package/dist/core/loop.js +290 -0
package/dist/core/quality.d.ts +1 -2
package/dist/core/sandbox.d.ts +236 -0
package/dist/core/sandbox.js +655 -0
package/dist/core/sandbox_cloudflare.d.ts +137 -0
package/dist/core/sandbox_cloudflare.js +505 -0
package/dist/core/sandbox_opensandbox.d.ts +59 -0
package/dist/core/sandbox_opensandbox.js +484 -0
package/dist/core/sandbox_sdk_types.d.ts +171 -0
package/dist/core/sandbox_sdk_types.js +20 -0
package/dist/core/watch.d.ts +56 -0
package/dist/core/watch.js +354 -51
package/dist/core/worktree_data.d.ts +1 -0
package/dist/core/worktree_data.js +37 -0
package/package.json +1 -1

package/dist/cli/commands/loop.js ADDED Viewed

@@ -0,0 +1,198 @@
+/**
+ * `spf loop <chain> "<goal>" --until-suite <name> --max N` — the wiring half
+ * of `core/loop.ts` (which owns the driver, the ledger, and the breakers):
+ * config, the issue fetch for `--issue`, the per-iteration `runChain`
+ * dispatch, the sqlite readback, and the final table. Same split as
+ * `core/fanout.ts` / `cli/commands/fanout.ts` for the same reason — `core/`
+ * stays out of `src/chains/`'s dependency direction, so the driver is
+ * testable with no chains, no agents, no real git.
+ *
+ * `--issue <id>` resolves the SAME `IssueProvider` `spf watch` does
+ * (`resolveIssueProvider`, exported from `watch.ts` for exactly this reuse)
+ * and builds the goal prompt the same way `core/watch.ts`'s `runIssue` does
+ * — `${issue.title}\n\n${issue.body}`.trim() — so a ticket-pointed loop and
+ * a hand-typed one share one prompt convention. This is deliberately the
+ * ONLY thing `--issue` does: it does not claim, label, or comment on the
+ * issue, and no daemon watches it. Filing the goal AS a ticket the daemon
+ * picks up on its own is a different, larger feature (a `goal-ready` watch
+ * lane) that needs its own crash-safe marker schema and is not this.
+ */
+import { existsSync } from "node:fs";
+import * as agents from "../../core/agents.js";
+import * as paths from "../../core/paths.js";
+import * as quality from "../../core/quality.js";
+import { makeGit } from "../../core/git_helper.js";
+import { cumulativeSpend, resolveGoalId, runLoop, summarize, } from "../../core/loop.js";
+import { findChain, runChain as runChainDef } from "../../chains/index.js";
+import { SfDb } from "../../ui/server/db.js";
+import { parseCli, resolvePrompt } from "../../core/utils.js";
+import { isInteractive } from "../ask.js";
+import { resolveIssueProvider } from "./watch.js";
+/**
+ * Just enough of `Run` for `quality.resolveSuite`/`runSuite` (`RunLike` in
+ * `core/quality.ts`) to work against a real filesystem/console without a
+ * full agent-capable `Run` — this driver never opens an agent phase itself
+ * (`runChainDef` already did, inside the chain), it only needs to run one
+ * more deterministic check afterward. `phases: [{seq: 0, ...}]` gives
+ * `checkDir`'s `run.phases[run.phases.length - 1].seq` something real to
+ * read, mirroring a genuine single-phase run rather than faking the type.
+ */
+function qualityRunLike(input) {
+    return {
+        cfg: { quality: input.cfg.quality },
+        phases: [{ phase_id: `${input.adwId}_00_loop_stop`, adw_id: input.adwId, seq: 0, params: { name: "loop_stop", kind: "code", owner: "quality", description: "loop stop check", retries: 0 }, status: "running", attempt: 0 }],
+        context_handoff_dir: input.contextHandoffDir,
+        repo_root: input.repoRoot,
+        console: { note: (message) => console.log(`[spf] loop    ${message}`) },
+        tracer: { event: () => "" },
+        adw_id: input.adwId,
+    };
+}
+const KNOWN_OPTIONS = ["config", "cwd", "issue", "until-suite", "max", "max-cost", "max-tokens", "stuck-after", "min-interval-ms", "goal-id", "base"];
+export const USAGE = `usage: spf loop <chain> "<goal or path/to/goal.md>" --until-suite <name> --max <N> [--issue <id>] ` +
+    `[--max-cost <usd>] [--max-tokens <n>] [--stuck-after <n>=3] [--min-interval-ms <n>=0] [--goal-id <id>] ` +
+    `[--config <path>] [--cwd <dir>] [--base <ref>]\n` +
+    `A goal cannot be judged by pixels in v1 — --until-suite names a quality.suites check (exit code = met), never a raw shell string.`;
+/** `<title>\n\n<body>` — the exact prompt convention `core/watch.ts`'s `runIssue` uses, so a ticket-pointed loop and the build lane read a ticket identically. */
+function promptFromIssue(issue) {
+    return `${issue.title}\n\n${issue.body}`.trim();
+}
+export async function loopCommand(argv) {
+    const { positionals, options } = parseCli(argv, KNOWN_OPTIONS);
+    if (positionals.length < 1) {
+        console.error(USAGE);
+        return 1;
+    }
+    const [chainName, promptArg] = positionals;
+    if (!options["until-suite"]) {
+        console.error(`--until-suite is required — name a quality.suites check whose exit code decides when the goal is met.\n${USAGE}`);
+        return 1;
+    }
+    if (!options["max"]) {
+        console.error(`--max is required — an outer iteration is a whole chain run, so there is no safe default.\n${USAGE}`);
+        return 1;
+    }
+    const max = Number.parseInt(options["max"], 10);
+    if (!Number.isInteger(max) || max < 1) {
+        console.error(`--max must be a positive integer (got ${JSON.stringify(options["max"])})`);
+        return 1;
+    }
+    if (promptArg === undefined && !options["issue"]) {
+        console.error(`a goal is required — either a prompt/path positional, or --issue <id>.\n${USAGE}`);
+        return 1;
+    }
+    if (promptArg !== undefined && options["issue"]) {
+        console.error(`pass a goal OR --issue <id>, not both`);
+        return 1;
+    }
+    const chain = findChain(chainName);
+    if (!chain) {
+        console.error(`unknown chain: ${chainName} — run \`spf list\` to see every chain`);
+        return 1;
+    }
+    const anchor = paths.resolveAnchor(options["cwd"]);
+    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);
+    let goal;
+    if (options["issue"]) {
+        const provider = resolveIssueProvider(cfg);
+        if (!provider)
+            return 1;
+        const issue = await provider.getIssue(options["issue"]);
+        if (!issue) {
+            console.error(`issue ${options["issue"]} not found`);
+            return 1;
+        }
+        goal = promptFromIssue(issue);
+    }
+    else {
+        goal = resolvePrompt(promptArg);
+    }
+    const stop = { kind: "script", suite: options["until-suite"] };
+    // Fail fast on an unconfigured suite BEFORE minting a ledger or spending
+    // anything — the same "before any check runs, let alone any agent spawns"
+    // discipline `quality.resolveSuite` documents for itself.
+    try {
+        quality.resolveSuite(qualityRunLike({ cfg, repoRoot: anchor.repo_root, contextHandoffDir: dataPaths.sessions_dir, adwId: "preflight" }), stop.suite);
+    }
+    catch (error) {
+        console.error(error instanceof Error ? error.message : String(error));
+        return 1;
+    }
+    const maxCost = options["max-cost"] ? Number.parseFloat(options["max-cost"]) : undefined;
+    const maxTokens = options["max-tokens"] ? Number.parseInt(options["max-tokens"], 10) : undefined;
+    const stuckAfter = options["stuck-after"] ? Number.parseInt(options["stuck-after"], 10) : 3;
+    const minIntervalMs = options["min-interval-ms"] ? Number.parseInt(options["min-interval-ms"], 10) : 0;
+    const goalId = resolveGoalId(options["goal-id"]);
+    const runIteration = async (iteration) => {
+        const ctx = {
+            prompt: iteration.prompt,
+            config_paths: configPaths,
+            adw_id: iteration.adw_id,
+            cwd: anchor.cwd,
+            chain_name: chain.name,
+            // Nobody is at a TTY for iteration 2 of N — same reasoning `fanout.ts`
+            // gives for its own per-attempt runs.
+            unattended: true,
+            chain_source: chain.source,
+        };
+        const chainOptions = {};
+        if (options["base"] !== undefined)
+            chainOptions["base"] = options["base"];
+        let exitCode = null;
+        let error = null;
+        try {
+            exitCode = await runChainDef(chain, ctx, chainOptions);
+        }
+        catch (caught) {
+            error = caught.message;
+        }
+        // Read back tokens/cost/gates by adw_id regardless of outcome — the
+        // same "never throw, rank as zero" discipline `fanout.ts`'s own
+        // `readMetrics` uses, since these numbers are for the ledger's spend
+        // total, not for deciding correctness.
+        let tokens = 0;
+        let cost = 0;
+        if (existsSync(dataPaths.db_path)) {
+            const db = new SfDb(dataPaths.db_path);
+            try {
+                const session = db.session(iteration.adw_id);
+                tokens = session?.total_tokens ?? 0;
+                cost = session?.total_cost ?? 0;
+            }
+            finally {
+                db.close();
+            }
+        }
+        let commitSha = null;
+        let stopVerdict = null;
+        if (exitCode === 0 && error === null) {
+            const git = makeGit(anchor.repo_root);
+            commitSha = git.shortSha();
+            const result = quality.runSuite(qualityRunLike({ cfg, repoRoot: anchor.repo_root, contextHandoffDir: dataPaths.sessions_dir, adwId: iteration.adw_id }), stop.suite);
+            stopVerdict = { passed: result.passed, failures: result.failures, artifacts: result.artifacts };
+        }
+        return { exit_code: exitCode, error, commit_sha: commitSha, tokens, cost, stop_verdict: stopVerdict };
+    };
+    const result = await runLoop({
+        chainName: chain.name,
+        goal,
+        stop,
+        max,
+        budget: { maxCost, maxTokens },
+        stuckAfter,
+        minIntervalMs,
+        dataDir: dataPaths.data_dir,
+        goalId,
+        runIteration,
+        log: (message) => console.log(`[spf] ${message}`),
+        sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+    });
+    console.log(`\n${summarize(result)}`);
+    const spend = cumulativeSpend(result.ledger.attempts);
+    if (isInteractive() && result.ledger.attempts.length > 0) {
+        console.log(`  ${result.ledger.attempts.length} attempt(s), $${spend.cost.toFixed(4)}`);
+    }
+    return result.exitCode;
+}

package/dist/cli/commands/run.js CHANGED Viewed

@@ -1,7 +1,8 @@
 /** Shared by both `spf <chain> "..."` and `spf run <chain> "..."` — same dispatch. */
 import * as paths from "../../core/paths.js";
 import * as agents from "../../core/agents.js";
-import { parseCli, resolvePrompt } from "../../core/utils.js";
+import { newId, parseCli, resolvePrompt } from "../../core/utils.js";
+import { withRunScope } from "../../core/sandbox.js";
 import { runChain } from "../../chains/index.js";
 import { isInteractive } from "../ask.js";
 const KNOWN_OPTIONS = ["config", "adw-id", "cwd", "agent", "base", "issue", "suite", "priority"];
@@ -24,10 +25,15 @@ export async function dispatchChain(chain, argv) {
         return 2;
     }
     const anchor = paths.resolveAnchor(options["cwd"]);
+    // Minted here, not left null-and-minted-later inside session.ensure — a
+    // sandbox lease is keyed on `<adw_id>/<agent>` (design §4.3) and
+    // `withRunScope` below needs the SAME id up front to know which leases
+    // this run's `finally` must tear down.
+    const adwId = options["adw-id"] ?? newId(8);
     const ctx = {
         prompt: resolvePrompt(positionals[0]),
         config_paths: paths.resolveConfigPaths(anchor, options["config"]).paths,
-        adw_id: options["adw-id"] ?? null,
+        adw_id: adwId,
         cwd: anchor.cwd,
         chain_name: chain.name,
         // Only `refine` reads this (a "## Parent: #<id>" back-reference on
@@ -74,11 +80,15 @@ export async function dispatchChain(chain, argv) {
         const dashboard = mountRunDashboard({ maxCost: cfg.defaults.max_run_cost, maxTokens: cfg.defaults.max_run_tokens });
         ctx.render_hooks = { sink: dashboard.sink, observer: dashboard.observer, pause: dashboard.pause, resume: dashboard.resume };
         try {
-            return await runChain(chain, ctx, chainOptions);
+            // Same withRunScope as the unattended path below — an interactive
+            // dispatch is just as capable of opening a sandbox lease (design
+            // §4.3), and skipping this here would leak it silently since nothing
+            // else in this branch calls teardownRun.
+            return await withRunScope(adwId, () => runChain(chain, ctx, chainOptions));
         }
         finally {
             await dashboard.close();
         }
     }
-    return runChain(chain, ctx, chainOptions);
+    return withRunScope(adwId, () => runChain(chain, ctx, chainOptions));
 }

package/dist/cli/commands/watch.d.ts CHANGED Viewed

@@ -1,4 +1,8 @@
-import { type ReviewOutputT } from "../../core/data_types.ts";
+import type { IssueProvider } from "../../core/issues/provider.ts";
+import { type WatchFanoutDeps } from "../../core/watch.ts";
+import { type ChainDefinition } from "../../chains/index.ts";
+import { type ReviewOutputT, type SFConfig } from "../../core/data_types.ts";
+import type { DataPaths } from "../../core/paths.ts";
 /**
  * `&`/`<`/`>` are active markup in every destination a digest lands in —
  * `<url|text>`/`*bold*` in Slack mrkdwn, raw HTML in GitHub's markdown
@@ -16,6 +20,14 @@ export declare function escapeForMarkup(text: string): string;
 export declare function truncateDigest(text: string): string;
 /** A `ReviewOutput` envelope, reduced to the short digest threaded into the PR body and the `pr_opened` notification — see `core/watch.ts`'s `ChainRunResult.reviewSummary`. */
 export declare function formatReviewDigest(review: ReviewOutputT): string;
+/**
+ * Shared by `watch`, `watch init`, and `loop`'s `--issue` flag: resolve
+ * config into an `IssueProvider` — checking only what every caller needs.
+ * `watch`'s own extra checks (a real git repo, a registered chain) don't
+ * apply to seeding labels or to a one-shot issue fetch. Prints its own
+ * error and returns `null` on failure — the caller just needs to `return 1`.
+ */
+export declare function resolveIssueProvider(cfg: SFConfig): IssueProvider | null;
 /**
  * `spf watch init` — idempotently seed the `<prefix>:*` labels the state
  * machine needs, with sensible colors/descriptions. Doesn't touch git or
@@ -31,4 +43,20 @@ export declare function formatReviewDigest(review: ReviewOutputT): string;
  * seed — see `jira_provider.ts`'s module comment).
  */
 export declare function watchInitCommand(argv: string[]): Promise<number>;
+/**
+ * The fan-out lane's dispatch trio, as a plain function of config + the
+ * resolved chain — mirrors `cli/commands/fanout.ts`'s own `runAttempt`
+ * (`:375-404`) and `readMetrics` (`:355-373`) closures, plus `adwIdsFree`
+ * (the sessions-db half of that command's reuse preflight) and `reviewFor`
+ * (§6.5 — the two expressions `runChain` above already computes, pointed at
+ * a WINNER instead of the sole attempt). Exported as a plain function of its
+ * inputs — not a `watchCommand`-local closure — the same reason
+ * `linkFanoutDataDir` is exported from `cli/commands/fanout.ts`: it can then
+ * be exercised directly against a real repo, real worktrees and a fake
+ * chain, with no tracker, no agent and no control plane
+ * (`src/test/watch_fanout_sandbox_wiring.test.ts`). `watchCommand` itself
+ * calls this SAME factory and spreads the result into `deps.fanout`, so the
+ * tested object and the shipped object are the same object.
+ */
+export declare function makeWatchFanoutDispatch(cfg: SFConfig, configPaths: string[], dataPaths: DataPaths, chainDef: ChainDefinition): Pick<WatchFanoutDeps, "runAttempt" | "readMetrics" | "adwIdsFree" | "reviewFor">;
 export declare function watchCommand(argv: string[]): Promise<number>;

package/dist/cli/commands/watch.js CHANGED Viewed

@@ -18,7 +18,9 @@ import { JiraProvider } from "../../core/issues/jira_provider.js";
 import { BitbucketProvider } from "../../core/issues/bitbucket_provider.js";
 import { isAuthoringProvider } from "../../core/issues/provider.js";
 import { createWatchState, tick } from "../../core/watch.js";
-import { findChain, resolveRequiredAgents, runChain as runChainDef } from "../../chains/index.js";
+import { findChain, hasCommitStep, resolveRequiredAgents, runChain as runChainDef } from "../../chains/index.js";
+import { withRunScope } from "../../core/sandbox.js";
+import { excludeSpfDataFromGit } from "../../core/worktree_data.js";
 import { ReviewOutput } from "../../core/data_types.js";
 import { SfDb } from "../../ui/server/db.js";
 import { parseCli } from "../../core/utils.js";
@@ -72,12 +74,13 @@ export function formatReviewDigest(review) {
     return truncateDigest(lines.join("\n"));
 }
 /**
- * Shared by `watch` and `watch init`: resolve config into an `IssueProvider`
- * — checking only what BOTH need. `watch`'s own extra checks (a real git
- * repo, a registered chain) don't apply to seeding labels. Prints its own
+ * Shared by `watch`, `watch init`, and `loop`'s `--issue` flag: resolve
+ * config into an `IssueProvider` — checking only what every caller needs.
+ * `watch`'s own extra checks (a real git repo, a registered chain) don't
+ * apply to seeding labels or to a one-shot issue fetch. Prints its own
  * error and returns `null` on failure — the caller just needs to `return 1`.
  */
-function resolveIssueProvider(cfg) {
+export function resolveIssueProvider(cfg) {
     if (cfg.watch.issue_provider === "github") {
         // `issue_repo` (falling back to `repo`) — NOT `repo` alone — because
         // `repo` always names `code_host`'s own repo (see WatchConfigSchema's
@@ -214,6 +217,152 @@ export async function watchInitCommand(argv) {
     }
     return 0;
 }
+/** Shared by `runChain`/`runRefine`/the fan-out lane's dispatch: best-effort enrichment of a generic "didn't succeed" message with the first phase that actually failed, read back from the worktree's own (symlinked) trace db. Top-level (not a `watchCommand` local) so `makeWatchFanoutDispatch` below can share it — see that factory's own doc comment for why. */
+function detailFromFailedPhase(cfg, cwd, adwId, prefix) {
+    let detail = prefix;
+    let db;
+    try {
+        const wtAnchor = paths.resolveAnchor(cwd);
+        const wtDataPaths = paths.resolveDataPaths(wtAnchor, cfg.defaults.data_dir, cfg.observability.db);
+        db = new SfDb(wtDataPaths.db_path);
+        const failed = db.phases(adwId).find((p) => p.status === "fail");
+        if (failed)
+            detail += ` Phase "${failed.name}" failed: ${failed.error ?? "(no detail)"}`;
+    }
+    catch {
+        // best-effort — the generic message above still points at where to look
+    }
+    finally {
+        db?.close();
+    }
+    return detail;
+}
+/**
+ * Best-effort: the reviewer's latest verdict for this run, read back from
+ * the worktree's own (symlinked) trace db and reduced to a digest — same
+ * DB, same try/catch shape as `detailFromFailedPhase` above, but on the
+ * SUCCESS path. `undefined` on any DB/parse hiccup, or when the chain
+ * never produced a `ReviewOutput` envelope at all — never thrown: a digest
+ * is a nice-to-have, not something that gets to block the PR-open flow
+ * it's decorating. Top-level for the same reason as `detailFromFailedPhase`.
+ */
+function reviewSummaryFor(cfg, cwd, adwId) {
+    let db;
+    try {
+        const wtAnchor = paths.resolveAnchor(cwd);
+        const wtDataPaths = paths.resolveDataPaths(wtAnchor, cfg.defaults.data_dir, cfg.observability.db);
+        db = new SfDb(wtDataPaths.db_path);
+        const envelope = db
+            .envelopes(adwId)
+            .filter((e) => e.output_type === ReviewOutput.name)
+            .at(-1); // the LATEST verdict — a revise loop can produce several
+        if (!envelope?.payload_json)
+            return undefined;
+        const review = v.parse(ReviewOutput.schema, JSON.parse(envelope.payload_json));
+        return formatReviewDigest(review);
+    }
+    catch {
+        return undefined; // best-effort — see the doc comment above
+    }
+    finally {
+        db?.close();
+    }
+}
+/**
+ * The fan-out lane's dispatch trio, as a plain function of config + the
+ * resolved chain — mirrors `cli/commands/fanout.ts`'s own `runAttempt`
+ * (`:375-404`) and `readMetrics` (`:355-373`) closures, plus `adwIdsFree`
+ * (the sessions-db half of that command's reuse preflight) and `reviewFor`
+ * (§6.5 — the two expressions `runChain` above already computes, pointed at
+ * a WINNER instead of the sole attempt). Exported as a plain function of its
+ * inputs — not a `watchCommand`-local closure — the same reason
+ * `linkFanoutDataDir` is exported from `cli/commands/fanout.ts`: it can then
+ * be exercised directly against a real repo, real worktrees and a fake
+ * chain, with no tracker, no agent and no control plane
+ * (`src/test/watch_fanout_sandbox_wiring.test.ts`). `watchCommand` itself
+ * calls this SAME factory and spreads the result into `deps.fanout`, so the
+ * tested object and the shipped object are the same object.
+ */
+export function makeWatchFanoutDispatch(cfg, configPaths, dataPaths, chainDef) {
+    const runAttempt = async (dispatch) => {
+        // NO `dispatch.isAborted()` early return, unlike `spf fanout`'s own
+        // runAttempt: that check only ever fires under `firstSuccess`, which
+        // `spf watch` never sets (`decided` is never flipped — see
+        // `core/fanout.ts`). Including a check that can never observe true would
+        // be a lie about the abort model this dispatch actually honors.
+        const ctx = {
+            prompt: dispatch.prompt,
+            config_paths: configPaths,
+            adw_id: dispatch.adwId, // "issue-<id>-<i>" (or the salted/random base's own) — fanout.ts's attemptAdwId
+            cwd: dispatch.cwd, // THIS attempt's own worktree — the Run's repo_root anchor
+            chain_name: chainDef.name,
+            unattended: true, // same as runChain's and spf fanout's own dispatch — nobody is at a TTY for attempt 2 of 3
+            chain_source: chainDef.source,
+        };
+        // `cfg.watch.chain_options` reaches every attempt exactly as it reaches
+        // the single dispatch above — one shared map for all N attempts.
+        return withRunScope(dispatch.adwId, () => runChainDef(chainDef, ctx, cfg.watch.chain_options));
+    };
+    /**
+     * Opened and closed PER CALL, unlike `spf fanout`'s lazily-held single
+     * handle: `spf watch` is a long-lived daemon with several issues (and
+     * fan-outs) potentially in flight at once and no single `finally` to close
+     * a shared handle in — the same per-call shape `detailFromFailedPhase`/
+     * `reviewSummaryFor` above already use against the same WAL db.
+     */
+    const readMetrics = (adwId) => {
+        if (!existsSync(dataPaths.db_path))
+            return { gate_passes: 0, gate_failures: 0, cost: 0, tokens: 0 };
+        let db;
+        try {
+            db = new SfDb(dataPaths.db_path);
+            const gates = db.gates(adwId);
+            const session = 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 wins.
+            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,
+            };
+        }
+        catch {
+            return { gate_passes: 0, gate_failures: 0, cost: 0, tokens: 0 };
+        }
+        finally {
+            db?.close();
+        }
+    };
+    /**
+     * The other half of `spf fanout`'s reuse preflight — "does this adw_id
+     * have a session row yet" — one `SfDb.session(id)` point lookup per
+     * candidate id. Safe direction is FALSE (see `WatchFanoutDeps.adwIdsFree`'s
+     * own doc comment): an unreadable db reports "taken" rather than "free".
+     */
+    const adwIdsFree = (adwIds) => {
+        if (!existsSync(dataPaths.db_path))
+            return true; // no db yet — nothing to collide with
+        let db;
+        try {
+            db = new SfDb(dataPaths.db_path);
+            return adwIds.every((id) => db.session(id) === null);
+        }
+        catch {
+            return false;
+        }
+        finally {
+            db?.close();
+        }
+    };
+    const reviewFor = (opts) => ({
+        reviewRequired: resolveRequiredAgents(chainDef, opts.chainOptions).includes("reviewer"),
+        reviewSummary: reviewSummaryFor(cfg, opts.cwd, opts.adwId),
+    });
+    return { runAttempt, readMetrics, adwIdsFree, reviewFor };
+}
 export async function watchCommand(argv) {
     const { options, flags } = parseCli(argv, ["cwd", "config"], ["dry-run", "once"]);
     const anchor = paths.resolveAnchor(options["cwd"]);
@@ -266,6 +415,39 @@ export async function watchCommand(argv) {
             }
         }
     }
+    // watch.fanout.n > 1 startup gates — all guarded so watch.fanout.n: 1 (the
+    // default) reaches none of them, and a bad configuration stops the daemon
+    // before it starts rather than failing silently every tick.
+    if (cfg.watch.fanout.n > 1) {
+        // §5.1 — `spf fanout` refuses a chain with no commit step
+        // (`cli/commands/fanout.ts`); `spf watch`'s single-dispatch lane has no
+        // such requirement (a chain that commits nothing is handled honestly by
+        // `openPrForWinner`'s own `diffFiles` -> blocked path). For `n > 1` the
+        // same gate MUST apply, for a worse reason: `runBestOf` force-removes
+        // every SUCCESSFUL LOSER's worktree after selection
+        // (`git worktree remove --force`, which deletes uncommitted/untracked
+        // files with no confirmation). A chain with no commit step leaves its
+        // entire payload as uncommitted edits, so fan-out would destroy N-1
+        // candidates outright and then block the issue anyway once the winner's
+        // own empty diff is discovered.
+        const watchChain = findChain(cfg.watch.chain); // already checked above
+        if (!hasCommitStep(watchChain.phases)) {
+            console.error(`watch.fanout.n is ${cfg.watch.fanout.n} but watch.chain ${JSON.stringify(cfg.watch.chain)} has no commit phase ` +
+                `(${watchChain.phases}) — best-of-N discards every losing attempt's worktree (uncommitted work included), ` +
+                `so a chain that leaves its payload uncommitted would destroy N-1 candidates and then block the issue for ` +
+                `an empty diff. Use a chain that commits (plan-build, plan-build-test, plan-build-test-quality, simple-sdlc, ` +
+                `or a repo-local chain with a commit step), or set watch.fanout.n: 1.`);
+            return 1;
+        }
+        // §5.2 — `spf fanout` prints this once, interactively, when it's about
+        // to spend --n times over an unbounded ceiling; a daemon would otherwise
+        // repeat that bill every tick with nobody watching, so it's said once,
+        // loudly, at startup instead.
+        if (cfg.defaults.max_run_cost === undefined && cfg.defaults.max_run_tokens === undefined) {
+            console.log(`[spf] watch     no defaults.max_run_cost / defaults.max_run_tokens configured — watch.fanout.n=${cfg.watch.fanout.n} ` +
+                `means every claimed issue runs ${cfg.watch.fanout.n} attempts to completion, unbounded`);
+        }
+    }
     const dataPaths = paths.resolveDataPaths(anchor, cfg.defaults.data_dir, cfg.observability.db);
     const lockPath = path.join(dataPaths.data_dir, "watch.lock");
     try {
@@ -308,61 +490,20 @@ export async function watchCommand(argv) {
             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 });
-        symlinkSync(dataPaths.data_dir, target, "dir");
-    }
-    /** Shared by `runChain`/`runRefine`: best-effort enrichment of a generic "didn't succeed" message with the first phase that actually failed, read back from the worktree's own (symlinked) trace db. */
-    function detailFromFailedPhase(cwd, adwId, prefix) {
-        let detail = prefix;
-        let db;
-        try {
-            const wtAnchor = paths.resolveAnchor(cwd);
-            const wtDataPaths = paths.resolveDataPaths(wtAnchor, cfg.defaults.data_dir, cfg.observability.db);
-            db = new SfDb(wtDataPaths.db_path);
-            const failed = db.phases(adwId).find((p) => p.status === "fail");
-            if (failed)
-                detail += ` Phase "${failed.name}" failed: ${failed.error ?? "(no detail)"}`;
-        }
-        catch {
-            // best-effort — the generic message above still points at where to look
-        }
-        finally {
-            db?.close();
-        }
-        return detail;
-    }
-    /**
-     * Best-effort: the reviewer's latest verdict for this run, read back from
-     * the worktree's own (symlinked) trace db and reduced to a digest — same
-     * DB, same try/catch shape as `detailFromFailedPhase` above, but on the
-     * SUCCESS path. `undefined` on any DB/parse hiccup, or when the chain
-     * never produced a `ReviewOutput` envelope at all — never thrown: a digest
-     * is a nice-to-have, not something that gets to block the PR-open flow
-     * it's decorating.
-     */
-    function reviewSummaryFor(cwd, adwId) {
-        let db;
-        try {
-            const wtAnchor = paths.resolveAnchor(cwd);
-            const wtDataPaths = paths.resolveDataPaths(wtAnchor, cfg.defaults.data_dir, cfg.observability.db);
-            db = new SfDb(wtDataPaths.db_path);
-            const envelope = db
-                .envelopes(adwId)
-                .filter((e) => e.output_type === ReviewOutput.name)
-                .at(-1); // the LATEST verdict — a revise loop can produce several
-            if (!envelope?.payload_json)
-                return undefined;
-            const review = v.parse(ReviewOutput.schema, JSON.parse(envelope.payload_json));
-            return formatReviewDigest(review);
-        }
-        catch {
-            return undefined; // best-effort — see the doc comment above
-        }
-        finally {
-            db?.close();
+        if (!existsSync(target)) {
+            mkdirSync(path.dirname(target), { recursive: true });
+            symlinkSync(dataPaths.data_dir, target, "dir");
         }
+        // Keeps the symlink invisible to `git status`/`git add -A` in THIS
+        // worktree — see `core/worktree_data.ts`'s doc comment for the ELOOP
+        // disaster this closes. Called every time, guarded by nothing of its
+        // own: it's idempotent and best-effort (a `git rev-parse` failure is
+        // swallowed), so there's no wrong time to call it, including when
+        // resuming an orphaned worktree whose `.spf/data` symlink already
+        // exists. Previously only `spf fanout`'s own worktrees got this; `spf
+        // watch`'s single-dispatch worktrees carried the same exposure and now
+        // get the identical fix.
+        excludeSpfDataFromGit(worktreePath);
     }
     const runChain = async (opts) => {
         // WATCH DIVERGENCE: `findChain` here resolves against the registry
@@ -397,15 +538,15 @@ export async function watchCommand(argv) {
         // 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);
+        const code = await withRunScope(opts.adwId, () => 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) };
+            return { accepted: true, adwId: opts.adwId, detail: "", reviewRequired, reviewSummary: reviewSummaryFor(cfg, opts.cwd, opts.adwId) };
         }
-        const detail = detailFromFailedPhase(opts.cwd, opts.adwId, `Chain "${cfg.watch.chain}" (adw_id ${opts.adwId}) did not complete successfully. Run \`spf phases ${opts.adwId} --cwd ${opts.cwd}\` for detail.`);
+        const detail = detailFromFailedPhase(cfg, opts.cwd, opts.adwId, `Chain "${cfg.watch.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, reviewRequired };
     };
     /**
@@ -435,9 +576,9 @@ export async function watchCommand(argv) {
         };
         // 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);
+        const code = await withRunScope(opts.adwId, () => 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.`);
+            const detail = detailFromFailedPhase(cfg, 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: [], questions: [] };
         }
         const wtAnchor = paths.resolveAnchor(opts.cwd);
@@ -523,6 +664,20 @@ export async function watchCommand(argv) {
             notifier?.send(event); // unaffected either way — see mountWatchDashboard's own doc comment
             dashboard?.mirrorNotify(event);
         },
+        // `undefined` at the default `watch.fanout.n: 1` — `core/watch.ts`'s
+        // `runIssue` never even looks at `deps.fanout` in that case, so the
+        // object below doesn't exist at runtime at all unless best-of-N is
+        // actually on. `makeWatchFanoutDispatch` is the SAME factory
+        // `src/test/watch_fanout_sandbox_wiring.test.ts` exercises directly —
+        // the tested object and this shipped object are the same object.
+        fanout: cfg.watch.fanout.n > 1
+            ? {
+                n: cfg.watch.fanout.n,
+                concurrency: cfg.watch.fanout.concurrency,
+                repoRoot: anchor.repo_root, // GitHandle has no repo-root accessor — this is the same value `git` above is bound to
+                ...makeWatchFanoutDispatch(cfg, configPaths, dataPaths, findChain(cfg.watch.chain)), // checked at startup
+            }
+            : undefined,
     };
     const state = createWatchState();
     let stopping = false;