talon-agent 1.48.0 → 1.50.0

package/README.md

@@ -23,6 +23,8 @@ Multi-platform agentic AI harness. Runs on **Telegram**, **Discord**, **Microsof
 | **Skills**            | Agent-authored reusable scripts (bash/python/node) — procedures worked out once get saved and replayed locally at zero token cost            |
 | **Triggers**          | Self-authored watcher scripts (bash/python/node) that wake the bot when conditions are met                                                   |
 | **Task table**        | Every unit of agent work — chat turns, heartbeat, dream, isolated cron/trigger jobs — registered live; `talon ps` / `talon kill`             |
+| **Event bus**         | Typed internal pub-sub spine (task + turn lifecycle events); subsystems subscribe instead of importing each other; `talon events -f`         |
+| **VFS**               | Unified `talon://` namespace over workspace, skills, scripts, logs, plus /proc-style live views of the task table, event bus, and plugin registry; `talon ls` / `talon cat` |
 | **Per-chat settings** | Model, effort level, and pulse toggle per conversation via inline keyboard                                                                   |
 | **Model registry**    | Models discovered from the active backend at startup — new models appear in all pickers automatically                                        |
 
@@ -161,6 +163,7 @@ The `desktop` frontend turns the daemon into a **client bridge** — a versioned
 
 - **Local (desktop):** the app connects to a Talon on the same machine and launches one if needed (`TALON_FRONTEND_OVERRIDE=desktop`).
 - **Remote (mobile/LAN):** point the app at `host:port` + token; the bridge requires `Authorization: Bearer …` (or `?token=` on the SSE stream) whenever a token is set.
+- **Encryption:** off-loopback binds serve **HTTPS by default** with a persistent self-signed certificate (`~/.talon/keys/`); the companion pins its SHA-256 fingerprint on first connect and refuses any change afterwards. The daemon logs the fingerprint at startup and `/health` advertises it. Opt out (or in, on loopback) with `"tls": false` / `true` in the `desktop` section.
 
 The app provides multi-chat history, live streaming with reasoning + tool-call visibility, per-chat model/effort/pulse/reset, and **settings sync** — read and change the daemon's own config (default model, display name, timezone, pulse/heartbeat/dream) and restart it. See [apps/companion/README.md](apps/companion/README.md).
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "talon-agent",
-  "version": "1.48.0",
+  "version": "1.50.0",
   "description": "Multi-frontend AI agent with full tool access, streaming, cron jobs, and plugin system",
   "author": "Dylan Neve",
   "license": "MIT",

package/src/backend/codex/factory.ts

@@ -10,6 +10,7 @@ import { registerBackend } from "../../core/agent-runtime/backend-registry.js";
 import type { BackendFactory } from "../../core/agent-runtime/backend-registry.js";
 import { log } from "../../util/log.js";
 import { handlerToEvents } from "../shared/handler-to-events.js";
