@gr8ful/spf 0.15.0 → 0.16.0

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

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);
     }

package/dist/cli/commands/loop.js

@@ -1,23 +1,3 @@
-/**
- * `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";
@@ -43,8 +23,13 @@ function qualityRunLike(input) {
         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: () => "" },
+        console: {
+            note: (message) => {
+                console.log(`[spf] loop    ${message}`);
+                return Promise.resolve();
+            },
+        },
+        tracer: { event: () => Promise.resolve("") },
         adw_id: input.adwId,
     };
 }
@@ -154,23 +139,37 @@ export async function loopCommand(argv) {
         // 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();
+        // `SfDb.exists` covers both backends: `existsSync(dataPaths.db_path)`
+        // for local sqlite, and a cheap `sqlite_master` probe (false, not a
+        // throw, when the table isn't there yet) for d1. Both the existence
+        // check and the read itself are inside this loop's own try/catch —
+        // `runIteration` is documented as never throwing (see loop.ts's header),
+        // and a D1 hiccup reaching this readback must rank as zero, not abort
+        // the iteration, the same "never throw, rank as zero" discipline
+        // `fanout.ts`'s `readMetrics` already uses.
+        try {
+            if (await SfDb.exists(dataPaths)) {
+                const db = await SfDb.open(dataPaths.db, dataPaths.sessions_dir);
+                try {
+                    const session = await db.session(iteration.adw_id);
+                    tokens = session?.total_tokens ?? 0;
+                    cost = session?.total_cost ?? 0;
+                }
+                finally {
+                    await db.close();
+                }
             }
         }
+        catch {
+            // best-effort readback only — tokens/cost simply stay 0 for this
+            // iteration's ledger row.
+        }
         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);
+            const result = await 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 };

package/dist/cli/commands/migrate.js

@@ -101,7 +101,14 @@ export function migrateCommand(argv) {
             }
         }
     });
-    const oldDbPath = resolveOld(oldConfig?.observability?.db ?? "adws/adw_data/spf.db");
+    // `observability.db` predates this schema's `{kind:"sqlite"|"d1",...}`
+    // object form (SPF #66) — a stamped `adws/` tree can only ever have written
+    // a bare path here, but a `typeof` guard costs nothing and keeps a
+    // legacy-config-carrying-a-d1-shaped-object from crashing `path.resolve()`
+    // with a TypeError, same explicit non-string handling `abort.ts` gives a
+    // d1-backed repo rather than letting it fail deep inside a file op.
+    const oldDbRaw = oldConfig?.observability?.db;
+    const oldDbPath = resolveOld(typeof oldDbRaw === "string" ? oldDbRaw : "adws/adw_data/spf.db");
     const oldSessionsDir = path.join(path.dirname(oldDbPath), "sessions");
     if (existsSync(oldDbPath)) {
         actions.push({ kind: "copy-file", detail: `${path.relative(anchor.repo_root, oldDbPath)} -> ${newDbRel} (WAL-checkpointed first)` });

package/dist/cli/commands/phases.js

@@ -8,8 +8,8 @@ export async function phasesCommand(argv) {
         return 1;
     }
     const adwId = positionals[0];
-    const { db } = openTrace(options);
-    const rows = db.phases(adwId);
+    const { db } = await openTrace(options);
+    const rows = await db.phases(adwId);
     if (flags["json"]) {
         console.log(JSON.stringify(rows, null, 2));
         return 0;

package/dist/cli/commands/sessions.js

@@ -3,9 +3,9 @@ import { openTrace } from "./trace.js";
 import { isInteractive } from "../ask.js";
 export async function sessionsCommand(argv) {
     const { options, flags } = parseCli(argv, ["cwd", "config", "limit"], ["json"]);
-    const { db } = openTrace(options);
+    const { db } = await openTrace(options);
     const limit = options["limit"] ? Number.parseInt(options["limit"], 10) : 20;
-    const rows = db.sessions(limit);
+    const rows = await db.sessions(limit);
     if (flags["json"]) {
         console.log(JSON.stringify(rows, null, 2));
         return 0;

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

@@ -8,19 +8,39 @@ export interface TraceHandle {
     /** Already loaded by this same resolution — `spf estimate` needs it (ceilings, resolveTiering) and reusing it means one loadConfig, not two. */
     cfg: SFConfig;
 }
