ashlr-plugin 1.36.4

package/servers/pipe-server-handlers.ts

@@ -0,0 +1,68 @@
+/**
+ * pipe-server-handlers — registers ashlr__pipe into the shared tool registry.
+ *
+ * ROLLOUT FLAG: the tool is only registered when ASHLR_PIPE_ENABLE=1.
+ * When the flag is absent (the default), this module runs as a no-op so the
+ * registered tool count stays at 40 and `bun run smoke:tools` keeps passing.
+ *
+ * To enable for testing:
+ *   ASHLR_PIPE_ENABLE=1 bun test __tests__/pipe-server.test.ts
+ *
+ * The conditional registration is evaluated at import time (side-effect
+ * module); the router imports this file unconditionally via _router-handlers.ts.
+ */
+
+import { registerTool, toErrorResult, type ToolCallContext, type ToolResult } from "./_tool-base";
+import { ashlrPipe, type PipeArgs } from "./pipe-server";
+
+// Guard: only register when the rollout flag is set.
+if (process.env.ASHLR_PIPE_ENABLE === "1") {
+  registerTool({
+    name: "ashlr__pipe",
+    description:
+      "[EXPERIMENTAL] Executes model-authored JS code server-side — off by default, enable with ASHLR_PIPE_ENABLE=1. " +
+      "Run a JS expression that calls ctx.{grep,read,ls,glob} internally — " +
+      "intermediate results NEVER enter context, only the return value does. " +
+      "Typical 80–95% token savings vs calling tools individually. " +
+      "ctx methods accept the same args as the ashlr__ tools they wrap. " +
+      "ctx.bash requires the additional ASHLR_PIPE_ALLOW_BASH=1 flag. " +
+      "Example: ctx.grep({pattern:'TODO',cwd:'.'}) returns the grep text as a string.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        expr: {
+          type: "string",
+          description:
+            "Async function body (≤2000 chars). Receives `ctx` with " +
+            "grep/read/ls/glob methods (always available) and bash (requires ASHLR_PIPE_ALLOW_BASH=1). " +
+            "Return value is serialized as JSON. " +
+            "Blocked tokens: process, Bun, require, import(, globalThis, eval, fetch(, etc.",
+        },
+        cwd: {
+          type: "string",
+          description: "Working directory for cwd-relative tool calls (default: project root).",
+        },
+        timeout_ms: {
+          type: "number",
+          description: "Execution timeout in ms (default 10000, hard max 30000).",
+        },
+        max_output_bytes: {
+          type: "number",
+          description: "Truncate output to this many bytes (default 4096).",
+        },
+      },
+      required: ["expr"],
+    },
+    handler: async (
+      args: Record<string, unknown>,
+      ctx: ToolCallContext,
+    ): Promise<ToolResult> => {
+      try {
+        const result = await ashlrPipe(args as unknown as PipeArgs, ctx);
+        return { content: [{ type: "text", text: result.text }] };
+      } catch (err) {
+        return toErrorResult("ashlr__pipe error", err);
+      }
+    },
+  });
+}

package/servers/pipe-server.ts

