@gr8ful/spf 0.15.0 → 0.17.0

package/dist/core/tracer.js

@@ -1,13 +1,28 @@
 /**
- * Tracer: every event lands in JSONL and SQLite AS IT HAPPENS.
+ * Tracer: every event lands in JSONL and the trace db AS IT HAPPENS.
  *
- * Files are the raw record; spf.db is the queryable mirror the UI polls.
- * WAL mode so the UI can read while ADW processes write.
+ * Files are the raw record; the trace db (local sqlite, or remote D1 — see
+ * `core/trace_db.ts`) is the queryable mirror the UI polls. For the LOCAL
+ * backend, WAL mode lets the UI read while ADW processes write, in the same
+ * instant, because both sides share one file on one filesystem.
+ *
+ * THE D1 BACKEND DOES NOT MAKE THAT SAME PROMISE — see `core/trace_db.ts`'s
+ * `D1TraceDb` doc comment for the consistency model it actually has and why
+ * this is a deliberate, documented trade-off (SPF #66) rather than a gap to
+ * close here.
  *
  * No push transport in the CONTROL flow — that is always, still, and only:
- * agents -> sqlite -> web ui. SQLite is the source of truth; nothing
+ * agents -> trace db -> web ui. The trace db is the source of truth; nothing
  * downstream of it can affect a phase, a gate, or a run outcome.
  *
+ * WHY EVERY WRITE METHOD BELOW IS ASYNC: the D1 backend's only way to reach
+ * a database from this plain Node CLI is its HTTP REST API — a network call.
+ * `core/trace_db.ts`'s `TraceDb` interface is async for that reason, and
+ * every write method here is a thin `await this.db...` over it — see that
+ * module's header. For the LOCAL backend this costs nothing but the syntax:
+ * `LocalTraceDb` wraps the exact same synchronous `Database` calls this file
+ * always made, immediately resolved.
+ *
  * The one amendment: when (and only when) `observability.otel` is configured,
  * each write method below ends with a single fan-out line to an optional
  * OtelExporter — a lossy, allowlisted PROJECTION of what was just written,
@@ -21,9 +36,9 @@
  * `processStart`/`processEnd` (pids) — have NO fan-out line on purpose. Do not
  * add one.
  */
-import { Database } from "./sqlite.js";
 import { appendFileSync, mkdirSync } from "node:fs";
 import path from "node:path";
