@akanjs/devkit 3.0.0-beta.19 → 3.0.0-beta.20

package/codeAgent/agent/CodeAgentEventMapper.ts

@@ -8,6 +8,7 @@ import {
   codeAgentLabelChars,
   codeAgentOutputChars,
 } from "akanjs/common";
+import { stringArg } from "./stringArg";
 
 const toolOps: { [key: string]: CodeAgentToolOp } = {
   read: "read",
@@ -19,13 +20,7 @@ const toolOps: { [key: string]: CodeAgentToolOp } = {
   bash: "execute",
 };
 
-/**
- * Narrows the engine's event stream into the akan wire.
- *
- * One turn here is one user prompt, not one LLM round trip: the engine's `turn_start` fires once per round trip
- * inside a run, which is an engine detail no host should have to fold. `agent_start`/`agent_end` are the
- * boundaries a person perceives, so they become our `turn_start`/`turn_end`.
- */
+// A turn is one prompt: the engine's `turn_start` fires per LLM round trip, so `agent_start`/`agent_end` bound it.
 export class CodeAgentEventMapper {
   #turn = 0;
   #turnId = "";
@@ -46,8 +41,7 @@ export class CodeAgentEventMapper {
         this.#outcome = undefined;
         return [{ type: "turn_start", turnId: this.#turnId }];
       case "agent_end":
-        // `turn_end` is last by contract. The engine finalizes the assistant message before the run ends even
-        // when the run was aborted, so a host that closes the turn on this frame has already seen it.
+        // `turn_end` is last by contract; the engine finalizes the message before the run ends, even on abort.
         return [
           ...this.flushBlocked(),
           { type: "turn_end", turnId: this.#turnId, stopReason: this.#stopReason(event) },
@@ -103,14 +97,7 @@ export class CodeAgentEventMapper {
     }
   }
 
-  /**
-   * Records that a call was refused before it ran.
-   *
-   * The refusal arrives in the `tool_call` hook, which fires **before** `tool_execution_start` — measured: a
-   * blocked call produces no start event at all, and then a `tool_execution_end` carrying `isError`. So the
-   * start frame is synthesised here and the engine's own end frame is relabelled `blocked`, rather than
-   * synthesising a terminal frame that would arrive twice.
-   */
+  // The engine sends a blocked call no start event, only an `isError` end: synthesise the start, relabel the end.
   markBlocked(toolCallId: string, toolName: string, args: unknown, reason: string): CodeAgentEventBody[] {
     this.#blocked.set(toolCallId, reason);
     if (this.#openTools.has(toolCallId)) return [];
@@ -155,25 +142,12 @@ export class CodeAgentEventMapper {
     };
   }
 
-  /**
-   * Records how this turn is ending, from the side that actually knows.
-   *
-   * Consumed once, by the next `agent_end`. See {@link CodeAgentEventMapper.#stopReason} for why the engine's
-   * own report cannot be trusted for this.
-   */
+  /** Consumed once, by the next `agent_end`, and wins over the engine's own stop reason. */
   noteOutcome(reason: CodeAgentStopReason) {
     this.#outcome = reason;
   }
 
-  /**
-   * **The engine does not report an abort.** Measured: interrupting a streaming turn finalizes the partial
-   * assistant message with `stopReason: "stop"` — the provider stream was cut, and from the engine's side that
-   * is an ordinary stop. Trusting it reports `done` for every interrupt, and a host then has no way to tell a
-   * finished answer from a truncated one.
-   *
-   * So the core's own record wins: it is the party that called `abort()`, and the party that suspended the
-   * turn to ask a question. The engine's report is only the fallback.
-   */
+  // The engine reports an interrupted stream as `stop`, so the core's own note wins and the engine's is a fallback.
   #stopReason(event: Extract<AgentSessionEvent, { type: "agent_end" }>): CodeAgentStopReason {
     const noted = this.#outcome;
     this.#outcome = undefined;
@@ -182,15 +156,13 @@ export class CodeAgentEventMapper {
     const last = event.messages.at(-1) as { stopReason?: string } | undefined;
     if (last?.stopReason === "aborted") return "aborted";
     if (last?.stopReason === "error") return "error";
-    // The engine's vocabulary is `stop | length | toolUse | error | aborted`. Branching on only the two that
-    // read as failures lets `length` — the model hitting its output cap — leave as `done`, and a half-written
-    // answer is then stored, and replayed to the next turn, as a finished one.
+    // `length` is the model hitting its output cap: a half-written answer must not be stored as `done`.
     if (last?.stopReason === "length") return "truncated";
     return "done";
   }
 
   #summary(toolCallId: string, name: string, args: unknown): CodeAgentToolSummary {
-    const path = CodeAgentEventMapper.#pathOf(args);
+    const path = stringArg(args, "path");
     return {
       toolCallId,
       name,
@@ -215,16 +187,6 @@ export class CodeAgentEventMapper {
     return [{ type: "message", turnId: this.#turnId, role: message.role, text }];
   }
 
-  static #pathOf(args: unknown) {
-    if (!args || typeof args !== "object") return undefined;
-    const value = (args as { path?: unknown }).path;
-    return typeof value === "string" && value ? value : undefined;
-  }
-
-  /**
-   * A one-line rendering, never the values themselves: a `write` call's argument is the whole new file body and
-   * an `edit` call's is every replacement in it.
-   */
   static #renderArgs(args: unknown) {
     if (!args || typeof args !== "object") return "";
     const entries = Object.entries(args as Record<string, unknown>).filter(([, value]) => value !== undefined);
@@ -233,12 +195,7 @@ export class CodeAgentEventMapper {
     return `(${codeAgentClip(rendered, 120)})`;
   }
 
-  /**
-   * A structured argument is described by its shape, not stringified.
-   *
-   * `String({})` is `"[object Object]"` and an array of them is that repeated — which is where an `edit` call's
-   * replacement list ends up, so the row says nothing about a call that changed three places in a file.
-   */
+  // By shape, not `String()`, which renders an `edit` call's replacement list as `[object Object]`s.
   static #renderArgValue(value: unknown) {
     if (Array.isArray(value)) return `${value.length} item${value.length === 1 ? "" : "s"}`;
     if (value && typeof value === "object") {

package/codeAgent/agent/CodeAgentGate.ts

@@ -1,5 +1,6 @@
 import path from "node:path";
 import type { CodeAgentProfile } from "akanjs/common";
+import { stringArg } from "./stringArg";
 
 const writeTools = new Set(["write", "edit"]);
 const commandTools = new Set(["bash"]);
@@ -10,13 +11,7 @@ export interface GateVerdict {
   approval?: string;
 }
 
-/**
- * Decides, per tool call, whether the profile lets it through, needs a human, or is refused outright.
- *
- * Paths are checked here rather than inside a replacement for the engine's file operations because a refusal
- * has to reach the model as a reason it can act on. An operations port that throws produces a stack trace the
- * model reads as a bug in the tool, and it retries.
- */
+// Gated here, not in the engine's file-ops port: a throw there reads to the model as a tool bug, and it retries.
 export class CodeAgentGate {
   readonly #profile: CodeAgentProfile;
   readonly #deny: Bun.Glob[];
@@ -31,12 +26,12 @@ export class CodeAgentGate {
   }
 
   verdict(toolName: string, args: unknown): GateVerdict {
-    const target = CodeAgentGate.#pathOf(args);
+    const target = stringArg(args, "path");
     if (target) {
       const denied = this.#deniedReason(target);
       if (denied) return { block: denied };
     }
-    const command = CodeAgentGate.#commandOf(args);
+    const command = stringArg(args, "command");
     if (command) {
       const denied = this.#deniedCommandReason(command);
       if (denied) return { block: denied };
@@ -45,15 +40,8 @@ export class CodeAgentGate {
     return { approval: CodeAgentGate.#summarize(toolName, args) };
   }
 
-  /**
-   * A shell command naming a denied file is refused on the literal text.
-   *
-   * ⚠️ **This is a speed bump, not a boundary.** A shell can reach any path the process can — through a
-   * variable, a glob, a subshell, `base64`, anything — and gating it properly would mean interpreting the
-   * command. The real boundary is the container the `pod` profile runs in. What this does buy is that the
-   * obvious accident, `cat .env`, does not put a live key into a transcript that is then persisted and
-   * replayed on every later turn.
-   */
+  // A speed bump, not a boundary: a shell reaches any path; the real boundary is the `pod` profile's container.
+  // It stops the obvious accident (`cat .env`) from persisting a live key into the transcript.
   #deniedCommandReason(command: string) {
     const hit = this.#deniedFragments.find((fragment) => command.includes(fragment));
     if (!hit) return undefined;
@@ -87,9 +75,7 @@ export class CodeAgentGate {
     }
   }
 
-  // A recursive secrets glob is only useful as the literal `secrets/`; a glob cannot be matched against a shell
-  // line. A pattern with a wildcard left in the middle yields nothing matchable, so it is dropped rather than
-  // guessed at.
+  // A glob cannot match a shell line, so a deny pattern is reduced to a literal; a mid-pattern wildcard is dropped.
   static #fragmentOf(pattern: string) {
     const trimmed = pattern
       .replace(/^\*\*\//, "")
@@ -98,22 +84,10 @@ export class CodeAgentGate {
     return trimmed.includes("*") ? "" : trimmed;
   }
 
-  static #commandOf(args: unknown) {
-    if (!args || typeof args !== "object") return undefined;
-    const value = (args as { command?: unknown }).command;
-    return typeof value === "string" && value ? value : undefined;
-  }
-
-  static #pathOf(args: unknown) {
-    if (!args || typeof args !== "object") return undefined;
-    const value = (args as { path?: unknown }).path;
-    return typeof value === "string" && value ? value : undefined;
-  }
-
   static #summarize(toolName: string, args: unknown) {
     const record = (args ?? {}) as Record<string, unknown>;
     if (toolName === "bash") return `run: ${String(record.command ?? "").slice(0, 200)}`;
-    const target = CodeAgentGate.#pathOf(args);
+    const target = stringArg(args, "path");
     return target ? `${toolName} ${target}` : toolName;
   }
 }

package/codeAgent/agent/CodeAgentProxy.ts

@@ -17,12 +17,7 @@ export interface CodeAgentProxyOptions {
   token?: string;
 }
 
-/**
- * Routes every model request through a host's LLM proxy, so a pod never holds a provider key: the host mints a
- * short-lived token, writes it to a file, and rotates it there while the worker keeps running.
- *
- * `baseUrl` may carry `{provider}` for a proxy that fronts several providers under one host.
- */
+/** `baseUrl` may carry `{provider}` for a proxy that fronts several providers under one host. */
 export class CodeAgentProxy {
   static readonly placeholderKey = "akan-code-proxy";
 
@@ -59,8 +54,7 @@ export class CodeAgentProxy {
     return this.baseUrl.replaceAll("{provider}", provider);
   }
 
-  //* Read per request, not cached: the host rotates a token that outlives no single turn, and a worker holding the
-  //* first one would start failing half an hour into a session it is still running.
+  //* Read per request, not cached: the host rotates the token while a session is still running.
   async token() {
     if (!this.#tokenFile) return this.#token ?? "";
     const token = (await readFile(this.#tokenFile, "utf8")).trim();
@@ -68,11 +62,8 @@ export class CodeAgentProxy {
     return token;
   }
 
-  /**
-   * `prepareRequest` is the one path every stream, completion, compaction and cache-warm request takes, which is
-   * why it is wrapped rather than the public stream methods. It is private in the engine's typings, so its
-   * absence after an engine upgrade fails here at boot instead of sending a request with no key.
-   */
+  // `prepareRequest` is the one path every request takes. It is engine-private, so an upgrade that drops it must
+  // fail here at boot rather than send a request with no key.
   async apply(runtime: ModelRuntime) {
     const target = runtime as unknown as { prepareRequest?: PrepareRequest };
     const original = target.prepareRequest?.bind(runtime);

package/codeAgent/agent/CodeAgentRpcHost.ts

@@ -1,16 +1,7 @@
 import type { CodeAgentCommand, CodeAgentEvent, CodeAgentReply, CodeAgentRequest } from "akanjs/common";
 import type { CodeAgent } from "./CodeAgent";
 
-/**
- * Serves one code agent as newline-delimited akan wire frames, over stdio or whatever transport attaches.
- *
- * The protocol is **ours**, not the engine's: a host — the web relay, a pod runner, a test harness — reads the
- * same events the in-process API emits, so an engine upgrade stops at the core instead of reaching every
- * consumer.
- *
- * stdout carries frames and nothing else. That only holds because `consoleToStderr` was imported before the
- * engine: under Bun the engine's own stdout guard misses `console.log`, which writes to fd 1 natively.
- */
+// stdout carries only frames because `consoleToStderr` was imported before the engine (Bun's console bypasses it).
 export class CodeAgentRpcHost {
   readonly #agent: CodeAgent;
   #write: ((line: string) => void) | null;
@@ -40,8 +31,7 @@ export class CodeAgentRpcHost {
     this.#agent.announce();
   }
 
-  //* Frames emitted while no client is attached are dropped here and kept in the agent's replay buffer; a client
-  //* that attaches catches up with `get_state { sinceSeq }` instead of receiving a burst it did not ask for.
+  //* Frames with no client attached are dropped; the next client catches up with `get_state { sinceSeq }`.
   attach(write: ((line: string) => void) | null) {
     this.#write = write;
     this.#buffer = "";
@@ -74,10 +64,7 @@ export class CodeAgentRpcHost {
     if (request.command?.type === "shutdown") this.#resolveShutdown();
   }
 
-  /**
-   * `prompt` answers as soon as the turn is accepted, not when it finishes — a client that had to wait for the
-   * reply could not send `abort`, which is the one command that matters while a turn runs.
-   */
+  // `prompt` replies on acceptance, not completion, so the client can still send `abort` while the turn runs.
   async #run(command: CodeAgentCommand): Promise<unknown> {
     switch (command.type) {
       case "prompt":

package/codeAgent/agent/CodeAgentRpcListener.ts

@@ -9,16 +9,8 @@ interface ClientState {
   decoder: TextDecoder;
 }
 
-/**
- * `akan code --rpc-listen <unix:PATH | tcp:[HOST:]PORT>` — the RPC host on a socket instead of stdio, so the agent
- * outlives the process driving it. A control plane that restarts reconnects and resumes with
- * `get_state { sinceSeq }`; the turn it was watching kept running in the meantime.
- *
- * One client at a time: a new connection replaces the old one, which is what a reconnecting control plane whose
- * previous socket has not timed out yet needs. TCP binds 127.0.0.1 unless a host is named, because the wire has
- * no authentication of its own — reach a pod through its unix socket and whatever the orchestrator already
- * authenticates.
- */
+// One client at a time: a reconnecting control plane replaces a socket that has not timed out yet.
+// TCP binds 127.0.0.1 unless a host is named, because the wire has no authentication of its own.
 export class CodeAgentRpcListener {
   readonly #host: CodeAgentRpcHost;
   readonly #address: CodeAgentRpcAddress;

package/codeAgent/agent/CodeAgentStreamPrinter.ts

@@ -8,12 +8,6 @@ export interface CodeAgentStreamPrinterOptions {
   write?: (text: string) => void;
 }
 
-/**
- * Prints the akan wire to a terminal, reading nothing but the contract.
- *
- * That restriction is the point: the TUI and the web host read the same events, so anything this printer cannot
- * render is a hole in the contract rather than a missing feature of one host.
- */
 export class CodeAgentStreamPrinter {
   readonly #options: CodeAgentStreamPrinterOptions;
   readonly #write: (text: string) => void;
@@ -34,28 +28,23 @@ export class CodeAgentStreamPrinter {
         if (!this.#options.thinking) return;
         this.#streaming = true;
         return this.#write(chalk.dim(event.text));
-      case "message":
-        return;
       case "tool_start":
         return this.#line(chalk.cyan(`→ ${event.tool.title}`));
-      case "tool_progress":
-        return;
       case "tool_end":
         return this.#line(CodeAgentStreamPrinter.#toolEnd(event));
       case "session":
         return this.#line(chalk.dim(codeAgentEventLabel(event)));
       case "turn_end":
-        // Every other reason is one the operator already knows: they typed the prompt, or pressed the key.
-        // A truncated answer is the one that looks exactly like a finished one unless it is said out loud.
+        // Only `truncated` is said: a cut answer looks exactly like a finished one.
         if (event.stopReason === "truncated") return this.#line(chalk.yellow(codeAgentEventLabel(event)));
         return;
+      case "message":
+      case "tool_progress":
       case "turn_start":
       case "idle":
       case "queue":
       case "context":
-        return;
-      // The rail is a live status for a screen that redraws. A stream has no row to update, and the pool
-      // already says on the transcript when a child starts and what it spent when it stops.
+      // A stream has no rail to redraw; the pool already reports a child's start and cost as notices.
       case "subagent":
         return;
       case "question":

package/codeAgent/agent/CodeAgentSuspended.ts

@@ -7,14 +7,7 @@ interface SuspendedState {
   approvals: CodeAgentApprovalRequest[];
 }
 
-/**
- * What a suspending profile is waiting on after its turn ended — the question it asked and the approvals it
- * parked. The turn is gone, so nothing in memory holds them; this does, and on a file-backed session it writes
- * them beside the session so a worker that restarts and resumes still knows what it asked.
- *
- * Taking an ask removes it, which is what makes an answer idempotent: a second tab or a retried frame finds
- * nothing to take and is refused instead of opening a second turn.
- */
+// Taking an ask removes it, which makes an answer idempotent: a second tab or a retried frame finds nothing.
 export class CodeAgentSuspended {
   readonly #file: string | null;
   #state: SuspendedState;

package/codeAgent/agent/CodeAgentUi.ts

@@ -5,13 +5,8 @@ export interface CodeAgentUiHandlers {
   notify(level: "info" | "warning" | "error", message: string): void;
 }
 
-/**
- * The engine's UI port, answered by the akan wire instead of by a terminal.
- *
- * Only the four dialog calls and `notify` mean anything off a TUI; the rest of the port paints widgets, footers
- * and editors that exist solely inside the engine's own interactive shell. They are no-ops here rather than
- * throws — an extension that sets a status line should not take the turn down with it.
- */
+// Only the dialogs and `notify` mean anything off the engine's TUI; the rest are no-ops, not throws, so an
+// extension that sets a status line does not take the turn down with it.
 export class CodeAgentUi {
   readonly #handlers: CodeAgentUiHandlers;
 

package/codeAgent/agent/CodeMailbox.ts

@@ -9,6 +9,7 @@ import {
   writeFileSync,
 } from "node:fs";
 import path from "node:path";
+import { parseJsonLine, readJsonLines } from "./jsonLines";
 
 export interface CodePeer {
   id: string;
@@ -26,18 +27,9 @@ export interface CodeMail {
   text: string;
 }
 
-/**
- * How two `akan code` sessions in one workspace reach each other.
- *
- * A directory, not a socket or a daemon: the sessions already share a checkout and already write their
- * transcripts there, and a mailbox on disk survives one end restarting, needs nothing listening to accept a
- * message, and is inspectable with `cat` when a message does not arrive.
- *
- * Presence is a heartbeat file rather than a registration, because the interesting failure is a session that
- * died without saying so — a registry would keep listing it forever, while a stale mtime says it is gone.
- */
+// A directory, not a socket or daemon: it survives either end restarting and needs nothing listening.
+// Presence is a heartbeat file, not a registration, so a session that died silently goes stale on its own.
 export class CodeMailbox {
-  /** A session older than this said nothing for four heartbeats, so it is not there to answer. */
   static readonly staleMs = 20_000;
   static readonly beatMs = 5_000;
   static readonly pollMs = 1_500;
@@ -66,9 +58,8 @@ export class CodeMailbox {
   open(cwd: string, onMail: (mail: CodeMail) => void) {
     mkdirSync(path.join(this.#dir, "live"), { recursive: true });
     mkdirSync(path.join(this.#dir, "inbox"), { recursive: true });
-    // Whatever was already in the inbox belongs to an earlier run of this session, which has read it or is
-    // never going to; delivering it now would replay a conversation that already happened.
-    this.#read = CodeMailbox.#lines(this.inbox).length;
+    // What is already in the inbox belongs to an earlier run; delivering it would replay a past conversation.
+    this.#read = readJsonLines(this.inbox).length;
     this.beat(cwd);
     this.#beat = setInterval(() => this.beat(cwd), CodeMailbox.beatMs);
     this.#poll = setInterval(() => {
@@ -137,12 +128,12 @@ export class CodeMailbox {
   }
 
   #drain(): CodeMail[] {
-    const lines = CodeMailbox.#lines(this.inbox);
+    const lines = readJsonLines(this.inbox);
     if (lines.length <= this.#read) return [];
     const fresh = lines.slice(this.#read);
     this.#read = lines.length;
     return fresh
-      .map((line) => CodeMailbox.#parse(line))
+      .map((line) => parseJsonLine<CodeMail>(line))
       .filter((mail): mail is CodeMail => !!mail?.text && typeof mail.from === "string");
   }
 
@@ -154,22 +145,4 @@ export class CodeMailbox {
       return undefined;
     }
   }
-
-  static #lines(file: string) {
-    try {
-      return readFileSync(file, "utf8")
-        .split("\n")
-        .filter((line) => !!line.trim());
-    } catch {
-      return [];
-    }
-  }
-
-  static #parse(line: string) {
-    try {
-      return JSON.parse(line) as CodeMail;
-    } catch {
-      return undefined;
-    }
-  }
 }

package/codeAgent/agent/CodeSessionFork.ts

@@ -3,6 +3,7 @@ import { readFileSync, writeFileSync } from "node:fs";
 import path from "node:path";
 import { codeAgentSessionName } from "akanjs/common";
 import { CodeSessionIndex } from "./CodeSessionIndex";
+import { parseJsonLine } from "./jsonLines";
 
 interface CodeSessionRecord {
   [key: string]: unknown;
@@ -10,14 +11,7 @@ interface CodeSessionRecord {
   id?: string;
 }
 
-/**
- * Copies a session's file so one conversation can continue two ways.
- *
- * A fork is a file copy because that is exactly what a session is: an append-only log the engine replays. The
- * copy is rewritten in one place — the `session` record's id — and then the two files know nothing about each
- * other, which is the property that matters. Sharing an id instead would give two live agents one inbox, one
- * presence entry and one resume target, and the second one to write would win silently.
- */
+// Only the `session` record's id is rewritten: a shared id would give two agents one inbox and one resume target.
 export class CodeSessionFork {
   static fork(dir: string, id: string, name?: string) {
     const source = CodeSessionIndex.fileOf(dir, id);
@@ -29,15 +23,14 @@ export class CodeSessionFork {
     const at = new Date();
     const forked = Bun.randomUUIDv7();
     const records = lines
-      .map((line) => CodeSessionFork.#parse(line))
+      .map((line) => parseJsonLine<CodeSessionRecord>(line))
       .filter((record): record is CodeSessionRecord => !!record);
     const first = records.find((record) => record.type === "session");
     if (!first) throw new Error(`Session ${id} carries no session record`);
     first.id = forked;
     first.timestamp = at.toISOString();
     records.push(CodeSessionFork.#named(records, name ?? CodeSessionFork.#nameOf(records), at));
-    // The name is the timestamp the file was created plus the id, which is the shape the engine writes and
-    // what `CodeSessionIndex` matches on when a resume names one.
+    // The engine's own file-name shape, which `CodeSessionIndex.fileOf` matches a resume against.
     const file = path.join(dir, `${at.toISOString().replace(/[:.]/g, "-")}_${forked}.jsonl`);
     writeFileSync(file, `${records.map((record) => JSON.stringify(record)).join("\n")}\n`);
     return { id: forked, file };
@@ -60,12 +53,4 @@ export class CodeSessionFork {
     const current = typeof named?.name === "string" ? named.name : "";
     return codeAgentSessionName(current ? `${current} fork` : "fork");
   }
-
-  static #parse(line: string) {
-    try {
-      return JSON.parse(line) as CodeSessionRecord;
-    } catch {
-      return undefined;
-    }
-  }
 }

package/codeAgent/agent/CodeSessionIndex.ts

@@ -1,5 +1,6 @@
-import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { existsSync, readdirSync, statSync } from "node:fs";
 import path from "node:path";
+import { parseJsonLine, readJsonLines } from "./jsonLines";
 
 export interface CodeSessionEntry {
   id: string;
@@ -12,15 +13,8 @@ export interface CodeSessionEntry {
   turns: number;
 }
 
-/**
- * The sessions on disk, read as files rather than through the engine.
- *
- * The engine's session manager addresses one session at a time — it can open a file and append to it, and has
- * nothing that enumerates the directory. The format is self-describing JSONL, so the listing is a read of
- * lines we already own the shape of, and it costs no engine instance to produce.
- */
+// Read as files: the engine's session manager has nothing that enumerates the directory.
 export class CodeSessionIndex {
-  /** Past this, a file is a session long enough that its opening lines are far from the interesting part. */
   static readonly readLimit = 512 * 1024;
 
   static list(dir: string, limit = 30): CodeSessionEntry[] {
@@ -52,11 +46,11 @@ export class CodeSessionIndex {
   }
 
   static #read(file: string, updatedAt: number): CodeSessionEntry | undefined {
-    const lines = CodeSessionIndex.#lines(file);
+    const lines = readJsonLines(file, CodeSessionIndex.readLimit);
     if (!lines.length) return undefined;
     const entry: CodeSessionEntry = { id: "", file, name: undefined, opening: "", updatedAt, turns: 0 };
     for (const line of lines) {
-      const record = CodeSessionIndex.#parse(line);
+      const record = parseJsonLine<{ [key: string]: unknown; type?: string }>(line);
       if (!record) continue;
       if (record.type === "session" && typeof record.id === "string") entry.id = record.id;
       // A rename appends a second entry rather than editing the first, so the last one on the file wins.
@@ -70,26 +64,6 @@ export class CodeSessionIndex {
     return entry.id ? entry : undefined;
   }
 
-  static #lines(file: string) {
-    try {
-      if (statSync(file).size > CodeSessionIndex.readLimit) return [];
-      return readFileSync(file, "utf8")
-        .split("\n")
-        .filter((line) => !!line.trim());
-    } catch {
-      return [];
-    }
-  }
-
-  static #parse(line: string): { [key: string]: unknown; type?: string } | undefined {
-    try {
-      return JSON.parse(line) as { type?: string };
-    } catch {
-      return undefined;
-    }
-  }
-
-  /** One line, always: the opening ask is a label in a list, and a pasted stack trace is not a label. */
   static #text(content: unknown) {
     const text =
       typeof content === "string"