@@ -0,0 +1,300 @@
+/**
+ * pipe-server — core logic for ashlr__pipe.
+ *
+ * ashlr__pipe lets the model run a multi-step JavaScript expression that
+ * calls grep/read/bash/ls/glob internally. Intermediate results NEVER enter
+ * the model context — only the expression's return value does. This yields
+ * 80–95% token savings vs calling the same tools individually.
+ *
+ * ROLLOUT: tool is only registered when ASHLR_PIPE_ENABLE=1 (off by default
+ * for v1.34). See pipe-server-handlers.ts for the registration guard.
+ *
+ * _noAccounting mechanism: ashlr__pipe calls intermediate tools via getTool()
+ * handler dispatch. Those handlers internally call recordSaving(). To prevent
+ * double-counting, pipe runs each intermediate call inside
+ * _withSuppressedAccounting() (AsyncLocalStorage-scoped) so the inner
+ * recordSaving() no-ops. The pipe then records ONE aggregate saving at the end
+ * (rawBytes = sum of intermediate result sizes, compactBytes = final output).
+ * Scoping is async-local, so a pipe in flight never suppresses a concurrent
+ * unrelated tool call.
+ */
+
+import { getTool, type ToolCallContext } from "./_tool-base";
+import { recordSaving, _withSuppressedAccounting } from "./_stats";
+import { clampToCwd } from "./_cwd-clamp";
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+const MAX_EXPR_LENGTH = 2000;
+const DEFAULT_TIMEOUT_MS = 10_000;
+const MAX_TIMEOUT_MS = 30_000;
+const DEFAULT_MAX_OUTPUT_BYTES = 4096;
+/** Per-intermediate-result heap guard: 64 KB */
+const INTERMEDIATE_CAP_BYTES = 64 * 1024;
+
+// ---------------------------------------------------------------------------
+// Security deny-list
+//
+// Defense-in-depth: reject expressions containing any of these tokens BEFORE
+// executing. This is not a sandbox — it's a best-effort guardrail to prevent
+// the most obvious misuse patterns (process exfiltration, dynamic import,
+// prototype pollution, timing attacks). The AsyncFunction constructor already
+// prevents direct access to module scope and closures; the deny-list adds a
+// second layer for runtime globals that ARE accessible via the global object.
+// ---------------------------------------------------------------------------
+
+const DENY_TOKENS = [
+  "process",
+  "Bun",
+  "require",
+  "import(",
+  "globalThis",
+  "__proto__",
+  "constructor[",
+  "eval",
+  "Function(",
+  "setTimeout",
+  "setInterval",
+  "fetch(",
+];
+
+export interface PipeArgs {
+  expr: string;
+  cwd?: string;
+  timeout_ms?: number;
+  max_output_bytes?: number;
+}
+
+export interface PipeResult {
+  text: string;
+  /** Accumulated byte length of all intermediate results (for accounting). */
+  rawIntermediate: number;
+}
+
+// ---------------------------------------------------------------------------
+// Deadline helper
+// ---------------------------------------------------------------------------
+
+function makeDeadline(ms: number): Promise<never> {
+  return new Promise((_, reject) =>
+    // Using the raw global setTimeout here is intentional — this is the
+    // internal timeout mechanism, NOT user-supplied code. The deny-list
+    // blocks "setTimeout" only in user expressions (expr).
+    (globalThis as unknown as { setTimeout: (fn: () => void, ms: number) => void }).setTimeout(
+      () => reject(new Error(`ashlr__pipe: timed out after ${ms}ms`)),
+      ms,
+    ),
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Build ctx proxy
+// ---------------------------------------------------------------------------
+
+/**
+ * Build the `ctx` object passed into the user's expression.
+ *
+ * Each method (grep/read/bash/ls/glob) delegates to the corresponding
+ * registered tool handler. Around each call, _setSuppressAccounting(true)
+ * prevents the inner handler from recording savings — the pipe records ONE
+ * aggregate at the end.
+ *
+ * Security design — two-tier ctx:
+ *
+ * By default `ctx` exposes ONLY read-only, non-shell tools: grep, read, ls,
+ * glob. These tools cannot mutate the filesystem or spawn arbitrary subprocesses.
+ *
+ * `ctx.bash` is included ONLY when ASHLR_PIPE_ALLOW_BASH=1 is set. Shell
+ * access is a separate, narrower opt-in so that enabling the pipe feature
+ * (ASHLR_PIPE_ENABLE=1) does NOT automatically expose unrestricted shell
+ * execution to model-authored expressions. The deny-list is best-effort, not
+ * a true sandbox — keeping bash out of the default ctx is the primary defence.
+ *
+ * Returns: `{ proxy, getIntermediate }` where `getIntermediate()` returns
+ * the running byte total of all intermediate results.
+ */
+function buildCtx(parentCtx: ToolCallContext): {
+  proxy: Record<string, (args: unknown) => Promise<string>>;
+  getIntermediate: () => number;
+} {
+  let intermediateBytes = 0;
+
+  async function callTool(name: string, args: Record<string, unknown>): Promise<string> {
+    const handler = getTool(name);
+    if (!handler) throw new Error(`ashlr__pipe: tool "${name}" is not registered`);
+
+    // Suppress savings accounting for this intermediate call, scoped to this
+    // call's async tree only (AsyncLocalStorage). Concurrent unrelated tool
+    // calls are never affected. The pipe records ONE aggregate at the end.
+    const result = await _withSuppressedAccounting(() => handler.handler(args, parentCtx));
+
+    const text = result.content.map((c) => c.text).join("");
+
+    // Cap each intermediate result to INTERMEDIATE_CAP_BYTES (heap guard).
+    const capped =
+      text.length > INTERMEDIATE_CAP_BYTES
+        ? text.slice(0, INTERMEDIATE_CAP_BYTES) +
+          "\n[ashlr__pipe: intermediate result capped at 64KB]"
+        : text;
+
+    intermediateBytes += Buffer.byteLength(capped, "utf8");
+    return capped;
+  }
+
+  // Read-only tools are always available in ctx.
+  const proxy: Record<string, (args: unknown) => Promise<string>> = {
+    grep: (args: unknown) => callTool("ashlr__grep", args as Record<string, unknown>),
+    read: (args: unknown) => callTool("ashlr__read", args as Record<string, unknown>),
+    ls:   (args: unknown) => callTool("ashlr__ls",   args as Record<string, unknown>),
+    glob: (args: unknown) => callTool("ashlr__glob", args as Record<string, unknown>),
+  };
+
+  // ctx.bash is an opt-in: requires ASHLR_PIPE_ALLOW_BASH=1 in addition to
+  // ASHLR_PIPE_ENABLE=1. When absent, calling ctx.bash() returns a clear
+  // error so the model knows why it failed and what flag to set.
+  if (process.env.ASHLR_PIPE_ALLOW_BASH === "1") {
+    proxy.bash = (args: unknown) => callTool("ashlr__bash", args as Record<string, unknown>);
+  } else {
+    proxy.bash = async () => {
+      throw new Error(
+        "ctx.bash is disabled; set ASHLR_PIPE_ALLOW_BASH=1 to enable shell access in pipes",
+      );
+    };
+  }
+
+  return { proxy, getIntermediate: () => intermediateBytes };
+}
+
+// ---------------------------------------------------------------------------
+// Main entry point
+// ---------------------------------------------------------------------------
+
+export async function ashlrPipe(args: PipeArgs, ctx: ToolCallContext): Promise<PipeResult> {
+  const { expr, cwd, timeout_ms, max_output_bytes } = args;
+
+  // --- Input validation ---
+
+  if (typeof expr !== "string" || expr.length === 0) {
+    throw new Error("ashlr__pipe: expr must be a non-empty string");
+  }
+
+  if (expr.length > MAX_EXPR_LENGTH) {
+    throw new Error(
+      `ashlr__pipe: expr exceeds ${MAX_EXPR_LENGTH} characters (got ${expr.length})`,
+    );
+  }
+
+  // Deny-list check — must happen BEFORE constructing/executing the function.
+  for (const token of DENY_TOKENS) {
+    if (expr.includes(token)) {
+      throw new Error(
+        `ashlr__pipe: expr contains disallowed token "${token}" — ` +
+          `process/Bun/require/import/globalThis/eval/fetch and similar globals are blocked`,
+      );
+    }
+  }
+
+  // Timeout validation.
+  const timeoutMs = (() => {
+    if (timeout_ms === undefined) return DEFAULT_TIMEOUT_MS;
+    if (!Number.isFinite(timeout_ms) || timeout_ms <= 0) {
+      throw new Error(
+        `ashlr__pipe: timeout_ms must be a positive finite number (got ${timeout_ms})`,
+      );
+    }
+    return Math.min(timeout_ms, MAX_TIMEOUT_MS);
+  })();
+
+  const maxOutputBytes = (() => {
+    if (max_output_bytes === undefined) return DEFAULT_MAX_OUTPUT_BYTES;
+    if (!Number.isFinite(max_output_bytes) || max_output_bytes <= 0) {
+      throw new Error(
+        `ashlr__pipe: max_output_bytes must be a positive finite number (got ${max_output_bytes})`,
+      );
+    }
+    return max_output_bytes;
+  })();
+
+  // cwd clamp — optional; if provided must be inside an allowed root.
+  if (cwd !== undefined) {
+    const clamp = clampToCwd(cwd, "ashlr__pipe");
+    if (!clamp.ok) {
+      throw new Error(clamp.message);
+    }
+  }
+
+  // --- Build the expression function ---
+  //
+  // Use AsyncFunction constructor, NOT eval. This creates a new function
+  // scope that does NOT capture the module's closures or `require`. The only
+  // binding available to the user expression is the explicit `ctx` argument.
+
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const AsyncFunction = Object.getPrototypeOf(async function () {}).constructor as new (
+    ...args: string[]
+  ) => (ctx: unknown) => Promise<unknown>;
+
+  // Force strict mode on the user body. In sloppy mode a Function-constructed
+  // function sees `this === globalThis` at call time, which would let an expr
+  // reach real globals via `this["pro"+"cess"]` and defeat the substring
+  // deny-list (token-splitting). Strict mode makes `this` undefined and turns
+  // implicit-global access into a ReferenceError — the deny-list is then a
+  // second layer, not the only one.
+  const fn = new AsyncFunction("ctx", `"use strict";\n${expr}`);
+
+  // --- Execute with deadline race ---
+
+  const { proxy, getIntermediate } = buildCtx(ctx);
+
+  let rawValue: unknown;
+  try {
+    rawValue = await Promise.race([fn(proxy), makeDeadline(timeoutMs)]);
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    throw new Error(msg);
+  }
+
+  // --- Serialize return value ---
+
+  let serialized: string;
+  try {
+    serialized = JSON.stringify(rawValue, null, 2) ?? "null";
+  } catch {
+    // Circular references or non-serializable values (BigInt, etc.).
+    serialized = "[non-serializable result]";
+  }
+
+  // --- Truncate to max_output_bytes ---
+
+  const outputBytes = Buffer.byteLength(serialized, "utf8");
+  let output = serialized;
+  if (outputBytes > maxOutputBytes) {
+    // Slice at byte boundary (Buffer) to avoid splitting a multi-byte codepoint.
+    output =
+      Buffer.from(serialized, "utf8").slice(0, maxOutputBytes).toString("utf8") +
+      "\n[ashlr__pipe: output truncated]";
+  }
+
+  // --- Savings accounting ---
+  //
+  // ONE aggregate recording for the entire pipe execution:
+  //   rawBytes    = sum of all intermediate result byte lengths
+  //                 (what the model would have seen calling tools individually)
+  //   compactBytes = final output byte length (what the model actually sees)
+  //
+  // Intermediate ctx calls had _setSuppressAccounting(true) active so they
+  // called recordSaving but it returned 0 immediately — no double-counting.
+
+  const rawBytes = getIntermediate();
+  const compactBytes = Buffer.byteLength(output, "utf8");
+  if (rawBytes > 0) {
+    // Fire-and-forget; accounting errors must never surface to the caller.
+    recordSaving(rawBytes, compactBytes, "ashlr__pipe", {
+      sessionId: ctx.sessionId,
+    }).catch(() => undefined);
+  }
+
+  return { text: output, rawIntermediate: rawBytes };
+}

package/servers/read-server-handlers.ts

@@ -0,0 +1,42 @@
+/**
+ * read-server-handlers — registers ashlr__read into the shared tool registry.
+ */
+
+import { registerTool, type ToolCallContext, type ToolResult } from "./_tool-base";
+import { ashlrRead } from "./read-server";
+
+registerTool({
+  name: "ashlr__read",
+  description:
+    "Read a file with snipCompact truncation (head + tail, elided middle). " +
+    "Use instead of native Read when the file is >2KB — avoids returning the " +
+    "full payload; compresses by preserving only the structurally significant " +
+    "head and tail; typical savings 60–90% on large files. " +
+    "Pass bypassSummary:true to get the full file when you need it.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      path: { type: "string", description: "Absolute or cwd-relative file path" },
+      bypassSummary: {
+        type: "boolean",
+        description: "Skip LLM summarization, return snipCompact-truncated content (default: false)",
+      },
+      mode: {
+        type: "string",
+        enum: ["auto", "ast", "snip"],
+        description: "auto (default): use AST skeleton for large wired-lang files; ast: force skeleton; snip: force snipCompact head+tail",
+      },
+    },
+    required: ["path"],
+  },
+  handler: async (args: Record<string, unknown>, _ctx: ToolCallContext): Promise<ToolResult> => {
+    const text = await ashlrRead({
+      path: String(args.path ?? ""),
+      bypassSummary: args.bypassSummary === true,
+      mode: ["auto", "ast", "snip"].includes(String(args.mode ?? ""))
+        ? (args.mode as "auto" | "ast" | "snip")
+        : undefined,
+    });
+    return { content: [{ type: "text", text }] };
+  },
+});

