pim-agent 0.12.1 → 0.14.0

package/packages/core/src/extensions/bash/capture.ts

@@ -22,7 +22,7 @@ export class StreamCapture {
     return this.totalBytesAccum;
   }
 
-  /** The first `n` bytes, read across however many chunks the kernel split them into. */
+  /** The first `n` bytes, across chunk boundaries. */
   lead(n: number): Uint8Array {
     if (this.fullBytes) {
       return this.fullBytes.subarray(0, n);
@@ -48,36 +48,29 @@ export class StreamCapture {
     return this.fullBytes;
   }
 
-  /** Opaque bytes are not text: a half-image is worthless, so they are neither cut nor decoded. */
+  /** Opaque streams (images) are neither cut nor decoded. */
   snapshot(opaque = false): CapturedStream {
-    if (this.totalBytesAccum === 0 || opaque) {
-      return {
-        text: "",
-        totalBytes: this.totalBytesAccum,
-        truncated: false,
-        path: null,
-        nextStart: null,
-      };
+    const totalBytes = this.totalBytesAccum;
+    const untruncated = {
+      totalBytes,
+      truncated: false,
+      path: null,
+      nextStart: null,
+    };
+    if (totalBytes === 0 || opaque) {
+      return { text: "", ...untruncated };
     }
     const dec = new TextDecoder();
     const all = this.full();
-    if (this.totalBytesAccum <= STREAM_HEAD_BYTES + STREAM_TAIL_BYTES) {
-      return {
-        text: dec.decode(all),
-        totalBytes: this.totalBytesAccum,
-        truncated: false,
-        path: null,
-        nextStart: null,
-      };
+    if (totalBytes <= STREAM_HEAD_BYTES + STREAM_TAIL_BYTES) {
+      return { text: dec.decode(all), ...untruncated };
     }
     const headText = dec.decode(all.subarray(0, STREAM_HEAD_BYTES));
-    const tailText = dec.decode(
-      all.subarray(all.byteLength - STREAM_TAIL_BYTES)
-    );
-    const middle = this.totalBytesAccum - STREAM_HEAD_BYTES - STREAM_TAIL_BYTES;
+    const tailText = dec.decode(all.subarray(totalBytes - STREAM_TAIL_BYTES));
+    const middle = totalBytes - STREAM_HEAD_BYTES - STREAM_TAIL_BYTES;
     return {
       text: `${headText}\n... ${middle} bytes truncated ...\n${tailText}`,
-      totalBytes: this.totalBytesAccum,
+      totalBytes,
       truncated: true,
       path: null,
       nextStart: Lines.continuationLine(headText),

package/packages/core/src/extensions/bash/format.ts

@@ -10,7 +10,7 @@ import {
 
 const STREAMS = ["stdout", "stderr"] as const;
 
-export function stripTrailingNewline(s: string): string {
+function stripTrailingNewline(s: string): string {
   return s.endsWith("\n") ? s.slice(0, -1) : s;
 }
 
@@ -68,7 +68,7 @@ export function formatResult(
   return lines.join("\n");
 }
 
-/** The words for a picture the content array will not carry; null when it will. */
+/** Null when the image is shown in the content array. */
 function unshownImageLine(
   result: BashCommandResult,
   sniffed: ImageMimeType,

package/packages/core/src/extensions/bash/image.ts

@@ -1,11 +1,7 @@
 import { Format } from "../../shared/Format";
 import { Images, type NormalisedImage } from "../../shared/Images";
 
-/**
- * The picture stdout printed, once a provider will take it. Bytes that sniffed
- * as an image but cannot be decoded are not an error here: the command ran, and
- * bash reports what it printed.
- */
+/** Null when the bytes cannot be decoded; that is not a tool error. */
 export async function normaliseStdoutImage(
   bytes: Uint8Array
 ): Promise<NormalisedImage | null> {
@@ -16,12 +12,12 @@ export async function normaliseStdoutImage(
   }
 }
 
-/** `stdout is a 1200x800 png (240 KB)`, the subject every note about the picture shares. */
-export function imageSubject(image: NormalisedImage): string {
+/** e.g. `stdout is a 1200x800 png (240 KB)`. */
+function imageSubject(image: NormalisedImage): string {
   return `stdout is a ${image.width}x${image.height} ${Images.extensionOf(image.mimeType)} (${Format.bytes(image.bytes)})`;
 }
 
-/** What the model is told next to the picture, or instead of it when it has no eyes. */
+/** Text sent with the image, or instead of it for a model without vision. */
 export function imageNote(image: NormalisedImage, vision: boolean): string {
   if (!vision) {
     return Images.noVisionNote("bash", imageSubject(image));

package/packages/core/src/extensions/bash/index.ts

@@ -24,7 +24,7 @@ function installLifecycleHandlers(): void {
   }
   lifecycleHandlersInstalled = true;
 
-  // Sweep escaped bash subtrees, then re-raise so the default handler still runs.
+  // Kill running commands, then re-raise so the default handler still runs.
   for (const sig of ["SIGTERM", "SIGINT", "SIGHUP"] as const) {
     process.once(sig, () => {
       try {

package/packages/core/src/extensions/bash/render.ts

@@ -12,7 +12,7 @@ export function bashView({ args, result }: BashViewInput): ToolView {
   return {
     label: "Bash",
     icon: "terminal",
-    // `spans`, not `text`: a `text` title is split on newlines and rejoined with spaces.
+    // Not `text`: that would join a multi-line command onto one line.
     title: [
       {
         kind: "spans",

package/packages/core/src/extensions/bash/run.ts

@@ -16,10 +16,8 @@ type Reader = ReadableStreamDefaultReader<Uint8Array>;
 const activePids = new Set<number>();
 
 const COMMAND_VAR = "PIM_BASH_COMMAND";
-// argv is what `pkill -f`/`pgrep -f` match, so a command naming its own target would
-// signal this shell before its target. The env hands it over out of argv's reach, and
-// the unset keeps it out of every child's environment too.
-// The raised oom_score_adj makes the command, not the agent or the desktop, the kernel's first victim.
+// The command goes via env, not argv, so `pkill -f <target>` inside it can't match this shell.
+// oom_score_adj makes the command the OOM killer's first victim, not pim.
 const RUNNER = `{ echo 500 > /proc/self/oom_score_adj; } 2>/dev/null; __pim_command=$${COMMAND_VAR}; unset ${COMMAND_VAR}; eval "$__pim_command"`;
 
 export function killAllActiveBashGroups(sig: NodeJS.Signals = "SIGTERM"): void {
@@ -59,11 +57,7 @@ async function spillIfTruncated(
   return stream.truncated ? SpillCache.write("bash", ext, cap.full()) : null;
 }
 
-/**
- * The picture stdout printed, or null. The verdict is the leading bytes',
- * before anything is decoded; the cap is the whole stream's, so an image too
- * big to send is text again and truncates like any other output.
- */
+/** Sniffs the leading bytes only. Over the size cap, stdout is treated as text. */
 export function sniffStdoutImage(cap: StreamCapture): ImageMimeType | null {
   if (
     cap.totalBytes < Images.SNIFF_BYTES ||
@@ -104,7 +98,7 @@ export async function runBashCommand(
   const stderrCap = new StreamCapture();
   const scope = await MemoryCap.scope();
 
-  // setsid gives the tree its own process group (pgid == proc.pid) so the whole tree can be signalled.
+  // setsid: own process group (pgid == pid), so the whole tree can be signalled.
   const proc = Bun.spawn({
     cmd: [...(scope?.argv ?? []), "setsid", "bash", "-lc", RUNNER],
     cwd,
@@ -119,7 +113,7 @@ export async function runBashCommand(
   let timedOut = false;
   let aborted = false;
 
-  // Hold the readers: cancelling a locked stream through the stream itself throws.
+  // Keep the readers: cancelling a locked stream directly throws.
   const stdoutReader = getReader(
     proc.stdout as unknown as ReadableStream<Uint8Array>
   );
@@ -127,7 +121,7 @@ export async function runBashCommand(
     proc.stderr as unknown as ReadableStream<Uint8Array>
   );
 
-  // Never block on EOF: a backgrounded child can hold the pipes open after bash exits.
+  // Not awaited: a backgrounded child can hold the pipes open after bash exits.
   const stdoutDrain = drain(stdoutReader, stdoutCap);
   const stderrDrain = drain(stderrReader, stderrCap);
 
@@ -181,7 +175,7 @@ export async function runBashCommand(
     exitCode = proc.exitCode ?? null;
     signalCode = (proc.signalCode as NodeJS.Signals | null | undefined) ?? null;
 
-    // Bound the drain: a detached grandchild holding the pipe would outlive this call.
+    // Bounded: a detached grandchild may hold the pipe open forever.
     await Promise.race([
       Promise.all([stdoutDrain, stderrDrain]),
       Bun.sleep(DRAIN_GRACE_MS),
@@ -206,14 +200,14 @@ export async function runBashCommand(
     }
   }
 
-  // A picture nothing will show is never decoded: a failed command reports its bytes instead.
+  // A failed command's image is never decoded.
   const sniffed = sniffStdoutImage(stdoutCap);
   const shows =
     sniffed !== null && !isErrorResult({ exitCode, timedOut, aborted });
   const stdout = stdoutCap.snapshot(sniffed !== null);
   const stderr = stderrCap.snapshot();
 
-  // Under OOMPolicy=kill a limit hit is a SIGKILL of the whole scope; systemd's own Result for it is racy.
+  // OOMPolicy=kill + KillSignal=SIGKILL: an OOM ends in SIGKILL whoever wins; systemd's Result is racy.
   const memoryLimitHit =
     scope !== null && signalCode === "SIGKILL" && !timedOut && !aborted
       ? scope.limitBytes

package/packages/core/src/extensions/bash/schema.ts

@@ -37,18 +37,18 @@ export type BashCommandResult = {
   readonly signal: NodeJS.Signals | null;
   readonly stdout: CapturedStream;
   readonly stderr: CapturedStream;
-  /** What stdout's leading bytes sniffed as, whether or not the picture could then be decoded. */
+  /** Set even when the image could not be decoded. */
   readonly stdoutSniffed: ImageMimeType | null;
-  /** Set only when stdout sniffed as a picture and a provider will take it. */
+  /** Set only when the image decoded and will be shown. */
   readonly stdoutImage: NormalisedImage | null;
   readonly timedOut: boolean;
   readonly aborted: boolean;
-  /** The limit in bytes, set when the capped command was SIGKILLed without pim sending it. */
+  /** The limit in bytes; set when the command was SIGKILLed by something other than pim. */
   readonly memoryLimitHit: number | null;
   readonly durationMs: number;
 };
 
-export type BashStreamDetails = {
+type BashStreamDetails = {
   readonly totalBytes: number;
   readonly truncated: boolean;
   readonly path: string | null;

package/packages/core/src/extensions/edit/edit.ts

@@ -1,4 +1,3 @@
-import type { Stats } from "node:fs";
 import { realpath, stat } from "node:fs/promises";
 import {
   EditMatcher,
@@ -11,12 +10,12 @@ import { FsErrors } from "../../shared/FsErrors";
 import { Lines } from "../../shared/Lines";
 import type { RawEdit } from "./schema";
 
-export type NoopEdit = {
+type NoopEdit = {
   readonly index: number;
   readonly range: string;
 };
 
-export type ResolvedEditMetadata = {
+type ResolvedEditMetadata = {
   readonly index: number;
   readonly ranges: readonly string[];
   readonly strategy: EditMatchStrategy;
@@ -162,10 +161,10 @@ async function performEdit(
 
   const nextContent = EditMatcher.applyAll(originalContent, effectiveMutations);
 
-  await writeFileAtomic(
+  await Fs.writeKeepingLinks(
     canonicalPath,
     hadBom ? `${Lines.utf8Bom}${nextContent}` : nextContent,
-    metadata
+    { mode: Number(metadata.mode), nlink: metadata.nlink }
   );
 
   const original = Lines.splitWithTrailingNewline(originalContent);
@@ -256,7 +255,11 @@ function assertNoDuplicateEdits(edits: readonly ParsedEdit[]): void {
   const seen = new Map<string, number>();
 
   for (const [index, edit] of edits.entries()) {
-    const key = duplicateKey(edit);
+    const key = JSON.stringify([
+      edit.oldString,
+      edit.newString,
+      edit.replaceAll,
+    ]);
     const previous = seen.get(key);
 
     if (previous !== undefined) {
@@ -269,22 +272,11 @@ function assertNoDuplicateEdits(edits: readonly ParsedEdit[]): void {
   }
 }
 
-function duplicateKey(edit: ParsedEdit): string {
-  return JSON.stringify({
-    oldString: edit.oldString,
-    newString: edit.newString,
-    replaceAll: edit.replaceAll,
-  });
-}
-
 function sortMutations(mutations: readonly Mutation[]): readonly Mutation[] {
-  return [...mutations].sort((left, right) => {
-    if (left.range[0] !== right.range[0]) {
-      return left.range[0] - right.range[0];
-    }
-
-    return left.range[1] - right.range[1];
-  });
+  return [...mutations].sort(
+    (left, right) =>
+      left.range[0] - right.range[0] || left.range[1] - right.range[1]
+  );
 }
 
 function assertNoOverlaps(sorted: readonly Mutation[]): void {
@@ -320,17 +312,6 @@ function renderAllNoopError(noops: readonly NoopEdit[]): string {
   ].join("\n");
 }
 
-async function writeFileAtomic(
-  canonicalPath: string,
-  content: string,
-  metadata: Stats
-): Promise<void> {
-  await Fs.writeKeepingLinks(canonicalPath, content, {
-    mode: Number(metadata.mode),
-    nlink: metadata.nlink,
-  });
-}
-
 async function enqueue<T>(key: string, task: () => Promise<T>): Promise<T> {
   const previous = editQueues.get(key) ?? Promise.resolve();
   const queued = previous.then(task, task);
@@ -359,7 +340,7 @@ function joinHuman(items: readonly string[]): string {
   }
 
   if (items.length === 1) {
-    return items[0] ?? "unknown";
+    return items[0]!;
   }
 
   return `${items.slice(0, -1).join(", ")} and ${items.at(-1)}`;

package/packages/core/src/extensions/glob/glob.ts

@@ -6,12 +6,10 @@ export type GlobMatch = {
   readonly mtime: number;
 };
 
-export type GlobScanOptions = FileScanOptions;
-
 export async function findFiles(
   root: string,
   pattern: string,
-  options: GlobScanOptions
+  options: FileScanOptions
 ): Promise<readonly GlobMatch[]> {
   const metadata = await FsErrors.statOrThrow(root);
 

package/packages/core/src/extensions/glob/index.ts

@@ -39,15 +39,15 @@ export default function (pi: ExtensionAPI): void {
         throw new Error("Glob aborted before execution.");
       }
 
-      const limit = headLimit ?? GLOB_HEAD_LIMIT_MAX;
-      const resolvedPathFormat = pathFormat ?? DEFAULT_PATH_FORMAT;
-      const absolutePath = Paths.resolve(path ?? ".", ctx.cwd);
-      const matches = await findFiles(absolutePath, pattern, {
+      const scan = {
         exclude,
         includeDotfiles: includeDotfiles ?? false,
         includeIgnored: includeIgnored ?? false,
-      });
-      const outcome = renderFiles(matches, limit, {
+      };
+      const resolvedPathFormat = pathFormat ?? DEFAULT_PATH_FORMAT;
+      const absolutePath = Paths.resolve(path ?? ".", ctx.cwd);
+      const matches = await findFiles(absolutePath, pattern, scan);
+      const outcome = renderFiles(matches, headLimit ?? GLOB_HEAD_LIMIT_MAX, {
         cwd: ctx.cwd,
         pathFormat: resolvedPathFormat,
       });
@@ -67,9 +67,7 @@ export default function (pi: ExtensionAPI): void {
         details: {
           absolutePath,
           pattern,
-          exclude,
-          includeDotfiles: includeDotfiles ?? false,
-          includeIgnored: includeIgnored ?? false,
+          ...scan,
           pathFormat: resolvedPathFormat,
           fileCount: matches.length,
           totalItems: outcome.totalItems,

package/packages/core/src/extensions/glob/render.ts

@@ -11,9 +11,7 @@ import type {
   globSchema,
 } from "./schema";
 
-export type RenderOutcome = SearchList;
-
-export type RenderOptions = {
+type RenderOptions = {
   readonly cwd: string;
   readonly pathFormat: GlobPathFormat;
 };
@@ -22,7 +20,7 @@ export function renderFiles(
   matches: readonly GlobMatch[],
   headLimit: number,
   options: RenderOptions
-): RenderOutcome {
+): SearchList {
   return SearchRender.capList(
     matches.map((match) => SearchRender.formatPath(match.path, options)),
     headLimit

package/packages/core/src/extensions/glob/schema.ts

@@ -3,7 +3,7 @@ import { type Static, Type } from "typebox";
 
 export const GLOB_HEAD_LIMIT_MAX = 1000;
 
-export const GLOB_PATH_FORMATS = ["relative", "absolute"] as const;
+const GLOB_PATH_FORMATS = ["relative", "absolute"] as const;
 
 export const globSchema = Type.Object({
   pattern: Type.String({

package/packages/core/src/extensions/grep/grep.ts

@@ -6,7 +6,7 @@ import { Pool } from "../../shared/Pool";
 
 const MATCH_CONCURRENCY = 16;
 
-export type GrepLine = {
+type GrepLine = {
   readonly lineNumber: number;
   readonly text: string;
 };
@@ -24,18 +24,18 @@ export type GrepMatch = {
   readonly fileLines: readonly string[];
 };
 
-export type GrepMatcher = {
+type GrepMatcher = {
   readonly regex: RegExp;
   readonly matchAcrossLines: boolean;
-  /** Raw-byte needle for the literal fast path; undefined leaves the regex path unchanged. */
+  /** Byte needle for the literal fast path. */
   readonly literal: Buffer | undefined;
 };
 
-export type GrepScanOptions = FileScanOptions & {
+type GrepScanOptions = FileScanOptions & {
   readonly retainFileLines?: boolean;
 };
 
-// ASCII-only: these stand for themselves in both a default-flag regex and raw UTF-8 bytes.
+// ASCII chars that mean the same as regex source and as raw bytes.
 const PURE_LITERAL = /^[A-Za-z0-9_ \-/]+$/;
 
 function literalNeedle(
@@ -95,7 +95,7 @@ export async function findMatches(
   return scanned.filter((match) => match !== undefined);
 }
 
-// An entry may not be a readable regular file: an unreadable one is a non-match, never a failure.
+// Unreadable entries are non-matches, not errors.
 async function matchFile(
   filePath: string,
   matcher: GrepMatcher,
@@ -110,7 +110,7 @@ async function matchFile(
     }
 
     if (matcher.literal !== undefined) {
-      // Literal fast path: an ASCII needle's raw-byte hit/miss matches the decoded result.
+      // Skip decoding files that can't contain the needle.
       const bytes = Buffer.from(await file.arrayBuffer());
       if (bytes.indexOf(matcher.literal) < 0) {
         return undefined;

package/packages/core/src/extensions/grep/render.ts

@@ -10,13 +10,13 @@ import type { ToolView, ViewBlock } from "../../view/ViewBlock";
 import type { GrepLineRange, GrepMatch } from "./grep";
 import type { GrepInput, GrepOutputMode, GrepPathFormat } from "./schema";
 
-export type RenderOutcome = SearchList & {
+type RenderOutcome = SearchList & {
   readonly fileCount: number;
   readonly totalMatches: number;
   readonly itemNoun: string;
 };
 
-export type RenderOptions = {
+type RenderOptions = {
   readonly cwd: string;
   readonly pathFormat: GrepPathFormat;
   readonly context: number;
@@ -60,7 +60,7 @@ export function renderMatches(
   };
 }
 
-export type TitleOptions = {
+type TitleOptions = {
   readonly pattern: string | undefined;
   readonly path: string | undefined;
   readonly glob: string | undefined;
@@ -81,10 +81,9 @@ export type GrepViewDetails = {
   readonly fileCount?: number;
 };
 
-export type GrepViewInput = {
-  /** Partially streamed while the call is in flight; every field is optional. */
+type GrepViewInput = {
   readonly args: Partial<GrepInput>;
-  /** The result body the tool already rendered for the model; empty in flight. */
+  /** Empty while in flight. */
   readonly body: string;
   readonly details?: GrepViewDetails;
   readonly cwd: string;

package/packages/core/src/extensions/grep/schema.ts

@@ -2,15 +2,11 @@ import { StringEnum } from "@earendil-works/pi-ai";
 import { type Static, Type } from "typebox";
 
 export const GREP_HEAD_LIMIT_MAX = 1000;
-export const GREP_CONTEXT_MAX = 20;
+const GREP_CONTEXT_MAX = 20;
 
-export const GREP_OUTPUT_MODES = [
-  "files_with_matches",
-  "content",
-  "count",
-] as const;
+const GREP_OUTPUT_MODES = ["files_with_matches", "content", "count"] as const;
 
-export const GREP_PATH_FORMATS = ["relative", "absolute"] as const;
+const GREP_PATH_FORMATS = ["relative", "absolute"] as const;
 
 export const grepSchema = Type.Object({
   pattern: Type.String({

package/packages/core/src/extensions/read/ImageMemory.ts

@@ -1,23 +1,17 @@
 import { PimSettings } from "../../shared/PimSettings";
 import type { ReadImageDetails } from "./schema";
 
-/** What the file looked like when its picture was last sent to the model. */
-export type ImageStamp = {
+type ImageStamp = {
   readonly mtimeMs: number;
   readonly size: number;
 };
 
 type Sent = ImageStamp & { readonly details: ReadImageDetails };
 
-/**
- * The pictures already in this conversation, so a screenshot loop pays the
- * resize once. One instance per extension factory, which is one per session;
- * a resumed session starts empty and re-sends every image once.
- */
+/** Images already sent this session, keyed by path. A resumed session starts empty. */
 export class ImageMemory {
   private readonly sent = new Map<string, Sent>();
 
-  /** The settings flag is the escape hatch, so it is read only once a picture repeats. */
   async recall(
     path: string,
     stamp: ImageStamp

package/packages/core/src/extensions/read/image.ts

@@ -11,18 +11,18 @@ export type ImageReadOutcome = {
   readonly details: ReadImageDetails;
 };
 
-/** The picture is already in the transcript: the row still draws it, the model is only told so. */
+/** Already sent earlier; the model only gets a note. */
 export type UnchangedImageReadOutcome = {
   readonly kind: "image-unchanged";
   readonly details: ReadImageDetails;
 };
 
-/** Bytes that are a picture, or a name that claims one — a claim that fails is a diagnostic, not text. */
+/** True for image bytes or an image filename; a bad image then errors rather than reading as text. */
 export function isImageRead(head: Uint8Array, path: string): boolean {
   return Images.sniff(head) !== null || Images.looksLikeImageName(path);
 }
 
-/** Both refusals that must land before the file is pulled into memory. */
+/** Checks to run before loading the file into memory. */
 export function assertImageReadable(
   path: string,
   sizeOnDisk: number,

package/packages/core/src/extensions/read/index.ts

@@ -68,20 +68,8 @@ export default function (pi: ExtensionAPI): void {
         });
       }
 
-      return {
-        content,
-        details: {
-          kind: "text",
-          absolutePath,
-          totalLines: outcome.totalLines,
-          visibleStart: outcome.visibleStart,
-          visibleEnd: outcome.visibleEnd,
-          truncatedByByteCap: outcome.truncatedByByteCap,
-          truncatedByEnd: outcome.truncatedByEnd,
-          hadBom: outcome.hadBom,
-          nextStart: outcome.nextStart,
-        },
-      };
+      const { body: _body, ...text } = outcome;
+      return { content, details: { ...text, absolutePath } };
     },
     toViewModel: readView,
   });

package/packages/core/src/extensions/read/read.ts

@@ -30,9 +30,8 @@ export type ReadOutcome =
   | ImageReadOutcome
   | UnchangedImageReadOutcome;
 
-export type ReadOptions = {
+type ReadOptions = {
   readonly model?: VisionModel;
-  /** The pictures this session has already sent; absent when the caller keeps none. */
   readonly memory?: ImageMemory;
 };
 
@@ -75,7 +74,7 @@ export async function readFile(
 
   const file = Bun.file(path);
 
-  // One head serves both verdicts: the signature is in its first bytes, a NUL anywhere in it.
+  // Sniffs both the image signature and binary-ness.
   const head = await bytesOf(file.slice(0, Lines.binarySniffBytes), path);
 
   if (isImageRead(head, path)) {
@@ -113,7 +112,7 @@ async function bytesOf(file: Bun.BunFile, path: string): Promise<Uint8Array> {
   try {
     return await file.bytes();
   } catch (error) {
-    rethrowFsError(error, path, "read");
+    rethrowFsError(error, path);
   }
 }
 
@@ -178,7 +177,7 @@ function renderText(
   };
 }
 
-function rethrowFsError(error: unknown, path: string, action: string): never {
+function rethrowFsError(error: unknown, path: string): never {
   const code = FsErrors.code(error);
 
   if (code === "EACCES" || code === "EPERM") {
@@ -186,6 +185,6 @@ function rethrowFsError(error: unknown, path: string, action: string): never {
   }
 
   throw new Error(
-    `Cannot ${action} ${path}: ${code ?? (error instanceof Error ? error.message : "unknown error")}.`
+    `Cannot read ${path}: ${code ?? (error instanceof Error ? error.message : "unknown error")}.`
   );
 }

package/packages/core/src/extensions/read/render.ts

@@ -44,7 +44,7 @@ function titleBlock(
   return { kind: "file", path, range: [input.start ?? 1, input.end] };
 }
 
-/** Legacy sessions predate the tag, so an untagged result is read for the range it may still carry. */
+/** Legacy details have no `kind`, so check the fields. */
 function visibleRange(
   details: ReadDetails | undefined
 ): readonly [number, number] | undefined {