@gr8ful/spf 0.14.0 → 0.16.0

package/dist/chains/steps.js

@@ -73,7 +73,7 @@ function makeStep(fn, meta = {}) {
 export async function startRun(ctx, requiredAgents, requiredSuites) {
     const cfg = agentsCfg.loadConfig(ctx.config_paths);
     agentsCfg.validate(cfg, requiredAgents, requiredSuites, ctx.cwd);
-    const run = session.ensure(cfg, ctx.adw_id, ctx.cwd, ctx.chain_name, ctx.render_hooks);
+    const run = await session.ensure(cfg, ctx.adw_id, ctx.cwd, ctx.chain_name, ctx.render_hooks);
     // Provenance, once per run, before any phase opens: a repo-local chain
     // (.spf/chains/*.yaml) records the file it came from. `chain_name` alone
     // stops being enough to reconstruct a run the moment a target repo can
@@ -88,7 +88,7 @@ export async function startRun(ctx, requiredAgents, requiredSuites) {
     // it is a note. Adding a picklist member would force a UI change for a
     // payload the UI already renders generically.
     if (ctx.chain_source) {
-        run.tracer.event(makeEventRecord({ adw_id: run.adw_id, type: "log", name: "chain_source", payload: { source: ctx.chain_source } }));
+        await run.tracer.event(makeEventRecord({ adw_id: run.adw_id, type: "log", name: "chain_source", payload: { source: ctx.chain_source } }));
     }
     // Tiering resolution (SPF #14) — one more run-scoped fact, computed once,
     // before any phase opens, beside chain_source above. `risk`/`signals` are
@@ -103,7 +103,7 @@ export async function startRun(ctx, requiredAgents, requiredSuites) {
         servedOllamaTags,
         required: requiredAgents,
     });
-    run.tracer.event(makeEventRecord({
+    await run.tracer.event(makeEventRecord({
         adw_id: run.adw_id,
         type: "log",
         name: "tiering",
@@ -123,7 +123,7 @@ export async function startRun(ctx, requiredAgents, requiredSuites) {
     // reading the console when the two disagree.
     for (const [agentName, effective] of Object.entries(tiering.changedModels(run.tiering))) {
         const route = run.tiering.routing[agentName];
-        run.console.note(`[spf] tiering ${agentName} ${route.tier} (${route.configured} -> ${effective}) risk=${run.tiering.risk}`);
+        await run.console.note(`[spf] tiering ${agentName} ${route.tier} (${route.configured} -> ${effective}) risk=${run.tiering.risk}`);
     }
     return run;
 }
@@ -176,7 +176,23 @@ function appendTrailer(message, trailer) {
  * -> no trailer, ever: a trailer that lies launders an AI verdict into a git
  * attestation.
  */
-export function commitEnvelope(run, ph, envelope, signoff) {
+export async function commitEnvelope(run, ph, envelope, signoff) {
+    // An agent's own plan can (and sometimes does) instruct it to `git commit`
+    // its own work directly — e.g. a "Commit convention" section the planner
+    // wrote into the plan, following a target repo's own commit-message
+    // rules. When that happens, this phase's working tree is already clean by
+    // the time it runs: `commitAll`'s `git status --porcelain` finds nothing
+    // staged and throws "nothing to commit", even though real, tested work
+    // already landed on the branch a phase ago. Distinguish that from the
+    // genuine "nothing happened at all" case by checking whether HEAD already
+    // holds committed changes ahead of `run.base` — if so, this phase has
+    // nothing left to do and the existing HEAD *is* the result, not a failure.
+    const base = run.cfg.watch?.base_branch ?? "main";
+    if (!run.git.isDirty() && run.git.diffFiles(base).length > 0) {
+        const sha = run.git.shortSha();
+        await ph.log({ sha, message: "(already committed by a preceding phase — nothing new to stage)" });
+        return;
+    }
     let message = envelope.commit_message || `spf(${run.adw_id}): ${envelope.summary}`;
     if (signoff) {
         const trailerLine = `Signed-off-by: ${signoff.name} <${signoff.email}>`;
@@ -186,11 +202,11 @@ export function commitEnvelope(run, ph, envelope, signoff) {
         if (!alreadyPresent)
             message = appendTrailer(message, trailerLine);
     }
-    ph.log({ sha: run.git.commitAll(message), message });
+    await ph.log({ sha: run.git.commitAll(message), message });
 }
 /** Log a change-capture result the same way every chain that captures one did. */
-export function logChangeset(ph, result) {
-    ph.log({
+export async function logChangeset(ph, result) {
+    await ph.log({
         base: `${result.base.label} @ ${result.base.commit.slice(0, 7)}`,
         reason: result.base.reason,
         files: result.files.length + result.untracked.length,
@@ -328,7 +344,7 @@ export function request(opts = {}) {
             const payload = { input: state.prompt };
             if (opts.logBaseline)
                 payload.baseline = run.git.shortSha(state.baseline);
-            ph.log(payload);
+            await ph.log(payload);
         });
     };
     return makeStep(fn, { label: "engineer(request)" });
@@ -454,8 +470,8 @@ export function qualityCheck(opts = { suite: "all" }) {
             description: opts.description ??
                 (suiteName === "all" ? "Run the deterministic quality blocks" : "Run the suite — a known command, so code runs it and no agent has to rediscover it"),
         }), async (ph) => {
-            const result = quality.runSuite(run, suiteName);
-            quality.record(ph, result);
+            const result = await quality.runSuite(run, suiteName);
+            await quality.record(ph, result);
             state.quality = result;
             state.accepted = result.passed;
             state.reason = result.passed ? "" : `quality failed: ${result.failures.join("; ")}`;
@@ -498,8 +514,8 @@ export function fixLoop(opts = { suite: "test" }) {
                         ? "Lint, typecheck, and build before testing"
                         : "Run the suite — a known command, so code runs it and no agent has to rediscover it"),
             }), async (ph) => {
-                const r = quality.runSuite(run, suiteName);
-                quality.record(ph, r);
+                const r = await quality.runSuite(run, suiteName);
+                await quality.record(ph, r);
                 return r;
             });
             if (result.passed)
@@ -597,7 +613,7 @@ export function commit(opts = {}) {
             owner: "git",
             description: opts.description ??
                 (opts.onlyIfAccepted ? "Land the code only after the suite came back green" : "Land the builder's changes, using the message it wrote"),
-        }), async (ph) => commitEnvelope(run, ph, state.previous));
+        }), async (ph) => await commitEnvelope(run, ph, state.previous));
     };
     return makeStep(fn, { label: "git(commit)" });
 }
@@ -616,7 +632,7 @@ export function changes(opts = {}) {
             description: opts.description ?? `Diff the working tree against ${base} — the change to be written up`,
         }), async (ph) => {
             const result = changesLib.capture(run, makeChangeCapture({ base }));
-            logChangeset(ph, result);
+            await logChangeset(ph, result);
             if (result.empty) {
                 throw new Error(`nothing changed since ${result.base.label} (${result.base.reason}) — documenting runs after a build. ` +
                     `Build something first, or point --base at the ref the work should be measured from.`);
@@ -770,7 +786,7 @@ export function publishIssues(opts = {}) {
             clearStaleRefineOutputFiles(run.context_handoff_dir);
             if (questions.length > 0) {
                 writeFileSync(path.join(run.context_handoff_dir, "refine_questions.json"), JSON.stringify(questions, null, 2));
-                ph.log({ escalated: questions.length });
+                await ph.log({ escalated: questions.length });
                 return;
             }
             if (split.length > 0) {
@@ -781,7 +797,7 @@ export function publishIssues(opts = {}) {
                 // `proposeSpecSplit`, same division of labor as the `questions`
                 // branch above (this writes, `runSpec` posts/transitions).
                 writeFileSync(path.join(run.context_handoff_dir, "refine_split.json"), JSON.stringify(split, null, 2));
-                ph.log({ split_proposed: split.length });
+                await ph.log({ split_proposed: split.length });
                 return;
             }
             const tracker = refineLib.resolveAuthoringProvider(run.cfg);
@@ -791,7 +807,7 @@ export function publishIssues(opts = {}) {
                 priorityCeiling,
             });
             writeFileSync(path.join(run.context_handoff_dir, "refine_publish.json"), JSON.stringify(created.map((c) => ({ id: c.issue.id, title: c.issue.title, kind: c.kind, isLeaf: c.isLeaf })), null, 2));
-            ph.log({ created: created.length, leaves: created.filter((c) => c.isLeaf).length, priority_ceiling: priorityCeiling });
+            await ph.log({ created: created.length, leaves: created.filter((c) => c.isLeaf).length, priority_ceiling: priorityCeiling });
         });
     };
     return makeStep(fn, { label: "code(publish)" });
@@ -843,5 +859,5 @@ export async function runSteps(ctx, requiredAgents, requiredSuites, steps, optio
     for (const step of steps) {
         await step(run, state);
     }
-    return run.finish(state.accepted, state.reason);
+    return await run.finish(state.accepted, state.reason);
 }

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

@@ -1 +1 @@
-export declare function abortCommand(argv: string[]): number;
+export declare function abortCommand(argv: string[]): Promise<number>;

package/dist/cli/commands/abort.js

@@ -4,18 +4,45 @@
  * recorded as still running for this adw_id and SIGTERM them. Since Flue
  * runs in-process, that pid is the whole `spf` invocation driving the chain
  * — this stops the run, not just the current model call.
+ *
+ * LOCAL-FILE-SPECIFIC: reads the `processes` table through a second raw
+ * `Database` handle on the same sqlite file `db` already opened — there is
+ * no such file for a `kind:"d1"` repo (SPF #66), so this fails clearly
+ * instead of pretending a network-backed process table works the same way.
+ * A future release could reach the same table over `SfDb`'s own (now async)
+ * query surface instead of a raw second handle — not done here because nothing
+ * else in this command needs it, and the raw handle already matched
+ * `db.journalMode`'s existing guarantees for the local case.
  */
 import { Database } from "../../core/sqlite.js";
 import { parseCli } from "../../core/utils.js";
-import { openTrace } from "./trace.js";
-export function abortCommand(argv) {
+import { openTrace, resolveTrace } from "./trace.js";
+export async function abortCommand(argv) {
     const { positionals, options } = parseCli(argv, ["cwd", "config"]);
     if (positionals.length < 1) {
         console.error("usage: spf abort <adw_id> [--cwd <dir>] [--config <path>]");
         return 1;
     }
     const adwId = positionals[0];
-    const { db, dataDir } = openTrace(options);
+    // Checked BEFORE opening anything: a d1-backed repo has no local process
+    // table regardless of whether its trace db can even be reached, so there
+    // is no reason to pay for (or risk failing) an `openTrace` HTTP round
+    // trip just to then refuse. This also means no `SfDb` handle is ever
+    // opened for the d1 case — nothing to leave unclosed.
+    const { dataPaths } = resolveTrace(options);
+    if (dataPaths.db.kind === "d1") {
+        console.error(`spf abort is not supported for a d1-backed repo (observability.db.kind: "d1") — ` +
+            `there is no local process table to read for database_id ${JSON.stringify(dataPaths.db.database_id)}. ` +
+            `Stop the process by pid/OS tooling directly, or on the machine that ran it.`);
+        return 1;
+    }
+    const { db, dataDir } = await openTrace(options);
+    if (db.path === null) {
+        // Unreachable in practice — the `dataPaths.db.kind === "d1"` guard above
+        // already rejected the only case `db.path` can be null for — but keeps
+        // this typed as a real narrowing rather than a `!` assertion.
+        throw new Error("spf abort: db.path is null after the d1 guard — this should never happen");
+    }
     // SfDb opens read-only; a live process row needs a separate writable
     // handle only to read it here (no write happens) — reuse the same file.
     const raw = new Database(db.path, { readonly: true });

package/dist/cli/commands/doctor.js

@@ -8,11 +8,13 @@
  */
 import { existsSync, statSync } from "node:fs";
 import { spawnSync } from "node:child_process";
+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 * as permissions from "../../core/permissions.js";
 import * as agentCc from "../../core/agent_cc.js";
+import * as agentOpencode from "../../core/agent_opencode.js";
 import { DEFAULT_NOTIFY_ENV_KEY } from "../../core/notify/notifier.js";
 import { endpointLabel, redact, resolveTracesUrl } from "../../core/otel.js";
 import { isKnownToolName as isKnownFlueToolName, resolveModel } from "../../core/agent_flue.js";
@@ -28,6 +30,7 @@ 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";
+import { SfDb } from "../../ui/server/db.js";
 /**
  * A transient "checking X..." status line around a network probe — real
  * work only starts inside `run()`; this doesn't touch the promise's timing.
@@ -283,7 +286,54 @@ export async function doctorCommand(argv) {
     }
     const dataPaths = paths.resolveDataPaths(anchor, cfg.defaults.data_dir, cfg.observability.db);
     check(report, "data_dir", true, dataPaths.data_dir);
-    check(report, "db_path", true, `${dataPaths.db_path}${existsSync(dataPaths.db_path) ? "" : " (not created yet — fine before the first run)"}`);
+    // `db_path` is `null` for a `kind: "d1"` observability.db — there is no
+    // local file to check for existence; `spf doctor`'s own D1 reachability
+    // probe (account id / API token / database id) is PR 3's job (SPF #66).
+    check(report, "db_path", true, dataPaths.db_path
+        ? `${dataPaths.db_path}${existsSync(dataPaths.db_path) ? "" : " (not created yet — fine before the first run)"}`
+        : `d1 database_id=${JSON.stringify(dataPaths.db.kind === "d1" ? dataPaths.db.database_id : "")} (remote — no local file)`);
+    // D1 trace db — only when observability.db resolves to a remote Cloudflare
+    // D1 database (PR 1's resolveObservabilityDb / PR 2's D1TraceDb, both
+    // already folded into `dataPaths.db` by `paths.resolveDataPaths` above).
+    // Same two-step shape as every other Cloudflare probe in this file (Workers
+    // AI above, sandbox.cloudflare below): a static config-shape check first —
+    // the account/token env vars actually need to be SET before there's
+    // anything to probe — then a separate, NEVER-hard-failing reachability
+    // check, gated on --no-probe like every other live probe here.
+    if (dataPaths.db.kind === "d1") {
+        const { account_id_env, api_token_env, database_id } = dataPaths.db;
+        const missingEnv = [account_id_env, api_token_env].filter((k) => !process.env[k]);
+        check(report, "D1 trace db credentials", true, // informational/warning only — same never-a-hard-failure contract as the Cloudflare Workers AI endpoint check above
+        missingEnv.length === 0
+            ? `${account_id_env} and ${api_token_env} are set`
+            : `${missingEnv.join(", ")} not set — required for observability.db kind: "d1"`, missingEnv.length === 0 ? undefined : "warn");
+        if (missingEnv.length === 0 && !flags["no-probe"]) {
+            // A cheap, read-only "does a sessions table exist yet" check —
+            // `SfDb.exists()` (PR 2), never a full `Tracer`/write. Mirrors
+            // `SfDb.open()`'s own friendly-error probe but collapses "nothing
+            // written yet" to a soft finding instead of throwing.
+            const probe = await withProbeStatus("D1 trace db reachability", async () => {
+                try {
+                    return { ok: true, exists: await SfDb.exists(dataPaths) };
+                }
+                catch (error) {
+                    return { ok: false, error: error.message };
+                }
+            });
+            check(report, "D1 trace db reachability", true, // informational/warning only — same contract as every other reachability probe in this file
+            probe.ok
+                ? probe.exists
+                    ? `reachable: D1 database ${database_id} has a "sessions" table`
+                    : `reachable: D1 database ${database_id} has no "sessions" table yet (fine before the first run)`
+                : `unreachable or errored: ${probe.error}`, 
+            // "warn" only when the request itself failed (unreachable, bad
+            // credentials, wrong database_id) — that's the case an operator
+            // needs to act on. A successful request that simply finds no
+            // "sessions" table yet is the healthy fresh-database state (same
+            // as the local `db_path` check above), so it's "info", not "warn".
+            probe.ok ? "info" : "warn");
+        }
+    }
     check(report, "flue_db_path", true, path.join(dataPaths.data_dir, "flue.db"));
     // Validate the WHOLE roster and EVERY declared suite — doctor's job is "is
     // everything defined here healthy", not "can one specific chain run".
@@ -366,6 +416,57 @@ export async function doctorCommand(argv) {
                 " (this is a real, billable inference request — pass --no-probe to skip both network probes)", result.ok ? "info" : "warn");
         }
     }
+    const usesOpencode = cfg.agents.some((a) => a.coding_agent === "opencode");
+    if (usesOpencode) {
+        // Mirrors the "claude CLI" check above — SPF_OPENCODE_CMD can point at a
+        // wrapper/launcher instead of the literal `opencode` binary (see
+        // agent_opencode.ts's module comment), so check whatever
+        // agent_opencode.ts will actually spawn: cmdSpec's first token.
+        const cmdSpec = process.env["SPF_OPENCODE_CMD"] || "opencode";
+        const cmdTokens = cmdSpec.split(/\s+/).filter(Boolean);
+        const cmdBin = cmdTokens[0] || "opencode";
+        const opencodeOnPath = binaryOnPath(cmdBin);
+        let version = "";
+        if (opencodeOnPath && cmdBin === "opencode") {
+            const result = spawnSync("opencode", ["--version"], { encoding: "utf-8" });
+            version = result.status === 0 ? result.stdout.trim() : "";
+        }
+        check(report, "opencode CLI", opencodeOnPath, opencodeOnPath
+            ? version || (cmdBin === "opencode" ? "on PATH, but --version failed" : `"${cmdBin}" on PATH (via SPF_OPENCODE_CMD) — --version not checked for a wrapper/launcher`)
+            : `"${cmdBin}" not found on PATH — required by any coding_agent: opencode agent${cmdBin !== "opencode" ? " (checked SPF_OPENCODE_CMD's first token, not the literal \"opencode\")" : ""}`);
+        // Auth is treated as ALREADY CONFIGURED territory here, not something
+        // doctor drives interactively (no `opencode auth login` flow) — per
+        // opencode's own docs, ~/.local/share/opencode/auth.json is the
+        // credential store and `opencode auth list` is the documented
+        // non-interactive check. Informational only (`ok: true` regardless),
+        // same "fine if authenticated another way" contract as the
+        // ANTHROPIC_API_KEY check above — and it also defends against a known
+        // upstream race condition that can write an empty (0-byte) token file,
+        // which existsSync alone would miss.
+        // `~/.local/share` is only the XDG_DATA_HOME *default* — an operator
+        // with that env var set (routine on Linux) has opencode's credential
+        // store elsewhere; honoring it here avoids a false "not authenticated"
+        // warning that `opencode auth login` (writing to the SAME XDG location)
+        // would never actually clear.
+        const dataHome = process.env["XDG_DATA_HOME"] || path.join(homedir(), ".local", "share");
+        const authPath = path.join(dataHome, "opencode", "auth.json");
+        let authDetail;
+        let authWarn = true;
+        if (!existsSync(authPath)) {
+            authDetail = `${authPath} not found — run \`opencode auth login\` (or set the provider's own env var) before running spf`;
+        }
+        else {
+            const size = statSync(authPath).size;
+            if (size > 0) {
+                authDetail = `${authPath} present (${size} bytes)`;
+                authWarn = false;
+            }
+            else {
+                authDetail = `${authPath} exists but is empty — a known opencode upstream race can write an empty token file; re-run \`opencode auth login\``;
+            }
+        }
+        check(report, "opencode auth", true, authDetail, authWarn ? "warn" : "info");
+    }
     // Flue agents pointed at a local Ollama server (`model: ollama/...`) have
     // no API key to check (providers.ts's PROVIDER_ENV_KEYS.ollama is `[]`,
     // handled in the per-agent loop below) but DO have a server that might
@@ -454,7 +555,7 @@ export async function doctorCommand(argv) {
                 check(report, `${label} model`, false, error.message);
             }
         }
-        const isKnownToolName = agent.coding_agent === "claude_code" ? agentCc.isKnownToolName : isKnownFlueToolName;
+        const isKnownToolName = agent.coding_agent === "claude_code" ? agentCc.isKnownToolName : agent.coding_agent === "opencode" ? agentOpencode.isKnownToolName : isKnownFlueToolName;
         for (const toolName of agent.tools ?? []) {
             if (!isKnownToolName(toolName))
                 check(report, `${label} tool "${toolName}"`, false, "not a known tool name");
@@ -750,14 +851,14 @@ export async function doctorCommand(argv) {
             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).
+        // #12 — claude_code/opencode 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`);
+            if ((agent.coding_agent === "claude_code" || agent.coding_agent === "opencode") && backend !== "local") {
+                check(report, `agent "${agent.name}" coding_agent x sandbox`, false, `coding_agent ${JSON.stringify(agent.coding_agent)} 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
@@ -861,6 +962,14 @@ export async function doctorCommand(argv) {
                 ? "set"
                 : 'not set — spf watch needs a classic PAT with "repo" scope (or "public_repo" for a public-only repo); see README.md\'s "GITHUB_TOKEN scope" section');
         }
+        if (cfg.watch.issue_provider === "github") {
+            const statusMapEntries = Object.entries(cfg.watch.github.status_map).filter(([, v]) => Boolean(v));
+            check(report, "watch.github.status_map", true, statusMapEntries.length > 0
+                ? cfg.watch.github.project_number
+                    ? `${statusMapEntries.length} state(s) configured to sync Projects v2 #${cfg.watch.github.project_number}'s Status field — run \`spf watch init\` to validate them, and make sure GITHUB_TOKEN has the "project" scope`
+                    : `${statusMapEntries.length} state(s) configured but watch.github.project_number is unset — status sync stays disabled until it's set`
+                : "not configured — spf watch will only update labels on this repo, never a Projects v2 board (optional, off by default)", "info");
+        }
         if (cfg.watch.issue_provider === "jira") {
             check(report, "watch.jira", Boolean(cfg.watch.jira.base_url.trim() && cfg.watch.jira.project_key.trim()), cfg.watch.jira.base_url.trim() && cfg.watch.jira.project_key.trim()
                 ? `${cfg.watch.jira.base_url} (${cfg.watch.jira.project_key})`
@@ -868,6 +977,10 @@ export async function doctorCommand(argv) {
             check(report, "JIRA_EMAIL / JIRA_API_TOKEN", Boolean(process.env["JIRA_EMAIL"] && process.env["JIRA_API_TOKEN"]), process.env["JIRA_EMAIL"] && process.env["JIRA_API_TOKEN"]
                 ? "set"
                 : 'not set — spf watch needs an Atlassian account email plus an API token (id.atlassian.com -> Security -> API tokens); see README.md\'s "spf watch" section');
+            const statusMapEntries = Object.entries(cfg.watch.jira.status_map).filter(([, v]) => Boolean(v));
+            check(report, "watch.jira.status_map", true, statusMapEntries.length > 0
+                ? `${statusMapEntries.length} state(s) configured to sync a native Jira status — run \`spf watch init\` to validate them against the real project's statuses`
+                : "not configured — spf watch will only update labels on this project, never the Jira Status field (optional, off by default)", "info");
         }
         if (cfg.watch.code_host === "bitbucket") {
             check(report, "BITBUCKET_EMAIL / BITBUCKET_API_TOKEN", Boolean(process.env["BITBUCKET_EMAIL"] && process.env["BITBUCKET_API_TOKEN"]), process.env["BITBUCKET_EMAIL"] && process.env["BITBUCKET_API_TOKEN"]

package/dist/cli/commands/estimate.js

@@ -173,7 +173,7 @@ export async function estimateCommand(argv) {
         return 1;
     }
     const prompt = resolvePrompt(promptArg);
-    const trace = openTraceIfExists(options);
+    const trace = await openTraceIfExists(options);
     const cfg = trace.cfg;
     // Same shape as run.ts:54-56 — conditional insertion, never `{agent: flags["agent"] ?? ""}`.
     // `flags` never carries a value-taking option, and an empty-string sentinel
@@ -195,7 +195,7 @@ export async function estimateCommand(argv) {
     catch (error) {
         validateError = error instanceof Error ? error.message : String(error);
     }
-    const history = trace.db ? trace.db.chainPhaseHistory(chain.name) : { sessions: [], joinedExcluded: 0 };
+    const history = trace.db ? await trace.db.chainPhaseHistory(chain.name) : { sessions: [], joinedExcluded: 0 };
     const sample = selectSample(history.sessions, history.joinedExcluded);
     const coldStart = sample.sessions.length === 0;
     const phases = aggregatePhases(sample.sessions);
@@ -205,7 +205,7 @@ export async function estimateCommand(argv) {
     const historicalModels = new Map();
     if (trace.db) {
         for (const session of sample.sessions) {
-            for (const row of trace.db.agentSessions(session.adw_id)) {
+            for (const row of await trace.db.agentSessions(session.adw_id)) {
                 if (row.model !== null && !historicalModels.has(row.agent))
                     historicalModels.set(row.agent, row.model);
             }

package/dist/cli/commands/events.js

@@ -20,9 +20,9 @@ export async function eventsCommand(argv) {
         return 1;
     }
     const adwId = positionals[0];
-    const { db } = openTrace(options);
+    const { db } = await openTrace(options);
     let after = options["after"] ? Number.parseInt(options["after"], 10) : 0;
-    const page = db.events(adwId, after, options["limit"] ? Number.parseInt(options["limit"], 10) : 500);
+    const page = await db.events(adwId, after, options["limit"] ? Number.parseInt(options["limit"], 10) : 500);
     if (flags["json"] && !flags["follow"]) {
         console.log(JSON.stringify(page.events, null, 2));
         return 0;
@@ -35,8 +35,8 @@ export async function eventsCommand(argv) {
     console.error(`-- following ${adwId}; ^C to stop --`);
     for (;;) {
         await sleep(500);
-        const session = db.session(adwId);
-        const next = db.events(adwId, after, 500);
+        const session = await db.session(adwId);
+        const next = await db.events(adwId, after, 500);
         for (const e of next.events)
             printEvent(e);
         if (next.events.length > 0)

package/dist/cli/commands/fanout.js

@@ -266,10 +266,11 @@ export async function fanoutCommand(argv) {
     // `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);
+    if (await SfDb.exists(dataPaths)) {
+        const preflight = await SfDb.open(dataPaths.db, dataPaths.sessions_dir);
         try {
-            const collisions = Array.from({ length: n }, (_, i) => attemptAdwId(baseAdwId, i + 1)).filter((id) => preflight.session(id) !== null);
+            const collisionChecks = await Promise.all(Array.from({ length: n }, (_, i) => attemptAdwId(baseAdwId, i + 1)).map(async (id) => ((await preflight.session(id)) !== null ? id : null)));
+            const collisions = collisionChecks.filter((id) => 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 ` +
@@ -279,7 +280,7 @@ export async function fanoutCommand(argv) {
             }
         }
         finally {
-            preflight.close();
+            await preflight.close();
         }
     }
     if (cfg.defaults.max_run_cost === undefined && cfg.defaults.max_run_tokens === undefined) {
@@ -292,24 +293,82 @@ export async function fanoutCommand(argv) {
     }
     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.
+     * The shared db, opened lazily: it does not exist until the first
+     * attempt's tracer creates it, and `SfDb.open` throws on a repo whose db
+     * has never been written to. 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.
+     *
+     * The IN-FLIGHT PROMISE is memoized, not the resolved value: `core/
+     * fanout.ts` runs `concurrency` workers in parallel, each calling
+     * `readMetrics` independently, so a bare "check `held.db`, then `await`
+     * open, then assign" would let two workers both observe `held.db` unset,
+     * both open a connection, and orphan one unclosed `SfDb` handle. Every
+     * concurrent caller instead awaits this SAME promise, so at most one
+     * `SfDb.exists`/`SfDb.open` pair ever runs at a time.
+     *
+     * Memoized ONLY while pending or successful, though — a rejected open (a
+     * transient D1 network/auth blip) clears the memo (`held.opening = null`
+     * in `ensureDb`'s `.catch()` below) rather than caching the failure
+     * forever. Without that, one blip on attempt 1 would leave every later
+     * attempt reading `ZERO_METRICS` for the rest of the run, degrading the
+     * whole fanout's ranking over a single transient error instead of just
+     * the one attempt that hit it.
+     *
+     * The same reasoning applies to `SfDb.exists` resolving `false`: "not
+     * created yet" is a snapshot, not a permanent fact — a sibling attempt
+     * still mid-`session.ensure` can create the db moments later. HEAD's
+     * `existsSync` re-checked on every call; memoizing a `false` verdict
+     * across this run's whole lifetime would silently zero out every later
+     * attempt's real metrics once the db does show up, so `ensureDb` clears
+     * the memo on a `false` verdict too, not just on rejection.
      */
-    // 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);
+    // A holder object rather than a bare `let`: with a bare `let db: SfDb |
+    // null = null` reassigned only inside `ensureDb`'s nested async closure,
+    // TypeScript cannot track that reassignment across the closure boundary —
+    // at the outer `finally`'s `db?.close()` read site (below), it infers
+    // `db`'s type as `never` (narrowed from the closure never having run, as
+    // far as the checker can tell at that point) and refuses to compile:
+    // "Property 'close' does not exist on type 'never'". Routing the same
+    // mutable cell through a holder object's property sidesteps that —
+    // `held.db` is never narrowed to a literal `null` the way a bare `let`
+    // is, so the read site stays typed `SfDb | null` throughout. `opening`
+    // rides the same holder for the same reason: it too is reassigned inside
+    // `ensureDb`'s `.catch()` closure (to clear the memo — see below), and a
+    // bare `let` there trips the identical `never`-narrowing bug at the
+    // outer `finally`'s own read of it.
+    const held = { db: null, opening: null };
+    function ensureDb() {
+        if (!held.opening) {
+            held.opening = (async () => {
+                if (await SfDb.exists(dataPaths)) {
+                    held.db = await SfDb.open(dataPaths.db, dataPaths.sessions_dir);
+                }
+                else {
+                    held.opening = null;
+                }
+            })().catch((error) => {
+                // Do not let one transient failure (a D1 network/auth blip) poison
+                // every subsequent attempt's metrics for the rest of this run: clear
+                // the memo so the NEXT caller gets a fresh open attempt instead of
+                // permanently reusing this rejected promise. The rejection itself
+                // still propagates to whichever concurrent callers are already
+                // awaiting this exact promise object (reassigning `held.opening`
+                // here does not change what an already-returned promise resolves
+                // to) — `readMetrics` above (and its caller in `core/fanout.ts`)
+                // already catches that and ranks the attempt on zero metrics.
+                held.opening = null;
+                throw error;
+            });
         }
-        const gates = held.db.gates(adwId);
-        const session = held.db.session(adwId);
+        return held.opening;
+    }
+    async function readMetrics(adwId) {
+        await ensureDb();
+        if (!held.db)
+            return ZERO_METRICS;
+        const gates = await held.db.gates(adwId);
+        const session = await 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
@@ -444,7 +503,20 @@ export async function fanoutCommand(argv) {
         return 0;
     }
     finally {
-        held.db?.close();
+        // `.catch(() => {})`, not a bare `await`: `held.opening` is a settled
+        // promise `readMetrics` (via `ensureDb`) may have already awaited and
+        // handled upstream (`core/fanout.ts` catches a `readMetrics` rejection,
+        // logs it, and ranks that attempt on zero metrics) — re-awaiting the
+        // SAME rejected promise here a second time would throw straight out of
+        // this `finally`, turning a completed, winner-printed `spf fanout` run
+        // into a nonzero exit, and would also skip `held.db?.close()` and the
+        // `process.off` calls below (a `finally` that throws never reaches its
+        // own remaining statements). Nothing here needs the resolved value or
+        // the rejection reason — only that the open attempt has settled before
+        // deciding whether there's a `held.db` to close.
+        if (held.opening)
+            await held.opening.catch(() => { });
+        await held.db?.close();
         process.off("SIGINT", onSignal);
         process.off("SIGTERM", onSignal);
     }