@gr8ful/spf 0.15.0 → 0.16.0

package/README.md

@@ -36,7 +36,7 @@ spf init --template ts-cc      # or start from a packaged, ready-to-run template
 spf list                       # every chain this install knows, its phases, what it needs
 ```
 
-On a real terminal, `spf init` asks a short interview — which coding agent (`claude_code` or `flue`) and model (optionally customized per agent instead of one model for the whole roster), which quality checks to gate on, whether to turn on `spf watch` and against which tracker/code host, and whether to push notifications to Slack/Teams/a webhook — and writes `.spf/spf.config.yaml` with only what you answered differently from the packaged defaults, plus whatever secrets those answers imply appended to `.env` (already gitignored, and already auto-loaded by every command) and their key names mirrored into a committable `.env.example`. Re-running it later shows any existing `.env` value masked and keeps it on an empty answer, so rotating one secret doesn't mean re-answering everything. Piped input, `--yes`, or `--template <name>` all skip the interview and fall back to the original non-interactive behavior — a scripted `spf init` never blocks on stdin.
+On a real terminal, `spf init` asks a short interview — which coding agent (`claude_code`, `flue`, or `opencode`) and model (optionally customized per agent instead of one model for the whole roster), which quality checks to gate on, whether to turn on `spf watch` and against which tracker/code host, and whether to push notifications to Slack/Teams/a webhook — and writes `.spf/spf.config.yaml` with only what you answered differently from the packaged defaults, plus whatever secrets those answers imply appended to `.env` (already gitignored, and already auto-loaded by every command) and their key names mirrored into a committable `.env.example`. Re-running it later shows any existing `.env` value masked and keeps it on an empty answer, so rotating one secret doesn't mean re-answering everything. Piped input, `--yes`, or `--template <name>` all skip the interview and fall back to the original non-interactive behavior — a scripted `spf init` never blocks on stdin.
 
 Without an interview, `spf init` writes the same small starter `.spf/spf.config.yaml`, commented, that merges on top of the packaged built-ins field by field. `--template <name>` writes a real, filled-in config instead of the commented-out starter — every packaged template's name prints after `spf init` runs, and the same files live in [`assets/templates/`](assets/templates/) to browse directly. Nothing here needs to exist for `spf` to run; it's how you make one repo's roster diverge from the defaults.
 
@@ -175,6 +175,14 @@ env:
 
 Applied to `process.env` before any command runs. A plain value commits as literal text; `${VAR}` interpolates from whatever's already in `process.env` at that point (the real shell, or `.env`, both of which load first) — so a real secret can live in `.env` (gitignored) and be referenced here without ever being written into this file. An already-set `process.env` value always wins over `env:`'s — `spf.config.yaml` supplies the default, a real export still overrides it per machine/session. A `${VAR}` reference to something that's genuinely unset fails loudly at startup, naming the missing variable, rather than silently interpolating to an empty string.
 
+### A third backend: opencode
+
+Set `coding_agent: opencode` on any agent (or in `defaults`) to run it on your own installed [OpenCode](https://opencode.ai) CLI instead of Flue or Claude Code — install it with `npm install -g opencode-ai` (the package is `opencode-ai`; the binary it puts on `PATH` is `opencode`). `spf doctor` checks that `opencode` resolves on `PATH` and that `~/.local/share/opencode/auth.json` exists, the same informational, not-enforced posture as its `claude_code` check for `ANTHROPIC_API_KEY`. Model names follow the same `provider/model-id` shape Flue uses (e.g. `anthropic/claude-sonnet-4-20250514`, `ollama/qwen3-coder:30b`) — not Claude Code's own bare-alias vocabulary (`sonnet`, `opus`, ...); everything else — `tools`, `writes`, `thinking` — stays the same shape.
+
+Authentication is handled entirely outside spf: run `opencode auth login` once (interactive), or `opencode auth list` to check non-interactively what's already configured. spf never drives this itself.
+
+Like `claude_code`, routing the `opencode` command through a wrapper or launcher uses the equivalent `SPF_CLAUDE_CMD`-style env var for this backend, with the same `{model}` token-substitution mechanic — see [Declarative env vars](#declarative-env-vars) above and check `opencode --help` for the flags a wrapper needs to forward.
+
 ### flue + local Ollama
 
 Point the default `flue` backend at a local Ollama server the same way you'd pick any other Flue provider — the model string's own prefix, `ollama/<tag>` (whatever `ollama list` shows on your machine) instead of `openai/...`/`anthropic/...`:
@@ -901,14 +909,16 @@ Full field reference: `spf install-skill`'s installed skill
 
 ## Observability
 
-Every run produces a complete trace: all events, phases, agent calls, and tool invocations stream into SQLite as they happen. The local trace stays the source of truth — prompts, envelopes, tool arguments, and your source code never leave the machine. Token counts and costs ride alongside.
+Every run produces a complete trace: all events, phases, agent calls, and tool invocations stream into SQLite as they happen. By default the trace is local-only and stays the source of truth — prompts, envelopes, tool arguments, and your source code never leave the machine. Token counts and costs ride alongside.
 
 ```bash
 spf ui                           # browser-based visualizer over the trace
 spf events <adw_id> --follow    # live event stream, tailable
 ```
 
-The default export is SQLite only (`.spf/data/spf.db`). Optionally, you can export **spans only** (phase/agent/tool timing and allowlisted metadata) to an OpenTelemetry collector for integration with a trace UI or observability platform:
+The default backend is local SQLite (`.spf/data/spf.db`) — nothing leaves the machine. `observability.db` can instead be pointed at a remote Cloudflare D1 database (`{kind: d1, database_id, ...}`, offered as an `spf init` advanced option): in that mode the **complete trace** — the raw request text, tool arguments and results, envelope payloads, and gate violation details, not just spans or metadata — is written to Cloudflare over the network on every run, and the local-only guarantee above does not hold. Pick D1 only when you're comfortable with your trace data (including prompts and tool arguments) leaving the machine; stay on the default SQLite backend otherwise. See `assets/skill/references/observability.md`'s D1 section for what's sent and how the backend is selected.
+
+Separately, and orthogonally to which trace-db backend you choose, you can export **spans only** (phase/agent/tool timing and allowlisted metadata, never prompts or tool arguments) to an OpenTelemetry collector for integration with a trace UI or observability platform:
 
 ```yaml
 observability:
