talon-agent 5.18.2 → 5.19.1

package/src/backend/remote-server/messages.ts

@@ -3,15 +3,11 @@
  *
  * Both `KiloClient.session.messages` and `OpencodeClient.session.messages`
  * return the same wire format: an array of `{ info: { role, ... }, parts: [...] }`
- * objects. Kilo and OpenCode previously duplicated the same `findLastAssistantMessage`
- * helper — same body, drifted formatting, identical `info as unknown as
- * KiloAssistantInfo` / `OpenCodeAssistantInfo` casts. This module centralises
- * the walker and pushes the `info` typing out as a generic the caller supplies.
+ * objects. The `info` typing is a generic the caller supplies.
  *
  * The runtime guard (`info.role === "assistant"`) lives here and runs once;
- * the generic just labels what the caller intends to consume. No new
- * unsafe-cast surface is introduced — callers no longer cast through
- * `unknown` themselves.
+ * the generic just labels what the caller intends to consume, so callers
+ * never cast through `unknown` themselves.
  */
 
 /**

package/src/backend/remote-server/one-shot.ts

@@ -9,9 +9,7 @@
  * frontend), creating an ephemeral session, running the prompt,
  * rendering the response parts into the run log, and cleaning up.
  *
- * Both backends previously carried byte-for-byte copies of this file
- * that drifted (the abort handler landed in one and not the other);
- * the per-backend differences are exactly the `RemoteOneShotBindings`
+ * The per-backend differences are exactly the `RemoteOneShotBindings`
  * fields — server bootstrap, model-selection parsing, and the
  * delivery-contract suffix.
  *

package/src/backend/remote-server/session-helpers.ts

@@ -32,6 +32,7 @@
 
 import { logWarn } from "../../util/log.js";
 import type { RemoteAgentClient } from "./client.js";
+import { errMsg } from "./state.js";
 
 // ── Constants ───────────────────────────────────────────────────────────────
 
@@ -153,10 +154,6 @@ export interface RemoteSessionClient extends RemoteAgentClient {
 
 // ── Local utility ───────────────────────────────────────────────────────────
 
-function errMsg(e: unknown): string {
-  return e instanceof Error ? e.message : String(e);
-}
-
 function hasAssistantUsage(info: RemoteAssistantInfo | undefined): boolean {
   return Boolean(
     info?.tokens?.input ||

package/src/backend/remote-server/sse-stream.ts

@@ -5,17 +5,12 @@
  * `client.global.event()` which (per the upstream wire format) returns
  * a `ServerSentEventsResult` whose `stream` field is an async iterable
  * of typed events. The SDK's published types under-promise this shape —
- * the call signature returns a wider type than the value it produces.
- *
- * Previously, every backend that consumed this called
- * `await oc.global.event() as unknown as { stream?: AsyncIterable<unknown> }`
- * inline. Three copies of the same lie. This helper centralises it
- * behind one narrowing function with a runtime guard, so subsequent
- * backends (or the next SDK revision) can update the typing in one
- * place.
+ * the call signature returns a wider type than the value it produces,
+ * so the narrowing lives here once, behind a runtime guard.
  */
 
-import { logWarn } from "../../util/log.js";
+import { faultText } from "../../core/engine/fault-text.js";
+import { logDebug, logWarn } from "../../util/log.js";
 
 /**
  * Minimal client surface — what both `KiloClient` and `OpencodeClient`
@@ -54,6 +49,10 @@ export async function subscribeSseStream(
       lastError = err;
     }
     if (attempt < 3) {
+      logDebug(
+        "agent",
+        `sse.subscribe.retry chat=${chatId} attempt=${attempt} delay_ms=${150 * attempt} error="${faultText(lastError)}"`,
+      );
       await new Promise((resolve) => setTimeout(resolve, 150 * attempt));
     }
   }

package/src/backend/runtime/metrics.ts

@@ -84,11 +84,7 @@ export type TurnMetricInputs = {
   usage?: TokenUsageSnapshot;
 };
 
-/**
- * Record the uniform per-turn metric set. Replaces the per-backend
- * `recordHistogram("response_latency_ms")` + `incrementCounter
- * ("queries_total")` pairs (and codex's private `codex.*` family).
- */
+/** Record the uniform per-turn metric set. */
 export function recordTurnMetrics(inputs: TurnMetricInputs): void {
   recordSessionMetrics(inputs.chatId, inputs);
 }
