@gr8ful/spf 0.9.2 → 0.10.0

package/dist/cli/commands/doctor.js

@@ -21,7 +21,9 @@ import { binaryOnPath, parseCli } from "../../core/utils.js";
 import { PROVIDER_ENV_KEYS } from "../../core/providers.js";
 import { probeServedOllamaTags, resolveTiering } from "../../core/tiering.js";
 import { isRepoAt } from "../../core/git_helper.js";
-import { allChains, findChain, repoChainProblems, resolveRequiredAgents, resolveRequiredSuites } from "../../chains/index.js";
+import { allChains, findChain, hasCommitStep, repoChainProblems, resolveRequiredAgents, resolveRequiredSuites } from "../../chains/index.js";
+import * as sandbox from "../../core/sandbox.js";
+import { loadOpenSandboxSdk } from "../../core/sandbox_opensandbox.js";
 import { isInteractive } from "../ask.js";
 import { paint as paintPlain } from "../../core/console.js";
 /**
@@ -194,6 +196,42 @@ async function probeAnthropicMessages(base, model) {
         clearTimeout(timer);
     }
 }
+/**
+ * `GET {base}/health`, parsed for the OpenSandbox control plane's own
+ * positive signal (`{"status":"healthy"}`) — checked in ADDITION to the
+ * HTTP status, because a 200 from something else entirely (the spike's own
+ * "unrelated process on 8090" trap — see check #3/#5 below) is not the same
+ * finding as a genuinely healthy control plane; a 404 specifically is that
+ * trap's own signature. Never throws.
+ */
+async function probeOpenSandboxHealth(baseUrl) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), PROBE_TIMEOUT_MS);
+    try {
+        const res = await fetch(`${baseUrl}/health`, { signal: controller.signal });
+        let healthy = false;
+        if (res.status === 200) {
+            try {
+                const body = (await res.json());
+                healthy = body?.status === "healthy";
+            }
+            catch {
+                healthy = false;
+            }
+        }
+        return { ok: true, status: res.status, healthy };
+    }
+    catch (error) {
+        return { ok: false, error: error.message };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/** Loopback host check for #4/#5's "is this control plane reachable from off-box" gate — same shape as the OTel `insecure` check above. */
+function isLoopbackUrl(url) {
+    return /^https?:\/\/(localhost|127\.0\.0\.1|\[::1\])(:|\/|$)/.test(url);
+}
 export async function doctorCommand(argv) {
     const { options, flags } = parseCli(argv, ["cwd", "config"], ["json", "no-probe"]);
     const report = { ok: true, checks: [] };
@@ -501,6 +539,248 @@ export async function doctorCommand(argv) {
         // actually wrote without a second command.
         check(report, `repo chain "${chain.name}" phases`, true, chain.phases, "info");
     }
+    // ── Sandbox backends (SPF #15) ──────────────────────────────────────────
+    // Gated on the RESOLVED backend, per check — not on "not local" — the same
+    // usesOllamaFlue precedent above (:318-320): a repo running only
+    // backend: cloudflare imports no OpenSandbox SDK at all, so a coarse gate
+    // would fail #2 on a package that backend never loads. #2-6 fire only when
+    // some agent resolves to "opensandbox"; #7-8 only "cloudflare". #1/#9-17
+    // are backend-agnostic and roster-wide (agents.validate() above is
+    // chain-scoped to the roster only because doctor passed the WHOLE roster
+    // as `required` — see the "roster + suites validate" check — but #12-15/
+    // #17 are reported here too, on purpose, so the specific rule that failed
+    // has its own name rather than one line buried in a combined error).
+    {
+        const resolvedBackend = (agent) => agent.sandbox ?? cfg.sandbox.backend;
+        const nonLocalAgents = cfg.agents.filter((a) => resolvedBackend(a) !== "local");
+        const openSandboxAgents = nonLocalAgents.filter((a) => resolvedBackend(a) === "opensandbox");
+        const cloudflareAgents = nonLocalAgents.filter((a) => resolvedBackend(a) === "cloudflare");
+        // #1 — backend/scope/dirs/image/fanout, plus the resulting sandbox count
+        // PER CHAIN this repo can run: distinct agents the chain DISPATCHES
+        // (kind: "agent" phases only) that resolve non-local, deduplicated by
+        // name, via resolveRequiredAgents — never chain.phases or the whole
+        // roster, both of which over-count (engineer/code phases like
+        // request/quality/commit dispatch no agent, and a fix loop's revise step
+        // reuses its builder's own lease rather than opening a second one).
+        check(report, "sandbox.backend", true, `backend=${cfg.sandbox.backend}, scope=${cfg.sandbox.scope} (default: agent), workspace_dir=${cfg.sandbox.workspace_dir}, ` +
+            `scratch_dir=${cfg.sandbox.scratch_dir}, handoff_dir=${cfg.sandbox.handoff_dir}, image=${cfg.sandbox.image || "(none)"}, ` +
+            `fanout=${cfg.sandbox.fanout}` +
+            (nonLocalAgents.length > 0
+                ? `; per-agent overrides to a non-local backend: ${nonLocalAgents.map((a) => `${a.name}(${resolvedBackend(a)})`).join(", ")}`
+                : "; no agent resolves to a non-local backend"), "info");
+        if (nonLocalAgents.length > 0) {
+            for (const chain of allChains()) {
+                const required = resolveRequiredAgents(chain, {});
+                const sandboxed = required.filter((name) => {
+                    const agent = cfg.agents.find((a) => a.name === name);
+                    return agent !== undefined && resolvedBackend(agent) !== "local";
+                });
+                if (sandboxed.length === 0)
+                    continue;
+                const perAttempt = cfg.sandbox.scope === "run" ? 1 : sandboxed.length;
+                check(report, `sandbox cost: chain "${chain.name}"`, true, `${perAttempt} sandbox(es) per attempt under scope: ${cfg.sandbox.scope} (dispatched agents: ${sandboxed.join(", ")}) — multiply by --n for a fan-out estimate`, "info");
+            }
+        }
+        // #2 — provider SDK present, opensandbox only, hard ✗. MUST go through
+        // the adapter's own indirected loader (never doctor's own `import()`
+        // with a literal specifier — that fails `tsc` with TS2307 on every
+        // machine, same class of bug as a literal specifier in the adapter
+        // itself). Same static, network-free misconfiguration class as the
+        // "claude CLI" check above (SPF_CLAUDE_CMD on PATH).
+        if (openSandboxAgents.length > 0) {
+            try {
+                await loadOpenSandboxSdk();
+                check(report, "opensandbox SDK present", true, "@alibaba-group/opensandbox loaded");
+            }
+            catch (error) {
+                check(report, "opensandbox SDK present", false, error.message);
+            }
+        }
+        // #3 — opensandbox control plane reachability, info/warn (never a hard
+        // failure — the rule every reachability probe in this file follows). A
+        // 404 specifically is the spike's own trap: something ELSE listening on
+        // that port, not this control plane being down.
+        let openSandboxHealthResult = null;
+        if (openSandboxAgents.length > 0 && !flags["no-probe"]) {
+            const baseUrl = cfg.sandbox.opensandbox.base_url.replace(/\/+$/, "");
+            openSandboxHealthResult = await probeOpenSandboxHealth(baseUrl);
+            check(report, "opensandbox control plane", true, !openSandboxHealthResult.ok
+                ? `unreachable: GET ${baseUrl}/health -> ${openSandboxHealthResult.error}`
+                : openSandboxHealthResult.healthy
+                    ? `reachable: GET ${baseUrl}/health -> HTTP ${openSandboxHealthResult.status} {"status":"healthy"}`
+                    : openSandboxHealthResult.status === 404
+                        ? `GET ${baseUrl}/health -> HTTP 404 — usually means something ELSE is listening on this port, not this control plane (the spike hit exactly this on 8090 and remapped to 8095 — a troubleshooting note, not a default; see check #5)`
+                        : `GET ${baseUrl}/health -> HTTP ${openSandboxHealthResult.status}, not the expected {"status":"healthy"}`, openSandboxHealthResult.ok && openSandboxHealthResult.healthy ? "info" : "warn");
+        }
+        // #4 — API key posture, opensandbox only. Prints the key NAME only,
+        // never the value. warn (not a hard fail) when unset AND the control
+        // plane is on a routable (non-loopback) address — an insecure control
+        // plane reachable off-box.
+        if (openSandboxAgents.length > 0) {
+            const keyEnv = cfg.sandbox.opensandbox.api_key_env;
+            const set = Boolean(process.env[keyEnv]);
+            const baseUrl = cfg.sandbox.opensandbox.base_url;
+            const routable = !isLoopbackUrl(baseUrl);
+            check(report, "opensandbox API key posture", true, set
+                ? `${keyEnv} is set`
+                : routable
+                    ? `${keyEnv} is NOT set, and sandbox.opensandbox.base_url (${baseUrl}) is a routable address — an insecure control plane reachable off-box`
+                    : `${keyEnv} is not set (fine for a loopback control plane)`, set || !routable ? "info" : "warn");
+            // #5 — [docker].host_ip note. CONDITIONAL, on purpose: this gotcha
+            // applies only to a containerized control plane; the README-canonical
+            // `uvx opensandbox-server` host process needs nothing here, and
+            // warning on plain loopback would be pure noise. Fires only when #3's
+            // probe failed/timed out AND base_url is loopback.
+            const probeFailed = openSandboxHealthResult !== null && (!openSandboxHealthResult.ok || !openSandboxHealthResult.healthy);
+            if (probeFailed && isLoopbackUrl(baseUrl)) {
+                check(report, "[docker].host_ip note", true, "if your control plane runs in a container (the compose route), its readiness probes and this host-side client must resolve [docker].host_ip to the SAME reachable address — the LAN IP (`ipconfig getifaddr en0`) is the only value that works for both; getting it wrong produces a 30s \"Egress sidecar did not become ready\". If you are running `uvx opensandbox-server` on the host, ignore this.", "info");
+            }
+            // #6 — image pre-pull + readiness reminder, info only.
+            check(report, "opensandbox image pre-pull", true, `the first sandbox of each kind pulls execd/egress lazily (30-90s cold, sub-2s warm) — this is a READINESS wait, separate from sandbox.request_timeout_seconds (${cfg.sandbox.request_timeout_seconds}s, the client-side HTTP timeout on control-plane calls); confusing the two is how "Egress sidecar did not become ready" gets misdiagnosed as an HTTP timeout. skipHealthCheck is deliberately not used.`, "info");
+        }
+        // #7 — cloudflare config, hard ✗ if selected and bridge_url/api_token_env
+        // unset. Static, knowable without network. `bridge_url`/`api_token_env`
+        // are sandbox-wide (not per-agent), so this is naturally roster-wide.
+        if (cloudflareAgents.length > 0) {
+            const bridgeUrl = cfg.sandbox.cloudflare.bridge_url.trim();
+            const tokenEnv = cfg.sandbox.cloudflare.api_token_env.trim();
+            check(report, "cloudflare config", Boolean(bridgeUrl) && Boolean(tokenEnv), !bridgeUrl
+                ? "sandbox.cloudflare.bridge_url is empty — required when the resolved backend is \"cloudflare\""
+                : !tokenEnv
+                    ? "sandbox.cloudflare.api_token_env is unset — required when the resolved backend is \"cloudflare\""
+                    : `bridge_url=${bridgeUrl}, api_token_env=${tokenEnv}${process.env[tokenEnv] ? " (set)" : " (NOT set)"}`);
+            // #8 — cloudflare bridge reachability, info/warn. The bridge's own
+            // unauthenticated `GET /health` (design doc §4.2/O-2).
+            if (bridgeUrl && !flags["no-probe"]) {
+                const result = await probeGet(`${bridgeUrl.replace(/\/+$/, "")}/health`);
+                check(report, "cloudflare bridge reachability", true, result.ok
+                    ? `reachable: GET ${bridgeUrl}/health -> HTTP ${result.status}`
+                    : `unreachable: GET ${bridgeUrl}/health -> ${result.error}`, result.ok ? "info" : "warn");
+            }
+        }
+        // #9 — env injection posture, one line per NON-LOCAL agent (the resolved
+        // key set is per-agent — §3.1). Never prints values, only key NAMES.
+        // warn for an allowlisted key absent from the operator env, and warn
+        // when env_allowlist is non-empty while egress.default: allow.
+        for (const agent of nonLocalAgents) {
+            const agentAllow = agent.env_allowlist; // undefined/null = no further narrowing
+            const keyNames = [...new Set(agentAllow == null ? cfg.sandbox.env_allowlist : cfg.sandbox.env_allowlist.filter((k) => agentAllow.includes(k)))].sort();
+            const missing = keyNames.filter((k) => process.env[k] === undefined);
+            const broadEgressWithCreds = keyNames.length > 0 && cfg.sandbox.egress.default === "allow";
+            const warn = missing.length > 0 || broadEgressWithCreds;
+            check(report, `agent "${agent.name}" sandbox env injection`, true, keyNames.length === 0
+                ? "no keys injected (sandbox.env_allowlist is empty, or this agent's own env_allowlist narrows it to nothing)"
+                : `injects: ${keyNames.join(", ")}` +
+                    (missing.length > 0 ? ` — NOT set in the operator env: ${missing.join(", ")}` : "") +
+                    (broadEgressWithCreds ? " — egress.default: allow with live credentials in the sandbox is worth a second look" : ""), warn ? "warn" : "info");
+        }
+        // #9b — SPF #15 PR B (§6.1/§7): the credential broker's own describe()
+        // line, one per non-local agent. `static` (the only registered broker)
+        // issues exactly the key set check #9 just printed — reused here rather
+        // than re-resolved, and reused rather than a real `broker.issue(spec)`
+        // call: doctor has no live SandboxSpec (no Run exists), and deliberately
+        // never reads an operator-env VALUE just to build this string.
+        if (nonLocalAgents.length > 0) {
+            const brokerKnown = sandbox.KNOWN_CREDENTIAL_BROKER_IDS.includes(cfg.sandbox.credentials.broker);
+            for (const agent of nonLocalAgents) {
+                const agentAllow = agent.env_allowlist;
+                const keyNames = agentAllow == null ? cfg.sandbox.env_allowlist : cfg.sandbox.env_allowlist.filter((k) => agentAllow.includes(k));
+                check(report, `agent "${agent.name}" credential grant`, brokerKnown, brokerKnown
+                    ? sandbox.describeStaticCredentials(keyNames)
+                    : `sandbox.credentials.broker ${JSON.stringify(cfg.sandbox.credentials.broker)} is not registered — known: ${sandbox.KNOWN_CREDENTIAL_BROKER_IDS.join(", ")}`, brokerKnown ? "info" : undefined);
+            }
+        }
+        // #10 — egress policy, verbatim, info only.
+        if (nonLocalAgents.length > 0) {
+            check(report, "sandbox egress policy", true, `default=${cfg.sandbox.egress.default}, allow=[${cfg.sandbox.egress.allow.join(", ")}]`, "info");
+        }
+        // #11 — live leases. The lease JOURNAL (<data_dir>/sandboxes.json,
+        // design doc §4.3) is not written by this build's core sandbox module —
+        // only the in-process registry exists, which is always empty inside
+        // `spf doctor`'s own process (doctor never creates a lease itself), so
+        // this cannot yet report an orphan left by a killed run. Reported
+        // honestly rather than fabricating a journal read.
+        if (nonLocalAgents.length > 0) {
+            const live = sandbox.leases();
+            check(report, "sandbox live leases", true, `${live.length} in THIS process (the lease journal at <data_dir>/sandboxes.json is not implemented in this build — cross-process/orphan visibility via \`spf sandbox list\` is not yet available)`, "info");
+        }
+        // #12 — claude_code x remote backend, hard ✗, roster-wide (validate()
+        // above is chain-scoped to whatever `required` it was called with —
+        // doctor happens to pass the whole roster there too, but this is named
+        // separately so the specific rule that failed has its own line).
+        for (const agent of cfg.agents) {
+            const backend = resolvedBackend(agent);
+            if (agent.coding_agent === "claude_code" && backend !== "local") {
+                check(report, `agent "${agent.name}" coding_agent x sandbox`, false, `coding_agent "claude_code" cannot use sandbox backend ${JSON.stringify(backend)} — it always spawns a host process with no sandbox seam; set agent.sandbox: local (or sandbox.backend: local) for this agent`);
+            }
+        }
+        // #13 — image set, and able to run the transport. Hard ✗ only when
+        // empty on a resolved opensandbox backend (the key has no default and
+        // is required for that backend); otherwise a warn on a known-git-less
+        // base image.
+        if (openSandboxAgents.length > 0) {
+            const image = cfg.sandbox.image.trim();
+            if (!image) {
+                check(report, "sandbox.image", false, 'sandbox.image is empty — required when the resolved backend is "opensandbox": the image MUST contain git, tar and base64 (the workspace transport shells out to all three)');
+            }
+            else {
+                const knownGitless = /python:.*-slim|^alpine(:|$)/.test(image) && !cfg.sandbox.setup.some((cmd) => /\bgit\b/.test(cmd));
+                check(report, "sandbox.image", true, knownGitless
+                    ? `${image} is a known git-less base — the mandatory create-time preflight (git/tar/base64) will fail unless sandbox.setup installs git`
+                    : `${image} (git/tar/base64 verified at create time by the mandatory preflight, not here)`, knownGitless ? "warn" : "info");
+            }
+        }
+        // #14 — handoff/scratch dir placement, hard ✗, roster-wide. Same rule,
+        // same reason as validateSandboxConfig's (agents.ts) — duplicated here
+        // in miniature because that function is not exported, and this is a
+        // static, network-free, config-shape check that doesn't need a per-agent
+        // loop (workspace_dir/handoff_dir/scratch_dir are sandbox-wide, not
+        // per-agent). Reported here as well as in validate() because the
+        // failure it prevents (a PermissionBreach on turn 1 of every sandboxed
+        // run) is expensive and its cause is non-obvious.
+        if (nonLocalAgents.length > 0) {
+            const posixUnderOrEqual = (root, child) => {
+                const normRoot = path.posix.normalize(root).replace(/\/+$/, "") || "/";
+                const normChild = path.posix.normalize(child);
+                return normChild === normRoot || normChild.startsWith(`${normRoot}/`);
+            };
+            const placementProblems = [];
+            for (const key of ["handoff_dir", "scratch_dir"]) {
+                if (posixUnderOrEqual(cfg.sandbox.workspace_dir, cfg.sandbox[key])) {
+                    placementProblems.push(`sandbox.${key} (${cfg.sandbox[key]}) is inside sandbox.workspace_dir (${cfg.sandbox.workspace_dir})`);
+                }
+            }
+            if (path.posix.normalize(cfg.sandbox.handoff_dir) === path.posix.normalize(cfg.sandbox.scratch_dir)) {
+                placementProblems.push(`sandbox.scratch_dir must not equal sandbox.handoff_dir (${cfg.sandbox.handoff_dir})`);
+            }
+            check(report, "sandbox handoff/scratch dir placement", placementProblems.length === 0, placementProblems.length === 0
+                ? `handoff_dir=${cfg.sandbox.handoff_dir}, scratch_dir=${cfg.sandbox.scratch_dir}, both outside workspace_dir=${cfg.sandbox.workspace_dir}`
+                : placementProblems.join("; "));
+        }
+        // #15 — scope: run x divergent env, hard ✗, roster-wide. validate()
+        // above is chain-scoped to whatever `required` it ran with; this calls
+        // the SAME exported function over the WHOLE roster, so a repo with
+        // several chains learns scope: run is unsafe for this roster before
+        // picking the one chain that would trip it.
+        const runScopeProblems = agents.validateSandboxRunScope(cfg, cfg.agents.map((a) => a.name));
+        if (cfg.sandbox.scope === "run") {
+            check(report, "sandbox scope: run env divergence (roster-wide)", runScopeProblems.length === 0, runScopeProblems.length === 0 ? "every non-local agent in the roster resolves to the same backend + env key set" : runScopeProblems.join("; "));
+        }
+        // #16 — submodules present, warn, static, network-free. Deliberately a
+        // warning, not a validate() failure: a submodule-bearing repo must still
+        // be able to run (the superproject alone is seeded/synced/extracted).
+        if (nonLocalAgents.length > 0 && existsSync(path.join(anchor.repo_root, ".gitmodules"))) {
+            check(report, "sandbox + submodules", true, `${anchor.repo_root} has .gitmodules — submodule content is not seeded, synced, or extracted by the sandbox transport (the superproject only is)`, "warn");
+        }
+        // #17 — timeout relation, hard ✗, roster-wide, network-free. The
+        // DEFAULT deadline must fit inside the client timeout; a caller-supplied
+        // timeoutMs still passes through unmodified (no clamp — sandbox.ts).
+        if (nonLocalAgents.length > 0) {
+            check(report, "sandbox timeout relation", cfg.sandbox.request_timeout_seconds >= cfg.sandbox.exec_timeout_seconds, cfg.sandbox.request_timeout_seconds >= cfg.sandbox.exec_timeout_seconds
+                ? `request_timeout_seconds=${cfg.sandbox.request_timeout_seconds} >= exec_timeout_seconds=${cfg.sandbox.exec_timeout_seconds} — a model-requested timeout longer than exec_timeout_seconds is honored, not clamped, exactly as on backend: local`
+                : `sandbox.request_timeout_seconds (${cfg.sandbox.request_timeout_seconds}) must be >= sandbox.exec_timeout_seconds (${cfg.sandbox.exec_timeout_seconds})`);
+        }
+    }
     // A protected_files pattern matching nothing anywhere in the trace is
     // usually a stale convention (e.g. an old adws/... pattern) that silently
     // stopped protecting anything.
@@ -582,9 +862,66 @@ export async function doctorCommand(argv) {
             // that is entirely built around a review loop, the moment its reviewer
             // is renamed.
             const hasReviewer = watchChain.phases.includes("(revise)");
-            const hasCommitPhase = watchChain.phases.includes("commit");
+            // `hasCommitStep` (structural: the derived phase string shows a real
+            // `git(commit` step), not a substring match on the word "commit" — the
+            // same predicate `watch.fanout commit phase` below uses, so a chain
+            // whose phase LABEL merely contains "commit" without an actual commit
+            // step can't get "includes" here and a hard ✗ on the very next line.
+            const hasCommitPhase = hasCommitStep(watchChain.phases);
             check(report, "watch.chain review posture", true, `${hasReviewer ? "includes" : "does not include"} a reviewer; ${hasCommitPhase ? "includes" : "does not include"} a commit phase`);
         }
+        // watch.fanout — the best-of-N multiplier `watch.fanout.n`/
+        // `watch.fanout.concurrency` drive (see `WatchFanoutConfigSchema`'s doc
+        // comment). This line always prints, even at the default n=1: n=1 is a
+        // no-op for the running DAEMON (`core/watch.ts`'s design doc, §7), but
+        // not a total no-op at the CLI surface — an operator should be able to
+        // see the posture either way. b-d below only fire when n > 1.
+        {
+            const n = cfg.watch.fanout.n;
+            const a = cfg.watch.fanout.concurrency;
+            const c = cfg.watch.concurrency;
+            if (n <= 1) {
+                check(report, "watch.fanout", true, "n=1 — single dispatch per claimed issue (best-of-N off)", "info");
+            }
+            else {
+                check(report, "watch.fanout", true, `n=${n}, attempts in flight per issue=${a}; with watch.concurrency=${c} that is up to ` +
+                    `${c} x ${a} = ${c * a} chain runs in flight, up to ${c} x ${n} = ${c * n} worktrees on disk at once ` +
+                    `(a successful attempt's tree is kept until every sibling settles), and ${n} chain runs per claimed issue`, "info");
+                if (watchChain) {
+                    // b — only when SOME dispatched agent of watch.chain resolves
+                    // non-local. Reuses check #1's own resolvedBackend +
+                    // resolveRequiredAgents computation (recomputed here, scoped to
+                    // THIS chain rather than every chain) so the two can never
+                    // disagree about what "resolves non-local" means.
+                    const resolvedBackendForFanout = (agent) => agent.sandbox ?? cfg.sandbox.backend;
+                    const required = resolveRequiredAgents(watchChain, cfg.watch.chain_options);
+                    const sandboxed = required.filter((name) => {
+                        const agent = cfg.agents.find((a2) => a2.name === name);
+                        return agent !== undefined && resolvedBackendForFanout(agent) !== "local";
+                    });
+                    if (sandboxed.length > 0) {
+                        const perAttempt = cfg.sandbox.scope === "run" ? 1 : sandboxed.length;
+                        check(report, "watch.fanout sandbox cost", true, `${perAttempt} sandbox(es) per attempt under scope: ${cfg.sandbox.scope} (dispatched agents: ${sandboxed.join(", ")}) ` +
+                            `-> up to ${c} x ${a} x ${perAttempt} = ${c * a * perAttempt} in flight; ${n} x ${perAttempt} = ${n * perAttempt} sandbox creations per claimed issue`, "info");
+                    }
+                    // c — hard ✗ when n > 1 and watch.chain has no commit phase.
+                    // Mirrors `spf watch`'s own startup refusal, so `spf doctor`
+                    // catches this before the daemon is ever started.
+                    check(report, "watch.fanout commit phase", hasCommitStep(watchChain.phases), hasCommitStep(watchChain.phases)
+                        ? `watch.chain "${cfg.watch.chain}" has a commit phase`
+                        : `watch.fanout.n is ${n} but watch.chain "${cfg.watch.chain}" has no commit phase (${watchChain.phases}) — ` +
+                            `best-of-N discards every losing attempt's worktree, uncommitted work included; see \`spf watch\`'s own startup refusal for the full explanation`);
+                }
+                // d — warn, not a hard failure: an unbounded run is the documented
+                // default (every reachability/posture check in this file is
+                // info/warn rather than a hard failure). A daemon repeats this bill
+                // every tick, though, which is what earns the warn over check #1's
+                // plain info line.
+                if (cfg.defaults.max_run_cost === undefined && cfg.defaults.max_run_tokens === undefined) {
+                    check(report, "watch.fanout budget ceiling", true, `no defaults.max_run_cost / defaults.max_run_tokens configured — every claimed issue runs ${n} attempts to completion, unbounded`, "warn");
+                }
+            }
+        }
         if (cfg.watch.refine.enabled) {
             const refineChain = findChain(cfg.watch.refine.chain);
             check(report, "watch.refine.chain", Boolean(refineChain), refineChain ? `${cfg.watch.refine.chain}${refineChain.source ? ` (repo: ${repoChainLabel(refineChain.source)})` : ""}` : `"${cfg.watch.refine.chain}" is not a registered chain`);

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

@@ -1,3 +1,4 @@
+import { excludeSpfDataFromGit } from "../../core/worktree_data.ts";
 /**
  * Wire `<worktreePath>/.spf/data` to the main repo's `dataDir` — same
  * purpose as `cli/commands/watch.ts`'s own `linkDataDir`: without it an
@@ -22,19 +23,11 @@
  */
 export declare function linkFanoutDataDir(worktreePath: string, dataDir: string): void;
 /**
- * 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.
+ * Re-exported so existing callers (`src/test/fanout_cli.test.ts`,
+ * `src/test/sandbox_fanout.test.ts`) keep compiling with no edit — the
+ * function itself moved to `core/worktree_data.ts` (§6.6) so
+ * `cli/commands/watch.ts`'s own `linkDataDir` can call it too without
+ * importing this command module.
  */
-export declare function excludeSpfDataFromGit(worktreePath: string): void;
+export { excludeSpfDataFromGit };
 export declare function fanoutCommand(argv: string[]): Promise<number>;

package/dist/cli/commands/fanout.js

@@ -21,14 +21,16 @@
  * 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 { existsSync, mkdirSync, readdirSync, 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 { findChain, hasCommitStep, runChain as runChainDef } from "../../chains/index.js";
+import { withRunScope } from "../../core/sandbox.js";
+import { excludeSpfDataFromGit } from "../../core/worktree_data.js";
 import { SfDb } from "../../ui/server/db.js";
 import { newId, parseCli, resolvePrompt } from "../../core/utils.js";
 import { isInteractive } from "../ask.js";
@@ -43,10 +45,6 @@ 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;
@@ -132,32 +130,13 @@ export function linkFanoutDataDir(worktreePath, dataDir) {
     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.
+ * Re-exported so existing callers (`src/test/fanout_cli.test.ts`,
+ * `src/test/sandbox_fanout.test.ts`) keep compiling with no edit — the
+ * function itself moved to `core/worktree_data.ts` (§6.6) so
+ * `cli/commands/watch.ts`'s own `linkDataDir` can call it too without
+ * importing this command module.
  */
-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`);
-}
+export { excludeSpfDataFromGit };
 /**
  * `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
@@ -170,6 +149,16 @@ export function excludeSpfDataFromGit(worktreePath) {
  * 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`).
+ *
+ * Scans BOTH `~/.spf/fanout/<basename>/worktrees` (this command's own attempt
+ * trees) AND `~/.spf/watch/<basename>/worktrees` (`spf watch`'s fan-out lane,
+ * `watch.fanout.n > 1` — see `core/watch.ts`'s design doc): the attempt naming
+ * scheme (`fanout-<base>-<i>` / `spf/fanout/<base>-<i>`) is identical either
+ * way, watch's automatic pre-sweep only ever reaches an issue it re-claims,
+ * and an issue `reconcileOrphans` gave up on permanently is never claimed
+ * again — so its attempt trees, and a §8.7 salt cap-fallback base's debris
+ * (whose random suffix the pre-sweep cannot enumerate by construction), have
+ * no other operator-facing cleanup tool.
  */
 function cleanFanoutAttempts(baseAdwId, cwdOpt) {
     const anchor = paths.resolveAnchor(cwdOpt);
@@ -177,10 +166,15 @@ function cleanFanoutAttempts(baseAdwId, cwdOpt) {
         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 worktreesDirs = [
+        path.join(homedir(), ".spf", "fanout", path.basename(anchor.repo_root), "worktrees"),
+        path.join(homedir(), ".spf", "watch", path.basename(anchor.repo_root), "worktrees"),
+    ];
     const git = makeGit(anchor.repo_root);
     let removed = 0;
-    if (existsSync(worktreesDir)) {
+    for (const worktreesDir of worktreesDirs) {
+        if (!existsSync(worktreesDir))
+            continue;
         for (const entry of readdirSync(worktreesDir)) {
             if (!entry.startsWith(`fanout-${baseAdwId}-`))
                 continue;
@@ -251,11 +245,14 @@ export async function fanoutCommand(argv) {
     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;
+    // Reused rather than given a knob of its own: `watch.fanout.concurrency`
+    // (default 2) is already this repo's answer to "how many ATTEMPTS of one
+    // prompt may run at once" — the exact thing `--concurrency` controls here —
+    // and it is the same machine, the same SQLite and the same agent quota
+    // either way. NOT `watch.concurrency`, which counts ISSUES in flight under
+    // `spf watch` and means something different (see `WatchFanoutConfigSchema`'s
+    // doc comment). `--concurrency` overrides it for one invocation.
+    const concurrency = options["concurrency"] ? Number.parseInt(options["concurrency"], 10) : cfg.watch.fanout.concurrency;
     if (!Number.isInteger(concurrency) || concurrency < 1) {
         console.error(`--concurrency must be a positive integer (got ${JSON.stringify(options["concurrency"])})`);
         return 1;
@@ -353,7 +350,7 @@ export async function fanoutCommand(argv) {
             unattended: true,
             chain_source: chain.source,
         };
-        return runChainDef(chain, ctx);
+        return withRunScope(dispatch.adwId, () => runChainDef(chain, ctx));
     };
     // Best-effort operator guidance on an abnormal exit — NOT a real
     // cancellation. Every code phase runs through a synchronous `spawnSync`
@@ -428,6 +425,15 @@ export async function fanoutCommand(argv) {
         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)`);
+        // SPF #15 PR B, design §5.5 — the one line of printed posture sandboxing
+        // adds to this contract. `sandbox.fanout: "sandbox"` rides the ordinary
+        // per-attempt SandboxSpec (each attempt's own worktree/adw_id — see
+        // core/agents.ts's sandboxSpecFor); this line just says so, honestly:
+        // the winner's WORKTREE and BRANCH are still local, no matter where the
+        // attempts' agent calls ran.
+        if (cfg.sandbox.fanout === "sandbox" && cfg.sandbox.backend !== "local") {
+            console.log(`attempts ran in ${cfg.sandbox.backend} sandboxes; branch is local`);
+        }
         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}`);

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

@@ -0,0 +1,2 @@
+export declare const USAGE: string;
+export declare function loopCommand(argv: string[]): Promise<number>;