talon-agent 5.18.1 → 5.19.0

package/src/backend/openai-agents/builtins.ts

@@ -31,9 +31,10 @@
  * shared prompt vocabulary applies uniformly.
  */
 import { tool } from "@openai/agents";
-import { spawn } from "node:child_process";
+import { spawn, type ChildProcess } from "node:child_process";
 import { readFile, writeFile, mkdir, glob } from "node:fs/promises";
 import { dirname, resolve as resolvePath } from "node:path";
+import { createOutputCapture } from "../../util/exec-output.js";
 import { expandFsPath as expandPath } from "../../util/fs-path.js";
 
 // ── Read ────────────────────────────────────────────────────────────────────
@@ -204,6 +205,12 @@ const editTool = tool({
 
 const BASH_DEFAULT_TIMEOUT_MS = 30_000;
 const BASH_MAX_TIMEOUT_MS = 600_000;
+/**
+ * After a timeout kill, how long to wait for `close` before settling with
+ * what was captured. `close` waits for the stdio pipes to drain, which a
+ * descendant that escaped the kill can hold open indefinitely.
+ */
+const BASH_CLOSE_GRACE_MS = 2_000;
 
 interface BashInput {
   command: string;
@@ -235,43 +242,64 @@ function runShell(
             ],
           }
         : { cmd: "bash", args: ["-lc", command] };
+    // detached → own process group on POSIX, so the timeout kill reaches
+    // the shell's children too. A surviving child (the `sleep` in
+    // `sleep 30; echo`) holds stdout open, and `close` waits for it.
+    const detached = process.platform !== "win32";
     const child = spawn(shell.cmd, shell.args, {
       cwd: process.cwd(),
       env: process.env,
       stdio: ["ignore", "pipe", "pipe"],
+      detached,
     });
-    let stdout = "";
-    let stderr = "";
-    child.stdout.on("data", (b: Buffer) => {
-      stdout += b.toString("utf8");
-    });
-    child.stderr.on("data", (b: Buffer) => {
-      stderr += b.toString("utf8");
-    });
+    // Bounded: an unbounded stream (`yes`, a verbose build) otherwise grows
+    // until V8's string limit throws inside the data listener.
+    const out = createOutputCapture();
+    const err = createOutputCapture();
+    child.stdout.on("data", out.push);
+    child.stderr.on("data", err.push);
+    let settled = false;
+    let timedOut = false;
+    let closeGrace: NodeJS.Timeout | undefined;
+    const finish = (code: number, stderr = err.value()): void => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(killer);
+      if (closeGrace) clearTimeout(closeGrace);
+      resolveResult({ stdout: out.value(), stderr, code, timedOut });
+    };
     const killer = setTimeout(() => {
       timedOut = true;
-      child.kill("SIGKILL");
+      killGroup(child, detached);
+      // A descendant that left the group can still hold the pipes open;
+      // don't let it pin the tool call past the timeout.
+      closeGrace = setTimeout(() => finish(-1), BASH_CLOSE_GRACE_MS);
     }, timeoutMs);
-    let timedOut = false;
-    child.on("error", (err) => {
-      // spawn failed (e.g. bash not in PATH on Windows). Resolve instead
-      // of letting Node emit an uncaught error — the tool returns the
-      // diagnostic so callers can surface it rather than crashing.
-      clearTimeout(killer);
-      resolveResult({
-        stdout,
-        stderr: err.message,
-        code: -1,
-        timedOut: false,
-      });
-    });
-    child.on("close", (code) => {
-      clearTimeout(killer);
-      resolveResult({ stdout, stderr, code: code ?? -1, timedOut });
-    });
+    // spawn failed (e.g. bash not in PATH on Windows). Resolve instead
+    // of letting Node emit an uncaught error — the tool returns the
+    // diagnostic so callers can surface it rather than crashing.
+    child.on("error", (spawnErr) => finish(-1, spawnErr.message));
+    child.on("close", (code) => finish(code ?? -1));
   });
 }
 
