talon-agent 1.49.0 → 1.51.0

package/README.md

@@ -17,13 +17,14 @@ Multi-platform agentic AI harness. Runs on **Telegram**, **Discord**, **Microsof
 | **Multi-frontend**    | Telegram (Grammy + GramJS userbot), Discord (discord.js), Microsoft Teams (Bot Framework), Terminal with live tool visibility, and a **Desktop/Mobile app** (Flutter) over a local/remote bridge |
 | **Pluggable backend** | Claude Agent SDK, Kilo, OpenCode, Codex, OpenAI Agents — selectable per-process via `backend` config. Streaming, model fallback, context-overflow recovery. |
 | **MCP tools**         | Messaging, media, history, search, web fetch, cron jobs, triggers, goals, stickers, file system, admin controls                              |
-| **Plugins**           | Hot-reloadable plugin system. Built-in: GitHub, MemPalace, Playwright, Brave Search                                                          |
+| **Plugins**           | Hot-reloadable plugin system with `talon plugin install/enable/disable` (npm, git, or local sources). Built-in: GitHub, MemPalace, Playwright, Brave Search |
 | **Background agents** | Heartbeat (hourly by default — advances goals, proactively messages when something matters) and Dream (memory consolidation + diary)         |
 | **Goals**             | Persistent multi-day objectives the agent commits to in chat; every heartbeat run re-reads them, makes progress, and records what it did     |
-| **Skills**            | Agent-authored reusable scripts (bash/python/node) — procedures worked out once get saved and replayed locally at zero token cost            |
+| **Skills**            | SKILL.md workflow bundles the agent authors and reuses, with `talon skill install/enable/disable` (local folders, git, or `owner/repo` — the Anthropic skills ecosystem installs directly) |
 | **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                                        |
 
@@ -162,11 +163,38 @@ 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).
 
 ---
 
+## Managing plugins & skills
+
+Both stores are managed from the CLI; changes hot-reload into a running
+daemon (plugins) or apply on the next session (skills):
+
+```bash
+# Plugins — npm specs, git repos, or local paths
+talon plugin install @scope/my-talon-plugin        # npm → module plugin
+talon plugin install some-mcp-server --mcp         # npm → standalone MCP server (npx)
+talon plugin install owner/repo                    # git → module plugin
+talon plugin list                                  # built-ins + configured entries
+talon plugin disable github                        # also toggles built-ins
+talon plugin remove my-talon-plugin
+
+# Skills — SKILL.md folders from local paths, git URLs, or owner/repo[/subpath]
+talon skill install anthropics/skills/document-skills/pdf
+talon skill install ./my-skill --force
+talon skill list
+talon skill disable pdf                            # hidden from the prompt index, still readable
+talon skill remove pdf
+```
+
+Module plugins install under `~/.talon/plugins/`; standalone MCP servers are
+registered as `npx` entries in `config.json`. Disabling keeps the entry (or a
+`.disabled` marker in the skill folder) so enabling restores it unchanged.
+
 ## Built-in Plugins
 
 ### GitHub

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "talon-agent",
-  "version": "1.49.0",
+  "version": "1.51.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

@@ -23,6 +23,7 @@ import {
   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 {
@@ -418,6 +419,10 @@ export async function initBackendAndDispatcher(
   // 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({

package/src/cli/daemon-api.ts

@@ -13,10 +13,11 @@ export async function fetchGateway(
   port: number,
   path: string,
   init?: RequestInit,
+  timeoutMs: number = REQUEST_TIMEOUT_MS,
 ): Promise<unknown> {
   const response = await fetch(`http://127.0.0.1:${port}${path}`, {
     ...init,
-    signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+    signal: AbortSignal.timeout(timeoutMs),
   });
   if (!response.ok) throw new Error(`gateway answered ${response.status}`);
   return response.json();

package/src/cli/events.ts

@@ -2,13 +2,15 @@
  * `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. Rendering only — the bus
- * itself lives in core/bus/.
+ * 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 } from "../core/bus/index.js";
+import type { PublishedEvent, TalonEvent } from "../core/bus/index.js";
 
 const FOLLOW_POLL_MS = 1_000;
 
@@ -17,7 +19,7 @@ function timestamp(at: number): string {
 }
 
 /** One tail line of type-specific detail, content-free like the events. */
-function describe(event: PublishedEvent): string {
+function describe(event: TalonEvent): string {
   switch (event.type) {
     case "task.started":
       return (
@@ -36,12 +38,37 @@ function describe(event: PublishedEvent): string {
   }
 }
 
-function render(event: PublishedEvent): void {
+function render(event: TalonEvent, at: number): void {
   console.log(
-    `  ${pc.dim(timestamp(event.at))}  ${pc.cyan(event.type.padEnd(14))}  ${describe(event)}`,
+    `  ${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,
@@ -57,21 +84,29 @@ function sleep(ms: number): Promise<void> {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
 
-export async function showEvents(follow: boolean): Promise<void> {
+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 && !follow) {
+    if (events.length === 0 && !options.follow) {
       console.log(
-        `  ${pc.dim("No events yet — the bus ring starts empty on each daemon start.")}\n`,
+        `  ${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);
+    for (const event of events) render(event, event.at);
     cursor = events.at(-1)?.id ?? 0;
   } catch (err) {
     console.log(
@@ -80,7 +115,7 @@ export async function showEvents(follow: boolean): Promise<void> {
     return;
   }
 
-  if (!follow) {
+  if (!options.follow) {
     console.log();
     return;
   }
@@ -89,7 +124,7 @@ export async function showEvents(follow: boolean): Promise<void> {
     await sleep(FOLLOW_POLL_MS);
     try {
       const events = await fetchEvents(port, cursor);
-      for (const event of events) render(event);
+      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);
+}