talon-agent 5.0.0 → 5.0.1

package/src/core/agent-runtime/agent-host.ts

@@ -0,0 +1,387 @@
+/**
+ * The agent-host seam — the contract between the daemon and the process
+ * that hosts the Claude Agent SDK.
+ *
+ * `docs/agent-host-sidecar.md` Phase 1. Today the SDK runs inside the
+ * daemon: an OOM or an SDK bug takes down every frontend with it. The
+ * sidecar moves it into its own process, and this file is the boundary
+ * that move happens across — written first, on purpose, so Phase 2 is a
+ * transport swap rather than a redesign.
+ *
+ * Two halves:
+ *
+ *   - **The wire vocabulary.** `HostRequest` / `HostReply` / `HostEvent` /
+ *     `HostNotice` are the NDJSON messages of the design's protocol
+ *     table, one TypeScript type per row, plus `parseHostMessage` /
+ *     `serializeHostMessage` — the codec both sides run, replayed against
+ *     `protocol/fixtures/agent-host_v1.json` in
+ *     `src/__tests__/agent-host-protocol.test.ts`.
+ *   - **The client.** `AgentHostClient` is what the daemon holds. Phase 1
+ *     ships one implementation (`backend/claude-sdk/host/in-process.ts`,
+ *     a direct call-through); Phase 2 adds a second that speaks the
+ *     messages above over a child process's stdio. The `Backend` object
+ *     the rest of the daemon sees is identical either way.
+ *
+ * Layering: the interface and the codec live in `core/` because `core/`
+ * may not import `backend/` (depcruise `core-not-to-backend`). Every
+ * implementation lives under `backend/`.
+ *
+ * Wire types vs client types
+ * ──────────────────────────
+ * They are deliberately not the same types. Two client arguments do not
+ * survive a process boundary and the wire shapes say so:
+ *
+ *   - `OneShotAgentParams` carries an `AbortController` and an
+ *     `appendLog` callback. `HostOneShotParams` is the serialisable
+ *     subset; Phase 2 maps `appendLog` onto `log` notices and the
+ *     abort onto an `interrupt`-shaped request.
+ *   - `hello.config` is the `claude-sdk` slice of `TalonConfig` as
+ *     JSON. The in-process client takes the real `TalonConfig` object.
+ *
+ * Forward compatibility: unknown fields on a known message type are
+ * additive evolution and must be preserved, never rejected. An unknown
+ * `type` parses to `HostUnknown`, which callers log and drop — the codec
+ * never throws, so one bad line can't kill a turn or the loop reading it.
+ */
+
+import type { AgentEvent, AgentError } from "./events.js";
+import type { ChatRunParams, PlanUsage } from "./capabilities.js";
+import type {
+  OneShotAgentParams,
+  OneShotUsage,
+  ReasoningEffortLevel,
+  UnifiedModelInfo,
+} from "../types.js";
+
+/** Wire-format version. Bump only on a breaking change — prefer additive. */
+export const AGENT_HOST_PROTOCOL_VERSION = 1;
+
+// ── Shared payload shapes ───────────────────────────────────────────────────
+
+/**
+ * The serialisable half of `OneShotAgentParams`. `abortController` and
+ * `appendLog` are host-local concerns (see the file header); everything
+ * else is exactly what a background run needs.
+ *
+ * Unexported on purpose — it is reachable as
+ * `Extract<HostRequest, { type: "one_shot" }>["params"]`, and a second
+ * name for the same shape is a thing to keep in sync for nothing.
+ */
+interface HostOneShotParams {
+  prompt: string;
+  systemPrompt: string;
+  workspace: string;
+  model: string;
+  reasoningEffort?: ReasoningEffortLevel;
+  contextLabel: string;
+}
+
+/**
+ * The MCP diff `set_mcp_servers` / `refresh_tools` answer with — the same
+ * shape `ToolRuntime.refreshTools` returns to the dispatcher today.
+ */
+export interface HostToolRefresh {
+  added: string[];
+  removed: string[];
+  errors: Record<string, string>;
+}
+
+/**
+ * What the host knows about one chat's session. `sessionId` is the SDK's
+ * resume handle; the context figures are the ones `warm_session` populates
+ * — which is why this query exists at all. In-process those numbers land
+ * in the daemon's own session store; across a process boundary they have
+ * to be asked for.
+ */
+export interface HostSessionInfo {
+  chatId: string;
+  sessionId?: string;
+  turns: number;
+  contextTokens: number;
+  contextWindow: number;
+}
+
+/** `ready`'s payload — the handshake answer, minus the envelope. */
+export interface HostReadyInfo {
+  protocol: number;
+  /** The host build's version. */
+  host: string;
+  /**
+   * The Claude Agent SDK version the host is running. Absent in-process,
+   * where there is no separately-pinned SDK to report (Phase 4 gives the
+   * host its own `package.json`).
+   */
+  sdk?: string;
+}
+
+// ── Daemon → host ───────────────────────────────────────────────────────────
+
+/**
+ * Every request the daemon can send. Each carries an `id`; the reply
+ * carries the same `id`. Turn-shaped requests (`run_turn`, `one_shot`)
+ * additionally carry a `runId`, which every streamed `event` repeats.
+ */
+export type HostRequest =
+  | {
+      type: "hello";
+      id: string;
+      protocol: number;
+      /** The daemon's version, for the host's compatibility log line. */
+      daemon: string;
+      /** The `claude-sdk` slice of `TalonConfig`, as JSON. */
+      config: Record<string, unknown>;
+    }
+  | { type: "run_turn"; id: string; runId: string; params: ChatRunParams }
+  | { type: "interrupt"; id: string; chatId: string }
+  | { type: "one_shot"; id: string; runId: string; params: HostOneShotParams }
+  | { type: "warm_session"; id: string; chatId: string }
+  | {
+      type: "set_mcp_servers";
+      id: string;
+      chatId: string;
+      /** SDK `McpServerConfig` map, opaque here — the host hands it to the SDK. */
+      servers: Record<string, unknown>;
+    }
+  | { type: "refresh_tools"; id: string; chatId: string }
+  | { type: "list_models"; id: string; filter?: "free" | "all" }
+  | { type: "plan_usage"; id: string }
+  | { type: "session_info"; id: string; chatId: string }
+  | { type: "reset_session"; id: string; chatId: string }
+  | { type: "shutdown"; id: string };
+
+// ── Host → daemon ───────────────────────────────────────────────────────────
+
+/**
+ * Every reply. `ok` is the generic ack, with one optional field per
+ * request that has something to say back; the queries get their own
+ * types so a reply is never ambiguous with the request that asked for it
+ * (`list_models` → `models`, `plan_usage` → `usage`, `session_info` →
+ * `session`).
+ */
+export type HostReply =
+  | ({ type: "ready"; id: string } & HostReadyInfo)
+  | {
+      type: "ok";
+      id: string;
+      /** `interrupt` — a running turn was found and signalled. */
+      interrupted?: boolean;
+      /** `set_mcp_servers` / `refresh_tools` — `null` when the chat has no live query. */
+      tools?: HostToolRefresh | null;
+      /** `reset_session` — host-side per-chat state was dropped. */
+      cleared?: boolean;
+    }
+  | { type: "run_done"; id: string; runId: string; usage?: OneShotUsage }
+  | { type: "error"; id: string; error: AgentError }
+  | { type: "models"; id: string; models: UnifiedModelInfo[]; total: number }
+  | { type: "usage"; id: string; usage?: PlanUsage }
+  | { type: "session"; id: string; session?: HostSessionInfo }
+  | { type: "bye"; id: string };
+
+/**
+ * One turn event. The `AgentEvent` union is unchanged and unwrapped —
+ * that is the whole point of the seam: the daemon's consumers switch on
+ * `event.type` exactly as they do against an in-process backend.
+ */
+export interface HostEvent {
+  type: "event";
+  runId: string;
+  event: AgentEvent;
+}
+
+/**
+ * Unsolicited host → daemon traffic, carrying no `id` because nothing
+ * asked for it. `log` is the host's stdout logging (stderr is tailed by
+ * the supervisor like an MCP child's); `metric` forwards the `cache.*`
+ * and turn counters the host records so the daemon's rollups are
+ * unchanged by the move.
+ */
+export type HostNotice =
+  | {
+      type: "log";
+      level: "debug" | "info" | "warn" | "error";
+      component: string;
+      msg: string;
+    }
+  | { type: "metric"; name: string; value: number };
+
+/** Anything that can appear on the wire, either direction. */
+export type HostMessage = HostRequest | HostReply | HostEvent | HostNotice;
+
+/**
+ * A line the codec could not place. Never thrown — returned, so the
+ * reader logs it and drops it. `raw` is whatever came off the wire so
+ * the log can say what was skipped.
+ */
+export interface HostUnknown {
+  type: "unknown";
+  reason: "malformed_json" | "not_an_object" | "unknown_type";
+  raw: unknown;
+}
+
+// ── The type registry the codec discriminates on ────────────────────────────
+
+/**
+ * `satisfies` rejects typos here; the `AssertNever` checks in
+ * `src/__tests__/agent-host-protocol.test.ts` fail to compile when a new
+ * member joins a union without being listed — which forces a fixture
+ * sample too, because the fixture test asserts these lists exactly.
+ */
+export const HOST_REQUEST_TYPES = [
+  "hello",
+  "run_turn",
+  "interrupt",
+  "one_shot",
+  "warm_session",
+  "set_mcp_servers",
+  "refresh_tools",
+  "list_models",
+  "plan_usage",
+  "session_info",
+  "reset_session",
+  "shutdown",
+] as const satisfies readonly HostRequest["type"][];
+
+export const HOST_REPLY_TYPES = [
+  "ready",
+  "ok",
+  "run_done",
+  "error",
+  "models",
+  "usage",
+  "session",
+  "bye",
+] as const satisfies readonly HostReply["type"][];
+
+export const HOST_NOTICE_TYPES = [
+  "log",
+  "metric",
+] as const satisfies readonly HostNotice["type"][];
+
+const KNOWN_TYPES: ReadonlySet<string> = new Set<string>([
+  ...HOST_REQUEST_TYPES,
+  ...HOST_REPLY_TYPES,
+  ...HOST_NOTICE_TYPES,
+  "event",
+]);
+
+// ── Codec ───────────────────────────────────────────────────────────────────
+
+/**
+ * Render one message as its NDJSON line — no trailing newline, so the
+ * transport owns the framing. Symmetric with `parseHostMessage`.
+ */
+export function serializeHostMessage(message: HostMessage): string {
+  return JSON.stringify(message);
+}
+
+/**
+ * Parse one NDJSON line. Total: malformed JSON, non-objects and unknown
+ * `type`s all come back as `HostUnknown` rather than throwing, because a
+ * single bad line from a newer peer must not take down the read loop.
+ *
+ * Unknown FIELDS on a known type are preserved as-is — additive evolution
+ * is the protocol's normal path, and dropping them here would silently
+ * downgrade a message the other end meant to send.
+ */
+export function parseHostMessage(line: string): HostMessage | HostUnknown {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(line);
+  } catch {
+    return { type: "unknown", reason: "malformed_json", raw: line };
+  }
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    return { type: "unknown", reason: "not_an_object", raw: parsed };
+  }
+  const type = (parsed as { type?: unknown }).type;
+  if (typeof type !== "string" || !KNOWN_TYPES.has(type)) {
+    return { type: "unknown", reason: "unknown_type", raw: parsed };
+  }
+  return parsed as HostMessage;
+}
+
+// ── The client the daemon holds ─────────────────────────────────────────────
+
+/**
+ * What the daemon calls instead of reaching into `backend/claude-sdk/`
+ * directly. One method per protocol-table row, with the signatures the
+ * claude-sdk `BackendFactory` actually uses today — no capability the
+ * backend does not have is invented here.
+ *
+ * Bound into the `Backend` object in Phase 1: `hello`, `runTurn`,
+ * `interrupt`, `runOneShot`, `warmSession`, `refreshTools`, `listModels`,
+ * `planUsage`. Defined-but-unbound: `setMcpServers` (the primitive
+ * `refreshTools` is built from), `sessionInfo` and `resetSession` (the
+ * Claude SDK backend exposes neither a `getSessionSnapshot` nor a
+ * `resetChat` slot, and Phase 1 may not change the `Backend` object), and
+ * `shutdown` (nothing to stop until there is a process).
+ */
+export interface AgentHostClient {
+  /**
+   * Handshake + initialisation. In-process this is `initAgent(config)`;
+   * across a process it is `hello` → `ready`. Must resolve before any
+   * other call — model discovery happens here.
+   */
+  hello(): Promise<HostReadyInfo>;
+
+  /**
+   * One chat turn. The returned stream is the canonical `AgentEvent`
+   * sequence, `run_started` first and `completed`/`error` last, exactly
+   * as `ChatBackend.runChatTurn` promises.
+   */
+  runTurn(params: ChatRunParams): AsyncIterable<AgentEvent>;
+
+  /** Best-effort stop of a chat's in-flight turn. `true` when one was signalled. */
+  interrupt(chatId: string): Promise<boolean>;
+
+  /**
+   * One background run (heartbeat / dream / cron). Resolves with the
+   * run's usage when the SDK reports it.
+   *
+   * Callback-shaped, not a stream: `OneShotAgentParams.appendLog` is how
+   * the background producers write their markdown logs today, and turning
+   * that into an event stream would be a behaviour change, not a seam.
+   * The design's "stream as above" row is Phase 2's problem, and the wire
+   * type (`HostOneShotParams`) already records what has to give.
+   */
+  runOneShot(params: OneShotAgentParams): Promise<OneShotUsage | void>;
+
+  /** Cold-start hint: spawn a throwaway query to prime the context figures. */
+  warmSession(chatId: string): Promise<void>;
+
+  /**
+   * Install an MCP server set on the chat's live query. `null` when the
+   * chat has no query in flight. The primitive `refreshTools` is built
+   * from; the two-phase teardown lives in the host, not the caller,
+   * because `Query` handles do not cross a process boundary.
+   */
+  setMcpServers(
+    chatId: string,
+    servers: Record<string, unknown>,
+  ): Promise<HostToolRefresh | null>;
+
+  /** Re-derive the chat's MCP config from the live plugin registry. */
+  refreshTools(chatId: string): Promise<HostToolRefresh | null>;
+
+  /**
+   * The model catalog, as the host discovered it from the SDK. The other
+   * seven `ModelCatalog` members are pure daemon-side formatting over
+   * `core/models/catalog.ts`, which `hello` populates — see
+   * `docs/agent-host-sidecar.md` Phase 1.
+   */
+  listModels(
+    filter?: "free" | "all",
+  ): Promise<{ models: UnifiedModelInfo[]; total: number }>;
+
+  /** Subscription rate-limit windows for `/status`. */
+  planUsage(): Promise<PlanUsage | undefined>;
+
+  /** What the host knows about a chat's session, including the context figures. */
+  sessionInfo(chatId: string): Promise<HostSessionInfo | undefined>;
+
+  /** Drop the host's per-chat state. `true` when there was something to drop. */
+  resetSession(chatId: string): Promise<boolean>;
+
+  /** Drain in-flight turns, then stop. A no-op while the host is in-process. */
+  shutdown(): Promise<void>;
+}

