talon-agent 2.0.1 → 3.0.0

package/README.md

@@ -24,7 +24,7 @@ Multi-platform agentic AI harness. Runs on **Telegram**, **Discord**, **Microsof
 | **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 — a real filesystem at `~/.talon/ns` (FUSE-backed live views), so plain `ls`/`cat` and every tool just work |
+| **VFS**               | Unified namespace at `~/.talon/ns` over workspace, skills, scripts, logs, plus /proc-style live views of the task table, event bus, and plugin registry — a real filesystem (FUSE-backed live views), so plain `ls`/`cat` and every tool just work |
 | **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                                        |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "talon-agent",
-  "version": "2.0.1",
+  "version": "3.0.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/handler/message.ts

@@ -388,37 +388,27 @@ export async function handleMessage(
 
   // Final authoritative usage settlement — shared by the success post-loop
   // and the terminal-failure path so failed turns account for the tokens
-  // they burned too. Codex's `turn.completed.usage` is CUMULATIVE, so we
-  // read the per-call `token_count` event from the rollout JSONL for an
-  // accurate /status display, falling back silently when unavailable.
+  // they burned too. Codex's `turn.completed.usage` is CUMULATIVE across
+  // every API call in the turn — never in the per-turn units the shared
+  // stream state (and everything downstream: /status, the companion's
+  // per-message counts) speaks. The rollout JSONL's totals diffed against
+  // the pre-turn baseline are this turn's real usage; that is the ONLY
+  // authoritative source. The SDK figure is a last-resort fallback when
+  // the rollout can't be read, and it overstates multi-call turns.
   const settleUsageAccounting = async (): Promise<void> => {
-    if (usage) {
-      recordTokens(streamState, {
-        inputTokens: usage.input_tokens,
-        outputTokens: usage.output_tokens,
-        cacheRead: usage.cached_input_tokens,
-        cacheWrite: 0, // Codex doesn't report cache writes
-      });
-    }
-    if (!resolvedThreadId) return;
-    const last = await readLastRolloutSnapshot(resolvedThreadId).catch(
-      () => null,
-    );
-    if (!last) return;
-    if (last.usage) {
+    const last = resolvedThreadId
+      ? await readLastRolloutSnapshot(resolvedThreadId).catch(() => null)
+      : null;
+    if (last?.usage) {
       streamState.contextTokens = last.usage.contextTokens;
       if (last.usage.contextWindow) {
         streamState.contextWindow = last.usage.contextWindow;
       }
     }
-    if (typeof last.numApiCalls === "number") {
+    if (typeof last?.numApiCalls === "number") {
       streamState.numApiCalls = last.numApiCalls;
     }
-    // Terminator-driven turns abort the stream before `turn.completed`
-    // fires, so the SDK-side `usage` capture above is null on almost
-    // every Talon turn. Recover this turn's real usage by diffing the
-    // rollout's cumulative totals against the pre-turn baseline.
-    if (!usage && last.totals && baselineTotals) {
+    if (last?.totals && baselineTotals) {
       recordTokens(streamState, {
         inputTokens: last.totals.inputTokens - baselineTotals.inputTokens,
         outputTokens: last.totals.outputTokens - baselineTotals.outputTokens,
@@ -426,6 +416,13 @@ export async function handleMessage(
           last.totals.cachedInputTokens - baselineTotals.cachedInputTokens,
         cacheWrite: 0, // Codex doesn't report cache writes
       });
+    } else if (usage) {
+      recordTokens(streamState, {
+        inputTokens: usage.input_tokens,
+        outputTokens: usage.output_tokens,
+        cacheRead: usage.cached_input_tokens,
+        cacheWrite: 0, // Codex doesn't report cache writes
+      });
     }
   };
 

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

@@ -33,12 +33,6 @@ import {
   setTeleport,
   setTeleportCwd,
 } from "../../mesh/teleport.js";
-import {
-  getVfs,
-  isNamespaceFsMounted,
-  resolveNamespacePath,
-  rewriteNamespaceRefs,
-} from "../../vfs/index.js";
 import {
   clampExecOutput,
   createOutputCapture,
@@ -169,39 +163,13 @@ async function bash(
   timeoutSec: unknown,
   background?: unknown,
 ): Promise<Result> {
-  let cmd = typeof command === "string" ? command : "";
+  const cmd = typeof command === "string" ? command : "";
   if (!cmd.trim()) return { ok: false, text: "No command given." };
   const timeoutMs = clampTimeout(timeoutSec);
   const active = await getTeleport(chatId);
 
-  // talon:// references in the command translate to real paths before the
-  // shell ever sees them — teleported they can't (wrong address space).
-  let mappings: string[] = [];
-  if (cmd.includes("talon:") && !active) {
-    const rewritten = rewriteNamespaceRefs(
-      cmd,
-      getVfs(),
-      isNamespaceFsMounted(),
-    );
-    if (!rewritten.ok) return { ok: false, text: rewritten.error };
-    cmd = rewritten.command;
-    mappings = rewritten.mappings;
-  }
-  if (cmd.includes(NAMESPACE_SCHEME) && active) {
-    return {
-      ok: false,
-      text:
-        `talon:// names the daemon's namespace, but native tools are ` +
-        `teleported onto ${active.deviceName} — teleport_back first, or use a device path.`,
-    };
-  }
-
   let dir = typeof cwd === "string" && cwd.trim() ? cwd.trim() : undefined;
-  if (dir !== undefined && !active) {
-    const resolved = resolvePathParam(dir, undefined);
-    if ("error" in resolved) return { ok: false, text: resolved.error };
-    dir = resolved.path;
-  }
+  if (dir !== undefined && !active) dir = resolvePathParam(dir, undefined);
 
   const result = await (async () => {
     if (background === true) {
@@ -219,10 +187,6 @@ async function bash(
     if (active) return bashTeleported(chatId, active.deviceId, cmd, timeoutMs);
     return bashLocal(cmd, dir, timeoutMs);
   })();
-  // Surface the translation so it's visible, never silent.
-  if (mappings.length > 0) {
-    return { ...result, text: `↪ ${mappings.join("  ")}\n${result.text}` };
-  }
   return result;
 }
 
@@ -490,38 +454,7 @@ async function bashTeleported(
   };
 }
 
-// ── talon:// address resolution ─────────────────────────────────────────────
-
-const NAMESPACE_SCHEME = "talon://";
-
-/**
- * talon:// addresses translate to real host paths (core/vfs/rewrite.ts)
- * and then flow through the exact same fs code as any other path — no
- * virtual nodes, no special branches. With the FUSE layer mounted even
- * proc/ and plugins/ are ordinary files; without it they are refused at
- * resolution. Teleport can't cross address spaces: talon:// names
- * daemon state, and a teleported chat's paths belong to the device, so
- * the combination is refused rather than resolved against the wrong
- * filesystem.
- */
-function resolveAddress(
-  address: string,
-  teleportedTo: string | undefined,
-): { path: string } | { error: string } {
-  if (teleportedTo !== undefined) {
-    return {
-      error:
-        `${address} names the daemon's namespace, but native tools are ` +
-        `teleported onto ${teleportedTo} — teleport_back first, or use a device path.`,
-    };
-  }
-  const resolved = resolveNamespacePath(
-    address,
-    getVfs(),
-    isNamespaceFsMounted(),
-  );
-  return resolved.ok ? { path: resolved.path } : { error: resolved.error };
-}
+// ── path parameter resolution ───────────────────────────────────────────────
 
 /** Expand a leading `~` — local runs only; a device's home is not ours. */
 function expandHome(path: string): string {
@@ -531,26 +464,21 @@ function expandHome(path: string): string {
 }
 
 /**
- * One rule for every path parameter: talon:// translates, `~` expands
- * (locally), everything else passes through untouched.
+ * One rule for every path parameter: `~` expands (local runs only),
+ * everything else passes through untouched.
+ *
+ * The namespace has no tool-facing address scheme — its nodes are reached
+ * by their real paths (`~/.talon/ns/…`, kept real by the symlink farm in
+ * nsdir.ts and the FUSE layer in fusefs.ts). Real paths need no
+ * translation and behave identically here, in a bare shell, in another
+ * backend's built-in shell (Codex), and in any spawned child process.
+ * Teleported, paths belong to the device and pass through verbatim.
  */
 function resolvePathParam(
   path: string,
   teleportedTo: string | undefined,
-): { path: string } | { error: string } {
-  if (path.startsWith(NAMESPACE_SCHEME)) {
-    return resolveAddress(path, teleportedTo);
-  }
-  return { path: teleportedTo !== undefined ? path : expandHome(path) };
-}
-
-/** glob/search root — same rule, defaulting to the working directory. */
-function resolveSearchRoot(
-  path: string | undefined,
-  teleportedTo: string | undefined,
-): { root: string } | { error: string } {
-  const resolved = resolvePathParam(path ?? ".", teleportedTo);
-  return "error" in resolved ? resolved : { root: resolved.path };
+): string {
+  return teleportedTo !== undefined ? path : expandHome(path);
 }
 
 // ── read / write / edit ─────────────────────────────────────────────────────
@@ -566,9 +494,7 @@ async function read(
   const active = await getTeleport(chatId);
   const where = active ? active.deviceName : "local";
 
-  const resolved = resolvePathParam(address, active?.deviceName);
-  if ("error" in resolved) return { ok: false, text: resolved.error };
-  const p = resolved.path;
+  const p = resolvePathParam(address, active?.deviceName);
   const shown = p === address ? p : `${address} → ${p}`;
 
   // Image files: return a viewable image block, not the raw bytes decoded as
@@ -648,9 +574,7 @@ async function write(
   if (!address) return { ok: false, text: "A file path is required." };
   const body = typeof content === "string" ? content : "";
   const active = await getTeleport(chatId);
-  const resolved = resolvePathParam(address, active?.deviceName);
-  if ("error" in resolved) return { ok: false, text: resolved.error };
-  const p = resolved.path;
+  const p = resolvePathParam(address, active?.deviceName);
   const shown = p === address ? p : `${address} → ${p}`;
   if (active) {
     return getMeshService().writeFileToDevice(active.deviceId, p, body);
@@ -681,9 +605,7 @@ async function edit(
   if (from === to)
     return { ok: false, text: "old_string and new_string are identical." };
   const active = await getTeleport(chatId);
-  const resolved = resolvePathParam(address, active?.deviceName);
-  if ("error" in resolved) return { ok: false, text: resolved.error };
-  const p = resolved.path;
+  const p = resolvePathParam(address, active?.deviceName);
   const shown = p === address ? p : `${address} → ${p}`;
   const svc = getMeshService();
 
@@ -754,9 +676,7 @@ async function glob(
   const pat = str(pattern);
   if (!pat) return { ok: false, text: "A glob pattern is required." };
   const active = await getTeleport(chatId);
-  const rooted = resolveSearchRoot(str(path), active?.deviceName);
-  if ("error" in rooted) return { ok: false, text: rooted.error };
-  const root = rooted.root;
+  const root = resolvePathParam(str(path) ?? ".", active?.deviceName);
   if (active) {
     // Prefer rg on the device; fall back to find (basename patterns via
     // -name, path patterns via -path). `command -v` gates the choice so a
@@ -803,9 +723,7 @@ async function search(
   const pat = str(pattern);
   if (!pat) return { ok: false, text: "A search pattern is required." };
   const active = await getTeleport(chatId);
-  const rooted = resolveSearchRoot(str(path), active?.deviceName);
-  if ("error" in rooted) return { ok: false, text: rooted.error };
-  const root = rooted.root;
+  const root = resolvePathParam(str(path) ?? ".", active?.deviceName);
   const g = str(globPat);
   const ci = caseInsensitive === true;
   // `-e` keeps a pattern that starts with "-" from being parsed as a flag

package/src/core/tools/native.ts

@@ -10,16 +10,18 @@ import type { ToolDefinition } from "./types.js";
  * Their extra power over the built-ins: every one honours the active
  * `teleport` target, so with a teleport engaged they run ON a companion
  * device (via the mesh exec/fs channel) instead of on the daemon host.
- * And every one speaks talon:// — Talon's own namespace, which is a real
- * filesystem location, so addresses translate to legitimate paths.
+ * Talon's namespace (~/.talon/ns) is a real filesystem location — its
+ * files are reached by their ordinary real paths, with no address scheme
+ * to translate, so the same path works here, in a bare shell, and in any
+ * spawned process.
  */
 
 /** One shared description of the namespace, stated once. */
 const NAMESPACE_DOC =
-  "talon:// is Talon's namespace, on disk at ~/.talon/ns: home/ (the workspace), " +
-  "skills/, scripts/, logs/, and — while the FUSE layer is mounted — the live views " +
-  "proc/ (task table at proc/tasks/<id>, event ring at proc/events, both JSON) and " +
-  "plugins/ (registry).";
+  "Talon's namespace lives on disk at ~/.talon/ns — home/ (the workspace), skills/, " +
+  "scripts/, logs/, and, while the FUSE layer is mounted, the live views proc/ (task " +
+  "table at proc/tasks/<id>, event ring at proc/events, both JSON) and plugins/ " +
+  "(registry). These are real paths: address them directly as ~/.talon/ns/<mount>/….";
 export const nativeTools: ToolDefinition[] = [
   {
     name: "teleport",
@@ -49,14 +51,14 @@ export const nativeTools: ToolDefinition[] = [
     description:
       "Run a shell command. Runs on the daemon host, or ON the active teleport device if one is engaged. On a teleported device, `cd` persists across calls (a real working-directory session). " +
       "Foreground runs are killed at timeout_sec — for streaming/never-ending commands (adb logcat, tail -f, dev servers, watchers) set background:true instead: the command is launched detached in its own process group with stdout+stderr captured to a log file, and the tool returns immediately with the pid + log path so you can poll the log and kill it when done. " +
-      `${NAMESPACE_DOC} talon:// references in the command are translated to real paths before the shell runs (local only), so \`ls talon://home\` or \`cat talon://proc/events | jq\` just work.`,
+      `${NAMESPACE_DOC} Reach them by real path, e.g. \`ls ~/.talon/ns/home\` or \`cat ~/.talon/ns/proc/events | jq\` (proc/ and plugins/ need the FUSE layer mounted).`,
     schema: {
       command: z.string().describe("The shell command to run."),
       cwd: z
         .string()
         .optional()
         .describe(
-          "Working directory (local runs only; teleport tracks its own cwd). talon:// accepted.",
+          "Working directory (local runs only; teleport tracks its own cwd). A real path, e.g. ~/.talon/ns/home.",
         ),
       timeout_sec: z
         .number()
@@ -81,7 +83,7 @@ export const nativeTools: ToolDefinition[] = [
       path: z
         .string()
         .describe(
-          "Absolute file path, ~ path, or a talon:// address (translated on the daemon host).",
+          "Absolute file path or ~ path (namespace files live under ~/.talon/ns, e.g. ~/.talon/ns/home/notes.md).",
         ),
       offset: z.number().optional().describe("0-based line to start from."),
       limit: z
@@ -95,12 +97,12 @@ export const nativeTools: ToolDefinition[] = [
   {
     name: "write",
     description:
-      "Write (create/overwrite) a file with the given content. Runs on the daemon host or the active teleport device. Writable talon:// mounts: home/, skills/, scripts/ (live views are read-only).",
+      "Write (create/overwrite) a file with the given content. Runs on the daemon host or the active teleport device. Under ~/.talon/ns the writable mounts are home/, skills/, scripts/ (logs/, proc/, plugins/ are read-only).",
     schema: {
       path: z
         .string()
         .describe(
-          "Absolute file path, ~ path, or a talon:// address (translated on the daemon host).",
+          "Absolute file path or ~ path (namespace files live under ~/.talon/ns, e.g. ~/.talon/ns/home/notes.md).",
         ),
       content: z.string().describe("Full file content to write."),
     },
@@ -115,7 +117,7 @@ export const nativeTools: ToolDefinition[] = [
       path: z
         .string()
         .describe(
-          "Absolute file path, ~ path, or a talon:// address (translated on the daemon host).",
+          "Absolute file path or ~ path (namespace files live under ~/.talon/ns, e.g. ~/.talon/ns/home/notes.md).",
         ),
       old_string: z.string().describe("Exact text to replace."),
       new_string: z.string().describe("Replacement text."),
@@ -136,7 +138,9 @@ export const nativeTools: ToolDefinition[] = [
       path: z
         .string()
         .optional()
-        .describe("Root directory to search (default cwd; talon:// accepted)."),
+        .describe(
+          "Root directory to search (default cwd; a real path e.g. ~/.talon/ns/home).",
+        ),
     },
     execute: (params, bridge) => bridge("native_glob", params),
     tag: "native",
@@ -150,7 +154,9 @@ export const nativeTools: ToolDefinition[] = [
       path: z
         .string()
         .optional()
-        .describe("Root directory or file (default cwd; talon:// accepted)."),
+        .describe(
+          "Root directory or file (default cwd; a real path e.g. ~/.talon/ns/home).",
+        ),
       glob: z
         .string()
         .optional()

package/src/core/vfs/index.ts

@@ -18,8 +18,11 @@
  * The namespace IS the filesystem: it lives at ~/.talon/ns (symlink
  * farm via nsdir.ts, live synthetic mounts via fusefs.ts when FUSE is
  * available), and every consumer — native tools, shell commands, the
- * user's own terminal — reaches it through real paths. Address
- * translation for tools lives in rewrite.ts.
+ * user's own terminal, other backends' shells (Codex), spawned
+ * processes — reaches it through the same real paths. There is no
+ * tool-facing address scheme to translate: `~/.talon/ns/home/…` is the
+ * address. (`talon://` survives only as the VFS's internal mount
+ * grammar in vfs.ts / fusefs.ts; consumers never see it.)
  */
 
 import { dirs } from "../../util/paths.js";
@@ -36,12 +39,6 @@ export { createFileMount } from "./mounts/files.js";
 export { createProcMount, type ProcMountDeps } from "./mounts/proc.js";
 export { createPluginsMount, type PluginView } from "./mounts/plugins.js";
 export { syncNamespaceDir, type NsDirSync } from "./nsdir.js";
-export {
-  resolveNamespacePath,
-  rewriteNamespaceRefs,
-  type CommandRewrite,
-  type PathResolution,
-} from "./rewrite.js";
 export {
   isNamespaceFsMounted,
   mountNamespaceFs,

package/src/core/vfs/types.ts

@@ -86,10 +86,10 @@ export interface VfsMount {
   /** Can write() ever succeed here? Synthetic views say false. */
   readonly writable: boolean;
   /**
-   * Absolute disk root, for file-backed mounts. The single fact that makes
-   * addresses bidirectional: the resolver routes OS-absolute addresses into
-   * the mount by containment, and `Vfs.locate` maps namespace addresses
-   * back to disk. Synthetic mounts omit it.
+   * Absolute disk root, for file-backed mounts. The resolver routes
+   * OS-absolute addresses into the mount by containment, and the symlink
+   * farm / FUSE layer expose the mount at its real path on disk.
+   * Synthetic mounts omit it.
    */
   readonly osRoot?: string;
   stat(rel: string): VfsResult<VfsStat>;

package/src/core/vfs/vfs.ts

@@ -102,29 +102,10 @@ export class Vfs {
     return result.ok ? vfsOk(withPrefix(result.value, prefix)) : result;
   }
 
-  /**
-   * Where an address lives on disk: the absolute path for nodes of
-   * file-backed mounts (whether or not the node exists yet), `undefined`
-   * for addresses with no disk representation (the root, synthetic
-   * mounts). This is the namespace→OS direction of the address grammar —
-   * OS-level tools call it to run real file operations on a talon://
-   * address.
-   */
-  locate(path: string): VfsResult<string | undefined> {
-    const parsed = this.#parse(path);
-    if (!parsed.ok) return parsed;
-    if (parsed.value === null) return vfsOk(undefined);
-    const { mount, rel } = parsed.value;
-    if (mount.osRoot === undefined) return vfsOk(undefined);
-    return vfsOk(
-      rel === "" ? mount.osRoot : resolve(mount.osRoot, ...rel.split("/")),
-    );
-  }
-
   /**
    * The mount table as data: name, description, writability, and — for
    * file-backed mounts — the disk root. Consumed by the namespace dir
-   * builder (symlink farm), the command rewriter, and docs/tool output.
+   * builder (symlink farm), the FUSE layer, and docs/tool output.
    */
   describeMounts(): {
     name: string;

package/src/core/vfs/rewrite.ts

@@ -1,170 +0,0 @@
-/**
- * talon:// → real path translation — the seam that makes the namespace
- * seamless for OS-level tools.
- *
- * Because the namespace exists on disk (~/.talon/ns/, see nsdir.ts and
- * fusefs.ts), translating an address is pure prefix substitution — no
- * tokenizing, no quoting rules, correct anywhere in a command string:
- *
- *   FUSE mounted   talon://           →  ~/.talon/ns/           (total)
- *   fuseless       talon://home/x     →  <workspace>/x          (per mount)
- *                  talon://           →  ~/.talon/ns            (symlink farm)
- *                  talon://proc/x     →  refused — live views exist only
- *                                        while the FUSE layer is mounted
- *
- * Two consumers: `resolveNamespacePath` for a single address parameter
- * (read/write/edit/glob/search), `rewriteNamespaceRefs` for a whole
- * shell command (bash). Both return real host paths that ordinary fs
- * code and child processes use with no further special-casing.
- */
-
-import { dirs } from "../../util/paths.js";
-import type { Vfs } from "./vfs.js";
-
-const SCHEME = "talon://";
-
-/** Chars that can continue a mount name — used as a replace boundary. */
-const MOUNT_NAME = /^[a-z0-9-]+/;
-
-export type PathResolution =
-  { ok: true; path: string } | { ok: false; error: string };
-
-export type CommandRewrite =
-  | { ok: true; command: string; mappings: string[] }
-  | { ok: false; error: string };
-
-function lockedError(name: string): string {
-  return (
-    `talon://${name} is a live view that only exists while the FUSE layer is ` +
-    `mounted, and it isn't mounted on this host (config \`fuse: "off"\`, ` +
-    `missing talon-fusefs addon, or no FUSE support). File-backed mounts ` +
-    `under ${dirs.ns} keep working.`
-  );
-}
-
-function unknownMountError(name: string, vfs: Vfs): string {
-  const mounts = vfs
-    .describeMounts()
-    .map((mount) => mount.name)
-    .join(", ");
-  return `No mount "${name}" in the talon:// namespace — mounts: ${mounts}`;
-}
-
-function isSynthetic(name: string, vfs: Vfs): boolean {
-  return vfs
-    .describeMounts()
-    .some((mount) => mount.name === name && mount.osRoot === undefined);
-}
-
-/**
- * Resolve one talon:// address to the real host path it names. The
- * caller has already checked the scheme prefix. With FUSE mounted every
- * address maps into the mountpoint; fuseless, file-backed mounts map to
- * their disk roots and live views are refused (they don't exist).
- */
-export function resolveNamespacePath(
-  address: string,
-  vfs: Vfs,
-  fuseMounted: boolean,
-  nsRoot: string = dirs.ns,
-): PathResolution {
-  const rest = address.slice(SCHEME.length).replace(/^\/+/, "");
-  if (rest === "") return { ok: true, path: nsRoot };
-  if (fuseMounted) return { ok: true, path: `${nsRoot}/${rest}` };
-
-  const name = MOUNT_NAME.exec(rest)?.[0] ?? "";
-  if (isSynthetic(name, vfs)) return { ok: false, error: lockedError(name) };
-
-  const located = vfs.locate(address);
-  if (!located.ok) {
-    return {
-      ok: false,
-      error: `Cannot resolve ${address}: ${located.error}${located.detail ? ` — ${located.detail}` : ""}`,
-    };
-  }
-  if (located.value === undefined) {
-    // A mount the table knows but has no disk root and isn't flagged
-    // synthetic can't exist; treat as locked for the same honest reason.
-    return { ok: false, error: lockedError(name) };
-  }
-  return { ok: true, path: located.value };
-}
-
-/**
- * Translate every talon:// reference in a shell command to its real
- * path, so `ls talon://home | head` runs untouched by any namespace
- * plumbing. Returns the applied mappings for the tool result, so the
- * translation is visible rather than silent.
- */
-export function rewriteNamespaceRefs(
-  command: string,
-  vfs: Vfs,
-  fuseMounted: boolean,
-  nsRoot: string = dirs.ns,
-): CommandRewrite {
-  if (!command.includes("talon:")) {
-    return { ok: true, command, mappings: [] };
-  }
-  // Near-miss schemes that are unambiguously typos get corrected rather
-  // than letting the shell chase a path that never existed: the
-  // single-slash form (talon:/x), and talon:<name> when <name> is a real
-  // mount. Anything else containing "talon:" (a grep pattern, a log tag)
-  // passes through untouched.
-  const nearMiss =
-    /talon:\/(?!\/)([a-z0-9-][^\s'"`]*)/.exec(command) ??
-    /talon:(?!\/)([a-z0-9-]+)/.exec(command);
-  if (nearMiss) {
-    const rest = nearMiss[1]!;
-    const name = MOUNT_NAME.exec(rest)?.[0] ?? "";
-    const known = vfs.describeMounts().some((mount) => mount.name === name);
-    if (nearMiss[0].startsWith("talon:/") || known) {
-      return {
-        ok: false,
-        error: `"${nearMiss[0]}" is not an address — spell it ${SCHEME}${rest}`,
-      };
-    }
-  }
-  if (!command.includes(SCHEME)) {
-    return { ok: true, command, mappings: [] };
-  }
-
-  if (fuseMounted) {
-    return {
-      ok: true,
-      command: command.split(SCHEME).join(`${nsRoot}/`),
-      mappings: [`talon:// → ${nsRoot}/`],
-    };
-  }
-
-  let rewritten = command;
-  const mappings: string[] = [];
-  const mounts = vfs
-    .describeMounts()
-    .filter((mount) => mount.osRoot !== undefined)
-    .sort((a, b) => b.name.length - a.name.length);
-  for (const mount of mounts) {
-    const ref = new RegExp(`talon://${mount.name}(?![a-z0-9-])`, "g");
-    if (ref.test(rewritten)) {
-      rewritten = rewritten.replace(ref, mount.osRoot!);
-      mappings.push(`talon://${mount.name} → ${mount.osRoot}`);
-    }
-  }
-
-  const residual = /talon:\/\/([a-z0-9-]+)/.exec(rewritten);
-  if (residual) {
-    const name = residual[1]!;
-    return {
-      ok: false,
-      error: isSynthetic(name, vfs)
-        ? lockedError(name)
-        : unknownMountError(name, vfs),
-    };
-  }
-
-  // Bare talon:// (the namespace root) — the symlink farm is always there.
-  if (rewritten.includes(SCHEME)) {
-    rewritten = rewritten.split(SCHEME).join(`${nsRoot}/`);
-    mappings.push(`talon:// → ${nsRoot}/`);
-  }
-  return { ok: true, command: rewritten, mappings };
-}