+import { createTraceDb } from "./trace_db.js";
 import { newId, nowIso } from "./utils.js";
 const SCHEMA = `
 CREATE TABLE IF NOT EXISTS sessions (
@@ -38,7 +53,7 @@ CREATE TABLE IF NOT EXISTS sessions (
 );
 CREATE TABLE IF NOT EXISTS phases (
   phase_id      TEXT PRIMARY KEY,
-  adw_id        TEXT REFERENCES sessions,
+  adw_id        TEXT,
   seq           INTEGER,
   name TEXT, kind TEXT, owner TEXT, description TEXT,
   status        TEXT DEFAULT 'fail',
@@ -48,8 +63,8 @@ CREATE TABLE IF NOT EXISTS phases (
 );
 CREATE TABLE IF NOT EXISTS events (
   event_id      TEXT PRIMARY KEY,
-  adw_id        TEXT REFERENCES sessions,
-  phase_id      TEXT REFERENCES phases,
+  adw_id        TEXT,
+  phase_id      TEXT,
   parent_id     TEXT,
   type          TEXT,
   name          TEXT,
@@ -59,8 +74,8 @@ CREATE TABLE IF NOT EXISTS events (
 );
 CREATE TABLE IF NOT EXISTS envelopes (
   envelope_id   TEXT PRIMARY KEY,
-  adw_id        TEXT REFERENCES sessions,
-  phase_id      TEXT REFERENCES phases,
+  adw_id        TEXT,
+  phase_id      TEXT,
   agent         TEXT,
   output_type   TEXT,
   payload_json  TEXT,
@@ -70,8 +85,8 @@ CREATE TABLE IF NOT EXISTS envelopes (
 );
 CREATE TABLE IF NOT EXISTS gate_results (
   id            INTEGER PRIMARY KEY AUTOINCREMENT,
-  adw_id        TEXT REFERENCES sessions,
-  phase_id      TEXT REFERENCES phases,
+  adw_id        TEXT,
+  phase_id      TEXT,
   attempt       INTEGER,
   gate          TEXT,
   passed        INTEGER,
@@ -81,7 +96,7 @@ CREATE TABLE IF NOT EXISTS gate_results (
 );
 CREATE TABLE IF NOT EXISTS processes (
   id            INTEGER PRIMARY KEY AUTOINCREMENT,
-  adw_id        TEXT REFERENCES sessions,
+  adw_id        TEXT,
   kind          TEXT,                -- 'adw' (the workflow process) | 'agent' (a coding-agent child)
   name          TEXT,                -- '' for the adw, the agent name for a child
   pid           INTEGER,
@@ -89,7 +104,7 @@ CREATE TABLE IF NOT EXISTS processes (
   started_at    TEXT, ended_at TEXT  -- ended_at NULL = believed alive
 );
 CREATE TABLE IF NOT EXISTS agent_sessions (
-  adw_id        TEXT REFERENCES sessions,
+  adw_id        TEXT,
   agent         TEXT,
   coding_agent  TEXT, model TEXT, color TEXT,
   session_id    TEXT,
@@ -111,50 +126,72 @@ const MIGRATIONS = [
 ];
 export class Tracer {
     db;
+    /** Absolute local sqlite path — `null` for a `kind:"d1"` config (`Console.sessionFinished`'s "db" line falls back to `runner.ts`'s `describeObservabilityDb` for a human label in that case). */
     dbPath;
     eventsJsonl;
     /** `null` unless `observability.otel` is configured — see the header. */
     otel;
-    constructor(dbPath, eventsJsonl, otel) {
-        this.otel = otel ?? null;
-        mkdirSync(path.dirname(dbPath), { recursive: true });
+    constructor(db, dbPath, eventsJsonl, otel) {
+        this.db = db;
         this.dbPath = dbPath;
         this.eventsJsonl = eventsJsonl;
+        this.otel = otel;
         mkdirSync(path.dirname(eventsJsonl), { recursive: true });
-        this.db = new Database(this.dbPath);
-        this.db.exec("PRAGMA journal_mode=WAL;");
-        this.db.exec("PRAGMA synchronous=NORMAL;");
-        this.db.exec("PRAGMA busy_timeout=5000;");
-        this.db.exec(SCHEMA);
-        this.migrate();
     }
     /**
-     * Close the sqlite handle. A one-shot CLI process never needs this — it
+     * Open (or create) the trace db, run schema + migrations, and return a
+     * ready-to-use Tracer. The one constructor path — a plain `new Tracer(...)`
+     * cannot do this work itself because opening a D1-backed db means awaited
+     * HTTP calls before the schema exists, and a constructor cannot be async.
+     *
+     * `dbConfig` accepts either a bare local sqlite path (sugar for
+     * `{kind:"sqlite",path}` — every test's shorthand, and what every caller
+     * before SPF #66 passed) or a normalized `observability.db` descriptor
+     * (`paths.resolveDataPaths(...).db` — sqlite or d1).
+     */
+    static async open(dbConfig, eventsJsonl, otel, traceDbOptions) {
+        const normalized = typeof dbConfig === "string" ? { kind: "sqlite", path: dbConfig } : dbConfig;
+        const db = createTraceDb(normalized, { fetchImpl: traceDbOptions?.fetchImpl });
+        if (normalized.kind === "sqlite") {
+            // WAL + the busy/synchronous pragmas below are meaningless over D1's
+            // HTTP API (there is no local journal file to configure), so this
+            // block only ever runs for the local backend.
+            await db.exec("PRAGMA journal_mode=WAL;");
+            await db.exec("PRAGMA synchronous=NORMAL;");
+            await db.exec("PRAGMA busy_timeout=5000;");
+        }
+        await db.exec(SCHEMA);
+        const tracer = new Tracer(db, normalized.kind === "sqlite" ? normalized.path : null, eventsJsonl, otel ?? null);
+        await tracer.migrate();
+        return tracer;
+    }
+    /**
+     * Close the trace db handle. A one-shot CLI process never needs this — it
      * exits right after its one Tracer anyway — but `spf watch`'s daemon loop
-     * builds a fresh Tracer (and a fresh `new Database(dbPath)`) per claimed
-     * issue, in-process, for the life of the daemon; without this, every
-     * issue's handle stayed open forever. Called from `session.ts`'s
-     * `finalize()`, once a run's own dispatch has fully settled — see its
-     * comment for why that timing is safe.
+     * builds a fresh Tracer (and a fresh local db connection, or a fresh
+     * stateless D1 client) per claimed issue, in-process, for the life of the
+     * daemon; without this, every issue's local handle stayed open forever.
+     * Called from `session.ts`'s `finalize()`, once a run's own dispatch has
+     * fully settled — see its comment for why that timing is safe. A no-op for
+     * `D1TraceDb` (stateless HTTP — nothing to release).
      */
-    close() {
-        this.db.close();
+    async close() {
+        await this.db.close();
     }
     /** Additive column migrations, so a db from an older SPF still opens. */
-    migrate() {
+    async migrate() {
         for (const [table, column, decl] of MIGRATIONS) {
-            const columns = new Set(this.db.query(`PRAGMA table_info(${table})`).all().map((row) => row.name));
+            const columns = new Set((await this.db.query(`PRAGMA table_info(${table})`).all()).map((row) => row.name));
             if (!columns.has(column)) {
-                this.db.exec(`ALTER TABLE ${table} ADD COLUMN ${column} ${decl}`);
+                await this.db.exec(`ALTER TABLE ${table} ADD COLUMN ${column} ${decl}`);
             }
         }
     }
     /**
-     * The ONE door to the optional otel projection, and the only reason a fan-out
-     * line is safe to put at the end of a synchronous write method: it is a
-     * no-op when unconfigured, and it swallows everything. An exporter bug, a
-     * malformed span, an exhausted queue — none of it may ever surface as a
-     * failed phase, because export is not allowed to dispose of anything. The
+     * The ONE door to the optional otel projection. It is a no-op when
+     * unconfigured, and it swallows everything: an exporter bug, a malformed
+     * span, an exhausted queue — none of it may ever surface as a failed
+     * phase, because export is not allowed to dispose of anything. The
      * exporter's own methods are synchronous enqueues; the network happens later,
      * on an unref'd timer.
      */
@@ -171,12 +208,12 @@ export class Tracer {
         }
     }
     // ── events ──────────────────────────────────────────────────────────────
-    event(record) {
+    async event(record) {
         const eventId = `evt_${newId(12)}`;
         const ts = nowIso();
         const line = { event_id: eventId, ts, ...record };
         appendFileSync(this.eventsJsonl, JSON.stringify(line) + "\n");
-        this.db
+        await this.db
             .query(`INSERT INTO events (event_id, adw_id, phase_id, parent_id, type, name,
          payload_json, tokens, started_at, ended_at) VALUES (?,?,?,?,?,?,?,?,?,?)`)
             .run(eventId, record.adw_id, record.phase_id, record.parent_id, record.type, record.name, JSON.stringify(record.payload), record.tokens ?? null, record.started_at || ts, record.ended_at ?? null);
@@ -184,37 +221,72 @@ export class Tracer {
         return eventId;
     }
     // ── sessions ────────────────────────────────────────────────────────────
-    sessionStart(adwId, engineer, adwName) {
+    async sessionStart(adwId, engineer, adwName) {
         const startedAt = nowIso();
-        this.db
+        await this.db
             .query(`INSERT INTO sessions (adw_id, status, engineer, started_at) VALUES (?,?,?,?)
          ON CONFLICT(adw_id) DO UPDATE SET status='running'`)
             .run(adwId, "running", engineer, startedAt);
         if (adwName) {
             // A joined session chains ADWs — record each distinct one, in run order.
-            const row = this.db.query("SELECT adw_name FROM sessions WHERE adw_id=?").get(adwId);
+            const row = (await this.db.query("SELECT adw_name FROM sessions WHERE adw_id=?").get(adwId));
             const names = row?.adw_name ? row.adw_name.split(" + ") : [];
             if (!names.includes(adwName)) {
                 names.push(adwName);
-                this.db.query("UPDATE sessions SET adw_name=? WHERE adw_id=?").run(names.join(" + "), adwId);
+                await this.db.query("UPDATE sessions SET adw_name=? WHERE adw_id=?").run(names.join(" + "), adwId);
             }
         }
         // otel projection: the run's clock only. `engineer` is a person's name —
         // outside the allowlist, and not a measure of anything.
         this.fanOut((otel) => otel.recordSessionStart(startedAt));
     }
-    sessionRequest(adwId, request) {
-        this.db.query("UPDATE sessions SET request=? WHERE adw_id=?").run(request.slice(0, 500), adwId);
+    async sessionRequest(adwId, request) {
+        await this.db.query("UPDATE sessions SET request=? WHERE adw_id=?").run(request.slice(0, 500), adwId);
     }
-    sessionFinish(adwId, ok) {
-        this.db
+    async sessionFinish(adwId, ok) {
+        // otel projection FIRST — synchronously, before ANY `await` in this
+        // method, including the ones below. `session.ts`'s `handleSignal` fires
+        // this method un-awaited and then calls `otel.flushAll()` -> `drain()`
+        // in that SAME synchronous turn (no microtask has run yet). `drain()`
+        // emits a placeholder "incomplete" root span the instant `rootEmitted`
+        // is still false, and `OtelExporter.emitRootSpan` latches on that flag —
+        // so once the placeholder fires, the real verdict below is silently
+        // dropped forever. `recordSessionFinish` -> `emitRootSpan` is a pure,
+        // synchronous, in-memory queue push (see otel.ts): safe to fire before
+        // either write below has actually landed, and it must fire here, not
+        // after them, to win that race unconditionally on both backends.
+        this.fanOut((otel) => otel.recordSessionFinish(ok)); // otel projection — see fanOut
+        // `processesEndAll` is CALLED (not awaited) before the sessions-row
+        // update below, on purpose: `session.ts`'s SIGINT/SIGTERM handler fires
+        // this method un-awaited and, on the local backend with no otel/notify
+        // configured, calls `process.exit()` in the very same synchronous turn —
+        // which never drains the microtask queue. `LocalTraceDb`'s writes happen
+        // synchronously the moment `.run(...)` is CALLED (only the `await` after
+        // it is deferred), so calling this first guarantees its write has
+        // already landed by the time this function reaches its own first
+        // `await`, exactly like the sessions-row write below. Awaiting it only
+        // after starting the sessions-row update would put it entirely after
+        // that update's `await`, i.e. in a microtask `process.exit()` never
+        // reaches — see session.ts's `handleSignal` for the full trace of why.
+        const processesDone = this.processesEndAll(adwId); // nothing of this run is alive any more
+        // Attach a handler to `processesDone` IMMEDIATELY — not after the
+        // sessions-row write below — so it can never become an unhandled
+        // rejection (fatal on Node 22). If the sessions-row write throws first,
+        // execution never reaches the `await processesDone` further down; without
+        // this line, `processesDone`'s own eventual rejection would then have no
+        // attached handler at all. `processesResult` resolves to the error
+        // (never rethrows here) so both writes stay independently handled; it is
+        // re-thrown below only once the sessions-row write has itself succeeded.
+        const processesResult = processesDone.then(() => null, (err) => err);
+        await this.db
             .query("UPDATE sessions SET status=?, ended_at=? WHERE adw_id=?")
             .run(ok ? "success" : "fail", nowIso(), adwId);
-        this.processesEndAll(adwId); // nothing of this run is alive any more
-        this.fanOut((otel) => otel.recordSessionFinish(ok)); // otel projection: emits the root run span, once
+        const processesError = await processesResult;
+        if (processesError)
+            throw processesError;
     }
-    sessionAddUsage(adwId, tokens, cost) {
-        this.db
+    async sessionAddUsage(adwId, tokens, cost) {
+        await this.db
             .query("UPDATE sessions SET total_tokens=total_tokens+?, total_cost=total_cost+? WHERE adw_id=?")
             .run(tokens, cost, adwId);
     }
@@ -227,22 +299,22 @@ export class Tracer {
      * belongs to. Writing it here makes the trace the answer to "what is this
      * run running, and how do I stop it".
      */
-    processStart(adwId, kind, name, pid, command) {
-        this.db
+    async processStart(adwId, kind, name, pid, command) {
+        await this.db
             .query(`INSERT INTO processes (adw_id, kind, name, pid, command, started_at) VALUES (?,?,?,?,?,?)`)
             .run(adwId, kind, name, pid, command.slice(0, 500), nowIso());
     }
     /** Mark the newest live row for this pid as finished. */
-    processEnd(adwId, pid) {
-        this.db
+    async processEnd(adwId, pid) {
+        await this.db
             .query(`UPDATE processes SET ended_at=? WHERE id = (
            SELECT id FROM processes WHERE adw_id=? AND pid=? AND ended_at IS NULL
            ORDER BY id DESC LIMIT 1)`)
             .run(nowIso(), adwId, pid);
     }
     /** Close out every live row for a run — called when the session ends. */
-    processesEndAll(adwId) {
-        this.db.query("UPDATE processes SET ended_at=? WHERE adw_id=? AND ended_at IS NULL").run(nowIso(), adwId);
+    async processesEndAll(adwId) {
+        await this.db.query("UPDATE processes SET ended_at=? WHERE adw_id=? AND ended_at IS NULL").run(nowIso(), adwId);
     }
     // ── phases ──────────────────────────────────────────────────────────────
     /**
@@ -253,13 +325,13 @@ export class Tracer {
      * ordering) and `phase_id` (silently overwriting a row through the
      * phase_upsert conflict clause).
      */
-    maxPhaseSeq(adwId) {
-        const row = this.db.query("SELECT MAX(seq) as m FROM phases WHERE adw_id = ?").get(adwId);
+    async maxPhaseSeq(adwId) {
+        const row = (await this.db.query("SELECT MAX(seq) as m FROM phases WHERE adw_id = ?").get(adwId));
         return row?.m ?? 0;
     }
-    phaseUpsert(phase) {
+    async phaseUpsert(phase) {
         const p = phase.params;
-        this.db
+        await this.db
             .query(`INSERT INTO phases (phase_id, adw_id, seq, name, kind, owner, description,
          status, attempt, retries, error, started_at, ended_at)
          VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?)