package/src/core/background/cron/scheduler.ts

@@ -34,7 +34,7 @@ import {
 } from "../../../storage/cron.js";
 import { appendDailyLog } from "../../../storage/daily-log.js";
 import { log, logError, logWarn } from "../../../util/log.js";
-import { numericChatIdFor } from "../../../util/chat-id.js";
+import { numericChatIdFor } from "../../frontend-runtime/chat-id.js";
 import { runJobOneShot } from "./job-oneshot.js";
 import {
   jobAllowsRun,

package/src/core/background/triggers/command.ts

@@ -6,7 +6,7 @@
 
 import { spawnSync } from "node:child_process";
 import type { Trigger } from "../../../storage/triggers.js";
-import { selfInvocation } from "../../../util/mcp-launcher.js";
+import { selfInvocation } from "../../mcp-hub/launcher.js";
 import { LUA_RUN_SUBCOMMAND } from "../../scripts/lua.js";
 
 export function commandForLanguage(

package/src/{util → core/config}/harden.ts

@@ -14,7 +14,7 @@
  */
 
 import { chmodSync } from "node:fs";
-import { dirs, files } from "./paths.js";
+import { dirs, files } from "../../util/paths.js";
 
 const OWNER_DIR = 0o700;
 const OWNER_FILE = 0o600;

package/src/core/config/index.ts

@@ -2,7 +2,7 @@ import { existsSync, readFileSync, mkdirSync } from "node:fs";
 import writeFileAtomic from "write-file-atomic";
 import { z } from "zod";
 import { dirs, files as pathFiles } from "../../util/paths.js";
-import { hardenTalonPermissions } from "../../util/harden.js";
+import { hardenTalonPermissions } from "./harden.js";
 import { setTimezone } from "../../util/time.js";
 import { BACKEND_IDS } from "../agent-runtime/model-ref.js";
 import { REASONING_LEVEL_ORDER } from "../models/reasoning-levels.js";

package/src/core/daemon/pidfile.ts

@@ -11,7 +11,7 @@
  *     gateway may fall back to a different port on EADDRINUSE, so the
  *     port is only known at runtime).
  *   - Removal is guarded by pid. During a `/restart` handoff
- *     (util/respawn.ts) the successor overwrites the file with its own
+ *     (./respawn.ts) the successor overwrites the file with its own
  *     pid *before* the dying parent finishes its graceful shutdown — an
  *     unconditional unlink there would orphan the new daemon, making
  *     `talon stop`/`talon restart` report "not running" and spawn

package/src/core/daemon/resource-sampler.ts

@@ -13,7 +13,7 @@
  *   - `boot.total_ms` — process start → frontends listening. The figure
  *     `Ready in …` already logs, kept as a distribution so successive
  *     restarts can be compared instead of grepped.
- *   - `boot.<phase>_ms` — each awaited startup phase (`util/boot-timer.ts`
+ *   - `boot.<phase>_ms` — each awaited startup phase (`./boot-timer.ts`
  *     records them), so a slow boot names its own culprit.
  *   - `boot.rss_mb` / `boot.heap_mb` — what the process costs the moment
  *     it is serving, before any turn has run. The floor an alternative
@@ -27,7 +27,7 @@
  * and a metric that can take the process down is worse than no metric.
  */
 
-import { bootPhases } from "../../util/boot-timer.js";
+import { bootPhases } from "./boot-timer.js";
 import { recordHistogram } from "../../storage/metrics.js";
 
 /** One minute. Idle RSS moves slowly; a tighter loop would only add noise. */

package/src/{util → core/daemon}/respawn.ts

@@ -29,7 +29,7 @@
  */
 
 import { spawn } from "node:child_process";
-import { log, logError } from "./log.js";
+import { log, logError } from "../../util/log.js";
 
 let pendingReason: string | null = null;
 

package/src/core/doctor/index.ts

@@ -423,7 +423,7 @@ export async function collectDoctorReport(opts: {
   // is which is the difference between "why didn't my prompt update?"
   // and a one-line answer.
   {
-    const { promptSeedReport } = await import("../../util/workspace.js");
+    const { promptSeedReport } = await import("../vfs/workspace.js");
     try {
       const { tracking, edited } = promptSeedReport();
       if (tracking.length + edited.length > 0) {

package/src/core/engine/gateway-actions/fetch-url.ts

@@ -18,7 +18,7 @@ import {
   isHtmlContent,
   isTextContent,
   matchesBinaryKind,
-} from "../../../util/web-content.js";
+} from "../../tools/content/web-content.js";
 import { dirs } from "../../../util/paths.js";
 import type { SharedActionHandlers } from "./types.js";
 

package/src/core/engine/gateway-actions/index.ts

@@ -43,7 +43,7 @@ import {
   whatsappAccountHandlers,
   whatsappAccountChatFreeActions,
 } from "./whatsapp-account.js";
-import { nativeHandlers } from "./native.js";
+import { nativeHandlers } from "./native/index.js";
 
 // Null-prototype so a request `action` of "toString" / "constructor" / etc.
 // can't resolve an inherited Object.prototype method — `handlers[action]` only

package/src/core/engine/gateway-actions/memory.ts

@@ -42,7 +42,7 @@ import {
   type MemorySource,
   type MemoryTrust,
 } from "../../../storage/memory.js";
-import { chatScope } from "../../../util/chat-id.js";
+import { chatScope } from "../../frontend-runtime/chat-id.js";
 import { log } from "../../../util/log.js";
 import type { ActionResult } from "../../types.js";
 import type { SharedActionHandlers } from "./types.js";
@@ -68,7 +68,7 @@ const KIND_LIST = MEMORY_KINDS.join(", ");
  * for its own principal, so that is `agent`.
  *
  * "Group" is read off the canonical chat-id grammar (`chatScope` in
- * util/chat-id.ts), which is the only identity a gateway action holds.
+ * core/frontend-runtime/chat-id.ts), which is the only identity a gateway action holds.
  * When the grammar cannot tell — Teams' `teams_chat_…` is 1:1 and group
  * alike — this fails closed to `group_chat`: over-restricting a claim
  * costs a pin, under-restricting one is a permanent prompt injection.

package/src/core/engine/gateway-actions/native/exec-background.ts

@@ -0,0 +1,129 @@
+/**
+ * `native_bash` with background:true — the detached local launch.
+ *
+ * POSIX-only by contract (own process group, `kill -- -pid` to stop, survives
+ * a daemon restart), with a short settle window so a command that dies
+ * immediately still reports like a normal foreground run.
+ */
+
+import { spawn } from "node:child_process";
+import { closeSync, openSync } from "node:fs";
+import { mkdir, readFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { renderExec, type Result } from "./results.js";
+
+/** How long a background launch waits to catch fast failures. */
+const BACKGROUND_SETTLE_MS = 1_200;
+/** Where background job output lands (one log file per job). */
+const BACKGROUND_LOG_DIR = join(tmpdir(), "talon-bash");
+
+/**
+ * Launch a command detached from the request cycle: its own process group,
+ * stdout+stderr appended to a per-job log file, tool returns immediately.
+ * This is the sanctioned path for streaming/long-running commands (adb
+ * logcat, dev servers, watchers) that would otherwise burn the whole
+ * foreground timeout and come back "killed".
+ *
+ * A short settle window catches fast failures (typo'd binary, instant
+ * non-zero exit) so those still surface as a normal error instead of a
+ * "started" message pointing at a log with one line in it.
+ */
+export async function bashBackground(
+  cmd: string,
+  cwd: string | undefined,
+): Promise<Result> {
+  // The background contract is POSIX-shaped end to end: detached process
+  // group, `kill -- -pid` to stop, survives daemon restarts. Windows has
+  // none of those (and the CI legs showed the detached writer's output not
+  // reaching the log) — refuse loudly with the native alternative instead
+  // of pretending.
+  if (process.platform === "win32") {
+    return {
+      ok: false,
+      text:
+        "background:true needs POSIX process groups and isn't supported on a Windows " +
+        "daemon host. Run it foreground with a bound command (`timeout 30 …`, `head -n 200`) " +
+        "or start it yourself: `powershell Start-Process -WindowStyle Hidden` with output redirected to a file.",
+    };
+  }
+  try {
+    await mkdir(BACKGROUND_LOG_DIR, { recursive: true });
+  } catch (err) {
+    return {
+      ok: false,
+      text: `Cannot create log dir ${BACKGROUND_LOG_DIR}: ${(err as Error).message}`,
+    };
+  }
+  const slug =
+    cmd
+      .replace(/[^a-zA-Z0-9]+/g, "-")
+      .replace(/^-+|-+$/g, "")
+      .slice(0, 40) || "job";
+  const logPath = join(BACKGROUND_LOG_DIR, `${Date.now()}-${slug}.log`);
+  let fd: number;
+  try {
+    fd = openSync(logPath, "a");
+  } catch (err) {
+    return {
+      ok: false,
+      text: `Cannot open log file ${logPath}: ${(err as Error).message}`,
+    };
+  }
+  // Always detached: the win32 guard above returned already, so this only
+  // runs on POSIX where the job gets its own process group.
+  const child = spawn("bash", ["-c", cmd], {
+    ...(cwd ? { cwd } : {}),
+    env: process.env,
+    detached: true,
+    stdio: ["ignore", fd, fd],
+  });
+  return new Promise((resolvePromise) => {
+    let settled = false;
+    const done = (r: Result) => {
+      if (settled) return;
+      settled = true;
+      try {
+        closeSync(fd);
+      } catch {
+        // parent's dup only; the child keeps its own copy either way
+      }
+      resolvePromise(r);
+    };
+    child.on("error", (err) =>
+      done({ ok: false, text: `Failed to start: ${err.message}` }),
+    );
+    // Fast failure inside the settle window → report it like a normal run.
+    child.on("close", (code) => {
+      void (async () => {
+        let logged = "";
+        try {
+          logged = await readFile(logPath, "utf8");
+        } catch {
+          // log unreadable — report the exit alone
+        }
+        done({
+          ok: (code ?? 0) === 0,
+          text:
+            `Background command exited almost immediately (exit ${code ?? 0}).\n` +
+            renderExec("local", `exit ${code ?? 0}`, logged, "") +
+            `\nFull log: ${logPath}`,
+        });
+      })();
+    });
+    setTimeout(() => {
+      if (settled) return;
+      child.unref();
+      done({
+        ok: true,
+        text: [
+          `🚀 Started in background [local] — pid ${child.pid}.`,
+          `Output (stdout+stderr) → ${logPath}`,
+          `Follow it with read/bash (e.g. \`tail -n 50 ${logPath}\`).`,
+          `Stop it with \`kill -- -${child.pid}\` (whole process group).`,
+          `Unsupervised: it keeps running until it exits or is killed — it even survives a Talon restart.`,
+        ].join("\n"),
+      });
+    }, BACKGROUND_SETTLE_MS);
+  });
+}