@gr8ful/spf 0.14.0 → 0.16.0

package/dist/core/issues/jira_provider.d.ts

@@ -18,13 +18,22 @@
  *    one paragraph of plain text, nothing richer.
  *
  * State is modeled as Jira labels (`<prefix>:ready`, etc.), mirroring
- * `github_provider.ts` exactly, rather than native workflow status
- * transitions — the latter would need per-project transition-id mapping
- * (workflows vary by project/scheme in Jira), while labels work
- * identically everywhere with zero per-project setup. One caveat, verified
- * against Atlassian's own docs: colons ARE a legal label character and JQL
- * matches on them fine, they just don't show up in Jira's label
- * autocomplete UI — cosmetic only, not a functional issue.
+ * `github_provider.ts` exactly — labels are spf's ACTUAL state machine and
+ * always get written, unconditionally. One caveat, verified against
+ * Atlassian's own docs: colons ARE a legal label character and JQL matches
+ * on them fine, they just don't show up in Jira's label autocomplete UI —
+ * cosmetic only, not a functional issue.
+ *
+ * Native workflow status is a separate, OPTIONAL, best-effort layer on top
+ * (`syncStatus()`), driven entirely by the configured `statusMap` — empty
+ * by default, so an existing config's behavior is unchanged. It's optional
+ * rather than baked into every `transition()` call unconditionally because
+ * Jira workflows vary by project/scheme (status names, which transitions
+ * are reachable from where) in a way labels never do; a project that wants
+ * its board's Status column to move when spf changes a label opts in with
+ * `watch.jira.status_map`, and a misconfigured or unreachable entry there
+ * degrades to a logged warning, never a thrown error — a status-sync miss
+ * must never block the label update `spf watch` actually depends on.
  *
  * `ensureLabels()` is a no-op that reports the labels this run will use:
  * Jira labels are freeform strings with no color/description registry to
@@ -58,7 +67,7 @@
  * Jira API error at publish time — a genuine platform difference, not
  * something this file tries to paper over.
  */
-import type { JiraIssueTypeMap } from "../data_types.ts";
+import type { JiraIssueTypeMap, JiraStatusMap } from "../data_types.ts";
 import type { EnsureLabelsResult, Issue, IssueAuthoringKind, IssueAuthoringProvider, IssueComment, IssueProvider, WatchMarker, WatchState } from "./provider.ts";
 export declare class JiraProvider implements IssueProvider, IssueAuthoringProvider {
     private readonly baseUrl;
@@ -67,8 +76,9 @@ export declare class JiraProvider implements IssueProvider, IssueAuthoringProvid
     private readonly email;
     private readonly apiToken;
     private readonly issueTypes;
+    private readonly statusMap;
     constructor(baseUrl: string, // e.g. "https://your-domain.atlassian.net", no trailing slash
-    projectKey: string, labelPrefix: string, email: string, apiToken: string, issueTypes: JiraIssueTypeMap);
+    projectKey: string, labelPrefix: string, email: string, apiToken: string, issueTypes: JiraIssueTypeMap, statusMap?: JiraStatusMap);
     private authHeader;
     private jira;
     private label;
@@ -145,6 +155,37 @@ export declare class JiraProvider implements IssueProvider, IssueAuthoringProvid
         to?: WatchState;
     }): Promise<boolean>;
     transition(issue: Issue, to: WatchState, detail?: string): Promise<void>;
+    /**
+     * Best-effort native workflow-status sync — a no-op unless `statusMap`
+     * configures a name for `to`. Looked up per call, not cached: the
+     * available transitions are FROM-status-dependent, so the same target
+     * status can need a different transition id depending where the issue
+     * currently sits, and this same issue's status keeps moving across calls
+     * as it advances through the build lane. Every failure mode here
+     * (unconfigured, unreachable, or a rejected transition) is logged and
+     * swallowed, never thrown — see this file's module comment on why a
+     * status-sync miss must never break the label update callers depend on.
+     */
+    private syncStatus;
+    /**
+     * Read-only validation of the configured `status_map` against this
+     * project's real statuses — what `spf watch init` and `spf watch`'s own
+     * startup check should call to catch a misnamed status before an
+     * unattended run silently no-ops its status sync every time, the same
+     * role `validateIssueTypes()` plays for `issue_types`.
+     *
+     * Uses `/rest/api/3/project/{key}/statuses`, which groups statuses by
+     * issue type — Jira workflows can differ per issue type within one
+     * project. A configured name is "exists" if ANY issue type in the project
+     * has it: good enough to catch a typo, not a guarantee every issue type
+     * this map is used against can actually reach it (that's what
+     * `syncStatus()`'s own per-call transition lookup is for).
+     */
+    validateStatusMap(): Promise<Array<{
+        state: string;
+        jiraStatus: string;
+        exists: boolean;
+    }>>;
     comment(issue: Issue, body: string): Promise<void>;
     /** The single fetch every comment-reading method (`findMarkerComment`, `listComments`) builds on. */
     private fetchComments;