@@ -271,15 +343,15 @@ export class Tracer {
         this.fanOut((otel) => otel.recordPhase(phase));
     }
     // ── envelopes / gates / agent sessions ──────────────────────────────────
-    envelopeRow(phase, agent, outputType, payloadJson, valid, attempt) {
-        this.db
+    async envelopeRow(phase, agent, outputType, payloadJson, valid, attempt) {
+        await this.db
             .query(`INSERT INTO envelopes (envelope_id, adw_id, phase_id, agent, output_type,
          payload_json, valid, attempt, created_at) VALUES (?,?,?,?,?,?,?,?,?)`)
             .run(`env_${newId(12)}`, phase.adw_id, phase.phase_id, agent, outputType, payloadJson, valid ? 1 : 0, attempt, nowIso());
     }
     /** The report carries both the verdict and the evidence behind it. */
-    gateRow(phase, gate, report, attempt) {
-        this.db
+    async gateRow(phase, gate, report, attempt) {
+        await this.db
             .query(`INSERT INTO gate_results (adw_id, phase_id, attempt, gate, passed,
          violations_json, checks_json, created_at) VALUES (?,?,?,?,?,?,?,?)`)
             .run(phase.adw_id, phase.phase_id, attempt, gate, report.passed ? 1 : 0, JSON.stringify(report.violations), JSON.stringify(report.checks), nowIso());
@@ -295,9 +367,9 @@ export class Tracer {
      * wants one number per agent — the latest — and a session that runs the
      * same agent twice overwrites it, exactly like model and session_id.
      */
-    agentSessionRow(adwId, agent, sessionId, contextTokens = 0, contextWindow = 0) {
+    async agentSessionRow(adwId, agent, sessionId, contextTokens = 0, contextWindow = 0) {
         const ts = nowIso();
-        this.db
+        await this.db
             .query(`INSERT INTO agent_sessions (adw_id, agent, coding_agent, model, color,
          session_id, context_tokens, context_window, created_at, last_used_at)
          VALUES (?,?,?,?,?,?,?,?,?,?)

package/dist/core/watch.d.ts

@@ -87,7 +87,7 @@ export interface WatchFanoutDeps {
     /** One attempt's chain, in that attempt's own worktree — the same ctx `runChain` builds, per attempt. */
     runAttempt: (dispatch: AttemptDispatch) => Promise<number>;
     /** Gate/usage rows for one attempt's adw_id, from the SHARED db. Must not throw. */
-    readMetrics: (adwId: string) => AttemptMetrics;
+    readMetrics: (adwId: string) => Promise<AttemptMetrics>;
     /**
      * True when NOT ONE of these adw_ids has a session row yet — the same db,
      * the same predicate and the same reasoning as `spf fanout`'s reuse
@@ -103,16 +103,16 @@ export interface WatchFanoutDeps {
      * rather than reporting "free" and letting a previous run's rows decide
      * this run's winner.
      */
-    adwIdsFree: (adwIds: string[]) => boolean;
+    adwIdsFree: (adwIds: string[]) => Promise<boolean>;
     /** The winner's review posture, read back post-hoc — the same two fields `runChain` returns, keyed on a WINNER instead of the sole attempt. */
     reviewFor: (opts: {
         cwd: string;
         adwId: string;
         chainOptions: Record<string, string>;
-    }) => {
+    }) => Promise<{
         reviewRequired: boolean;
         reviewSummary?: string;
-    };
+    }>;
 }
 export interface WatchDeps {
     provider: IssueProvider;

package/dist/core/watch.js

@@ -878,7 +878,7 @@ async function runIssueFanout(deps, issue, fanout) {
         let salt = 0;
         for (; salt <= MAX_FANOUT_SALT; salt++) {
             const ids = Array.from({ length: n }, (_, i) => attemptAdwId(baseFor(issue, salt), i + 1));
-            if (fanout.adwIdsFree(ids))
+            if (await fanout.adwIdsFree(ids))
                 break;
         }
         const baseAdwId = salt <= MAX_FANOUT_SALT ? baseFor(issue, salt) : `issue-${issue.id}-x${newId(4)}`;
@@ -994,7 +994,7 @@ async function runIssueFanout(deps, issue, fanout) {
         deps.git.deleteLocalBranch(winner.branch);
         won = { worktree: winner.worktree, branch };
         await deps.provider.writeMarker(issue, { worktree: won.worktree, branch: won.branch, attempt: 0 });
-        const review = fanout.reviewFor({ cwd: winner.worktree, adwId: winner.adw_id, chainOptions: deps.chainOptions });
+        const review = await fanout.reviewFor({ cwd: winner.worktree, adwId: winner.adw_id, chainOptions: deps.chainOptions });
         // `won` stays set from here on — openPrForWinner catches nothing, so
         // this function's own catch (below) is the only cleanup for a throw
         // from push/openPr/writeMarker/transition/notify inside it, exactly as

package/dist/ui/server/app.js

@@ -39,11 +39,11 @@ export function createApp(db, webDir) {
         await next();
         c.header("cache-control", "no-store");
     });
-    app.get("/api/health", (c) => c.json({ ok: true, db: db.path, journal_mode: db.journalMode, sessions: db.sessionCount() }));
-    app.get("/api/sessions", (c) => c.json(db.sessions(intQueryParam(c.req.query("limit"), 200))));
-    app.get("/api/sessions/:adw_id", (c) => {
+    app.get("/api/health", async (c) => c.json({ ok: true, db: db.label, journal_mode: db.journalMode, sessions: await db.sessionCount() }));
+    app.get("/api/sessions", async (c) => c.json(await db.sessions(intQueryParam(c.req.query("limit"), 200))));
+    app.get("/api/sessions/:adw_id", async (c) => {
         const adwId = c.req.param("adw_id");
-        const detail = db.sessionDetail(adwId);
+        const detail = await db.sessionDetail(adwId);
         if (!detail)
             return c.json({ error: `no session ${adwId}` }, 404);
         return c.json(detail);
@@ -56,22 +56,22 @@ export function createApp(db, webDir) {
             return c.json({ error: "invalid adw_id" }, 400);
         const body = (await c.req.json().catch(() => ({})));
         const archived = body.archived === undefined ? true : Boolean(body.archived);
-        if (!db.setArchived(adwId, archived))
+        if (!(await db.setArchived(adwId, archived)))
             return c.json({ error: `no session ${adwId}` }, 404);
         return c.json({ adw_id: adwId, archived });
     });
-    app.get("/api/sessions/:adw_id/events", (c) => c.json(db.events(c.req.param("adw_id"), intQueryParam(c.req.query("after"), 0), intQueryParam(c.req.query("limit"), 500))));
-    app.get("/api/sessions/:adw_id/envelopes", (c) => c.json(db.envelopes(c.req.param("adw_id"))));
-    app.get("/api/sessions/:adw_id/gates", (c) => c.json(db.gates(c.req.param("adw_id"))));
+    app.get("/api/sessions/:adw_id/events", async (c) => c.json(await db.events(c.req.param("adw_id"), intQueryParam(c.req.query("after"), 0), intQueryParam(c.req.query("limit"), 500))));
+    app.get("/api/sessions/:adw_id/envelopes", async (c) => c.json(await db.envelopes(c.req.param("adw_id"))));
+    app.get("/api/sessions/:adw_id/gates", async (c) => c.json(await db.gates(c.req.param("adw_id"))));
     // The exact prompts an agent was sent, read from the session dir. Files are
     // the raw record; the db has no copy of them.
-    app.get("/api/sessions/:adw_id/agents/:agent/prompts", (c) => {
+    app.get("/api/sessions/:adw_id/agents/:agent/prompts", async (c) => {
         const adwId = c.req.param("adw_id");
         const agent = c.req.param("agent");
         if (!isSafeSegment(adwId) || !isSafeSegment(agent)) {
             return c.json({ error: "invalid adw_id or agent" }, 400);
         }
-        if (!db.session(adwId))
+        if (!(await db.session(adwId)))
             return c.json({ error: `no session ${adwId}` }, 404);
         const dir = resolve(db.sessionsDir, adwId, agent, "prompts");
         // Defense in depth: the segment check already forbids traversal.

package/dist/ui/server/db.d.ts

@@ -1,21 +1,75 @@
+import type { NormalizedObservabilityDb } from "../../core/data_types.ts";
+import type { DataPaths } from "../../core/paths.ts";
 import type { AgentSession, Envelope, EventsPage, GateResult, Phase, Session, SessionDetail, SessionSummary, SessionUsage } from "../shared/types.ts";
 export declare class SfDb {
-    readonly path: string;
+    /** Absolute local sqlite path — `null` for a `kind:"d1"` config. */
+    readonly path: string | null;
+    /** Human label for API/console display: the sqlite path, or `d1:<database_id>`. */
+    readonly label: string;
     /**
      * Where the ADW session dirs live: `{data_dir}/sessions/{adw_id}/{agent}/`.
-     * The db sits in the same data_dir (config's `observability.db` defaults to
-     * `adws/adw_data/spf.db`), so deriving it as a sibling of the db file keeps
-     * working when the whole data_dir is relocated.
+     * Passed in explicitly (from `paths.resolveDataPaths(...).sessions_dir`)
+     * rather than derived from the db path — session JSONL/envelope artifact
+     * files always live on the local filesystem regardless of where the
+     * queryable trace mirror (`db` below) lives; see `paths.ts`'s `DataPaths`.
      */
     readonly sessionsDir: string;
+    /** `"n/a (d1)"` for a remote backend — journal mode is a local-file concept. */
     readonly journalMode: string;
     private readonly db;
-    /** Opened on first archive and kept; null until then. */
+    private readonly dbConfig;
+    /** D1-only; carried from `open()`'s `options.fetchImpl` so a lazily-opened writer (`setArchived`) uses the same injected fetch a test gave the reader. */
+    private readonly fetchImpl;
+    /** Opened on first archive and kept; `null` until then. */
     private writer;
     /** Cache for optionalColumn(), keyed "table.column". Only ever false → true. */
     private readonly columnCache;
-    /** `path` is always absolute — resolved upstream by the ui command via paths.resolveAnchor/resolveDataPaths. */
-    constructor(path: string);
+    private constructor();
+    /**
+     * Open a trace db for reading. `dbConfig` accepts either a bare local
+     * sqlite path (sugar for `{kind:"sqlite",path}` — `--db <path>`/`SF_DB`
+     * CLI overrides, and every test's shorthand) or a normalized
+     * `observability.db` descriptor (`paths.resolveDataPaths(...).db`).
+     *
+     * `sessionsDir` should be `paths.resolveDataPaths(...).sessions_dir`
+     * whenever the caller has a `DataPaths` in hand; omitted, it falls back to
+     * the historical "sibling of the sqlite file" derivation — only valid for
+     * the LOCAL backend (a bare-path caller has no other sessions dir to
+     * offer), so it is required when `dbConfig` names a `kind:"d1"` config.
+     *
+     * `options.fetchImpl` is D1-only and exists purely so tests can drive this
+     * end-to-end against a mocked D1 HTTP response shape — every real caller
+     * omits it and gets the global `fetch`, same as `createTraceDb` itself.
+     */
+    static open(dbConfig: NormalizedObservabilityDb | string, sessionsDir?: string, options?: {
+        fetchImpl?: typeof fetch;
+    }): Promise<SfDb>;
+    /**
+     * Cheap "is there anything to read yet" check — the async equivalent of
+     * the `existsSync(dataPaths.db_path)` fast path every sqlite-only caller
+     * used before D1 existed, extended to cover the d1 case those callers
+     * never accounted for.
+     *
+     * `open()` deliberately THROWS a friendly, actionable error on a
+     * never-written db (see above) — the right behavior for `spf ui`, where
+     * "nothing here yet" is a misconfiguration to surface loudly. Callers that
+     * instead want to treat a never-written db as "empty, skip this check" —
+     * `spf fanout`'s collision preflight and lazy metrics reader, `spf loop`'s
+     * per-iteration readback, `spf estimate`'s cold-start path, `spf watch`'s
+     * salt-collision short-circuit — use this instead, so they behave
+     * identically whether the backend is local sqlite or a fresh D1 database
+     * that has never been written to.
+     *
+     * For a `kind:"sqlite"` db: `existsSync(dataPaths.db_path)`, unchanged.
+     * For a `kind:"d1"` db: the same `sqlite_master` probe `open()`'s
+     * friendly-error path already runs, but returning `false` instead of
+     * throwing when the `sessions` table isn't there yet. Any OTHER failure
+     * (network, auth, a malformed database_id) still throws — only "nothing
+     * written yet" collapses to `false`.
+     */
+    static exists(dataPaths: Pick<DataPaths, "db" | "db_path">, options?: {
+        fetchImpl?: typeof fetch;
+    }): Promise<boolean>;
     /**
      * A SELECT fragment for a column the tracer adds by migration.
      *
@@ -32,7 +86,21 @@ export declare class SfDb {
      */
     private hasColumn;
     private optionalColumn;
-    close(): void;
+    /**
+     * D1 caps bound parameters at 100 per statement; local sqlite allows tens
+     * of thousands. Any query that binds a whole id list into an `IN (...)`
+     * clause must go through this instead of a single unbounded bind, or it
+     * throws past ~100 ids on the D1 backend. Chunking is harmless on the
+     * local backend too (just slightly less efficient), so this is used
+     * unconditionally rather than special-cased per backend.
+     *
+     * Each id belongs to exactly one chunk, so per-id ordering from `fn`'s own
+     * ORDER BY is preserved — only the relative order of rows belonging to
+     * *different* chunks can interleave, which none of this class's callers
+     * depend on (they always regroup by id afterward).
+     */
+    private chunked;
+    close(): Promise<void>;
     /**
      * Archive or restore a session — the only write in this process.
      *
@@ -40,12 +108,12 @@ export declare class SfDb {
      * click should wait its turn rather than fail. Returns false when the id
      * does not exist, so the route can 404 instead of silently succeeding.
      */
-    setArchived(adwId: string, archived: boolean): boolean;
+    setArchived(adwId: string, archived: boolean): Promise<boolean>;
     /** Sessions, most recent first, each with its phase statuses for the progress dots. */
-    sessions(limit?: number): SessionSummary[];
-    session(adwId: string): Session | null;
-    phases(adwId: string): Phase[];
-    agentSessions(adwId: string): AgentSession[];
+    sessions(limit?: number): Promise<SessionSummary[]>;
+    session(adwId: string): Promise<Session | null>;
+    phases(adwId: string): Promise<Phase[]>;
+    agentSessions(adwId: string): Promise<AgentSession[]>;
     /**
      * Agents per session, for a set of ids at once: the agent_sessions rows plus
      * anything that has started but not finished.
@@ -57,7 +125,7 @@ export declare class SfDb {
      */
     private agentsFor;
     /** Session + phases + agents in one shot — L2 needs all three to draw lanes. */
-    sessionDetail(adwId: string): SessionDetail | null;
+    sessionDetail(adwId: string): Promise<SessionDetail | null>;
     /**
      * Raw tokens read and written, beside the billed headline.
      *
@@ -70,15 +138,15 @@ export declare class SfDb {
      * material generated. The gap between them and the headline is cached
      * re-reads, which is usually most of it.
      */
-    usage(adwId: string): SessionUsage;
+    usage(adwId: string): Promise<SessionUsage>;
     /**
      * The polling query. Rowid cursor, insertion order, bounded page — the same
      * mechanism serves the live tail and lazy-paged history.
      */
-    events(adwId: string, after?: number, limit?: number): EventsPage;
-    envelopes(adwId: string): Envelope[];
-    gates(adwId: string): GateResult[];
-    sessionCount(): number;
+    events(adwId: string, after?: number, limit?: number): Promise<EventsPage>;
+    envelopes(adwId: string): Promise<Envelope[]>;
+    gates(adwId: string): Promise<GateResult[]>;
+    sessionCount(): Promise<number>;
     /**
      * `spf estimate`'s one read: every session that ran EXACTLY `chainName`
      * (never a joined one — see below), each with its per-phase token totals,
@@ -100,10 +168,10 @@ export declare class SfDb {
      * first (`spf estimate`'s own sample-selection order), which is a decision
      * `estimate.ts` makes, not this method.
      */
-    chainPhaseHistory(chainName: string): {
+    chainPhaseHistory(chainName: string): Promise<{
         sessions: ChainHistorySession[];
         joinedExcluded: number;
-    };
+    }>;
 }
 /** One EXACT-match session's history, as `chainPhaseHistory` returns it — `spf estimate`'s raw material. */
 export interface ChainHistorySession {