@gr8ful/spf 0.15.0 → 0.17.0

package/dist/core/agents.js

@@ -13,6 +13,7 @@ import { parse as parseYaml } from "yaml";
 import * as v from "valibot";
 import * as agentCc from "./agent_cc.js";
 import * as agentFlue from "./agent_flue.js";
+import * as agentOpencode from "./agent_opencode.js";
 import * as paths from "./paths.js";
 import * as permissions from "./permissions.js";
 import * as prompts from "./prompts.js";
@@ -309,11 +310,13 @@ export function validate(cfg, required, requiredSuites = [], cwd) {
                 problems.push(`agent ${JSON.stringify(name)}: ${label} ${error.message}`);
             }
         }
-        // Model shape depends on the backend: Flue needs provider/model-id (no
-        // catalog to check against, only the static shape); claude_code takes
-        // its own bare alias/full-name vocabulary (see agent_cc.ts), so only a
-        // non-empty check applies.
-        if (agent.coding_agent === "flue") {
+        // Model shape depends on the backend: Flue and opencode both need
+        // provider/model-id (no catalog to check against for either — opencode's
+        // own provider set differs from Flue's — only the static shape, so
+        // `agentFlue.resolveModel`'s shape-only check is reused as-is); claude_code
+        // takes its own bare alias/full-name vocabulary (see agent_cc.ts), so only
+        // a non-empty check applies.
+        if (agent.coding_agent === "flue" || agent.coding_agent === "opencode") {
             try {
                 agentFlue.resolveModel(agent.model);
             }
@@ -333,7 +336,7 @@ export function validate(cfg, required, requiredSuites = [], cwd) {
             problems.push(`agent ${JSON.stringify(name)}: harness_engineering is not supported (${JSON.stringify(agent.harness_engineering)}) — ` +
                 `use useSubagent()/defineSkill() (flue) or an MCP server/plugin (claude_code) in a custom tool instead`);
         }
-        const isKnownToolName = agent.coding_agent === "claude_code" ? agentCc.isKnownToolName : agentFlue.isKnownToolName;
+        const isKnownToolName = agent.coding_agent === "claude_code" ? agentCc.isKnownToolName : agent.coding_agent === "opencode" ? agentOpencode.isKnownToolName : agentFlue.isKnownToolName;
         for (const toolName of agent.tools ?? []) {
             if (!isKnownToolName(toolName)) {
                 problems.push(`agent ${JSON.stringify(name)}: unknown tool ${JSON.stringify(toolName)} — known: read, write, edit, bash, grep, glob, find (alias for glob), ls (dropped, covered by bash/glob)`);
@@ -360,7 +363,7 @@ export function validate(cfg, required, requiredSuites = [], cwd) {
         // declared backend — the same branch this function already runs for
         // agent.model, just keyed off the tier's coding_agent instead.
         for (const tier of cfg.tiering.tiers) {
-            if (tier.coding_agent === "flue") {
+            if (tier.coding_agent === "flue" || tier.coding_agent === "opencode") {
                 try {
                     agentFlue.resolveModel(tier.model);
                 }
@@ -468,12 +471,13 @@ export function validateSandboxConfig(cfg, agent) {
     const problems = [];
     const sb = cfg.sandbox;
     const backend = agent.sandbox ?? sb.backend;
-    // claude_code spawns a host process (agent_cc.ts's spawn()) with no
-    // sandbox seam at all — sandboxing it would mean running the `claude` CLI
-    // INSIDE the container, a different feature, not this config flag.
-    if (agent.coding_agent === "claude_code" && backend !== "local") {
-        problems.push(`agent ${JSON.stringify(agent.name)}: coding_agent "claude_code" cannot use sandbox backend ${JSON.stringify(backend)} — ` +
-            `claude_code always spawns a host process with no sandbox seam; set agent.sandbox: local (or sandbox.backend: local) for this agent`);
+    // claude_code and opencode both spawn a host process (agent_cc.ts's /
+    // agent_opencode.ts's own spawn()) with no sandbox seam at all —
+    // sandboxing either would mean running the CLI INSIDE the container, a
+    // different feature, not this config flag.
+    if ((agent.coding_agent === "claude_code" || agent.coding_agent === "opencode") && backend !== "local") {
+        problems.push(`agent ${JSON.stringify(agent.name)}: coding_agent ${JSON.stringify(agent.coding_agent)} cannot use sandbox backend ${JSON.stringify(backend)} — ` +
+            `${agent.coding_agent} always spawns a host process with no sandbox seam; set agent.sandbox: local (or sandbox.backend: local) for this agent`);
     }
     if (backend === "opensandbox") {
         if (!sb.opensandbox.base_url.trim()) {
@@ -738,13 +742,15 @@ export async function execute(run, phase, call) {
     // translation need the spec baked into the rendered prompt text.
     const spec = sandboxSpecFor(run, agent);
     if (spec) {
-        sandbox.registerRunLog(spec.adw_id, (e) => run.tracer.event(makeEventRecord({
+        sandbox.registerRunLog(spec.adw_id, (e) => void run.tracer
+            .event(makeEventRecord({
             adw_id: run.adw_id,
             phase_id: phase.phase_id,
             type: "log",
             name: "sandbox",
             payload: { level: e.level, msg: e.msg, ...(e.data ? { data: e.data } : {}) },
-        })));
+        }))
+            .catch(() => { }));
     }
     const variables = {
         prompt: call.prompt,
@@ -762,8 +768,18 @@ export async function execute(run, phase, call) {
     const userText = prompts.render(paths.resolvePromptRef(run, agent.prompt_engineering.user), variables);
     prompts.save(path.join(agentDir, "prompts"), "system.md", systemText);
     prompts.save(path.join(agentDir, "prompts"), "user.md", userText);
-    const { session_id: sessionId, is_new: isNewSession } = agentSessionId(run, agent);
-    run.tracer.event(makeEventRecord({
+    // `sessionId` is reassigned by `send()` below (see its comment), ONLY for
+    // opencode, whenever its result carries the real captured id — its
+    // first-contact call starts from a cosmetic placeholder (see
+    // agent_opencode.ts's `pendingSessionLabel()`) and must swap in the real
+    // one before any later send() in this same phase (a JSON-repair retry, a
+    // gate correction). Deliberately scoped to opencode only, not a blanket
+    // reassignment from every backend's result — see `send()`'s comment for
+    // why that would NOT be a no-op for claude_code.
+    const initialSession = agentSessionId(run, agent);
+    const isNewSession = initialSession.is_new;
+    let sessionId = initialSession.session_id;
+    await run.tracer.event(makeEventRecord({
         adw_id: run.adw_id,
         phase_id: phase.phase_id,
         type: "agent_start",
@@ -779,7 +795,7 @@ export async function execute(run, phase, call) {
             harness_engineering: agent.harness_engineering,
         },
     }));
-    run.console.agentStarted(agent.name, agent.model, sessionId);
+    await run.console.agentStarted(agent.name, agent.model, sessionId);
     // Parse retries and gate corrections re-enter the SAME Flue conversation,
     // so the last send is the one whose context occupancy is current — while
     // spend is the opposite: every send costs, so usage accumulates across all.
@@ -808,17 +824,46 @@ export async function execute(run, phase, call) {
             sandbox: spec,
         };
         const forward = eventForwarder(run, phase, agent.name, agent.coding_agent);
-        const onSpawn = (pid) => run.tracer.processStart(run.adw_id, "agent", agent.name, pid, `${agent.coding_agent} ${agent.name} ${agent.model}`);
-        const onExit = (pid) => run.tracer.processEnd(run.adw_id, pid);
+        // Best-effort, fire-and-forget: these fire from a plain process-lifecycle
+        // callback (agent_cc.ts/agent_flue.ts's onSpawn/onExit hooks), not from
+        // this function's own async control flow, so there is nothing useful to
+        // await here — same swallow-and-log discipline as tracer.ts's otel fanOut.
+        const onSpawn = (pid) => void run.tracer.processStart(run.adw_id, "agent", agent.name, pid, `${agent.coding_agent} ${agent.name} ${agent.model}`).catch(() => { });
+        const onExit = (pid) => void run.tracer.processEnd(run.adw_id, pid).catch(() => { });
         if (spec)
             await sandbox.reconcileWorkspace(spec);
-        const result = agent.coding_agent === "claude_code"
-            ? await agentCc.run(request, forward, onSpawn, onExit)
-            : await agentFlue.run(request, forward, onSpawn, onExit);
+        let result;
+        if (agent.coding_agent === "claude_code") {
+            result = await agentCc.run(request, forward, onSpawn, onExit);
+        }
+        else if (agent.coding_agent === "opencode") {
+            result = await agentOpencode.run(request, forward, onSpawn, onExit);
+        }
+        else {
+            result = await agentFlue.run(request, forward, onSpawn, onExit);
+        }
         // SPEND IS RECORDED BEFORE THE EXTRACT CAN THROW: a failed extract must
         // not also lose this call's tokens/cost off the Run's ledger.
-        run.addUsage(result.tokens, result.cost);
+        await run.addUsage(result.tokens, result.cost);
         spent.merge(result.usage);
+        // opencode-ONLY: every subsequent send() in THIS phase (JSON-repair
+        // retries, gate corrections) must target the real captured session, not
+        // the placeholder this phase started with (see `initialSession`'s
+        // comment above and agent_opencode.ts's session-id lifecycle notes).
+        // Deliberately NOT applied to flue/claude_code — agent_cc.ts returns
+        // `final.session_id ?? request.session_id`, which PREFERS Claude Code's
+        // own reported id over the requested one when the two differ, so
+        // reassigning unconditionally here would let a claude_code run's
+        // recorded session id (agent_map.json, the agent_sessions trace table)
+        // drift from the one actually passed to `--session-id`/`--resume` —
+        // scoping this to opencode keeps flue/claude_code byte-identical to
+        // before this backend existed. `result.session_id` is also guarded
+        // against a falsy value here: a still-unresolved [SOURCE] NDJSON field
+        // name in agent_opencode.ts's `run()` should surface as a thrown error
+        // there (see its "sawStop but no captured session id" check), never as
+        // a silently-persisted empty/placeholder id.
+        if (agent.coding_agent === "opencode" && result.session_id)
+            sessionId = result.session_id;
         latest = result;
         if (spec)
             await sandbox.extractWorkspace(spec);
@@ -837,15 +882,15 @@ export async function execute(run, phase, call) {
         for (const gate of call.gates || []) {
             const report = asReport(gate(envelope, run));
             const found = report.violations;
-            run.tracer.gateRow(phase, gate.name, report, gateAttempt);
-            run.tracer.event(makeEventRecord({
+            await run.tracer.gateRow(phase, gate.name, report, gateAttempt);
+            await run.tracer.event(makeEventRecord({
                 adw_id: run.adw_id,
                 phase_id: phase.phase_id,
                 type: found.length > 0 ? "gate_fail" : "gate_pass",
                 name: gate.name,
                 payload: { attempt: gateAttempt, violations: found, checks: report.checks },
             }));
-            run.console.gateResult(gate.name, report);
+            await run.console.gateResult(gate.name, report);
             violations.push(...found);
         }
         if (violations.length === 0)
@@ -854,7 +899,7 @@ export async function execute(run, phase, call) {
             throw new GateFailure(`${agent.name} failed gates after ${gateAttempt} attempt(s):\n- ` + violations.join("\n- "));
         }
         phase.attempt = gateAttempt;
-        run.console.retry(agent.name, gateAttempt, phase.params.retries, `${violations.length} gate violation(s)`);
+        await run.console.retry(agent.name, gateAttempt, phase.params.retries, `${violations.length} gate violation(s)`);
         const correction = "Your previous response failed validation:\n- " +
             violations.join("\n- ") +
             "\n\nFix these problems, then re-emit ONLY your Report JSON.";
@@ -870,7 +915,7 @@ export async function execute(run, phase, call) {
         touched = permissions.enforce(run, phase, agent, treeBefore);
     }
     catch (breach) {
-        run.tracer.event(makeEventRecord({
+        await run.tracer.event(makeEventRecord({
             adw_id: run.adw_id,
             phase_id: phase.phase_id,
             type: "error",
@@ -885,7 +930,7 @@ export async function execute(run, phase, call) {
         throw breach;
     }
     if (touched.length > 0) {
-        run.tracer.event(makeEventRecord({
+        await run.tracer.event(makeEventRecord({
             adw_id: run.adw_id,
             phase_id: phase.phase_id,
             type: "log",
@@ -893,19 +938,19 @@ export async function execute(run, phase, call) {
             payload: { agent: agent.name, paths: touched },
         }));
     }
-    persistEnvelope(run, phase, agent.name, call, envelope, parsed.attempt, true);
-    run.console.envelopeSummary(envelope, call.output_type.name);
+    await persistEnvelope(run, phase, agent.name, call, envelope, parsed.attempt, true);
+    await run.console.envelopeSummary(envelope, call.output_type.name);
     const context = latest ?? result;
-    run.tracer.agentSessionRow(run.adw_id, agent, sessionId, context.context_tokens, context.context_window);
+    await run.tracer.agentSessionRow(run.adw_id, agent, sessionId, context.context_tokens, context.context_window);
     run.saveAgentMap(agent.name, { session_id: sessionId, model: agent.model, coding_agent: agent.coding_agent });
-    run.tracer.event(makeEventRecord({
+    await run.tracer.event(makeEventRecord({
         adw_id: run.adw_id,
         phase_id: phase.phase_id,
         type: "handoff",
         name: agent.name,
         payload: { artifacts: envelope.artifacts, summary: envelope.summary },
     }));
-    run.tracer.event(makeEventRecord({
+    await run.tracer.event(makeEventRecord({
         adw_id: run.adw_id,
         phase_id: phase.phase_id,
         type: "agent_end",
@@ -919,7 +964,7 @@ export async function execute(run, phase, call) {
             context_window: context.context_window,
         },
     }));
-    run.console.agentFinished(agent.name, spent.total_tokens, spent.total_cost);
+    await run.console.agentFinished(agent.name, spent.total_tokens, spent.total_cost);
     if (envelope.status !== "success") {
         throw new Error(`${agent.name} reported status=${JSON.stringify(envelope.status)}: ${envelope.summary}`);
     }
@@ -943,9 +988,26 @@ function asReport(result) {
  */
 function agentSessionId(run, agent) {
     const entry = run.agent_map[agent.name];
-    if (entry && entry.model === agent.model)
+    // A session handle from one backend is meaningless to another — flue and
+    // opencode share the identical provider/model-id vocabulary, so a
+    // coding_agent flip on an existing agent_map.json entry can otherwise
+    // leave `entry.model === agent.model` true while the stored session_id's
+    // SHAPE no longer matches the new backend (e.g. a flue `spf-...` id handed
+    // to opencode's `--session`, which requires its own `ses_<ULID>` shape).
+    if (entry && entry.model === agent.model && entry.coding_agent === agent.coding_agent) {
         return { session_id: entry.session_id, is_new: false }; // rejoin the existing context window
-    const session_id = agent.coding_agent === "claude_code" ? agentCc.newSessionId() : `spf-${run.adw_id}-${agent.name}-${newId(4)}`;
+    }
+    // opencode assigns its OWN real session id on first contact (never
+    // client-choosable — see agent_opencode.ts's module doc comment); what's
+    // minted here is a purely cosmetic placeholder for the pre-call trace
+    // event / console log, replaced by the real captured id the moment
+    // send() gets its first result back (see execute()'s `sessionId` handling
+    // below).
+    const session_id = agent.coding_agent === "claude_code"
+        ? agentCc.newSessionId()
+        : agent.coding_agent === "opencode"
+            ? agentOpencode.pendingSessionLabel()
+            : `spf-${run.adw_id}-${agent.name}-${newId(4)}`;
     return { session_id, is_new: true };
 }
 /**
@@ -955,15 +1017,19 @@ function agentSessionId(run, agent) {
  * this stays a plain pass-through regardless of which one it's given.
  */
 function eventForwarder(run, phase, agentName, codingAgent) {
-    const tracker = codingAgent === "claude_code" ? new agentCc.CcToolCallTracker() : new agentFlue.ToolCallTracker();
+    const tracker = codingAgent === "claude_code" ? new agentCc.CcToolCallTracker() : codingAgent === "opencode" ? new agentOpencode.OcToolCallTracker() : new agentFlue.ToolCallTracker();
     return (chunk) => {
         const record = tracker.observe(chunk);
         if (record === null)
             return;
         // The call's span rides the columns; duration_ms stays in the payload as
-        // Flue's own authoritative number.
+        // Flue's own authoritative number. Fire-and-forget, same reasoning as
+        // onSpawn/onExit above: this callback fires from a synchronous stream
+        // event handler (agent_cc.ts's readline `line` event / agent_flue.ts's
+        // chunk stream), never from this function's own async control flow.
         const { label, started_at, ended_at, ...rest } = record;
-        run.tracer.event(makeEventRecord({
+        void run.tracer
+            .event(makeEventRecord({
             adw_id: run.adw_id,
             phase_id: phase.phase_id,
             type: "tool_call",
@@ -971,7 +1037,8 @@ function eventForwarder(run, phase, agentName, codingAgent) {
             started_at: started_at ?? null,
             ended_at: ended_at ?? null,
             payload: { ...rest, agent: agentName },
-        }));
+        }))
+            .catch(() => { });
     };
 }
 function extractJson(text) {
@@ -1016,11 +1083,11 @@ async function parseWithRetries(run, phase, call, result, send, spec) {
         }
         catch (error) {
             const message = describeParseError(error);
-            persistEnvelope(run, phase, phase.params.owner, call, null, attempt, false, current.text);
+            await persistEnvelope(run, phase, phase.params.owner, call, null, attempt, false, current.text);
             if (attempt > JSON_FIX_ATTEMPTS) {
                 throw new Error(`${phase.params.owner} never produced valid ${call.output_type.name} JSON: ${message}`);
             }
-            run.console.retry(phase.params.owner, attempt, JSON_FIX_ATTEMPTS, `invalid ${call.output_type.name} JSON: ${message}`);
+            await run.console.retry(phase.params.owner, attempt, JSON_FIX_ATTEMPTS, `invalid ${call.output_type.name} JSON: ${message}`);
             const fields = call.output_type.fields.join(", ");
             current = await send(`Your response was not valid JSON for the required structure ` +
                 `(${message}). Respond again with ONLY a JSON object with these ` +
@@ -1029,9 +1096,9 @@ async function parseWithRetries(run, phase, call, result, send, spec) {
     }
     throw new Error("unreachable");
 }
-function persistEnvelope(run, phase, agentName, call, envelope, attempt, valid, raw = "") {
+async function persistEnvelope(run, phase, agentName, call, envelope, attempt, valid, raw = "") {
     const payloadJson = envelope ? JSON.stringify(envelope, null, 2) : JSON.stringify({ raw: raw.slice(-2000) });
-    run.tracer.envelopeRow(phase, agentName, call.output_type.name, payloadJson, valid, attempt);
+    await run.tracer.envelopeRow(phase, agentName, call.output_type.name, payloadJson, valid, attempt);
     if (envelope) {
         const record = {
             agent_name: agentName,

package/dist/core/console.d.ts

@@ -13,7 +13,7 @@ interface Notifier {
 }
 export declare function paint(style: string, text: string): string;
 interface Tracer {
-    event(record: EventRecord): string;
+    event(record: EventRecord): Promise<string>;
 }
 /**
  * A run-scoped hook for a live TTY view (`cli/ui/run_dashboard.tsx`) to
@@ -70,19 +70,19 @@ export declare class Console {
     /** See `RunObserver`'s own doc comment. `null` outside an interactive `cli/commands/run.ts` dispatch. */
     observer?: RunObserver | null);
     private emit;
-    sessionStarted(adwId: string, engineer: string): void;
-    sessionFinished(ok: boolean, tokens: number, cost: number, dbPath: string): void;
-    phaseStarted(phase: Phase): void;
-    phaseEnded(phase: Phase, seconds: number): void;
+    sessionStarted(adwId: string, engineer: string): Promise<void>;
+    sessionFinished(ok: boolean, tokens: number, cost: number, dbPath: string): Promise<void>;
+    phaseStarted(phase: Phase): Promise<void>;
+    phaseEnded(phase: Phase, seconds: number): Promise<void>;
     /** Free-form detail inside the current phase — what `ph.log()` recorded. */
-    note(message: string): void;
+    note(message: string): Promise<void>;
     /** `Run.addUsage()`'s only hook into `Console` — the running total lives on `Run`, not here, so this just forwards it to the observer. No line prints for this on its own; the totals already show up in `sessionFinished`'s panel. */
-    notifyUsage(tokens: number, cost: number): void;
-    agentStarted(name: string, model: string, sessionId: string): void;
-    agentFinished(name: string, tokens: number, cost: number): void;
-    retry(name: string, attempt: number, limit: number, reason: string): void;
+    notifyUsage(tokens: number, cost: number): Promise<void>;
+    agentStarted(name: string, model: string, sessionId: string): Promise<void>;
+    agentFinished(name: string, tokens: number, cost: number): Promise<void>;
+    retry(name: string, attempt: number, limit: number, reason: string): Promise<void>;
     /** A gate reports WHAT it checked, not just whether it passed. */
-    gateResult(name: string, report: GateReport): void;
-    envelopeSummary(envelope: EnvelopeBase, typeName: string): void;
+    gateResult(name: string, report: GateReport): Promise<void>;
+    envelopeSummary(envelope: EnvelopeBase, typeName: string): Promise<void>;
 }
 export {};

package/dist/core/console.js

@@ -77,9 +77,9 @@ export class Console {
         this.observer = observer;
     }
     // ── the one helper: print AND trace, always together ────────────────────
-    emit(line, level = "info") {
+    async emit(line, level = "info") {
         this.sink(line);
-        this.tracer.event(makeEventRecord({
+        await this.tracer.event(makeEventRecord({
             adw_id: this.adwId,
             phase_id: this.phaseId,
             type: "log",
@@ -88,8 +88,8 @@ export class Console {
         }));
     }
     // ── session ─────────────────────────────────────────────────────────────
-    sessionStarted(adwId, engineer) {
-        this.emit(`${paint("bold cyan", "adw_id:")} ${paint("bold", adwId)}   ${paint("dim", "engineer")} ${engineer}`);
+    async sessionStarted(adwId, engineer) {
+        await this.emit(`${paint("bold cyan", "adw_id:")} ${paint("bold", adwId)}   ${paint("dim", "engineer")} ${engineer}`);
         this.notifier?.send({
             kind: "run_started",
             level: "info",
@@ -100,7 +100,7 @@ export class Console {
             ],
         });
     }
-    sessionFinished(ok, tokens, cost, dbPath) {
+    async sessionFinished(ok, tokens, cost, dbPath) {
         if (this.finished)
             return;
         this.finished = true;
@@ -119,7 +119,7 @@ export class Console {
         this.sink(rendered);
         this.observer?.onSessionEnd?.(ok);
         const plain = `session ${this.adwId} ${ok ? "success" : "fail"} · ${passed}/${this.results.length} phases · ${tokens.toLocaleString()} tokens · $${cost.toFixed(4)}`;
-        this.tracer.event(makeEventRecord({
+        await this.tracer.event(makeEventRecord({
             adw_id: this.adwId,
             phase_id: this.phaseId,
             type: "log",
@@ -139,7 +139,7 @@ export class Console {
         });
     }
     // ── phases ──────────────────────────────────────────────────────────────
-    phaseStarted(phase) {
+    async phaseStarted(phase) {
         this.phaseId = phase.phase_id;
         this.phaseName = phase.params.name;
         const p = phase.params;
@@ -148,17 +148,17 @@ export class Console {
             `  ${paint(color, p.kind)} ${paint("dim", `· ${p.owner}`)}`;
         if (p.description)
             line += `  ${paint("dim", clip(p.description))}`;
-        this.emit(line);
+        await this.emit(line);
         this.observer?.onPhaseStart?.(phase);
     }
-    phaseEnded(phase, seconds) {
+    async phaseEnded(phase, seconds) {
         const ok = phase.status === "success";
         this.results.push(phase.status);
         this.observer?.onPhaseEnd?.(phase, seconds);
         let line = `  ${ok ? paint("green", "✓") : paint("red", "✗")} ${phase.params.name} ${paint("dim", `${seconds.toFixed(1)}s`)}`;
         if (!ok && phase.error)
             line += `  ${paint("red", clip(phase.error))}`;
-        this.emit(line, ok ? "info" : "error");
+        await this.emit(line, ok ? "info" : "error");
         if (!ok) {
             this.notifier?.send({
                 kind: "phase_failed",
@@ -176,22 +176,22 @@ export class Console {
         this.phaseName = "";
     }
     /** Free-form detail inside the current phase — what `ph.log()` recorded. */
-    note(message) {
-        this.emit(`  ${paint("dim", `· ${clip(message)}`)}`);
+    async note(message) {
+        await this.emit(`  ${paint("dim", `· ${clip(message)}`)}`);
     }
     /** `Run.addUsage()`'s only hook into `Console` — the running total lives on `Run`, not here, so this just forwards it to the observer. No line prints for this on its own; the totals already show up in `sessionFinished`'s panel. */
-    notifyUsage(tokens, cost) {
+    async notifyUsage(tokens, cost) {
         this.observer?.onUsage?.(tokens, cost);
     }
     // ── agents ──────────────────────────────────────────────────────────────
-    agentStarted(name, model, sessionId) {
-        this.emit(`  ${paint("magenta", "▸")} ${name} ${paint("dim", model)}  ${paint("dim", `session ${sessionId}`)}`);
+    async agentStarted(name, model, sessionId) {
+        await this.emit(`  ${paint("magenta", "▸")} ${name} ${paint("dim", model)}  ${paint("dim", `session ${sessionId}`)}`);
     }
-    agentFinished(name, tokens, cost) {
-        this.emit(`  ${paint("dim", `└ ${name} used ${tokens.toLocaleString()} tokens · $${cost.toFixed(4)}`)}`);
+    async agentFinished(name, tokens, cost) {
+        await this.emit(`  ${paint("dim", `└ ${name} used ${tokens.toLocaleString()} tokens · $${cost.toFixed(4)}`)}`);
     }
-    retry(name, attempt, limit, reason) {
-        this.emit(`  ${paint("yellow", "⟳")} ${name} retry ${attempt}/${limit} ${paint("dim", `— same session · ${clip(reason)}`)}`, "warn");
+    async retry(name, attempt, limit, reason) {
+        await this.emit(`  ${paint("yellow", "⟳")} ${name} retry ${attempt}/${limit} ${paint("dim", `— same session · ${clip(reason)}`)}`, "warn");
         // info-level: routine self-healing, same as watch's own untracked
         // orphan retries — visible under `events: all`, silent under `errors`.
         this.notifier?.send({
@@ -204,25 +204,25 @@ export class Console {
     }
     // ── verification ────────────────────────────────────────────────────────
     /** A gate reports WHAT it checked, not just whether it passed. */
-    gateResult(name, report) {
+    async gateResult(name, report) {
         const ok = report.passed;
         const mark = ok ? paint("green", "✓") : paint("red", "✗");
         const summary = ok
             ? `${report.checks.length} checked`
             : paint("red", `${report.violations.length} of ${report.checks.length} failed`);
-        this.emit(`  ${mark} gate ${paint("dim", name)} ${paint("dim", summary)}`, ok ? "info" : "error");
+        await this.emit(`  ${mark} gate ${paint("dim", name)} ${paint("dim", summary)}`, ok ? "info" : "error");
         for (const check of report.checks) {
             const style = check.ok ? "dim" : "dim red";
             const detail = check.note ? ` — ${clip(check.note)}` : "";
-            this.emit(`    ${paint(style, `${check.ok ? "·" : "✗"} ${clip(check.item)}${detail}`)}`, check.ok ? "info" : "error");
+            await this.emit(`    ${paint(style, `${check.ok ? "·" : "✗"} ${clip(check.item)}${detail}`)}`, check.ok ? "info" : "error");
         }
     }
-    envelopeSummary(envelope, typeName) {
+    async envelopeSummary(envelope, typeName) {
         const ok = envelope.status === "success";
         const line = `  ${ok ? paint("green", "✓") : paint("red", "✗")} ${typeName} ${paint("dim", clip(envelope.summary))}`;
-        this.emit(line, ok ? "info" : "error");
+        await this.emit(line, ok ? "info" : "error");
         if (envelope.artifacts.length > 0) {
-            this.emit(`    ${paint("dim", `artifacts: ${clip(envelope.artifacts.join(", "))}`)}`);
+            await this.emit(`    ${paint("dim", `artifacts: ${clip(envelope.artifacts.join(", "))}`)}`);
         }
     }
 }