-export declare function openTrace(options: Record<string, string>): TraceHandle;
 /**
- * Like `openTrace`, but never throws on a missing db file: `db` is `null`
- * in that one slot instead. `anchor`/`dataDir`/`cfg` still come from the
- * SAME `resolveTrace` call either way — a cold start (no `spf.db` yet)
- * still carries a real, loaded `cfg`, which is what lets `spf estimate`
- * echo `defaults.max_run_tokens`/`max_run_cost` and resolve planned routing
+ * The one place anchor/config/data-path resolution happens, so `openTrace`
+ * and `openTraceIfExists` cannot diverge on it. Exported (not just used
+ * internally) so a caller that needs to inspect `dataPaths.db.kind` BEFORE
+ * deciding whether to open anything at all — `abort.ts`'s d1 guard — can
+ * reuse this exact resolution instead of a second, divergence-prone copy.
+ */
+export declare function resolveTrace(options: Record<string, string>): {
+    dataPaths: paths.DataPaths;
+    anchor: paths.RepoAnchor;
+    dataDir: string;
+    cfg: SFConfig;
+};
+export declare function openTrace(options: Record<string, string>): Promise<TraceHandle>;
+/**
+ * Like `openTrace`, but never throws on a db that has never been written
+ * to: `db` is `null` in that one slot instead. `anchor`/`dataDir`/`cfg`
+ * still come from the SAME `resolveTrace` call either way — a cold start
+ * (no `spf.db` yet, or a fresh D1 database with no `sessions` table) still
+ * carries a real, loaded `cfg`, which is what lets `spf estimate` echo
+ * `defaults.max_run_tokens`/`max_run_cost` and resolve planned routing
  * before it exits, rather than crashing with `SfDb`'s "point spf ui at a
  * target repo" message (which is about `spf ui`, not `spf estimate`).
+ *
+ * `SfDb.exists` covers both backends: `existsSync(dataPaths.db_path)` for
+ * local sqlite, and a cheap `sqlite_master` probe (false, not a throw, when
+ * the `sessions` table isn't there yet) for d1 — so `spf estimate`'s
+ * documented cold-start path (report + exit 3) actually reaches on a fresh
+ * D1 repo instead of crashing.
  */
-export declare function openTraceIfExists(options: Record<string, string>): {
+export declare function openTraceIfExists(options: Record<string, string>): Promise<{
     db: SfDb | null;
     anchor: paths.RepoAnchor;
     dataDir: string;
     cfg: SFConfig;
-};
+}>;

package/dist/cli/commands/trace.js

@@ -1,29 +1,42 @@
 /** Shared by sessions/phases/events/abort/estimate — resolve the workspace and open its trace db. */
-import { existsSync } from "node:fs";
 import * as agents from "../../core/agents.js";
 import * as paths from "../../core/paths.js";
 import { SfDb } from "../../ui/server/db.js";
-/** The one place anchor/config/data-path resolution happens, so `openTrace` and `openTraceIfExists` cannot diverge on it. */
-function resolveTrace(options) {
+/**
+ * The one place anchor/config/data-path resolution happens, so `openTrace`
+ * and `openTraceIfExists` cannot diverge on it. Exported (not just used
+ * internally) so a caller that needs to inspect `dataPaths.db.kind` BEFORE
+ * deciding whether to open anything at all — `abort.ts`'s d1 guard — can
+ * reuse this exact resolution instead of a second, divergence-prone copy.
+ */
+export function resolveTrace(options) {
     const anchor = paths.resolveAnchor(options["cwd"]);
     const cfg = agents.loadConfig(paths.resolveConfigPaths(anchor, options["config"]).paths);
     const dataPaths = paths.resolveDataPaths(anchor, cfg.defaults.data_dir, cfg.observability.db);
-    return { dbPath: dataPaths.db_path, anchor, dataDir: dataPaths.data_dir, cfg };
+    return { dataPaths, anchor, dataDir: dataPaths.data_dir, cfg };
 }
-export function openTrace(options) {
-    const { dbPath, anchor, dataDir, cfg } = resolveTrace(options);
-    return { db: new SfDb(dbPath), anchor, dataDir, cfg };
+export async function openTrace(options) {
+    const { dataPaths, anchor, dataDir, cfg } = resolveTrace(options);
+    return { db: await SfDb.open(dataPaths.db, dataPaths.sessions_dir), anchor, dataDir, cfg };
 }
 /**
- * Like `openTrace`, but never throws on a missing db file: `db` is `null`
- * in that one slot instead. `anchor`/`dataDir`/`cfg` still come from the
- * SAME `resolveTrace` call either way — a cold start (no `spf.db` yet)
- * still carries a real, loaded `cfg`, which is what lets `spf estimate`
- * echo `defaults.max_run_tokens`/`max_run_cost` and resolve planned routing
+ * Like `openTrace`, but never throws on a db that has never been written
+ * to: `db` is `null` in that one slot instead. `anchor`/`dataDir`/`cfg`
+ * still come from the SAME `resolveTrace` call either way — a cold start
+ * (no `spf.db` yet, or a fresh D1 database with no `sessions` table) still
+ * carries a real, loaded `cfg`, which is what lets `spf estimate` echo
+ * `defaults.max_run_tokens`/`max_run_cost` and resolve planned routing
  * before it exits, rather than crashing with `SfDb`'s "point spf ui at a
  * target repo" message (which is about `spf ui`, not `spf estimate`).
+ *
+ * `SfDb.exists` covers both backends: `existsSync(dataPaths.db_path)` for
+ * local sqlite, and a cheap `sqlite_master` probe (false, not a throw, when
+ * the `sessions` table isn't there yet) for d1 — so `spf estimate`'s
+ * documented cold-start path (report + exit 3) actually reaches on a fresh
+ * D1 repo instead of crashing.
  */
-export function openTraceIfExists(options) {
-    const { dbPath, anchor, dataDir, cfg } = resolveTrace(options);
-    return { db: existsSync(dbPath) ? new SfDb(dbPath) : null, anchor, dataDir, cfg };
+export async function openTraceIfExists(options) {
+    const { dataPaths, anchor, dataDir, cfg } = resolveTrace(options);
+    const db = (await SfDb.exists(dataPaths)) ? await SfDb.open(dataPaths.db, dataPaths.sessions_dir) : null;
+    return { db, anchor, dataDir, cfg };
 }