@gr8ful/spf 0.14.0 → 0.16.0

package/dist/core/tracer.d.ts

@@ -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,43 +36,58 @@
  * `processStart`/`processEnd` (pids) — have NO fan-out line on purpose. Do not
  * add one.
  */
-import { Database } from "./sqlite.ts";
-import type { AgentConfig, EventRecord, GateReport, Phase } from "./data_types.ts";
+import type { AgentConfig, EventRecord, GateReport, NormalizedObservabilityDb, Phase } from "./data_types.ts";
 import type { OtelExporter } from "./otel.ts";
+import { type TraceDb } from "./trace_db.ts";
 export declare class Tracer {
-    db: Database;
-    dbPath: string;
+    db: TraceDb;
+    /** 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: string | null;
     eventsJsonl: string;
     /** `null` unless `observability.otel` is configured — see the header. */
     otel: OtelExporter | null;
-    constructor(dbPath: string, eventsJsonl: string, otel?: OtelExporter | null);
+    private constructor();
+    /**
+     * 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 open(dbConfig: NormalizedObservabilityDb | string, eventsJsonl: string, otel?: OtelExporter | null, traceDbOptions?: {
+        fetchImpl?: typeof fetch;
+    }): Promise<Tracer>;
     /**
-     * Close the sqlite handle. A one-shot CLI process never needs this — it
+     * 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(): void;
+    close(): Promise<void>;
     /** Additive column migrations, so a db from an older SPF still opens. */
     private migrate;
     /**
-     * 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.
      */
     private fanOut;
-    event(record: EventRecord): string;
-    sessionStart(adwId: string, engineer: string, adwName?: string | null): void;
-    sessionRequest(adwId: string, request: string): void;
-    sessionFinish(adwId: string, ok: boolean): void;
-    sessionAddUsage(adwId: string, tokens: number, cost: number): void;
+    event(record: EventRecord): Promise<string>;
+    sessionStart(adwId: string, engineer: string, adwName?: string | null): Promise<void>;
+    sessionRequest(adwId: string, request: string): Promise<void>;
+    sessionFinish(adwId: string, ok: boolean): Promise<void>;
+    sessionAddUsage(adwId: string, tokens: number, cost: number): Promise<void>;
     /**
      * Record a live process for this run.
      *
@@ -66,11 +96,11 @@ export declare 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: string, kind: string, name: string, pid: number, command: string): void;
+    processStart(adwId: string, kind: string, name: string, pid: number, command: string): Promise<void>;
     /** Mark the newest live row for this pid as finished. */
-    processEnd(adwId: string, pid: number): void;
+    processEnd(adwId: string, pid: number): Promise<void>;
     /** Close out every live row for a run — called when the session ends. */
-    processesEndAll(adwId: string): void;
+    processesEndAll(adwId: string): Promise<void>;
     /**
      * Highest seq already recorded for this session; 0 when it is new.
      *
@@ -79,11 +109,11 @@ export declare class Tracer {
      * ordering) and `phase_id` (silently overwriting a row through the
      * phase_upsert conflict clause).
      */
-    maxPhaseSeq(adwId: string): number;
-    phaseUpsert(phase: Phase): void;
-    envelopeRow(phase: Phase, agent: string, outputType: string, payloadJson: string, valid: boolean, attempt: number): void;
+    maxPhaseSeq(adwId: string): Promise<number>;
+    phaseUpsert(phase: Phase): Promise<void>;
+    envelopeRow(phase: Phase, agent: string, outputType: string, payloadJson: string, valid: boolean, attempt: number): Promise<void>;
     /** The report carries both the verdict and the evidence behind it. */
-    gateRow(phase: Phase, gate: string, report: GateReport, attempt: number): void;
+    gateRow(phase: Phase, gate: string, report: GateReport, attempt: number): Promise<void>;
     /**
      * The agent's config row is the source of truth for its label and color.
      *
@@ -91,5 +121,5 @@ export declare 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: string, agent: AgentConfig, sessionId: string, contextTokens?: number, contextWindow?: number): void;
+    agentSessionRow(adwId: string, agent: AgentConfig, sessionId: string, contextTokens?: number, contextWindow?: number): Promise<void>;
 }

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.