package/servers/read-server.ts

@@ -0,0 +1,206 @@
+/**
+ * read-server — ashlr__read tool implementation.
+ *
+ * Owns the snipCompact + summarization pipeline for file reads.
+ * Uses _read-cache for per-session mtime-keyed caching.
+ */
+
+import { readFile } from "fs/promises";
+import { statSync } from "fs";
+import {
+  estimateTokensFromString,
+  type Message,
+  snipCompact,
+} from "@ashlr/core-efficiency";
+import { summarizeIfLarge, PROMPTS, confidenceBadge, confidenceTier } from "./_summarize";
+import { logEvent } from "./_events";
+import { recordSaving } from "./_stats";
+import { clampToCwd, primaryProjectRoot } from "./_cwd-clamp";
+import { getCached, setCached, type ReadCacheEntry } from "./_read-cache";
+import { schedulePrefetch, type PrefetchTier } from "./_prefetch";
+import { resolveLanguage } from "./_ast-languages";
+import { renderAstSkeleton } from "./_ast-skeleton";
+import { isProSync } from "./_pro";
+
+/**
+ * Minimum content byte-length before AST skeleton rendering is attempted.
+ * Below this threshold the full snipCompact path is cheaper.
+ */
+const AST_THRESHOLD = 6144;
+
+/**
+ * File extensions treated as code for the line-number-preservation path.
+ * When ashlr__read returns a snipCompact-truncated view of one of these files,
+ * every preserved line is prefixed with its original line number so Claude can
+ * cite `file:line` accurately even across the elided middle.
+ */
+const CODE_EXTENSIONS = new Set([
+  ".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs",
+  ".py", ".go", ".rs", ".java", ".kt", ".kts",
+  ".rb", ".php", ".swift", ".cs", ".scala", ".cpp", ".c", ".h", ".hpp",
+  ".sh", ".bash", ".zsh", ".fish",
+  ".sql", ".graphql", ".proto", ".css", ".scss", ".html", ".vue", ".svelte",
+]);
+
+function isCodeFile(path: string): boolean {
+  const m = path.match(/\.[a-zA-Z0-9]+$/);
+  if (!m) return false;
+  return CODE_EXTENSIONS.has(m[0].toLowerCase());
+}
+
+/**
+ * Prepend every line with its 1-based line number + ": " so that head/tail
+ * fragments surviving snipCompact still carry positional information.
+ */
+function numberCodeLines(source: string): string {
+  const lines = source.split("\n");
+  const pad = String(lines.length).length;
+  return lines.map((line, i) => `${String(i + 1).padStart(pad, " ")}: ${line}`).join("\n");
+}
+
+export async function ashlrRead(input: { path: string; bypassSummary?: boolean; preserveLineNumbers?: boolean; mode?: "auto" | "ast" | "snip" }): Promise<string> {
+  const clamp = clampToCwd(input.path, "ashlr__read");
+  if (!clamp.ok) return clamp.message;
+  const abs = clamp.abs;
+
+  // Cache hit path: same absolute path + unchanged mtime → return cached result.
+  let mtimeMs = 0;
+  try {
+    mtimeMs = statSync(abs).mtimeMs;
+    const hit = getCached(abs);
+    if (hit && hit.mtimeMs === mtimeMs && input.bypassSummary !== true) {
+      // On a repeat read we would otherwise have re-paid the full source bytes.
+      // Credit the original-size saving again since the agent received zero new
+      // tokens of file content.
+      await recordSaving(hit.sourceBytes, 0, "ashlr__read");
+      return `(cached)\n${hit.result}`;
+    }
+  } catch {
+    // If stat fails (broken symlink, perms), fall through to the normal read
+    // path which will surface a descriptive error.
+  }
+
+  const content = await readFile(abs, "utf-8");
+
+  // ------------------------------------------------------------------
+  // AST skeleton path: for large wired-language files in auto/ast mode,
+  // return signatures-only skeleton instead of snipCompact head+tail.
+  // Falls back to snipCompact on ANY failure (null return from skeleton).
+  // ------------------------------------------------------------------
+  const mode = input.mode ?? "auto";
+  const wantAst =
+    input.bypassSummary !== true &&
+    mode !== "snip" &&
+    (mode === "ast" ||
+      (isCodeFile(abs) &&
+        content.length > AST_THRESHOLD &&
+        (() => {
+          const lang = resolveLanguage(abs);
+          return (
+            lang === "typescript" || lang === "tsx" || lang === "javascript"
+          );
+        })()));
+
+  if (wantAst) {
+    const skel = await renderAstSkeleton(abs, content).catch(() => null);
+    if (skel !== null && skel.length < content.length) {
+      await recordSaving(content.length, skel.length, "ashlr__read");
+      const skelBadgeOpts = {
+        toolName: "ashlr__read",
+        rawBytes: content.length,
+        outputBytes: skel.length,
+        fellBack: false,
+        extra: `ast-skeleton${mtimeMs > 0 ? ` · mtime=${mtimeMs}` : ""}`,
+      };
+      const skelBadge = confidenceBadge(skelBadgeOpts);
+      const skelNote =
+        "\n// [ast-skeleton] Signatures only. Use bypassSummary:true to get the full file.";
+      const skelResult = skel + skelNote + skelBadge;
+      if (mtimeMs > 0) {
+        setCached(abs, {
+          mtimeMs,
+          result: skelResult,
+          sourceBytes: content.length,
+        });
+      }
+      return skelResult;
+    }
+    // skeleton was null or not smaller → fall through to snipCompact
+  }
+
+  // For code files, prepend 1-based line numbers to every line before
+  // snipCompact runs so `file:line` citations survive truncation.
+  const preserveLineNumbers =
+    input.preserveLineNumbers ?? isCodeFile(abs);
+  const renderedContent = preserveLineNumbers
+    ? numberCodeLines(content)
+    : content;
+
+  // Wrap as a fake tool_result message so snipCompact has something to snip.
+  const msgs: Message[] = [
+    {
+      role: "user",
+      content: [
+        { type: "tool_result", tool_use_id: "ashlr-read", content: renderedContent },
+      ],
+    },
+  ];
+
+  const compact = snipCompact(msgs);
+  const block = (compact[0]!.content as { type: string; content: string }[])[0]!;
+  const out = (block as { content: string }).content;
+
+  if (!(renderedContent.length > out.length)) {
+    await logEvent("tool_noop", { tool: "ashlr__read", reason: "small-file" });
+  }
+  const summarizeInput = renderedContent.length > out.length ? renderedContent : out;
+  const summarized = await summarizeIfLarge(summarizeInput, {
+    toolName: "ashlr__read",
+    systemPrompt: PROMPTS.read,
+    bypass: input.bypassSummary === true,
+  });
+  const finalText = summarized.summarized || summarized.fellBack || input.bypassSummary ? summarized.text : out;
+  const finalBytes = summarized.summarized || summarized.fellBack ? summarized.outputBytes : out.length;
+  await recordSaving(content.length, finalBytes, "ashlr__read");
+
+  const badgeOpts = {
+    toolName: "ashlr__read",
+    rawBytes: content.length,
+    outputBytes: finalBytes,
+    fellBack: summarized.fellBack,
+    extra: mtimeMs > 0 ? `mtime=${mtimeMs}` : undefined,
+  };
+  if (confidenceTier(badgeOpts) === "low") {
+    await logEvent("tool_low_confidence_shipped", { tool: "ashlr__read", reason: "low-confidence" });
+  }
+  const badge = confidenceBadge(badgeOpts);
+  const finalTextWithBadge = finalText + badge;
+
+  // Cache the fully computed result for this (path, mtimeMs). Skip caching
+  // when bypassSummary was used — that's an opt-out path and shouldn't
+  // poison future non-bypass calls.
+  if (input.bypassSummary !== true && mtimeMs > 0) {
+    setCached(abs, { mtimeMs, result: finalTextWithBadge, sourceBytes: content.length });
+  }
+
+  // Fire-and-forget predictive prefetch — Q3 supporting pillar. Scans X's
+  // imports via lightweight regex and pre-caches the top-N neighbours so the
+  // next ashlr__read on any of them is instant.
+  //
+  // MUST NOT be awaited. setImmediate inside schedulePrefetch defers the work
+  // to the next tick, so the user's read response goes out first.
+  try {
+    const tier: PrefetchTier = isProSync() ? "pro" : "free";
+    // Pro tier is the conservative default — team plans get bumped via cap.
+    // schedulePrefetch clamps to per-tier cap regardless of what we pass.
+    void schedulePrefetch(abs, {
+      tier,
+      maxNeighbors: 10,
+      cwd: primaryProjectRoot(),
+    });
+  } catch {
+    // Never let prefetch failures touch the read path.
+  }
+
+  return finalTextWithBadge;
+}