@@ -921,9 +931,9 @@ observability:
       Authorization: Bearer ...
 ```
 
-OTEL export is **explicit config only** — an unrelated shell variable cannot become a data-egress switch. OTEL is strictly a spans-only export: each phase is a span with child spans for agent calls and tool calls, annotated with phase status, agent model, token/cost counts, and gate results. This export never blocks a run: if the collector is slow or unreachable, SPF continues normally and logs a single line per run when export fails (not one per batch), and reports the number of dropped spans on the final flush as `spf.otel.dropped_spans` for the backend to surface. The complete trace stays in SQLite regardless.
+OTEL export is **explicit config only** — an unrelated shell variable cannot become a data-egress switch. OTEL is strictly a spans-only export: each phase is a span with child spans for agent calls and tool calls, annotated with phase status, agent model, token/cost counts, and gate results. This export never blocks a run: if the collector is slow or unreachable, SPF continues normally and logs a single line per run when export fails (not one per batch), and reports the number of dropped spans on the final flush as `spf.otel.dropped_spans` for the backend to surface. The complete trace stays in the trace db regardless of OTEL export — but, per above, the trace db itself is remote Cloudflare D1, not local SQLite, when `observability.db` is configured for `kind: d1`.
 
-**Attribute allowlist**: only phase name/kind/owner/status, chain name, adw_id, agent name/model/coding_agent, gate name + passed + violation count, token counts and cost, and durations. Prompts, envelopes, tool arguments, and your source code never leave — that guarantee is enforced in code, not just in documentation.
+**OTEL attribute allowlist**: only phase name/kind/owner/status, chain name, adw_id, agent name/model/coding_agent, gate name + passed + violation count, token counts and cost, and durations. Prompts, envelopes, tool arguments, and your source code never leave *via OTEL* — that guarantee is enforced in code, not just in documentation, and it holds regardless of trace-db backend. It is separate from the trace-db egress question above: a `kind: d1` trace db ships the full trace (prompts, tool arguments, envelope payloads) to Cloudflare even with OTEL left unconfigured.
 
 See `assets/skill/references/config.md`'s `observability` section for the full field reference.
 

package/assets/skill/references/config.md

@@ -70,8 +70,8 @@ agents:
 
 | Field | Type | Meaning |
 |---|---|---|
-| `coding_agent` | `"flue"` \| `"claude_code"` | Which backend runs the agent. Default `flue`. `claude_code` shells out to your own installed `claude` CLI — `spf doctor` checks it's on `PATH`. |
-| `model` | string | Vocabulary depends on `coding_agent`: Flue wants `provider/model-id`; Claude Code wants its own bare alias/full name (`sonnet`, `claude-sonnet-5`, ...). Default `google/gemini-3.6-flash`. |
+| `coding_agent` | `"flue"` \| `"claude_code"` \| `"opencode"` | Which backend runs the agent. Default `flue`. `claude_code` shells out to your own installed `claude` CLI — `spf doctor` checks it's on `PATH`. `opencode` shells out to your own installed `opencode` CLI (`npm install -g opencode-ai`) — `spf doctor` checks it's on `PATH` and that `~/.local/share/opencode/auth.json` exists. |
+| `model` | string | Vocabulary depends on `coding_agent`: Flue and opencode want `provider/model-id`; Claude Code wants its own bare alias/full name (`sonnet`, `claude-sonnet-5`, ...). Default `google/gemini-3.6-flash`. |
 | `thinking` | enum | `off\|minimal\|low\|medium\|high\|xhigh\|max`. Default `medium`. On a `claude_code` agent this maps to `--effort` (`off`/`minimal` both floor to Claude Code's own minimum — it has no true "disabled" level for a headless run). |
 | `color` | hex string | Lane color fallback for agents that don't set their own. |
 | `harness_engineering` | string[] | **Must stay `[]`** — no analogue on any current backend; a non-empty entry fails validate(). |
@@ -108,7 +108,7 @@ the two runs' cost/tokens/gates together.
 
 | Field | Type | Meaning |
 |---|---|---|
-| `db` | path | The trace sqlite db. Default `.spf/data/spf.db`. |
+| `db` | path \| `{kind: sqlite, path?}` \| `{kind: d1, database_id, account_id_env?, api_token_env?}` | Where the trace db lives. A bare string (or the equivalent spelled-out `{kind: sqlite, ...}`) is a repo-relative local sqlite path, default `.spf/data/spf.db`. `{kind: d1, ...}` points at a remote Cloudflare D1 database instead — `database_id` is required; `account_id_env`/`api_token_env` default to `CLOUDFLARE_ACCOUNT_ID`/`CLOUDFLARE_API_TOKEN` (the same env vars the `cloudflare` model provider reads), naming the env vars to read the credentials from, never the credentials themselves. **Egress**: `kind: d1` sends the complete trace — raw request text, tool arguments/results, envelope payloads, gate violation details — to Cloudflare's D1 HTTP API on every run; `kind: sqlite` (the default) never leaves the machine. See `observability.md`'s "Two stores, one truth" and "D1 ships the complete trace off-box" sections for what changes (and what deliberately doesn't) with a D1-backed trace db — notably, the local backend's WAL live-read guarantee does not hold for D1. |
 | `poll_ms` | int | UI live-poll cadence. Default `500`. |
 | `otel.endpoint` | string | OTLP/HTTP collector endpoint (e.g., `https://your-host/v1/traces`). Omit to disable OTel export. |
 | `otel.headers` | object | Optional HTTP headers (e.g., auth tokens). Each value is a string. |