@@ -97,11 +93,10 @@ export function recordTurnMetrics(inputs: TurnMetricInputs): void {
  * Terminal-failure accounting — call right before re-throwing a turn
  * that exhausted its retries.
  *
- * Historically every backend skipped BOTH `recordTurnMetrics` and
- * `recordUsage` when a turn errored: the tokens the failed turn burned
- * vanished from /status and /metrics, latency histograms only sampled
- * successes, and the live-turn overlay leaked until the next turn.
- * This helper closes all three gaps in one call:
+ * A failed turn still burned tokens. Without this, they vanish from
+ * /status and /metrics, latency histograms sample only successes, and
+ * the live-turn overlay leaks until the next turn. One call covers all
+ * three:
  *
  *   - per-turn metrics with `failed: true` (also feeds
  *     `backend.<id>.turn_failed`)
@@ -158,9 +153,8 @@ export function recordFailedTurnAccounting(inputs: {
 /**
  * Record a flow violation (prose written without a delivery tool).
  * Always counts the dropped text; the outcome picks the second
- * counter. Centralised because openai-agents historically skipped the
- * cap-exhausted counter, making "how often do models ignore the
- * reminder" unanswerable for that backend.
+ * counter. Centralised so every backend counts cap exhaustion — "how
+ * often do models ignore the reminder" needs both halves.
  */
 export function recordFlowViolation(
   chatId: string,

package/src/backend/runtime/sleep.ts

@@ -3,8 +3,7 @@
  *
  * Resolves after `ms` milliseconds, or immediately when the optional
  * `AbortSignal` fires. Used by the remote-server backends (kilo,
- * opencode) for throttled retries and stream pacing. Previously
- * duplicated inline in `kilo/handler.ts` and `opencode/handler.ts`.
+ * opencode) for throttled retries and stream pacing.
  */
 
 export function sleep(ms: number, signal?: AbortSignal): Promise<void> {

package/src/backend/runtime/turn/handle-retry.ts

@@ -24,12 +24,42 @@
 
 import type { QueryParams, QueryResult } from "./handler-types.js";
 import { classify, type TalonError } from "../../../core/errors.js";
-import { logWarn } from "../../../util/log.js";
+import { faultText } from "../../../core/engine/fault-text.js";
+import { log, logWarn } from "../../../util/log.js";
 import { incrementCounter } from "../../../storage/metrics.js";
 import { resetSession } from "../../../storage/sessions.js";
-import { classifyRetry } from "./model-retry.js";
+import { classifyRetry, type RetryDecision } from "./model-retry.js";
 import type { AgentEvent } from "../../../core/agent-runtime/events.js";
 
+/**
+ * One greppable line per recovery decision — what failed, how it was
+ * classified, and what the ladder does next. A retry is a warning (the
+ * turn is about to be re-run); a propagate is the turn's final error
+ * leaving the backend, and says so.
+ */
+function logRetryDecision(
+  chatId: string,
+  backendLabel: string | undefined,
+  activeModel: string,
+  retried: boolean,
+  classified: TalonError,
+  decision: RetryDecision,
+): void {
+  const action =
+    decision.kind === "reset_and_retry"
+      ? `reset_and_retry(${decision.reason})`
+      : decision.kind === "fallback_model"
+        ? `fallback_model(${decision.fallbackModelId})`
+        : "propagate";
+  const line =
+    `retry.decision chat=${chatId} backend=${(backendLabel || "claude").toLowerCase().replace(/\s+/g, "-")} ` +
+    `model=${activeModel} attempt=${retried ? 2 : 1} reason=${classified.reason} ` +
+    `retryable=${classified.retryable} status=${classified.status ?? "-"} ` +
+    `decision=${action} error="${faultText(classified)}"`;
+  if (decision.kind === "propagate") log("agent", line);
+  else logWarn("agent", line);
+}
+
 /** Inputs for `applyRetryDecision`. */
 export interface ApplyRetryDecisionInputs {
   /** The error caught by the backend's handler. */
@@ -112,6 +142,14 @@ export async function applyRetryDecision(
   });
 
   const prefix = backendLabel ? `${backendLabel} ` : "";
+  logRetryDecision(
+    chatId,
+    backendLabel,
+    activeModel,
+    retried,
+    classified,
+    decision,
+  );
 
   if (decision.kind === "reset_and_retry") {
     logWarn(
@@ -218,6 +256,14 @@ export async function* applyRetryDecisionStream(
   });
 
   const prefix = backendLabel ? `${backendLabel} ` : "";
+  logRetryDecision(
+    chatId,
+    backendLabel,
+    activeModel,
+    retried,
+    classified,
+    decision,
+  );
 
   if (decision.kind === "reset_and_retry") {
     logWarn(

package/src/backend/runtime/turn/handler-to-events.ts

@@ -10,10 +10,9 @@
  * skip this entirely and yield events directly — `runChatTurn` lives
  * in the backend module and owns its own stream surface.
  *
- * Replaces the historical `to-event-stream.ts` shim that lived under
- * "shared". The reframing matters: this is not a "legacy adapter,"
- * it's the canonical bridge between an SDK that emits via callbacks
- * and the `AgentEvent` contract every consumer reads.
+ * This is not a legacy adapter: it is the canonical bridge between an
+ * SDK that emits via callbacks and the `AgentEvent` contract every
+ * consumer reads.
  */
 
 import {

package/src/bootstrap.ts

@@ -28,6 +28,7 @@ import { initPulse, resetPulseTimer } from "./core/background/pulse/pulse.js";
 import { initCron } from "./core/background/cron/scheduler.js";
 import { initPlanAlerts } from "./core/background/pulse/plan-alerts.js";
 import { setAdminNotifier } from "./core/frontend-runtime/admin-notify.js";
+import { configureAlerts } from "./core/frontend-runtime/alerts.js";
 import { startAuthExpiryMonitor } from "./core/auth/expiry-monitor.js";
 import {
   initTriggers,
@@ -629,12 +630,19 @@ function initWakeSubsystems(config: TalonConfig): void {
  * Wire the admin notification seam to the admin's frontend, and start the
  * login-expiry monitor that rides it: the CLIs' "N days to log in again"
  * banner, delivered to the admin instead of a terminal nobody is watching
- * (/auth then completes the sign-in from the chat).
+ * (/auth then completes the sign-in from the chat). Operator alerts ride
+ * the same seam, so their settings are applied here too.
  */
 function wireAdminNotifier(
   config: TalonConfig,
   frontends: Parameters<typeof resolveFrontendByNumericId>[2],
 ): void {
+  if (config.alerts) {
+    configureAlerts({
+      enabled: config.alerts.enabled,
+      cooldownMs: config.alerts.cooldownMinutes * 60_000,
+    });
+  }
   if (!config.adminUserId) return;
   const adminChatId = config.adminUserId;
   setAdminNotifier(async (text: string) =>

package/src/cli/doctor.ts

@@ -6,6 +6,7 @@
 import pc from "picocolors";
 import { existsSync } from "node:fs";
 import { findRunningInstance } from "../core/daemon/discovery.js";
+import { formatAlertLines } from "./status.js";
 import { printBanner, loadConfig } from "./config.js";
 import { CONFIG_FILE } from "./context.js";
 
@@ -56,6 +57,8 @@ export async function runDoctor(): Promise<void> {
   const instance = await findRunningInstance();
   if (instance) {
     console.log(`  ${pc.green("✓")} Bot is running (PID ${instance.pid})`);
+    for (const line of formatAlertLines(instance.health ?? {}))
+      console.log(line);
   } else {
     console.log(`  ${pc.dim("-")} Bot is not running`);
   }

package/src/cli/index.ts

@@ -28,7 +28,7 @@ import { printBanner, ConfigFileError } from "./config.js";
 import { runSetup } from "./setup.js";
 import { showStatus } from "./status.js";
 import { viewConfig } from "./config-view.js";
-import { tailLogs } from "./logs.js";
+import { runLogsCommand } from "./logs.js";
 import { runDoctor } from "./doctor.js";
 import { startChat } from "./chat.js";
 import { daemonStart, daemonStop, daemonRestart } from "./daemon.js";
@@ -116,7 +116,9 @@ function printHelp(): void {
     `    ${pc.cyan("mesh")}       Device credentials (list/revoke/rotate/scopes)`,
   );
   console.log(`    ${pc.cyan("config")}     View/edit configuration`);
-  console.log(`    ${pc.cyan("logs")}       Tail log file`);
+  console.log(
+    `    ${pc.cyan("logs")}       Tail log file (--errors, --since 1h, --component, --grep, --turn)`,
+  );
   console.log(`    ${pc.cyan("doctor")}     Validate environment`);
   console.log(`    ${pc.cyan("--version")}  Print the package version`);
   console.log();
@@ -129,13 +131,9 @@ export async function runCli(): Promise<void> {
   try {
     await dispatch(command);
   } catch (err) {
-    // A present-but-invalid config.json: every command below that reads
-    // config (directly, or via `mainMenu`'s "is this configured?" check)
-    // is async but was previously invoked without `await`, so this throw
-    // would otherwise surface as a bare unhandled-rejection stack trace —
-    // or, worse for the main menu, never happen at all, because the old
-    // loader swallowed the error and returned defaults, sending a broken
-    // install into the first-run wizard, which then saves over the file.
+    // A present-but-invalid config.json: say so and exit non-zero, rather
+    // than a stack trace — or, for the main menu, a first-run wizard that
+    // would save defaults over the operator's real file.
     if (err instanceof ConfigFileError) {
       console.error(`\n  ${pc.red("✖")} ${err.message}\n`);
       process.exitCode = 1;
@@ -152,7 +150,7 @@ const COMMANDS: Record<string, CommandHandler> = {
   setup: () => runSetup(),
   status: () => showStatus(),
   config: () => viewConfig(),
-  logs: () => tailLogs(),
+  logs: (args) => runLogsCommand(args),
   start: async () => {
     printBanner();
     await daemonStart();

package/src/cli/logs.ts

@@ -1,13 +1,72 @@
 /**
  * `talon logs` — pretty-print the last lines of the JSON log file and then
  * tail it live.
+ *
+ * Filters (`--errors`, `--component`, `--since`, `--grep`, `--turn`)
+ * switch to the shared log reader (core/daemon/log-reader.ts — the same
+ * parser behind proc/log, proc/errors and doctor): the backlog is read
+ * across rotated generations, and the live tail applies the same filter.
+ * `--no-follow` prints the backlog and exits, for scripts and agents.
  */
 
 import pc from "picocolors";
 import { existsSync, readFileSync, watchFile } from "node:fs";
+import type { LogFilter, LogRecord } from "../core/daemon/log-reader.js";
 import { printBanner } from "./config.js";
 import { LOG_FILE } from "./context.js";
 
+export type LogsOptions = {
+  filter: LogFilter;
+  /** Keep tailing after the backlog (default true). */
+  follow: boolean;
+  /** Backlog size; undefined = 30, or 1000 under `--since`. */
+  lines?: number;
+};
+
+const LOGS_USAGE =
+  "talon logs [--errors] [--component <c>] [--since <30m|2h|1d>] " +
+  "[--grep <text>] [--turn <id>] [-n <lines>] [--no-follow]";
+
+/** Parse `talon logs` argv; a string is a usage error to print. */
+export async function parseLogsArgs(
+  args: string[],
+  now: number = Date.now(),
+): Promise<LogsOptions | string> {
+  const { parseLogDuration } = await import("../core/daemon/log-reader.js");
+  const opts: LogsOptions = { filter: {}, follow: true };
+  for (let i = 0; i < args.length; i++) {
+    const flag = args[i];
+    const value = (): string | undefined => args[++i];
+    if (flag === "--errors") opts.filter.minLevel = "warn";
+    else if (flag === "--no-follow") opts.follow = false;
+    else if (flag === "--component") opts.filter.component = value();
+    else if (flag === "--grep") opts.filter.grep = value();
+    else if (flag === "--turn") opts.filter.turn = value();
+    else if (flag === "--since") {
+      const ms = parseLogDuration(value() ?? "");
+      if (ms === null) return `--since needs a duration like 30m, 2h, 1d`;
+      opts.filter.since = now - ms;
+    } else if (flag === "-n" || flag === "--lines") {
+      const n = Number(value());
+      if (!Number.isInteger(n) || n <= 0) return `${flag} needs a count`;
+      opts.lines = n;
+    } else return `unknown option: ${flag}\n  usage: ${LOGS_USAGE}`;
+    if (i >= args.length) return `${flag} needs a value`;
+  }
+  return opts;
+}
+
+/** `parseLogsArgs` then run; usage errors exit non-zero. */
+export async function runLogsCommand(args: string[]): Promise<void> {
+  const opts = await parseLogsArgs(args);
+  if (typeof opts === "string") {
+    console.error(`  ${pc.red("✖")} ${opts}`);
+    process.exitCode = 1;
+    return;
+  }
+  await tailLogs(opts);
+}
+
 const LEVEL_LABELS: Record<number, string> = {
   10: pc.dim("TRC"),
   20: pc.dim("DBG"),
@@ -17,6 +76,25 @@ const LEVEL_LABELS: Record<number, string> = {
   60: pc.bgRed(pc.white("FTL")),
 };
 
+const LEVEL_NAME_LABELS: Record<LogRecord["level"], string> = {
+  trace: LEVEL_LABELS[10],
+  debug: LEVEL_LABELS[20],
+  info: LEVEL_LABELS[30],
+  warn: LEVEL_LABELS[40],
+  error: LEVEL_LABELS[50],
+  fatal: LEVEL_LABELS[60],
+};
+
+/** A parsed record in the same shape as {@link formatLogLine}. */
+function formatRecord(rec: LogRecord): string {
+  const time = pc.dim(new Date(rec.ts).toTimeString().slice(0, 8));
+  const comp = pc.cyan((rec.component ?? "?").padEnd(10));
+  const turn =
+    rec.turn && !rec.msg.includes("turn=") ? ` turn=${rec.turn}` : "";
+  const err = rec.err ? pc.red(` (${rec.err})`) : "";
+  return `  ${time} ${LEVEL_NAME_LABELS[rec.level]} ${comp} ${rec.msg}${turn}${err}`;
+}
+
 function formatLogLine(line: string): string {
   try {
     const obj = JSON.parse(line);
@@ -31,7 +109,13 @@ function formatLogLine(line: string): string {
   }
 }
 
-export async function tailLogs(): Promise<void> {
+function hasFilter(filter: LogFilter): boolean {
+  return Object.values(filter).some((v) => v !== undefined);
+}
+
+export async function tailLogs(
+  opts: LogsOptions = { filter: {}, follow: true },
+): Promise<void> {
   printBanner();
   if (!existsSync(LOG_FILE)) {
     console.log(
@@ -39,18 +123,73 @@ export async function tailLogs(): Promise<void> {
     );
     return;
   }
-  console.log(
-    `  ${pc.dim("Tailing")} ${pc.dim(LOG_FILE)}\n  ${pc.dim("Press Ctrl+C to stop")}\n`,
-  );
+  if (hasFilter(opts.filter)) return tailFiltered(opts);
+  if (opts.follow) {
+    console.log(
+      `  ${pc.dim("Tailing")} ${pc.dim(LOG_FILE)}\n  ${pc.dim("Press Ctrl+C to stop")}\n`,
+    );
+  }
   const content = readFileSync(LOG_FILE, "utf-8");
   const lines = content.trim().split("\n");
-  for (const line of lines.slice(-30)) console.log(formatLogLine(line));
-  let lastSize = lines.length;
-  watchFile(LOG_FILE, { interval: 500 }, () => {
+  for (const line of lines.slice(-(opts.lines ?? 30)))
+    console.log(formatLogLine(line));
+  if (!opts.follow) return;
+  await followLog(lines.length, (line) => console.log(formatLogLine(line)));
+}
+
+/** The filtered path: backlog across generations, then a filtered tail. */
+async function tailFiltered(opts: LogsOptions): Promise<void> {
+  const { readLogRecords, parseLogLine, matchesLogFilter } =
+    await import("../core/daemon/log-reader.js");
+  const limit = opts.lines ?? (opts.filter.since !== undefined ? 1000 : 30);
+  const backlog = readLogRecords(LOG_FILE, {
+    limit,
+    filter: opts.filter,
+    // The CLI owns its process: read whole generations, not a window.
+    maxBytesPerFile: 64 * 1024 * 1024,
+  });
+  const desc = describeFilter(opts.filter);
+  console.log(
+    `  ${pc.dim(`${backlog.length} matching entr${backlog.length === 1 ? "y" : "ies"} (${desc})`)}` +
+      (opts.follow ? `\n  ${pc.dim("Following — Ctrl+C to stop")}` : "") +
+      "\n",
+  );
+  for (const rec of backlog) console.log(formatRecord(rec));
+  if (!opts.follow) return;
+  const start = readFileSync(LOG_FILE, "utf-8").trim().split("\n").length;
+  await followLog(start, (line) => {
+    const rec = parseLogLine(line);
+    if (rec && matchesLogFilter(rec, opts.filter))
+      console.log(formatRecord(rec));
+  });
+}
+
+function describeFilter(filter: LogFilter): string {
+  const parts: string[] = [];
+  if (filter.minLevel) parts.push(`>=${filter.minLevel}`);
+  if (filter.component) parts.push(`component=${filter.component}`);
+  if (filter.since !== undefined)
+    parts.push(`since ${new Date(filter.since).toTimeString().slice(0, 8)}`);
+  if (filter.grep) parts.push(`grep "${filter.grep}"`);
+  if (filter.turn) parts.push(`turn=${filter.turn}`);
+  return parts.join(", ");
+}
+
+/** Print each line appended to the log from line `from` on, forever. */
+async function followLog(
+  from: number,
+  onLine: (line: string) => void,
+): Promise<void> {
+  let lastSize = from;
+  watchFile(LOG_FILE, { interval: 500 }, (curr, prev) => {
+    // A rotation (daemon start → talon.log.old, or the sink's runtime
+    // shift to talon.log.1) leaves a new file under the name, and counting
+    // its lines against the old one's would stay silent until it outgrew
+    // the file it replaced.
+    if (curr.ino !== prev.ino || curr.size < prev.size) lastSize = 0;
     try {
       const nl = readFileSync(LOG_FILE, "utf-8").trim().split("\n");
-      for (let i = lastSize; i < nl.length; i++)
-        console.log(formatLogLine(nl[i]));
+      for (let i = lastSize; i < nl.length; i++) onLine(nl[i]);
       lastSize = nl.length;
     } catch {
       /* ignore */

package/src/cli/setup.ts

@@ -26,11 +26,9 @@ const trimmedOrUndefined = (raw: string) => raw.trim() || undefined;
 /**
  * Await a clack prompt; on Esc/Ctrl-C say so and leave the wizard.
  *
- * Every prompt used to be followed by the same four-line `isCancel` guard,
- * and because `@clack/core` narrows `isCancel` to its own unique symbol
- * the unguarded remainder still needed an `as string` cast. clack only
- * ever resolves a symbol to mean "cancelled", so narrowing on `typeof`
- * here removes both.
+ * clack only ever resolves a symbol to mean "cancelled", so narrowing on
+ * `typeof` replaces a per-prompt `isCancel` guard and the `as` cast that
+ * `@clack/core`'s own unique-symbol narrowing would still need.
  *
  * The answer type is subtracted with `Exclude` rather than inferred from a
  * `Promise<T | symbol>` parameter: clack 1.8.1 retyped `CANCEL_SYMBOL` as a
@@ -667,12 +665,12 @@ function telegramAccess(
  *
  * Extracted from `runSetup` so the merge is testable without driving the
  * prompts — the behaviour that matters here is what it *doesn't* touch.
- * The wizard models roughly half of ~/.talon/config.json; it used to
- * rebuild the file from its own named fields alone, which silently
- * deleted every other key (whatsapp, native, soul, memory, github,
- * heartbeat/dream, allowlists, plugin blocks…). Spreading `existing`
- * first keeps them. Fields below still override, and an explicit
- * `undefined` still deletes, because `saveConfig` strips undefined.
+ * The wizard models roughly half of ~/.talon/config.json. Spreading
+ * `existing` first keeps every key it does not model (whatsapp, native,
+ * memory, github, heartbeat/dream, allowlists, plugin blocks…) — building
+ * from the named fields alone silently deletes them. Fields below still
+ * override, and an explicit `undefined` still deletes, because
+ * `saveConfig` strips undefined.
  */
 export function buildSetupConfig(
   existing: Config,

package/src/cli/status.ts

@@ -15,6 +15,29 @@ function formatUptime(seconds: number): string {
   return `${Math.floor(seconds / 3600)}h ${Math.floor((seconds % 3600) / 60)}m`;
 }
 
+type HealthAlert = { key: string; severity: string; message: string };
+
+/** The daemon's active alerts from its /health body (older daemons: none). */
+function healthAlerts(health: Record<string, unknown>): HealthAlert[] {
+  const raw = health.alerts;
+  if (!Array.isArray(raw)) return [];
+  return raw.filter(
+    (a): a is HealthAlert =>
+      typeof a === "object" &&
+      a !== null &&
+      typeof a.key === "string" &&
+      typeof a.message === "string",
+  );
+}
+
+/** One line per active alert, coloured by severity. Shared with doctor. */
+export function formatAlertLines(health: Record<string, unknown>): string[] {
+  return healthAlerts(health).map((a) => {
+    const dot = a.severity === "warn" ? pc.yellow("●") : pc.red("●");
+    return `  ${dot} ${pc.bold(a.key)}  ${a.message}`;
+  });
+}
+
 export async function showStatus(): Promise<void> {
   printBanner();
   const instance = await findRunningInstance();
@@ -38,6 +61,12 @@ export async function showStatus(): Promise<void> {
     console.log(`  ${pc.dim("Queue")}        ${h.queue} pending`);
     console.log(`  ${pc.dim("Errors")}       ${h.errors}`);
     console.log(`  ${pc.dim("Last active")}  ${h.lastActivity}\n`);
+    const alerts = formatAlertLines(h);
+    if (alerts.length > 0) {
+      console.log(`  ${pc.bold("Active alerts")}\n`);
+      for (const line of alerts) console.log(line);
+      console.log();
+    }
     return;
   }
 

package/src/core/agent-runtime/README.md

@@ -41,15 +41,16 @@ error | completed
 ```
 
 Plus `UsageSnapshot`, `AgentError` (with `AgentErrorKind`),
-`AgentResult`. Helpers: `emptyUsage`, `addUsage`, `isAgentEventOf`,
-`isAgentRunTerminator`.
+`AgentResult`, and `AgentRunError` — what the dispatcher rethrows an
+`error` terminator as. Helpers: `emptyUsage`, `toolInputToRecord`,
+`classifiedToAgentError`.
 
 ### `model-ref.ts`
 
 Typed model identity. `ModelRef = { backend: BackendId, id,
 displayName, ... }`. Owns the `BACKEND_IDS` literal — single source of
 truth for which backends the typed union can route to. Helpers:
-`isBackendId`, `sameModelRef`, `makeBareModelRef`.
+`isBackendId`, `makeBareModelRef`.
 
 ### `capabilities.ts`
 
@@ -101,16 +102,6 @@ Backend contract assertions any conforming `Backend` must pass:
 
 Each throws `ContractViolation` with a descriptive message.
 
-### `event-bridge.ts`
-
-The bridge between the canonical `AgentEvent` stream and the
-callback-shaped consumer contract the dispatcher uses upstream of the
-backend. `pipeEventsToCallbacks(stream, callbacks)` consumes an
-`AgentEvent` stream and invokes the supplied callbacks (`onStreamDelta`
-/ `onTextBlock` / `onToolUse`), returns the final `AgentResult`, and
-throws `BridgedAgentError` carrying the original `AgentError` if the
-stream terminates with an error event.
-
 ## Migration cookbook
 
 ### Adding a new backend
@@ -164,11 +155,6 @@ returns `{ model: string | null, ref: ModelRef | null, source }`:
 - `source` carries the chain step that produced the model, useful
   for toast wording and stale-slot cleanup.
 
-Convenience wrappers:
-
-- `getActiveModelForChat(...)` → `model`
-- `getActiveModelRefForChat(...)` → `ref`
-
 ### Adding a new store
 
 New structured state goes in the SQLite layer — see the layering doc
@@ -178,7 +164,7 @@ in `src/storage/db.ts` (sql/<store>.sql → repositories/<store>-repo.ts
 ## Invariants
 
 - `BACKEND_IDS` in `model-ref.ts` is the source of truth for the typed
-  union. `src/util/config.ts` zod enums are wired to the same literal.
+  union. `core/config/index.ts` zod enums are wired to the same literal.
 - `AgentEvent.type` is the ONLY discrimination mechanism. No class
   hierarchy, no `instanceof` checks.
 - Every `ChatBackend.runChatTurn` stream terminates with `completed`