package/servers/rename-file-server-handlers.ts

@@ -0,0 +1,67 @@
+/**
+ * rename-file-server-handlers — registers ashlr__rename_file on the shared
+ * registry (Track A · v1.19).
+ *
+ * Companion to `ashlr__edit_structural`. That tool renames IDENTIFIERS
+ * (symbol names); this one renames MODULE PATHS (file locations + every
+ * import specifier that resolves to them).
+ */
+
+import { registerTool, toErrorResult, type ToolCallContext, type ToolResult } from "./_tool-base";
+import { ashlrRenameFile, type RenameFileArgs } from "./rename-file-server";
+import { recordSaving } from "./_stats";
+
+const ERR_PREFIX = "ashlr__rename_file error";
+
+registerTool({
+  name: "ashlr__rename_file",
+  description:
+    "Rename (move) a source file AND update every import specifier in the project that resolved to it. " +
+    "Handles extension elision ('./foo' → './bar'), directory-index resolution ('./foo' when foo/index.ts), " +
+    "and skips bare package specifiers. Refuses if 'to' already exists, 'to's parent directory is missing, " +
+    "paths escape cwd, or either path is a binary file. Supports dryRun. Complements ashlr__edit_structural " +
+    "(which renames identifiers, not module paths).",
+  inputSchema: {
+    type: "object",
+    properties: {
+      from: { type: "string", description: "Current file path (absolute or cwd-relative). Must exist." },
+      to: { type: "string", description: "New file path (absolute or cwd-relative). Must NOT exist; parent dir must exist." },
+      dryRun: {
+        type: "boolean",
+        description: "If true, list planned edits without writing or renaming (default false).",
+      },
+      maxFiles: {
+        type: "number",
+        description: "Hard cap on importer candidate files (default 200). Beyond this the scan truncates with a warning.",
+      },
+      roots: {
+        type: "array",
+        items: { type: "string" },
+        description: "Limit the importer scan to these subdirectories (absolute or cwd-relative). Default: process.cwd().",
+      },
+    },
+    required: ["from", "to"],
+  },
+  handler: async (args: Record<string, unknown>, _ctx: ToolCallContext): Promise<ToolResult> => {
+    try {
+      const a = args as unknown as RenameFileArgs;
+      const text = await ashlrRenameFile(a);
+      // Savings accounting: the baseline is the byte-size of the importer
+      // source files we rewrote (what a naive "read every candidate and
+      // have the model stitch a multi_edit call" approach would have
+      // shipped). We don't know the per-file sizes from the summary alone,
+      // so approximate via the summary length itself against a nominal
+      // multiplier — compact-vs-raw accounting in this tool is a lower
+      // bound, not exact. Any positive saving is credited.
+      const compactBytes = Buffer.byteLength(text, "utf-8");
+      // Claim a conservative 2× multiplier so we don't inflate savings on
+      // zero-importer renames; on large renames the real savings are
+      // much higher. This is a floor — the router's recordSaving is
+      // additive, not a source of truth for per-call math.
+      await recordSaving(compactBytes * 2, compactBytes, "ashlr__rename_file");
+      return { content: [{ type: "text", text }] };
+    } catch (err) {
+      return toErrorResult(ERR_PREFIX, err);
+    }
+  },
+});