@@ -116,6 +116,10 @@ the two runs' cost/tokens/gates together.
 
 **No ambient env activation**: OTEL export requires explicit `observability.otel` config — the `OTEL_EXPORTER_OTLP_ENDPOINT` shell variable is never consulted. An unrelated shell env variable must not become a data-egress switch.
 
+**`spf init`'s interview** asks local-vs-D1 only inside the "advanced" gate (declining advanced settings, or `--yes`, leaves `observability.db` unset — local sqlite at its default path, today's behavior, unchanged). Choosing D1 asks for `database_id` (required) and, unless this same interview run already collected `CLOUDFLARE_ACCOUNT_ID`/`CLOUDFLARE_API_TOKEN` for the Cloudflare Workers AI provider, asks for those too — reusing them instead of asking twice when it did. The generated config omits `account_id_env`/`api_token_env` (they match the schema's own defaults above), so a D1 choice writes just `db: {kind: d1, database_id: ...}`.
+
+**`spf doctor`** probes a `kind: d1` `observability.db` in two steps, right after its `db_path` check: first a static, hard check that the resolved `account_id_env`/`api_token_env` are actually set (naming whichever is missing) — informational, same never-a-hard-failure contract as every other credential-presence check in this file. Then, only when both are set and `--no-probe` isn't passed, a cheap read-only reachability check (`SfDb.exists()` — no `Tracer`, no write) reports `info` whenever the request succeeds, whether the database already has a `sessions` table or (expected before the first run against a fresh database) not — a reachable database is healthy either way, exactly like the local `db_path` check's plain `✓` for a not-yet-created sqlite file. Only when the request itself fails (bad credentials, wrong `database_id`, network error) does it report `warn` (never a hard failure), naming the actual error.
+
 ### `quality`
 
 `checks[]`: `{name, area: "frontend"|"backend", operation: "lint"|"typecheck"|"build", argv: string[], timeout_seconds}`.
@@ -364,8 +368,8 @@ unordered splice of both).
 | `enabled` | bool | Default `false`. `true` turns on the ladder walk described below; `false` (or the key absent) is a total no-op, checked nowhere and dispatched nowhere. |
 | `tiers` | array, WEAKEST FIRST | The ladder. A risk level shifts every routed role UP or DOWN this list by the same step — order is the whole semantics, which is why this is a sequence and not a mapping. Default `[]`. |
 | `tiers[].name` | string | What `roles` values point at. |