package/dist/core/issues/jira_provider.js

@@ -52,14 +52,16 @@ export class JiraProvider {
     email;
     apiToken;
     issueTypes;
+    statusMap;
     constructor(baseUrl, // e.g. "https://your-domain.atlassian.net", no trailing slash
-    projectKey, labelPrefix, email, apiToken, issueTypes) {
+    projectKey, labelPrefix, email, apiToken, issueTypes, statusMap = {}) {
         this.baseUrl = baseUrl;
         this.projectKey = projectKey;
         this.labelPrefix = labelPrefix;
         this.email = email;
         this.apiToken = apiToken;
         this.issueTypes = issueTypes;
+        this.statusMap = statusMap;
     }
     authHeader() {
         return `Basic ${Buffer.from(`${this.email}:${this.apiToken}`).toString("base64")}`;
@@ -213,8 +215,9 @@ export class JiraProvider {
         return Object.entries(this.issueTypes).map(([kind, jiraType]) => ({ kind, jiraType, exists: available.has(jiraType) }));
     }
     async claim(issue, opts) {
+        const toState = opts?.to ?? "working";
         const from = this.label(opts?.from ?? "ready");
-        const to = this.label(opts?.to ?? "working");
+        const to = this.label(toState);
         const next = issue.labels.filter((l) => l !== from);
         next.push(to);
         await this.jira(`/rest/api/3/issue/${issue.id}`, { method: "PUT", body: JSON.stringify({ fields: { labels: next } }) });
@@ -226,15 +229,72 @@ export class JiraProvider {
             revert.push(from);
             await this.jira(`/rest/api/3/issue/${issue.id}`, { method: "PUT", body: JSON.stringify({ fields: { labels: revert } }) }).catch(() => undefined);
         }
+        else {
+            await this.syncStatus(issue, toState);
+        }
         return claimed;
     }
     async transition(issue, to, detail) {
         const next = issue.labels.filter((l) => !STATES.some((s) => this.label(s) === l));
         next.push(this.label(to));
         await this.jira(`/rest/api/3/issue/${issue.id}`, { method: "PUT", body: JSON.stringify({ fields: { labels: next } }) });
+        await this.syncStatus(issue, to);
         if (detail)
             await this.comment(issue, detail);
     }
+    /**
+     * Best-effort native workflow-status sync — a no-op unless `statusMap`
+     * configures a name for `to`. Looked up per call, not cached: the
+     * available transitions are FROM-status-dependent, so the same target
+     * status can need a different transition id depending where the issue
+     * currently sits, and this same issue's status keeps moving across calls
+     * as it advances through the build lane. Every failure mode here
+     * (unconfigured, unreachable, or a rejected transition) is logged and
+     * swallowed, never thrown — see this file's module comment on why a
+     * status-sync miss must never break the label update callers depend on.
+     */
+    async syncStatus(issue, to) {
+        const statusName = this.statusMap[to];
+        if (!statusName)
+            return;
+        let transitions;
+        try {
+            ({ transitions } = await this.jira(`/rest/api/3/issue/${issue.id}/transitions`));
+        }
+        catch (err) {
+            console.error(`spf watch: ${issue.id} — couldn't fetch available Jira transitions to sync status ${JSON.stringify(statusName)}; label already updated — ${err instanceof Error ? err.message : String(err)}`);
+            return;
+        }
+        const match = transitions.find((t) => t.to.name === statusName);
+        if (!match) {
+            console.error(`spf watch: ${issue.id} has no available transition to Jira status ${JSON.stringify(statusName)} (watch.jira.status_map.${to}) from its current status — skipping status sync, label already updated`);
+            return;
+        }
+        await this.jira(`/rest/api/3/issue/${issue.id}/transitions`, { method: "POST", body: JSON.stringify({ transition: { id: match.id } }) }).catch((err) => {
+            console.error(`spf watch: ${issue.id} — Jira transition to ${JSON.stringify(statusName)} failed; label already updated — ${err instanceof Error ? err.message : String(err)}`);
+        });
+    }
+    /**
+     * Read-only validation of the configured `status_map` against this
+     * project's real statuses — what `spf watch init` and `spf watch`'s own
+     * startup check should call to catch a misnamed status before an
+     * unattended run silently no-ops its status sync every time, the same
+     * role `validateIssueTypes()` plays for `issue_types`.
+     *
+     * Uses `/rest/api/3/project/{key}/statuses`, which groups statuses by
+     * issue type — Jira workflows can differ per issue type within one
+     * project. A configured name is "exists" if ANY issue type in the project
+     * has it: good enough to catch a typo, not a guarantee every issue type
+     * this map is used against can actually reach it (that's what
+     * `syncStatus()`'s own per-call transition lookup is for).
+     */
+    async validateStatusMap() {
+        const result = await this.jira(`/rest/api/3/project/${encodeURIComponent(this.projectKey)}/statuses`);
+        const available = new Set(result.flatMap((t) => t.statuses.map((s) => s.name)));
+        return Object.entries(this.statusMap)
+            .filter((entry) => Boolean(entry[1]))
+            .map(([state, jiraStatus]) => ({ state, jiraStatus, exists: available.has(jiraStatus) }));
+    }
     async comment(issue, body) {
         await this.jira(`/rest/api/3/issue/${issue.id}/comment`, { method: "POST", body: JSON.stringify({ body: toAdf(body) }) });
     }

package/dist/core/paths.d.ts

@@ -16,6 +16,7 @@
  * levels below the package root, so the same relative path resolves either
  * way), with `assets/` a direct child of it.
  */
+import { type NormalizedObservabilityDb, type ObservabilityDbInput } from "./data_types.ts";
 export declare const PACKAGE_ROOT: string;
 export declare const ASSETS_DIR: string;
 /** The prebuilt SPA — a sibling of dist/ and assets/, built once at publish time (see app/). */
@@ -54,9 +55,22 @@ export interface DataPaths {
     data_dir: string;
     /** Repo-root-relative, forward-slash — for matching against git's own path output. */
     data_dir_rel: string;
-    /** Absolute. */
-    db_path: string;
-    /** Absolute. ALWAYS a sibling of `db_path` — relocating `data_dir` must never break this. */
+    /**
+     * The normalized `observability.db` descriptor — `core/trace_db.ts`'s
+     * `createTraceDb()` (called by both `Tracer` and `SfDb`) is built against
+     * exactly this shape. For `kind: "sqlite"`, `path` here is already
+     * resolved ABSOLUTE (byte-for-byte the same value as `db_path` below); for
+     * `kind: "d1"` there is no local path at all.
+     */
+    db: NormalizedObservabilityDb;
+    /** Absolute local sqlite path, or `null` for a `kind: "d1"` config — there is no local file to open. */
+    db_path: string | null;
+    /**
+     * Absolute. Anchored directly off `data_dir` (NOT off `db_path`) — session
+     * JSONL/envelope artifact files always live on the local filesystem
+     * regardless of where the queryable trace mirror (`db` above) lives, so
+     * this must resolve even when `db_path` is `null` for a d1-backed repo.
+     */
     sessions_dir: string;
 }
 /**
@@ -70,8 +84,31 @@ export interface DataPaths {
  *
  * Not otherwise side-effect-free: see `healBrokenDataDir` above, which every
  * caller needs run before its own first `mkdirSync` against `data_dir`.
+ *
+ * `rawDb` accepts every form `ObservabilityConfigSchema.db` accepts (bare
+ * string, `{kind:"sqlite",...}`, `{kind:"d1",...}`) — normalized here via
+ * `resolveObservabilityDb` — so every existing call site
+ * (`resolveDataPaths(anchor, cfg.defaults.data_dir, cfg.observability.db)`)
+ * keeps compiling and behaving unchanged with no call-site edit needed.
+ *
+ * For a `"sqlite"`-kind db, `db_path`/`db.path` resolve BYTE-FOR-BYTE
+ * identically to before this PR: `path.resolve(repo_root, path)`.
+ *
+ * For a `"d1"`-kind db there is no local file at all — `db_path` is `null`,
+ * and `db` carries the resolved `{kind:"d1", database_id, account_id_env,
+ * api_token_env}` for `core/trace_db.ts`'s `createTraceDb()` to open (PR 2:
+ * SPF #66). `sessions_dir` has no `db_path` to anchor off in this case, so it
+ * falls back to `data_dir/sessions` — session JSONL/envelope artifacts still
+ * always live on disk regardless of where the queryable trace mirror lives.
+ *
+ * For a `"sqlite"`-kind db, `sessions_dir` stays what it always was — ALWAYS
+ * a sibling of `db_path` (`dirname(db_path)/sessions`), never `data_dir`
+ * directly — `migrate.ts` and `SfDb` both depend on that: a repo whose db
+ * lives outside `data_dir` (`observability.db: elsewhere/custom.db` next to
+ * `defaults.data_dir: .spf/data`) still has its sessions found. Relocating
+ * `data_dir` alone must never orphan an existing db's session artifacts.
  */
-export declare function resolveDataPaths(anchor: RepoAnchor, rawDataDir: string, rawDbPath: string): DataPaths;
+export declare function resolveDataPaths(anchor: RepoAnchor, rawDataDir: string, rawDb: ObservabilityDbInput): DataPaths;
 /**
  * Resolve a prompt ref (a `prompt_engineering.system`/`.user` value from
  * config) to an absolute path, trying every root a ref could sensibly be

package/dist/core/paths.js

@@ -19,6 +19,7 @@
 import { existsSync, lstatSync, realpathSync, rmSync, statSync } from "node:fs";
 import path from "node:path";
 import { findRepoRoot } from "./git_helper.js";
+import { resolveObservabilityDb } from "./data_types.js";
 export const PACKAGE_ROOT = path.resolve(import.meta.dirname, "..", "..");
 export const ASSETS_DIR = path.join(PACKAGE_ROOT, "assets");
 /** The prebuilt SPA — a sibling of dist/ and assets/, built once at publish time (see app/). */
@@ -121,14 +122,42 @@ function healBrokenDataDir(data_dir) {
  *
  * Not otherwise side-effect-free: see `healBrokenDataDir` above, which every
  * caller needs run before its own first `mkdirSync` against `data_dir`.
+ *
+ * `rawDb` accepts every form `ObservabilityConfigSchema.db` accepts (bare
+ * string, `{kind:"sqlite",...}`, `{kind:"d1",...}`) — normalized here via
+ * `resolveObservabilityDb` — so every existing call site
+ * (`resolveDataPaths(anchor, cfg.defaults.data_dir, cfg.observability.db)`)
+ * keeps compiling and behaving unchanged with no call-site edit needed.
+ *
+ * For a `"sqlite"`-kind db, `db_path`/`db.path` resolve BYTE-FOR-BYTE
+ * identically to before this PR: `path.resolve(repo_root, path)`.
+ *
+ * For a `"d1"`-kind db there is no local file at all — `db_path` is `null`,
+ * and `db` carries the resolved `{kind:"d1", database_id, account_id_env,
+ * api_token_env}` for `core/trace_db.ts`'s `createTraceDb()` to open (PR 2:
+ * SPF #66). `sessions_dir` has no `db_path` to anchor off in this case, so it
+ * falls back to `data_dir/sessions` — session JSONL/envelope artifacts still
+ * always live on disk regardless of where the queryable trace mirror lives.
+ *
+ * For a `"sqlite"`-kind db, `sessions_dir` stays what it always was — ALWAYS
+ * a sibling of `db_path` (`dirname(db_path)/sessions`), never `data_dir`
+ * directly — `migrate.ts` and `SfDb` both depend on that: a repo whose db
+ * lives outside `data_dir` (`observability.db: elsewhere/custom.db` next to
+ * `defaults.data_dir: .spf/data`) still has its sessions found. Relocating
+ * `data_dir` alone must never orphan an existing db's session artifacts.
  */
-export function resolveDataPaths(anchor, rawDataDir, rawDbPath) {
+export function resolveDataPaths(anchor, rawDataDir, rawDb) {
     const data_dir = path.resolve(anchor.repo_root, rawDataDir);
     healBrokenDataDir(data_dir);
     const data_dir_rel = path.relative(anchor.repo_root, data_dir).split(path.sep).join("/");
-    const db_path = path.resolve(anchor.repo_root, rawDbPath);
+    const normalized = resolveObservabilityDb(rawDb);
+    if (normalized.kind === "d1") {
+        const sessions_dir = path.resolve(data_dir, "sessions");
+        return { data_dir, data_dir_rel, db: normalized, db_path: null, sessions_dir };
+    }
+    const db_path = path.resolve(anchor.repo_root, normalized.path);
     const sessions_dir = path.resolve(path.dirname(db_path), "sessions");
-    return { data_dir, data_dir_rel, db_path, sessions_dir };
+    return { data_dir, data_dir_rel, db: { kind: "sqlite", path: db_path }, db_path, sessions_dir };
 }
 /**
  * Resolve a prompt ref (a `prompt_engineering.system`/`.user` value from

package/dist/core/quality.d.ts

@@ -22,10 +22,10 @@ export interface RunLike {
     context_handoff_dir: string;
     repo_root: string;
     console: {
-        note: (message: string) => void;
+        note: (message: string) => Promise<void>;
     };
     tracer: {
-        event: (record: EventRecord) => string;
+        event: (record: EventRecord) => Promise<string>;
     };
     adw_id: string;
 }
@@ -41,7 +41,7 @@ export declare function resolveSuite(run: RunLike, suiteName: string): QualityCh
  * QualityNotConfigured (via resolveSuite) if the suite or any of its checks
  * isn't in the config — before any check runs, let alone any agent spawns.
  */
-export declare function runSuite(run: RunLike, suiteName: string): QualityResult;
+export declare function runSuite(run: RunLike, suiteName: string): Promise<QualityResult>;
 /**
  * The `test` suite alone — the deterministic test phase most chains use.
  *
@@ -50,9 +50,9 @@ export declare function runSuite(run: RunLike, suiteName: string): QualityResult
  * subprocess already knows; the repair loop is unchanged, because a failure
  * still reaches the builder through `asEnvelope` below.
  */
-export declare function runTests(run: RunLike): QualityResult;
+export declare function runTests(run: RunLike): Promise<QualityResult>;
 /** Every configured check, across every configured suite's union — the `all` suite. */
-export declare function runQuality(run: RunLike): QualityResult;
+export declare function runQuality(run: RunLike): Promise<QualityResult>;
 /**
  * Log a deterministic block's verdict — the same shape every chain uses.
  *
@@ -60,8 +60,8 @@ export declare function runQuality(run: RunLike): QualityResult;
  * hand; one copy here instead of one per chain.
  */
 export declare function record(ph: {
-    log: (payload: Record<string, unknown>) => void;
-}, result: QualityResult): void;
+    log: (payload: Record<string, unknown>) => Promise<void>;
+}, result: QualityResult): Promise<void>;
 /**
  * Wrap a deterministic result so an agent can be handed it directly.
  *

package/dist/core/quality.js

@@ -56,13 +56,13 @@ function shellJoin(argv) {
         .map((arg) => (/[\s"'$`\\!*?[\](){}<>|&;#~]/.test(arg) ? `'${arg.replace(/'/g, `'\\''`)}'` : arg))
         .join(" ");
 }
-function runCheck(spec, run) {
+async function runCheck(spec, run) {
     const phase = run.phases[run.phases.length - 1];
     const outputDir = checkDir(run, spec.name);
     const outputArtifact = path.join(outputDir, "command.log");
     const command = shellJoin(spec.argv);
     const env = operatorEnv(); // the engineer's own shell environment
-    run.console.note(`quality ${spec.name}: ${command}`);
+    await run.console.note(`quality ${spec.name}: ${command}`);
     const startedAt = nowIso();
     const clock = performance.now();
     let stdout = "";
@@ -100,7 +100,7 @@ function runCheck(spec, run) {
     writeFileSync(outputArtifact, `$ ${command}\nexit: ${returncode}\nduration_seconds: ${duration.toFixed(3)}\n` +
         `\n--- stdout ---\n${stdout}\n--- stderr ---\n${stderr}\n`);
     const passed = returncode === 0;
-    run.tracer.event(makeEventRecord({
+    await run.tracer.event(makeEventRecord({
         adw_id: run.adw_id,
         phase_id: phase.phase_id,
         type: "tool_call",
@@ -116,7 +116,7 @@ function runCheck(spec, run) {
         started_at: startedAt,
         ended_at: nowIso(),
     }));
-    run.console.note(`quality ${spec.name}: ${passed ? "passed" : "failed"} (exit ${returncode}, ${duration.toFixed(1)}s)`);
+    await run.console.note(`quality ${spec.name}: ${passed ? "passed" : "failed"} (exit ${returncode}, ${duration.toFixed(1)}s)`);
     return {
         name: spec.name,
         area: spec.area,
@@ -139,9 +139,15 @@ function runCheck(spec, run) {
  * QualityNotConfigured (via resolveSuite) if the suite or any of its checks
  * isn't in the config — before any check runs, let alone any agent spawns.
  */
-export function runSuite(run, suiteName) {
+export async function runSuite(run, suiteName) {
     const specs = resolveSuite(run, suiteName);
-    const checks = specs.map((spec) => runCheck(spec, run));
+    // Sequential, not Promise.all: check output/duration/tool_call ordering has
+    // always been one-at-a-time (spawnSync itself was always sequential) — a
+    // parallel run would interleave `run.console.note`/`run.tracer.event`
+    // calls across checks with no ordering guarantee.
+    const checks = [];
+    for (const spec of specs)
+        checks.push(await runCheck(spec, run));
     // A failure is the command, its exit code, and what it actually printed —
     // everything a builder needs to repair without opening a log or being told
     // what the error "means" by a parser that guessed.
@@ -163,11 +169,11 @@ export function runSuite(run, suiteName) {
  * subprocess already knows; the repair loop is unchanged, because a failure
  * still reaches the builder through `asEnvelope` below.
  */
-export function runTests(run) {
+export async function runTests(run) {
     return runSuite(run, "test");
 }
 /** Every configured check, across every configured suite's union — the `all` suite. */
-export function runQuality(run) {
+export async function runQuality(run) {
     return runSuite(run, "all");
 }
 /**
@@ -176,9 +182,9 @@ export function runQuality(run) {
  * Every quality/test phase in every chain reported this same summary by
  * hand; one copy here instead of one per chain.
  */
-export function record(ph, result) {
+export async function record(ph, result) {
     const passed = result.checks.filter((c) => c.passed).length;
-    ph.log({ passed: result.passed, checks: `${passed}/${result.checks.length}`, artifacts: result.artifacts.join(", ") });
+    await ph.log({ passed: result.passed, checks: `${passed}/${result.checks.length}`, artifacts: result.artifacts.join(", ") });
 }
 /**
  * Wrap a deterministic result so an agent can be handed it directly.

package/dist/core/refine.js

@@ -41,7 +41,7 @@ export function resolveAuthoringProvider(cfg) {
         if (!email || !token) {
             throw new Error('JIRA_EMAIL and JIRA_API_TOKEN must both be set — the refine lane needs an Atlassian account email plus an API token (id.atlassian.com -> Security -> API tokens)');
         }
-        return new JiraProvider(cfg.watch.jira.base_url, cfg.watch.jira.project_key, cfg.watch.label_prefix, email, token, cfg.watch.jira.issue_types);
+        return new JiraProvider(cfg.watch.jira.base_url, cfg.watch.jira.project_key, cfg.watch.label_prefix, email, token, cfg.watch.jira.issue_types, cfg.watch.jira.status_map);
     }
     if (cfg.watch.issue_provider !== "github") {
         throw new Error(`watch.issue_provider ${JSON.stringify(cfg.watch.issue_provider)} does not support issue authoring — the refine lane needs "github" or "jira"`);
@@ -61,7 +61,7 @@ export function resolveAuthoringProvider(cfg) {
     if (!token) {
         throw new Error('GITHUB_TOKEN is not set — the refine lane needs a classic PAT with "repo" scope (or "public_repo" for a public-only repo)');
     }
-    return new GitHubProvider(repo, cfg.watch.label_prefix, token);
+    return new GitHubProvider(repo, cfg.watch.label_prefix, token, cfg.watch.github.project_number, cfg.watch.github.status_map);
 }
 function typeLabel(labelPrefix, kind) {
     return `${labelPrefix}:type:${kind}`;

package/dist/core/runner.d.ts

@@ -20,13 +20,19 @@ interface AgentMapEntry {
     coding_agent: string;
 }
 export interface PhaseHandle {
-    log(payload: Record<string, unknown>): void;
+    log(payload: Record<string, unknown>): Promise<void>;
     call<T extends EnvelopeBase>(call: AgentCall<T>): Promise<T>;
 }
 export interface RunInit {
     cfg: SFConfig;
     adwId: string;
     tracer: Tracer;
+    /**
+     * `tracer.maxPhaseSeq(adwId)`, resolved by the caller BEFORE constructing
+     * `Run` — a real trace-db read now (a network call for a D1-backed repo),
+     * and `Run`'s own constructor cannot be async. See `session.ts`'s `ensure()`.
+     */
+    startSeq: number;
     engineer: string;
     /** Absolute. Resolved once, upstream, by paths.resolveAnchor(). */
     repoRoot: string;
@@ -75,7 +81,7 @@ export declare class Run {
     private agentMapPath;
     constructor(init: RunInit);
     saveAgentMap(agent: string, entry: AgentMapEntry): void;
-    addUsage(tokens: number, cost: number): void;
+    addUsage(tokens: number, cost: number): Promise<void>;
     phase<T>(params: PhaseParams, fn: (ph: PhaseHandle) => Promise<T>): Promise<T>;
     /**
      * Finalize the run and return its exit code. Call this exactly once.
@@ -86,6 +92,6 @@ export declare class Run {
      * so the exit code, the session status, and the banner are decided
      * together and cannot disagree.
      */
-    finish(accepted?: boolean, reason?: string): number;
+    finish(accepted?: boolean, reason?: string): Promise<number>;
 }
 export {};

package/dist/core/runner.js

@@ -14,8 +14,20 @@ import * as agents from "./agents.js";
 import { makeGit } from "./git_helper.js";
 import { Console } from "./console.js";
 import { Tracer } from "./tracer.js";
-import { makeEventRecord } from "./data_types.js";
+import { makeEventRecord, resolveObservabilityDb } from "./data_types.js";
 import { ensureDir, nowIso } from "./utils.js";
+/**
+ * `Console.sessionFinished`'s trailing `db` row wants a short, human-facing
+ * label, not a filesystem path specifically — `cfg.observability.db` is now
+ * a discriminated shape (see `data_types.ts`'s migration note), so this
+ * normalizes it to whichever of "the sqlite path" or "the D1 database id"
+ * is actually meaningful to show, rather than assuming it's always a path
+ * string the way this call site did before that field existed.
+ */
+function describeObservabilityDb(db) {
+    const resolved = resolveObservabilityDb(db);
+    return resolved.kind === "sqlite" ? resolved.path : `d1:${resolved.database_id}`;
+}
 class PhaseHandleImpl {
     run;
     phase;
@@ -23,17 +35,17 @@ class PhaseHandleImpl {
         this.run = run;
         this.phase = phase;
     }
-    log(payload) {
-        this.run.tracer.event(makeEventRecord({
+    async log(payload) {
+        await this.run.tracer.event(makeEventRecord({
             adw_id: this.run.adw_id,
             phase_id: this.phase.phase_id,
             type: "log",
             name: this.phase.params.name,
             payload,
         }));
-        this.run.console.note(Object.entries(payload).map(([k, v]) => `${k}: ${v}`).join(", "));
+        await this.run.console.note(Object.entries(payload).map(([k, v]) => `${k}: ${v}`).join(", "));
         if (this.phase.params.kind === "engineer" && "input" in payload) {
-            this.run.tracer.sessionRequest(this.run.adw_id, String(payload.input));
+            await this.run.tracer.sessionRequest(this.run.adw_id, String(payload.input));
         }
     }
     async call(call) {
@@ -80,7 +92,7 @@ export class Run {
         this.notify = init.notifier ?? null;
         this.console = new Console(init.tracer, init.adwId, this.notify, init.chainName || "adw", init.sink, init.observer);
         this.engineer = init.engineer;
-        this.seq = init.tracer.maxPhaseSeq(init.adwId);
+        this.seq = init.startSeq;
         this.repo_root = init.repoRoot;
         this.spf_dir = init.sfDir;
         this.git = makeGit(init.repoRoot);
@@ -95,12 +107,12 @@ export class Run {
         this.agent_map[agent] = entry;
         writeFileSync(this.agentMapPath, JSON.stringify(this.agent_map, null, 2));
     }
-    // ── usage (run totals mirror what the tracer accumulates in sqlite) ─────
-    addUsage(tokens, cost) {
+    // ── usage (run totals mirror what the tracer accumulates in the trace db) ─
+    async addUsage(tokens, cost) {
         this.tokens += tokens;
         this.cost += cost;
-        this.tracer.sessionAddUsage(this.adw_id, tokens, cost);
-        this.console.notifyUsage(this.tokens, this.cost);
+        await this.tracer.sessionAddUsage(this.adw_id, tokens, cost);
+        await this.console.notifyUsage(this.tokens, this.cost);
     }
     // ── the phase primitive ─────────────────────────────────────────────────
     async phase(params, fn) {
@@ -117,35 +129,35 @@ export class Run {
             ended_at: null,
         };
         this.phases.push(phase);
-        this.tracer.phaseUpsert(phase);
-        this.tracer.event(makeEventRecord({
+        await this.tracer.phaseUpsert(phase);
+        await this.tracer.event(makeEventRecord({
             adw_id: this.adw_id,
             phase_id: phase.phase_id,
             type: "phase_start",
             name: params.name,
             payload: { kind: params.kind, owner: params.owner, description: params.description },
         }));
-        this.console.phaseStarted(phase);
+        await this.console.phaseStarted(phase);
         const clock = performance.now();
         try {
             const result = await fn(new PhaseHandleImpl(this, phase));
             phase.status = "success";
             phase.ended_at = nowIso();
-            this.tracer.event(makeEventRecord({ adw_id: this.adw_id, phase_id: phase.phase_id, type: "phase_end", name: params.name, payload: { status: "success" } }));
-            this.tracer.phaseUpsert(phase);
-            this.console.phaseEnded(phase, (performance.now() - clock) / 1000);
+            await this.tracer.event(makeEventRecord({ adw_id: this.adw_id, phase_id: phase.phase_id, type: "phase_end", name: params.name, payload: { status: "success" } }));
+            await this.tracer.phaseUpsert(phase);
+            await this.console.phaseEnded(phase, (performance.now() - clock) / 1000);
             return result;
         }
         catch (error) {
             phase.status = "fail"; // success must be earned
             phase.error = String(error?.message ?? error).slice(0, 1000);
             phase.ended_at = nowIso();
-            this.tracer.event(makeEventRecord({ adw_id: this.adw_id, phase_id: phase.phase_id, type: "error", name: params.name, payload: { error: phase.error } }));
-            this.tracer.event(makeEventRecord({ adw_id: this.adw_id, phase_id: phase.phase_id, type: "phase_end", name: params.name, payload: { status: "fail" } }));
-            this.tracer.phaseUpsert(phase);
-            this.tracer.sessionFinish(this.adw_id, false);
-            this.console.phaseEnded(phase, (performance.now() - clock) / 1000);
-            this.console.sessionFinished(false, this.tokens, this.cost, this.cfg.observability.db);
+            await this.tracer.event(makeEventRecord({ adw_id: this.adw_id, phase_id: phase.phase_id, type: "error", name: params.name, payload: { error: phase.error } }));
+            await this.tracer.event(makeEventRecord({ adw_id: this.adw_id, phase_id: phase.phase_id, type: "phase_end", name: params.name, payload: { status: "fail" } }));
+            await this.tracer.phaseUpsert(phase);
+            await this.tracer.sessionFinish(this.adw_id, false);
+            await this.console.phaseEnded(phase, (performance.now() - clock) / 1000);
+            await this.console.sessionFinished(false, this.tokens, this.cost, describeObservabilityDb(this.cfg.observability.db));
             throw error;
         }
     }
@@ -158,22 +170,22 @@ export class Run {
      * so the exit code, the session status, and the banner are decided
      * together and cannot disagree.
      */
-    finish(accepted = true, reason = "") {
+    async finish(accepted = true, reason = "") {
         const phasesOk = this.phases.length > 0 && this.phases.every((p) => p.status === "success");
         const ok = phasesOk && accepted;
         if (phasesOk && !accepted) {
             const note = reason || "the run's acceptance criterion was not met";
-            this.tracer.event(makeEventRecord({
+            await this.tracer.event(makeEventRecord({
                 adw_id: this.adw_id,
                 phase_id: this.phases.length > 0 ? this.phases[this.phases.length - 1].phase_id : "",
                 type: "error",
                 name: "not_accepted",
                 payload: { reason: note },
             }));
-            this.console.note(`not accepted: ${note}`);
+            await this.console.note(`not accepted: ${note}`);
         }
-        this.tracer.sessionFinish(this.adw_id, ok);
-        this.console.sessionFinished(ok, this.tokens, this.cost, this.cfg.observability.db);
+        await this.tracer.sessionFinish(this.adw_id, ok);
+        await this.console.sessionFinished(ok, this.tokens, this.cost, describeObservabilityDb(this.cfg.observability.db));
         return ok ? 0 : 1;
     }
 }

package/dist/core/session.d.ts

@@ -30,7 +30,7 @@ import type { SFConfig } from "./data_types.ts";
  * `releaseOtelExporter`, and harmless for the same reason: that process
  * exits right after anyway.
  */
-export declare function finalize(adwId: string | null | undefined): void;
+export declare function finalize(adwId: string | null | undefined): Promise<void>;
 /** Tests only: which adw_ids the process-wide signal handler currently considers active. */
 export declare function activeRunIdsForTest(): string[];
 /**
@@ -49,4 +49,4 @@ export declare function ensure(cfg: SFConfig, adwId?: string | null, cwd?: strin
 renderHooks?: {
     sink?: (line: string) => void;
     observer?: RunObserver | null;
-}): Run;
+}): Promise<Run>;