+/** SIGKILL the child's whole process group, falling back to the child. */
+function killGroup(child: ChildProcess, detached: boolean): void {
+  if (detached && child.pid) {
+    try {
+      process.kill(-child.pid, "SIGKILL");
+      return;
+    } catch {
+      // group already gone — fall through to the direct kill
+    }
+  }
+  try {
+    child.kill("SIGKILL");
+  } catch {
+    // already dead
+  }
+}
+
 const bashTool = tool({
   name: "Bash",
   description:

package/src/backend/openai-agents/factory.ts

@@ -93,9 +93,9 @@ const openAIAgentsFactory: BackendFactory = {
 
     return {
       backend,
-      // Cleanup: close every per-chat MCP bundle in the pool so the
-      // ~15 plugin subprocesses per active chat don't outlive the
-      // backend itself, then drop the cached state.
+      // Cleanup: close every per-chat MCP bundle in the pool so its hub
+      // sessions don't outlive the backend itself, then drop the cached
+      // state.
       cleanup: async () => {
         await releaseAllBundles();
         resetState();

package/src/backend/openai-agents/handler/message.ts

@@ -118,8 +118,7 @@ function buildTurnPrompt(
 
 /**
  * Acquire the per-chat MCP bundle. Persistent across turns — built on
- * first use, kept alive until `releaseBundle(chatId)`. Avoids the
- * ~15-subprocess re-spawn the original per-turn build caused.
+ * first use, kept until the backend's cleanup releases the pool.
  */
 async function acquireMcpBundle(
   chatId: string,
@@ -366,7 +365,7 @@ export async function handleMessage(
   } catch (err) {
     // Swallow the terminator abort — the turn completed via a delivery tool.
     if (!isTerminatorAbort(streamState, err)) {
-      // MCP bundle is retained across a retry — subprocesses are
+      // MCP bundle is retained across a retry — its servers are
       // stateless wrt the model conversation. See `mcp-pool.ts`.
       const outcome = await applyRetryDecision({
         err,
@@ -400,8 +399,7 @@ export async function handleMessage(
       activeAborts.delete(chatId);
     }
     // MCP bundle is NOT closed here — it persists across turns via the
-    // pool in `mcp-pool.ts`. Release happens on chat rebind, `/reset`, and
-    // at backend cleanup.
+    // pool in `mcp-pool.ts` and is released at backend cleanup.
   }
 
   // ── Post-loop accounting ──────────────────────────────────────────────────

package/src/backend/openai-agents/mcp-pool.ts

@@ -4,17 +4,11 @@
  * Every server is a lightweight `MCPServerStreamableHttp` client
  * pointing at the daemon's MCP hub (`core/mcp-hub`): Talon's own tools
  * run in-process there, and plugin/brave servers are hub-managed
- * children shared across chats and reaped when idle.
+ * children shared across chats and reaped when idle. A bundle is just
+ * HTTP client objects; the process count is owned and bounded by the hub.
  *
- * Historical note: this pool used to hold one **subprocess set** per
- * chat (every plugin × every chat, held until release) — the daemon's
- * memory grew linearly with the number of chats. With the hub, a
- * bundle is just HTTP client objects; the process count is owned and
- * bounded by the hub.
- *
- * The bundle is still cached per chat (and released on reset/rebind)
- * so `cacheToolsList` survives across turns and each turn skips the
- * connect handshake.
+ * The bundle is cached per chat so `cacheToolsList` survives across
+ * turns and each turn skips the connect handshake.
  *
  * Concurrency: `getOrCreateBundle` serialises the build-or-return
  * decision on a per-chat in-flight Promise so two concurrent turns from
@@ -36,18 +30,13 @@ import { frontendsForChat } from "../runtime/frontends.js";
 import { log, logWarn } from "../../util/log.js";
 
 /**
- * One per-chat bundle. Subprocesses stay alive until `close()` is
+ * One per-chat bundle. Its hub sessions stay open until `close()` is
  * called via `releaseBundle()` / `releaseAllBundles()`.
  */
 export interface OpenAIAgentsMcpBundle {
-  /**
-   * Connected MCP servers ready to pass to `new Agent({ mcpServers })`.
-   * `connectMcpServers` returns the structural `MCPServer` type — the
-   * underlying instances are `MCPServerStdio` but the Agent constructor
-   * only needs the interface.
-   */
+  /** Connected MCP servers ready to pass to `new Agent({ mcpServers })`. */
   servers: MCPServer[];
-  /** Close every spawned subprocess. Safe to call multiple times. */
+  /** Close every server's hub session. Safe to call multiple times. */
   close: () => Promise<void>;
   /** Servers that failed to connect — exposed for diagnostics. */
   failed: ReadonlyArray<{ name: string; error: string }>;
@@ -115,14 +104,8 @@ export async function getOrCreateBundle(
  * Close the bundle for `chatId` and drop it from the pool. No-op when
  * the chat has no live bundle.
  *
- * Call when:
- *   - The chat rebinds to a non-openai-agents backend.
- *   - The user runs `/reset`.
- *   - The chat is destroyed.
- *
  * If `getOrCreateBundle` is in flight when called, releases the bundle
- * once the in-flight build resolves to avoid leaving an unreleased
- * subprocess set.
+ * once the in-flight build resolves so it is not left open.
  */
 export async function releaseBundle(chatId: string): Promise<void> {
   // If a build is in flight, wait for it then close the result.
@@ -152,8 +135,8 @@ export async function releaseBundle(chatId: string): Promise<void> {
 
 /**
  * Close every live bundle. Used by the backend factory's `cleanup`
- * hook so unbinding the openai-agents backend leaves no orphan MCP
- * subprocesses.
+ * hook so unbinding the openai-agents backend leaves no hub sessions
+ * behind.
  */
 export async function releaseAllBundles(): Promise<void> {
   const ids = [...bundles.keys()];

package/src/backend/remote-server/chat-turn.ts

@@ -253,12 +253,6 @@ export async function runRemoteChatTurn<TClient extends RemoteAgentClient>(
   });
 }
 
-/**
- * If the SSE loop missed the usage info, fall back to the session summary
- * endpoint (which always reflects the final server state). Best-effort:
- * session summaries can race on cancellation, so a failure leaves the
- * counts at zero.
- */
 /**
  * The turn's user prompt: the shared framing every backend emits, plus
  * whatever this turn's memory retrieval produced. `formatUserPrompt` is
@@ -276,6 +270,12 @@ function buildTurnPrompt(params: QueryParams): string {
   });
 }
 
+/**
+ * If the SSE loop missed the usage info, fall back to the session summary
+ * endpoint (which always reflects the final server state). Best-effort:
+ * session summaries can race on cancellation, so a failure leaves the
+ * counts at zero.
+ */
 async function fillUsageFromSummary(
   oc: RemoteSessionClient,
   sessionId: string,

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

@@ -39,11 +39,7 @@ import {
   type RemoteAssistantInfo,
 } from "./session-helpers.js";
 import { log, logDebug } from "../../util/log.js";
-
-/** Format an error for a debug log line. */
-function errMsg(err: unknown): string {
-  return err instanceof Error ? err.message : String(err);
-}
+import { errMsg } from "./state.js";
 
 // ── Streaming timing ───────────────────────────────────────────────────────
 

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

@@ -19,7 +19,6 @@
  *   - Bindings (server-bindings.ts, chat-turn.ts, turn.ts, factory.ts) —
  *     the helpers closed over one backend's state, the SSE-driven turn,
  *     the chat-turn orchestration, and the registry factory composition.
- *     This is where the code that used to be copied per backend lives.
  *
  *   - Profiles (`profiles/bind.ts` + `profiles/{kilo,opencode}.ts`) —
  *     `bindRemoteProfile` closes all of the above over one driver's

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();