-| `tiers[].coding_agent` | `"flue"` \| `"claude_code"` | Which backend's vocabulary this rung's `model` speaks. Default `flue`, same default an agent's own `coding_agent` uses. A tier changes an agent's `model` and **nothing else** — `coding_agent` always stays the agent's own — so a rung can only route roles whose backend matches (**rule T**, below). |
-| `tiers[].model` | string | Same vocabulary as an agent's own `model:` for that backend: `provider/model-id` for `flue`, Claude Code's bare alias/full name for `claude_code`. No per-provider table — for `flue` the provider is already the string's first segment. |
+| `tiers[].coding_agent` | `"flue"` \| `"claude_code"` \| `"opencode"` | Which backend's vocabulary this rung's `model` speaks. Default `flue`, same default an agent's own `coding_agent` uses. A tier changes an agent's `model` and **nothing else** — `coding_agent` always stays the agent's own — so a rung can only route roles whose backend matches (**rule T**, below). |
+| `tiers[].model` | string | Same vocabulary as an agent's own `model:` for that backend: `provider/model-id` for `flue` and `opencode`, Claude Code's bare alias/full name for `claude_code`. No per-provider table — for `flue`/`opencode` the provider is already the string's first segment. |
 | `roles` | map of agent name -> tier name | The baseline tier per **role**. Naming an agent here is the operator's statement "route this one by tier" — the resolved tier then wins over that agent's own `model:`. An agent **not** named here is never retiered; its `model:` stands, untouched. That is the whole precedence rule. Default `{}`. |
 
 ```yaml

package/assets/skill/references/observability.md

@@ -6,12 +6,47 @@ always: **agents → sqlite → CLI / web UI.**
 ## Two stores, one truth
 
 **Files are the raw record** (`envelope.json`, `agent_map.json`, Flue's own
-`.spf/data/flue.db` conversation store); **SQLite (`.spf/data/spf.db`, via
-`node:sqlite`) is the queryable mirror** the CLI and UI read. `tracer.ts`
-writes both. Losing the db loses nothing that can't be rebuilt from files.
-
-Location comes from `observability.db` in `spf.config.yaml`, default
-`.spf/data/spf.db` — inside the target repo, always gitignored.
+`.spf/data/flue.db` conversation store); **the trace db is the queryable
+mirror** the CLI and UI read. `tracer.ts` writes both. Losing the trace db
+loses nothing that can't be rebuilt from files.
+
+`observability.db` in `spf.config.yaml` names WHICH trace db backend and
+where — a bare string (a local sqlite path, default `.spf/data/spf.db`,
+inside the target repo, always gitignored), `{kind: sqlite, path?}` spelled
+out the same way, or `{kind: d1, database_id, account_id_env?,
+api_token_env?}` for a remote Cloudflare D1 database instead of a local
+file. `core/trace_db.ts`'s `TraceDb` interface is the one seam both `Tracer`
+(writes) and `SfDb` (reads) go through — `createTraceDb()` picks
+`LocalTraceDb` or `D1TraceDb` from the resolved kind. See `config.md`'s
+`observability.db` rows for the full field reference.
+
+**The WAL live-read guarantee is LOCAL-ONLY.** The rest of this doc's "WAL
+pragmas" section describes a guarantee specific to the local sqlite
+backend — `spf ui` reading while a chain writes, through one shared file.
+A D1-backed repo has no such file to share: `spf ui` and a running chain
+each speak to D1 over independent HTTP calls, and D1's own consistency
+model (sequential consistency, with a Sessions-API "bookmark" for
+read-your-own-writes that this adapter does not use — see
+`D1TraceDb`'s own doc comment in `core/trace_db.ts`) does not promise the
+same instant. This is a deliberate, documented trade-off (SPF #66), not a
+gap: no phase/gate/run OUTCOME depends on it — only how quickly `spf ui`
+can catch up to a chain still writing.
+
+**D1 ships the complete trace off-box.** The "Two stores, one truth"
+guarantee above ("local sqlite, always gitignored") is specific to
+`kind: sqlite`. Point `observability.db` at `kind: d1` and every write
+`tracer.ts` makes — `sessions.request` (the operator's raw request text),
+`events.payload_json` (including each `tool_call` event's `args` and
+`result_snippet`), `envelopes.payload_json`, and
+`gate_results.violations_json` — is POSTed over HTTPS to
+`https://api.cloudflare.com/client/v4/accounts/{account_id}/d1/database/{database_id}/query`
+(`trace_db.ts`'s `D1TraceDb`). This is the full trace, not the OTEL
+spans-only attribute allowlist described elsewhere in this doc: prompts,
+tool arguments, and tool results leave the machine on every run once
+`kind: d1` is configured. There is no partial mode — a repo is either
+fully local (`kind: sqlite`, the default) or fully remote for trace data
+(`kind: d1`). Choose D1 only when shipping that data to Cloudflare is
+acceptable for the repo in question.
 
 ## Event schema
 
@@ -86,6 +121,16 @@ up through `agents.execute`, `run.phase`, and every chain's `main()` is
 
 ## Tables
 
+No `REFERENCES` / foreign keys on `adw_id` or `phase_id` anywhere below — a
+deliberate change for the D1 backend (SPF #66), not an oversight: Cloudflare
+D1 enforces FKs unconditionally with no way to disable them, and a session's
+very first write (e.g. its first `events` row) can otherwise land before its
+own `sessions` row has committed, throwing `FOREIGN KEY constraint failed` on
+a perfectly ordinary run. The relationships still hold logically (every
+`adw_id` should resolve to a `sessions` row eventually) — they are just no
+longer enforced by the schema on either backend, so local sqlite and D1
+behave identically.
+
 ```sql
 sessions (
   adw_id TEXT PRIMARY KEY, adw_name TEXT, request TEXT, status TEXT, engineer TEXT,
@@ -93,37 +138,37 @@ sessions (
   archived INTEGER DEFAULT 0            -- review triage, set by the UI; never by a run
 );
 phases (
-  phase_id TEXT PRIMARY KEY, adw_id TEXT REFERENCES sessions, seq INTEGER,
+  phase_id TEXT PRIMARY KEY, adw_id TEXT, seq INTEGER,
   name TEXT, kind TEXT, owner TEXT, description TEXT,
   status TEXT DEFAULT 'fail',           -- success must be earned
   attempt INTEGER DEFAULT 0, retries INTEGER DEFAULT 0, error TEXT,
   started_at TEXT, ended_at TEXT
 );
 events (
-  event_id TEXT PRIMARY KEY, adw_id TEXT REFERENCES sessions, phase_id TEXT REFERENCES phases,
+  event_id TEXT PRIMARY KEY, adw_id TEXT, phase_id TEXT,
   parent_id TEXT, type TEXT, name TEXT, payload_json TEXT, tokens INTEGER,
   started_at TEXT, ended_at TEXT        -- ended_at set only on events that span time
 );
 envelopes (
-  envelope_id TEXT PRIMARY KEY, adw_id TEXT REFERENCES sessions, phase_id TEXT REFERENCES phases,
+  envelope_id TEXT PRIMARY KEY, adw_id TEXT, phase_id TEXT,
   agent TEXT, output_type TEXT, payload_json TEXT, valid INTEGER, attempt INTEGER, created_at TEXT
 );
 gate_results (
-  id INTEGER PRIMARY KEY AUTOINCREMENT, adw_id TEXT REFERENCES sessions, phase_id TEXT REFERENCES phases,
+  id INTEGER PRIMARY KEY AUTOINCREMENT, adw_id TEXT, phase_id TEXT,
   attempt INTEGER, gate TEXT, passed INTEGER,
   violations_json TEXT,                 -- derived: the failed checks, as "item: note"
   checks_json TEXT,                     -- [{item, ok, note}] — everything the gate looked at
   created_at TEXT
 );
 processes (                             -- adw_id -> pid, so a stuck run can be stopped
-  id INTEGER PRIMARY KEY AUTOINCREMENT, adw_id TEXT REFERENCES sessions,
+  id INTEGER PRIMARY KEY AUTOINCREMENT, adw_id TEXT,
   kind TEXT,                            -- 'adw' (the chain process) | 'agent' (a real child pid for claude_code; same as the chain's own pid for Flue, which is in-process)
   name TEXT, pid INTEGER,
   command TEXT,                         -- what the pid WAS; pids get recycled, verify before killing
   started_at TEXT, ended_at TEXT        -- ended_at NULL = believed alive
 );
 agent_sessions (                        -- the queryable mirror of agent_map.json
-  adw_id TEXT REFERENCES sessions, agent TEXT,
+  adw_id TEXT, agent TEXT,
   coding_agent TEXT, model TEXT, color TEXT, session_id TEXT,
   context_tokens INTEGER,               -- window occupancy after the agent's last turn
   context_window INTEGER,               -- backend-dependent; 0 = unknown — see "Context is occupancy" above

package/assets/templates/ts-opencode.spf.config.yaml

@@ -0,0 +1,54 @@
+# .spf/spf.config.yaml — OpenCode backend. `spf init --template ts-opencode`
+# writes this file as-is.
+#
+# `coding_agent: opencode` shells out to your own locally installed
+# `opencode` CLI — install it with:
+#   npm install -g opencode-ai
+# (the package is `opencode-ai`; the binary it puts on PATH is `opencode` —
+# a common point of confusion, so double-check `which opencode` if a run
+# can't find it.)
+#
+# model: is provider/model-id, the same free-form vocabulary shape Flue
+# uses — NOT Claude Code's own bare-alias vocabulary (sonnet/opus/...).
+# A few concrete examples:
+#   anthropic/claude-sonnet-4-20250514
+#   ollama/qwen3-coder:30b
+#   opencode/gpt-5.1-codex
+#
+# Authentication is handled entirely outside spf: run `opencode auth login`
+# (interactive) once, which writes credentials to
+# ~/.local/share/opencode/auth.json. `spf doctor` checks that `opencode` is
+# on PATH and that that auth.json file exists, but it does not drive login
+# itself and does not know whether the credentials inside are actually
+# valid — same informational, not-enforced posture as its claude_code check
+# for ANTHROPIC_API_KEY.
+quality:
+  checks:
+    - { name: typecheck, operation: typecheck, argv: ["npm", "run", "typecheck"], timeout_seconds: 60 }
+    - { name: lint, operation: lint, argv: ["npm", "run", "lint"], timeout_seconds: 60 }
+    - { name: build, operation: build, argv: ["npm", "run", "build"], timeout_seconds: 300 }
+    - { name: test, operation: build, argv: ["npm", "test"], timeout_seconds: 300 }
+  suites:
+    test: [test]
+    all: [typecheck, lint, build, test]
+
+defaults:
+  coding_agent: opencode
+  model: anthropic/claude-sonnet-4-20250514
+
+# REQUIRED, not just an example: the packaged default roster pins
+# planner/reviewer/documenter to their own explicit provider/model-id
+# strings, which an agent's own model always wins over defaults.model
+# above — switching coding_agent globally does NOT reset those three, so
+# they'd run on opencode with whatever model string the packaged roster
+# happened to pin them to, which may point at a provider/model your
+# `opencode auth login` was never set up for. builder/scout/refiner have no
+# model of their own in the packaged roster, so they correctly inherit
+# defaults.model above and need no override here.
+agents:
+  - name: planner
+    model: anthropic/claude-sonnet-4-20250514
+  - name: reviewer
+    model: anthropic/claude-sonnet-4-20250514
+  - name: documenter
+    model: anthropic/claude-sonnet-4-20250514

package/dist/chains/index.js

@@ -195,6 +195,6 @@ export async function runChain(chain, ctx, options = {}) {
         // exactly as it always did (the signal listener needs no such fallback:
         // the process is gone).
         await otel.releaseOtelExporter(ctx.adw_id);
-        session.finalize(ctx.adw_id);
+        await session.finalize(ctx.adw_id);
     }
 }

package/dist/chains/simple_sdlc.d.ts

@@ -71,8 +71,8 @@ export interface SignoffParams {
     asker: Asker | null;
     /** `undefined` when `git config user.name`/`user.email` is unset at this repo — see `git_helper.committerIdentity`. */
     identity: CommitterIdentity | undefined;
-    /** Routes into the phase's own trace record — `ph.log`, unchanged (no tracer changes on this thread). */
-    log: (payload: Record<string, unknown>) => void;
+    /** Routes into the phase's own trace record — `ph.log`, now async (`Tracer`'s write methods all are — see `core/tracer.ts`'s header). */
+    log: (payload: Record<string, unknown>) => Promise<void>;
     /** Console-only, never traced — the prompt itself and its framing, kept out of the event stream on purpose (the DECISION is what `log` records). */
     warn: (line: string) => void;
 }

package/dist/chains/simple_sdlc.js

@@ -95,7 +95,7 @@ export async function decideSignoff(params) {
                 "or run via `spf watch`, where a human merges the PR instead of this phase.");
         }
         warn(paint("bold yellow", `⚠ ${AI_ONLY_SIGNOFF_WARNING}`));
-        log({
+        await log({
             decision: "ai_only",
             warning: AI_ONLY_SIGNOFF_WARNING,
             human: false,
@@ -118,7 +118,7 @@ export async function decideSignoff(params) {
     }
     warn("");
     const accepted = await asker.confirm(identity ? `${identity.name}, approve and commit?` : "Approve and commit?", false, { timeoutMs: signoffTimeoutSeconds * 1000 });
-    log({
+    await log({
         decision: accepted ? "approved" : "declined",
         human: true,
         engineer: identity?.name ?? null,
@@ -128,7 +128,7 @@ export async function decideSignoff(params) {
     });
     if (accepted && !identity) {
         warn(paint("dim", "  no git committer identity (user.name/user.email) is set — sign-off recorded, no Signed-off-by trailer"));
-        log({ note: "signoff recorded without a git committer identity — trailer skipped" });
+        await log({ note: "signoff recorded without a git committer identity — trailer skipped" });
     }
     return { accepted, recordedYes: accepted };
 }
@@ -151,10 +151,10 @@ export async function main(ctx) {
     const run = await startRun(ctx, REQUIRED_AGENTS, REQUIRED_SUITES);
     const baseline = run.git.rev("HEAD"); // pinned before this run commits anything
     await run.phase(makePhaseParams({ name: "request", kind: "engineer", owner: run.engineer, description: "Capture the incoming ask" }), async (ph) => {
-        ph.log({ input: prompt, baseline: run.git.shortSha(baseline) });
+        await ph.log({ input: prompt, baseline: run.git.shortSha(baseline) });
     });
     const plan = await run.phase(makePhaseParams({ name: "plan", kind: "agent", owner: "planner", description: "Turn the request into an implementable plan" }), (ph) => ph.call(makeAgentCall({ output_type: PlanOutput, prompt, gates: [gates.artifactsExist, gates.filesNonEmpty] })));
-    await run.phase(makePhaseParams({ name: "commit_plan", kind: "code", owner: "git", description: "Put the spec on record before any code exists to blur it" }), async (ph) => commitEnvelope(run, ph, plan));
+    await run.phase(makePhaseParams({ name: "commit_plan", kind: "code", owner: "git", description: "Put the spec on record before any code exists to blur it" }), async (ph) => await commitEnvelope(run, ph, plan));
     let build = await run.phase(makePhaseParams({ name: "build", kind: "agent", owner: "builder", description: "Implement the plan exactly" }), (ph) => ph.call(makeAgentCall({ output_type: BuildOutput, prompt, previous: plan, gates: [gates.diffMatchesClaims] })));
     let test = null;
     for (let i = 1; i <= MAX_FIX_LOOPS; i++) {
@@ -164,8 +164,8 @@ export async function main(ctx) {
             owner: "quality",
             description: "Run the suite — a known command, so code runs it and no agent has to rediscover it",
         }), async (ph) => {
-            const result = quality.runTests(run);
-            quality.record(ph, result);
+            const result = await quality.runTests(run);
+            await quality.record(ph, result);
             return result;
         });
         if (test.passed)
@@ -198,8 +198,8 @@ export async function main(ctx) {
             owner: "quality",
             description: "Re-run the suite — the revision changed code after the last green result",
         }), async (ph) => {
-            const result = quality.runTests(run);
-            quality.record(ph, result);
+            const result = await quality.runTests(run);
+            await quality.record(ph, result);
             return result;
         });
     }
@@ -254,10 +254,10 @@ export async function main(ctx) {
         // trailerFor gates the trailer on recordedYes, not just `verified` — see
         // its own comment: a Signed-off-by line must trace back to an explicit
         // "yes", never to the AI-only path (where `verified` can also be true).
-        async (ph) => commitEnvelope(run, ph, build, trailerFor({ accepted: verified, recordedYes }, identity)));
+        async (ph) => await commitEnvelope(run, ph, build, trailerFor({ accepted: verified, recordedYes }, identity)));
         const changeset = await run.phase(makePhaseParams({ name: "changes", kind: "code", owner: "git", description: "Diff the whole run against its pinned baseline, for the documenter" }), async (ph) => {
             const result = changes.capture(run, makeChangeCapture({ base: baseline }));
-            logChangeset(ph, result);
+            await logChangeset(ph, result);
             if (result.empty) {
                 throw new Error(`nothing changed since ${result.base.label} (${result.base.reason}) — there is nothing to document.`);
             }
@@ -269,7 +269,7 @@ export async function main(ctx) {
             previous: changes.asEnvelope(changeset, DOCUMENT_NOTES),
             gates: [gates.artifactsExist, gates.filesNonEmpty],
         })));
-        await run.phase(makePhaseParams({ name: "commit_docs", kind: "code", owner: "git", description: "Ship the write-up in its own commit, beside the code it describes" }), async (ph) => commitEnvelope(run, ph, document));
+        await run.phase(makePhaseParams({ name: "commit_docs", kind: "code", owner: "git", description: "Ship the write-up in its own commit, beside the code it describes" }), async (ph) => await commitEnvelope(run, ph, document));
     }
-    return run.finish(verified, "the suite or the review never came back clean, or sign-off never came");
+    return await run.finish(verified, "the suite or the review never came back clean, or sign-off never came");
 }

package/dist/chains/steps.d.ts

@@ -107,9 +107,9 @@ export declare function startRun(ctx: ChainContext, requiredAgents: string[], re
  */
 export declare function commitEnvelope(run: Run, ph: PhaseHandle, envelope: EnvelopeBase & {
     commit_message?: string;
-}, signoff?: CommitterIdentity | null): void;
+}, signoff?: CommitterIdentity | null): Promise<void>;
 /** Log a change-capture result the same way every chain that captures one did. */
-export declare function logChangeset(ph: PhaseHandle, result: ChangeSet): void;
+export declare function logChangeset(ph: PhaseHandle, result: ChangeSet): Promise<void>;
 /**
  * The gates a chain definition is allowed to name, by name.
  *

package/dist/chains/steps.js

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

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

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

package/dist/cli/commands/abort.js

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