+import { interruptChatTurn } from "../shared/turn-interrupt.js";
 import {
   composeBackend,
   type ChatBackend,
@@ -46,6 +47,7 @@ const codexFactory: BackendFactory = {
     const chat: ChatBackend = {
       runChatTurn: (params) =>
         handlerToEvents((p) => codexHandleMessage(p), params),
+      interruptChatTurn: (chatId) => interruptChatTurn(chatId),
     };
 
     const background: BackgroundRunner = {

package/src/backend/codex/handler/message.ts

@@ -40,6 +40,7 @@ import {
   recordTurnMetrics,
   recordFailedTurnAccounting,
   pushLiveUsage,
+  registerTurnInterrupt,
 } from "../../shared/index.js";
 
 import {
@@ -322,6 +323,14 @@ export async function handleMessage(
   const codexToolMetrics = { count: 0 };
   const abortController = new AbortController();
   activeAborts.set(chatId, abortController);
+  // A user interrupt is a synthetic turn terminator: marking the flag
+  // before aborting routes the close through the same clean path a
+  // model-fired end_turn takes (abort swallowed, no retry, no flow
+  // violation), settling with the partial text and real usage.
+  const unregisterInterrupt = registerTurnInterrupt(chatId, () => {
+    streamState.turnTerminated = true;
+    abortController.abort();
+  });
 
   let usage: Usage | null = null;
   let turnFailedError: string | undefined;
@@ -539,6 +548,7 @@ export async function handleMessage(
       throw outcome.classified;
     }
   } finally {
+    unregisterInterrupt();
     if (activeAborts.get(chatId) === abortController) {
       activeAborts.delete(chatId);
     }

package/src/backend/kilo/factory.ts

@@ -13,6 +13,7 @@ import { registerBackend } from "../../core/agent-runtime/backend-registry.js";
 import type { BackendFactory } from "../../core/agent-runtime/backend-registry.js";
 import { log } from "../../util/log.js";
 import { handlerToEvents } from "../shared/handler-to-events.js";
+import { interruptChatTurn } from "../shared/turn-interrupt.js";
 import {
   composeBackend,
   type ChatBackend,
@@ -47,6 +48,7 @@ const kiloFactory: BackendFactory = {
     const chat: ChatBackend = {
       runChatTurn: (params) =>
         handlerToEvents((p) => kiloHandleMessage(p), params),
+      interruptChatTurn: (chatId) => interruptChatTurn(chatId),
     };
 
     const background: BackgroundRunner = {

package/src/backend/kilo/handler/message.ts

@@ -45,6 +45,7 @@ import {
   applyRetryDecision,
   recordTurnMetrics,
   recordFailedTurnAccounting,
+  registerTurnInterrupt,
 } from "../../shared/index.js";
 import { activeSessions } from "./state.js";
 import { runKiloTurn } from "./turn.js";
@@ -119,6 +120,14 @@ export async function handleMessage(
   // into the live-turn overlay — /status updates while the turn runs.
   const state = createStreamState(chatId);
   state.newSessionId = sessionId;
+  // A user interrupt is a synthetic turn terminator: marking the flag
+  // before aborting the session routes the close through the same clean
+  // path a model-fired end_turn takes (MessageAborted swallowed as the
+  // expected close, no retry), settling with whatever the turn produced.
+  const unregisterInterrupt = registerTurnInterrupt(chatId, async () => {
+    state.turnTerminated = true;
+    await oc.session.abort({ sessionID: sessionId });
+  });
   const promptStartedAt = Date.now();
   const seenQuestionIds = new Set<string>();
   const seenToolCallIds = new Set<string>();
@@ -185,6 +194,7 @@ export async function handleMessage(
     logError("agent", `[${chatId}] Kilo error: ${outcome.classified.message}`);
     throw outcome.classified;
   } finally {
+    unregisterInterrupt();
     if (activeSessions.get(chatId) === sessionId) {
       activeSessions.delete(chatId);
     }

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

@@ -13,6 +13,7 @@ import { registerBackend } from "../../core/agent-runtime/backend-registry.js";
 import type { BackendFactory } from "../../core/agent-runtime/backend-registry.js";
 import { log } from "../../util/log.js";
 import { handlerToEvents } from "../shared/handler-to-events.js";
+import { interruptChatTurn } from "../shared/turn-interrupt.js";
 import {
   composeBackend,
   type ChatBackend,
@@ -46,6 +47,7 @@ const openAIAgentsFactory: BackendFactory = {
     const chat: ChatBackend = {
       runChatTurn: (params) =>
         handlerToEvents((p) => openAIAgentsHandleMessage(p), params),
+      interruptChatTurn: (chatId) => interruptChatTurn(chatId),
     };
 
     const defaultIdSync = (): string | null => {

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

@@ -38,6 +38,7 @@ import {
   recordTurnMetrics,
   recordFailedTurnAccounting,
   recordFlowViolation,
+  registerTurnInterrupt,
 } from "../../shared/index.js";
 import {
   detectFlowViolation,
@@ -182,6 +183,14 @@ export async function handleMessage(
   const seenToolCallIds = new Set<string>();
   const abortController = new AbortController();
   activeAborts.set(chatId, abortController);
+  // A user interrupt is a synthetic turn terminator: marking the flag
+  // before aborting routes the close through the same clean path a
+  // model-fired end_turn takes (abort swallowed, no retry, no flow
+  // violation), settling with the partial text and real usage.
+  const unregisterInterrupt = registerTurnInterrupt(chatId, () => {
+    streamState.turnTerminated = true;
+    abortController.abort();
+  });
 
   const setupMs = Date.now() - t0;
   let turnMs = 0;
@@ -385,6 +394,7 @@ export async function handleMessage(
       throw classified;
     }
   } finally {
+    unregisterInterrupt();
     if (activeAborts.get(chatId) === abortController) {
       activeAborts.delete(chatId);
     }

package/src/backend/opencode/factory.ts

@@ -13,6 +13,7 @@ import { registerBackend } from "../../core/agent-runtime/backend-registry.js";
 import type { BackendFactory } from "../../core/agent-runtime/backend-registry.js";
 import { log } from "../../util/log.js";
 import { handlerToEvents } from "../shared/handler-to-events.js";
+import { interruptChatTurn } from "../shared/turn-interrupt.js";
 import {
   composeBackend,
   type ChatBackend,
@@ -47,6 +48,7 @@ const opencodeFactory: BackendFactory = {
     const chat: ChatBackend = {
       runChatTurn: (params) =>
         handlerToEvents((p) => ocHandleMessage(p), params),
+      interruptChatTurn: (chatId) => interruptChatTurn(chatId),
     };
 
     const background: BackgroundRunner = {

package/src/backend/opencode/handler/message.ts

@@ -47,6 +47,7 @@ import {
   applyRetryDecision,
   recordTurnMetrics,
   recordFailedTurnAccounting,
+  registerTurnInterrupt,
 } from "../../shared/index.js";
 import { activeSessions } from "./state.js";
 import { runOpenCodeTurn } from "./turn.js";
@@ -122,6 +123,14 @@ export async function handleMessage(
   // into the live-turn overlay — /status updates while the turn runs.
   const state = createStreamState(chatId);
   state.newSessionId = sessionId;
+  // A user interrupt is a synthetic turn terminator: marking the flag
+  // before aborting the session routes the close through the same clean
+  // path a model-fired end_turn takes (MessageAborted swallowed as the
+  // expected close, no retry), settling with whatever the turn produced.
+  const unregisterInterrupt = registerTurnInterrupt(chatId, async () => {
+    state.turnTerminated = true;
+    await oc.session.abort({ sessionID: sessionId });
+  });
   const promptStartedAt = Date.now();
   const seenQuestionIds = new Set<string>();
   const seenToolCallIds = new Set<string>();
@@ -191,6 +200,7 @@ export async function handleMessage(
     );
     throw outcome.classified;
   } finally {
+    unregisterInterrupt();
     if (activeSessions.get(chatId) === sessionId) {
       activeSessions.delete(chatId);
     }

package/src/backend/shared/index.ts

@@ -21,6 +21,8 @@
  *     (assembly itself lives in `core/prompt/`).
  *   - `model-retry` — session-expiry / context-overflow / fallback decisions.
  *   - `stream-state` — backend-agnostic accumulator for stream loops.
+ *   - `turn-interrupt` — user-driven mid-turn interrupt registry (the
+ *     shared `ChatBackend.interruptChatTurn` for callback backends).
  *
  * What's NOT here (intentionally):
  *   - SDK-specific event types — those live in each backend.
@@ -43,6 +45,8 @@ export {
   type FlowViolationResult,
 } from "./flow-violation.js";
 
+export { registerTurnInterrupt, interruptChatTurn } from "./turn-interrupt.js";
+
 export {
   formatUserPrompt,
   formatPromptWithRetrievedMemory,

package/src/backend/shared/turn-interrupt.ts

@@ -0,0 +1,61 @@
+/**
+ * User-driven mid-turn interrupts, shared by the callback backends
+ * (Codex, OpenAI Agents, Kilo, OpenCode). The Claude SDK backend has a
+ * native `Query.interrupt()` and doesn't come through here.
+ *
+ * A handler registers how to stop its in-flight turn when the turn
+ * starts and unregisters when it settles; `interruptChatTurn` — the
+ * shared implementation of `ChatBackend.interruptChatTurn` — invokes it.
+ *
+ * The registered closure must make the turn end the way a model-fired
+ * terminator does: mark `state.turnTerminated` FIRST, then fire the
+ * native abort. Every backend's close-out logic already keys off that
+ * flag — abort errors are swallowed as the expected close, wrap-up
+ * round-trips are skipped, and the flow-violation retry (which would
+ * otherwise resurrect a killed turn as a "missed delivery") stands
+ * down. The stream then settles as a normal completion carrying the
+ * partial text and real usage — never as an error, never as a retry.
+ */
+
+import { log, logWarn } from "../../util/log.js";
+import { incrementCounter } from "../../util/metrics.js";
+
+const interrupts = new Map<string, () => void | Promise<void>>();
+
+/**
+ * Register the abort path for a chat's in-flight turn. Returns the
+ * unregister function; it only removes its own registration, so a retry
+ * that re-registered for the same chat is never torn down by the
+ * attempt that spawned it.
+ */
+export function registerTurnInterrupt(
+  chatId: string,
+  interrupt: () => void | Promise<void>,
+): () => void {
+  interrupts.set(chatId, interrupt);
+  return () => {
+    if (interrupts.get(chatId) === interrupt) interrupts.delete(chatId);
+  };
+}
+
+/**
+ * Best-effort interrupt of the chat's in-flight turn. Resolves `true`
+ * when a running turn was found and signalled, `false` otherwise —
+ * the `ChatBackend.interruptChatTurn` contract.
+ */
+export async function interruptChatTurn(chatId: string): Promise<boolean> {
+  const interrupt = interrupts.get(chatId);
+  if (!interrupt) return false;
+  try {
+    await interrupt();
+    log("agent", `[${chatId}] turn interrupted by user`);
+    incrementCounter("turn_interrupted");
+    return true;
+  } catch (err) {
+    logWarn(
+      "agent",
+      `[${chatId}] interrupt failed: ${err instanceof Error ? err.message : err}`,
+    );
+    return false;
+  }
+}

package/src/bootstrap.ts

@@ -22,6 +22,8 @@ import {
   initDispatcher,
   execute as dispatcherExecute,
 } from "./core/engine/dispatcher.js";
+import { bus } from "./core/bus/index.js";
+import { appendToJournal } from "./storage/journal.js";
 import { initPulse, resetPulseTimer } from "./core/background/pulse.js";
 import { initCron } from "./core/background/cron.js";
 import {
@@ -410,13 +412,18 @@ export async function initBackendAndDispatcher(
       resolveFrontendByNumericId(chatId, stringId, frontends).sendTyping(
         chatId,
       ),
-    onActivity: () => resetPulseTimer(),
-    // Turn-start hook: fire-and-forget dream (background memory
-    // consolidation) check. Wired here so the Weaver stays ignorant of
-    // the dream subsystem.
-    onTurnStart: maybeStartDream,
   });
 
+  // Cross-subsystem reactions ride the bus, so the Weaver stays ignorant of
+  // dream and pulse: a bound turn kicks the fire-and-forget dream check, a
+  // completed turn resets the pulse idle timer.
+  bus.subscribe("turn.started", () => maybeStartDream());
+  bus.subscribe("turn.completed", () => resetPulseTimer());
+  // The journal is the bus's durable tail: every published event lands in
+  // talon.db so history survives restarts (`talon events --history`,
+  // `talon ps --all`). Append failures are logged and swallowed inside.
+  bus.subscribeAll((event) => appendToJournal(event));
+
   initPulse();
   initCron({
     sendMessage: async (chatId: number, text: string, stringId?: string) =>

package/src/cli/daemon-api.ts

@@ -0,0 +1,39 @@
+/**
+ * Shared CLI access to the running daemon's gateway (127.0.0.1 JSON
+ * endpoints: /tasks, /events/recent, …). Discovery finds the instance the
+ * same way `talon status` does; commands render, this module only fetches.
+ */
+
+import pc from "picocolors";
+import { findRunningInstance } from "../core/daemon/discovery.js";
+
+const REQUEST_TIMEOUT_MS = 3_000;
+
+export async function fetchGateway(
+  port: number,
+  path: string,
+  init?: RequestInit,
+): Promise<unknown> {
+  const response = await fetch(`http://127.0.0.1:${port}${path}`, {
+    ...init,
+    signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+  });
+  if (!response.ok) throw new Error(`gateway answered ${response.status}`);
+  return response.json();
+}
+
+/** Find the daemon and return its gateway port, or render why not. */
+export async function requireGatewayPort(): Promise<number | null> {
+  const instance = await findRunningInstance();
+  if (!instance) {
+    console.log(`  ${pc.red("●")} Talon is not running\n`);
+    return null;
+  }
+  if (!instance.port) {
+    console.log(
+      `  ${pc.yellow("●")} Talon is running (PID ${instance.pid}) but its gateway port is unknown — possibly still starting.\n`,
+    );
+    return null;
+  }
+  return instance.port;
+}

package/src/cli/events.ts

@@ -0,0 +1,133 @@
+/**
+ * `talon events` — tail the daemon's event bus.
+ *
+ * Renders the gateway's `/events/recent` ring; `--follow` (`-f`) keeps
+ * polling with a since-cursor for a live tail; `--history [N]` reads the
+ * durable journal in talon.db instead (works across restarts, daemon up
+ * or down). Rendering only — the bus lives in core/bus/, the journal in
+ * storage/journal.ts.
+ */
+
+import pc from "picocolors";
+import { fetchGateway, requireGatewayPort } from "./daemon-api.js";
+import type { PublishedEvent, TalonEvent } from "../core/bus/index.js";
+
+const FOLLOW_POLL_MS = 1_000;
+
+function timestamp(at: number): string {
+  return new Date(at).toTimeString().slice(0, 8);
+}
+
+/** One tail line of type-specific detail, content-free like the events. */
+function describe(event: TalonEvent): string {
+  switch (event.type) {
+    case "task.started":
+      return (
+        `#${event.task.id} ${event.task.kind} "${event.task.label}"` +
+        (event.task.chatId ? ` chat=${event.task.chatId}` : "")
+      );
+    case "task.settled":
+      return (
+        `#${event.task.id} ${event.task.kind} "${event.task.label}" → ${event.task.state}` +
+        (event.task.error ? ` (${event.task.error})` : "")
+      );
+    case "turn.started":
+      return `chat=${event.chatId} ${event.backendId}/${event.model} (${event.source})`;
+    case "turn.completed":
+      return `chat=${event.chatId} ${event.durationMs}ms in=${event.inputTokens} out=${event.outputTokens}`;
+  }
+}
+
+function render(event: TalonEvent, at: number): void {
+  console.log(
+    `  ${pc.dim(timestamp(at))}  ${pc.cyan(event.type.padEnd(14))}  ${describe(event)}`,
+  );
+}
+
+/**
+ * The journal path: read the durable tail from talon.db directly — no
+ * daemon required, and it answers across restarts (unlike the ring).
+ */
+async function showHistory(limit: number): Promise<void> {
+  const { readJournal } = await import("../storage/journal.js");
+  let entries;
+  try {
+    entries = readJournal({ limit });
+  } catch (err) {
+    console.log(
+      `  ${pc.red("✖")} Could not read the journal: ${err instanceof Error ? err.message : err}\n`,
+    );
+    process.exitCode = 1;
+    return;
+  }
+  if (entries.length === 0) {
+    console.log(`  ${pc.dim("Journal is empty — no events recorded yet.")}\n`);
+    return;
+  }
+  // readJournal returns newest-first; a tail reads oldest-to-newest.
+  for (const entry of entries.reverse()) render(entry.event, entry.at);
+  console.log();
+}
+
+async function fetchEvents(
+  port: number,
+  sinceId: number,
+): Promise<PublishedEvent[]> {
+  const body = (await fetchGateway(
+    port,
+    `/events/recent?since=${sinceId}`,
+  )) as { events?: PublishedEvent[] };
+  return body.events ?? [];
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+export async function showEvents(options: {
+  follow: boolean;
+  history?: number;
+}): Promise<void> {
+  console.log();
+  if (options.history !== undefined) {
+    await showHistory(options.history);
+    return;
+  }
+
+  const port = await requireGatewayPort();
+  if (port === null) return;
+
+  let cursor = 0;
+  try {
+    const events = await fetchEvents(port, cursor);
+    if (events.length === 0 && !options.follow) {
+      console.log(
+        `  ${pc.dim("No events yet — the ring starts empty on each daemon start. Older events: talon events --history")}\n`,
+      );
+      return;
+    }
+    for (const event of events) render(event, event.at);
+    cursor = events.at(-1)?.id ?? 0;
+  } catch (err) {
+    console.log(
+      `  ${pc.red("✖")} Could not read the event bus: ${err instanceof Error ? err.message : err}\n`,
+    );
+    return;
+  }
+
+  if (!options.follow) {
+    console.log();
+    return;
+  }
+  console.log(`  ${pc.dim("Following — Ctrl+C to stop.")}`);
+  for (;;) {
+    await sleep(FOLLOW_POLL_MS);
+    try {
+      const events = await fetchEvents(port, cursor);
+      for (const event of events) render(event, event.at);
+      if (events.length > 0) cursor = events.at(-1)!.id;
+    } catch {
+      // Transient gateway hiccup (restart mid-follow) — keep polling.
+    }
+  }
+}

package/src/cli/fs.ts

@@ -0,0 +1,138 @@
+/**
+ * `talon ls` / `talon cat` — the talon:// namespace from the outside.
+ *
+ * A running daemon answers through the gateway (`GET /vfs/list|read`) so
+ * the synthetic mounts (proc, plugins) show live state. With no daemon,
+ * the same namespace is served in-process — file mounts work identically,
+ * the synthetic mounts are simply empty — so browsing the workspace never
+ * requires Talon to be up.
+ */
+
+import pc from "picocolors";
+import { findRunningInstance } from "../core/daemon/discovery.js";
+import type { VfsErrorCode, VfsResult, VfsStat } from "../core/vfs/index.js";
+import { fetchGateway } from "./daemon-api.js";
+
+/**
+ * Ask the daemon first (live proc/plugins state), fall back to serving the
+ * namespace in-process. `live` records which one answered.
+ */
+async function query(
+  op: "list" | "read",
+  path: string,
+): Promise<{ result: VfsResult<VfsStat[] | string>; live: boolean }> {
+  const instance = await findRunningInstance();
+  if (instance?.port) {
+    const body = (await fetchGateway(
+      instance.port,
+      `/vfs/${op}?path=${encodeURIComponent(path)}`,
+    )) as {
+      ok: boolean;
+      entries?: VfsStat[];
+      content?: string;
+      error?: string;
+      detail?: string;
+    };
+    const result: VfsResult<VfsStat[] | string> = body.ok
+      ? { ok: true, value: op === "list" ? body.entries! : body.content! }
+      : {
+          ok: false,
+          error: (body.error ?? "io-error") as VfsErrorCode,
+          ...(body.detail !== undefined ? { detail: body.detail } : {}),
+        };
+    return { result, live: true };
+  }
+
+  const { getVfs } = await import("../core/vfs/index.js");
+  const vfs = getVfs();
+  return {
+    result: op === "list" ? vfs.list(path) : vfs.read(path),
+    live: false,
+  };
+}
+
+function printError(
+  path: string,
+  result: { error: string; detail?: string },
+): void {
+  console.error(
+    `  ${pc.red("✖")} talon://${path}: ${result.error}${result.detail ? ` — ${result.detail}` : ""}`,
+  );
+  process.exitCode = 1;
+}
+
+function formatModified(entry: VfsStat): string {
+  if (entry.modifiedAt === undefined) return "-";
+  return new Date(entry.modifiedAt)
+    .toISOString()
+    .slice(0, 16)
+    .replace("T", " ");
+}
+
+export async function showLs(rawPath: string | undefined): Promise<void> {
+  const path = (rawPath ?? "").trim();
+  console.log();
+  const { result, live } = await query("list", path);
+  if (!result.ok) {
+    printError(path, result);
+    return;
+  }
+  const entries = result.value as VfsStat[];
+
+  if (!live) {
+    console.log(
+      `  ${pc.dim("Talon is not running — file mounts only; proc/ and plugins/ are empty.")}`,
+    );
+  }
+  if (entries.length === 0) {
+    console.log(`  ${pc.dim("(empty)")}\n`);
+    return;
+  }
+
+  const header = ["KIND", "SIZE", "MODIFIED", "NAME"];
+  const cells = entries.map((entry) => [
+    entry.kind === "dir" ? "dir" : "file",
+    entry.kind === "dir" ? "-" : String(entry.size ?? "?"),
+    formatModified(entry),
+    entry.kind === "dir" ? `${entry.name}/` : entry.name,
+  ]);
+  const widths = header.map((h, col) =>
+    Math.max(h.length, ...cells.map((row) => row[col]!.length)),
+  );
+  console.log(
+    `  ${pc.dim(header.map((h, col) => h.padEnd(widths[col]!)).join("  "))}`,
+  );
+  cells.forEach((row, i) => {
+    const padded = row.map((cell, col) => cell.padEnd(widths[col]!));
+    const name = entries[i]!.kind === "dir" ? pc.cyan(padded[3]!) : padded[3]!;
+    // Root entries carry the mount's disk location — show the mapping, it's
+    // what shell commands (which can't read talon://) need.
+    const entry = entries[i]!;
+    const mapping =
+      entry.osPath !== undefined && !entry.path.includes("/")
+        ? pc.dim(`  → ${entry.osPath}`)
+        : "";
+    console.log(
+      `  ${padded[0]}  ${padded[1]}  ${padded[2]}  ${name}${mapping}`,
+    );
+  });
+  console.log();
+}
+
+export async function showCat(rawPath: string | undefined): Promise<void> {
+  if (!rawPath || !rawPath.trim()) {
+    console.error(
+      `  ${pc.red("✖")} Usage: ${pc.cyan("talon cat <path>")} — e.g. ${pc.cyan("talon cat proc/events")}`,
+    );
+    process.exitCode = 1;
+    return;
+  }
+  const path = rawPath.trim();
+  const { result } = await query("read", path);
+  if (!result.ok) {
+    printError(path, result);
+    return;
+  }
+  // Raw content, no decoration — `talon cat x | jq` must work.
+  process.stdout.write(result.value as string);
+}