pennyrouter 0.2.9 → 0.2.11

package/src/thread-session-codex.js

@@ -0,0 +1,152 @@
+/* Write a canonical thread into a Codex rollout it will resume from.
+
+   `codex resume <session-id>` reads ~/.codex/sessions/YYYY/MM/DD/rollout-<stamp>-<uuid>.jsonl,
+   so a synthesized rollout in that tree resumes like any other session. Verified end-to-end on
+   codex-cli 0.146.0: a file written by this shape resumed and the model answered from history it
+   never lived.
+
+   The format differs from Claude Code's in every structural respect, which is why this is a
+   separate writer rather than a flag on the other one:
+
+     - Records are a {timestamp, type, payload} envelope, not flat message objects.
+     - There is no parentUuid chain. Order in the file IS the order; nothing to link.
+     - The first record is a `session_meta` header carrying cwd, cli_version and the id.
+     - User content is `input_text`; assistant content is `output_text`. Using the wrong key
+       for a role is the one mistake that produces a file which loads but renders empty.
+     - Ids are UUIDv7 (time-ordered), and both the filename stamp and the id encode when the
+       session began. Codex sorts its picker by these, so a random v4 sorts to 1970.
+
+   THE FORMAT IS UNDOCUMENTED, exactly as with Claude Code, and the same three rules apply:
+   never overwrite, version-gate, and fail loudly rather than write something that only reveals
+   itself as broken at resume time. */
+
+import { randomBytes } from "node:crypto";
+import { mkdirSync, existsSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+import { orientation, renderMessage } from "./thread-session.js";
+
+/** Versions this writer has been verified against. */
+export const VERIFIED_MIN = "0.100.0";
+export const VERIFIED_MAX = "0.999.999";
+
+/** UUIDv7: 48-bit big-endian millisecond timestamp, then version/variant bits, then random.
+    Codex orders sessions by this, so a v4 would sort as if it began in 1970. */
+export function uuidv7(now = Date.now()) {
+  const bytes = randomBytes(16);
+  const ms = BigInt(now);
+  for (let i = 0; i < 6; i += 1) {
+    bytes[i] = Number((ms >> BigInt(8 * (5 - i))) & 0xffn);
+  }
+  bytes[6] = (bytes[6] & 0x0f) | 0x70;
+  bytes[8] = (bytes[8] & 0x3f) | 0x80;
+  const hex = bytes.toString("hex");
+  return [
+    hex.slice(0, 8),
+    hex.slice(8, 12),
+    hex.slice(12, 16),
+    hex.slice(16, 20),
+    hex.slice(20),
+  ].join("-");
+}
+
+function compare(a, b) {
+  const pa = String(a).split(".").map((n) => parseInt(n, 10) || 0);
+  const pb = String(b).split(".").map((n) => parseInt(n, 10) || 0);
+  for (let i = 0; i < 3; i += 1) {
+    if ((pa[i] || 0) !== (pb[i] || 0)) return (pa[i] || 0) < (pb[i] || 0) ? -1 : 1;
+  }
+  return 0;
+}
+
+export function versionSupported(version) {
+  if (!version) return false;
+  // `codex --version` prints "codex-cli 0.146.0"; take the numeric field wherever it sits.
+  const match = String(version).match(/(\d+\.\d+\.\d+)/);
+  if (!match) return false;
+  return compare(match[1], VERIFIED_MIN) >= 0 && compare(match[1], VERIFIED_MAX) <= 0;
+}
+
+/** ~/.codex/sessions/YYYY/MM/DD — Codex partitions rollouts by date. */
+export function sessionDirFor(date = new Date()) {
+  const yyyy = String(date.getUTCFullYear());
+  const mm = String(date.getUTCMonth() + 1).padStart(2, "0");
+  const dd = String(date.getUTCDate()).padStart(2, "0");
+  return join(homedir(), ".codex", "sessions", yyyy, mm, dd);
+}
+
+/** The stamp embedded in a rollout filename: 2026-08-09T22-15-30. */
+export function fileStamp(date = new Date()) {
+  return date.toISOString().replace(/\.\d+Z$/, "").replace(/:/g, "-");
+}
+
+export function buildRecords(thread, { cwd, sessionId, version, timestamp = new Date() }) {
+  const ts = timestamp.toISOString();
+  const envelope = (type, payload) => ({ timestamp: ts, type, payload });
+
+  const message = (role, text) =>
+    envelope("response_item", {
+      type: "message",
+      id: `msg_${uuidv7(timestamp.getTime())}`,
+      role,
+      // The content key is role-dependent. Swapping them yields a file that loads and shows
+      // nothing, which is the worst failure mode available here.
+      content: [{ type: role === "assistant" ? "output_text" : "input_text", text }],
+    });
+
+  const records = [
+    envelope("session_meta", {
+      session_id: sessionId,
+      id: sessionId,
+      timestamp: ts,
+      cwd,
+      originator: "pennyrouter",
+      cli_version: String(version || "").match(/(\d+\.\d+\.\d+)/)?.[1] || "0.0.0",
+      source: "cli",
+      thread_source: "user",
+      model_provider: "openai",
+      history_mode: "legacy",
+    }),
+    message("user", orientation(thread)),
+    message("assistant", "Understood — I have the imported conversation and will continue from it."),
+  ];
+
+  for (const entry of thread.messages || []) {
+    const text = renderMessage(entry);
+    if (!text) continue;
+    if (entry.role === "assistant") records.push(message("assistant", text));
+    else if (entry.role === "user") records.push(message("user", text));
+  }
+
+  return records;
+}
+
+/**
+ * Write `thread` as a resumable Codex rollout.
+ * Returns { sessionId, path, messageCount }.
+ */
+export function writeSession(thread, { cwd, version, timestamp = new Date() }) {
+  if (!versionSupported(version)) {
+    throw new Error(
+      `Codex ${version || "(unknown version)"} is outside the range this importer has been ` +
+        `verified against (${VERIFIED_MIN}–${VERIFIED_MAX}). Refusing to write a rollout that ` +
+        `may not resume.`,
+    );
+  }
+
+  const dir = sessionDirFor(timestamp);
+  mkdirSync(dir, { recursive: true });
+
+  const sessionId = uuidv7(timestamp.getTime());
+  const path = join(dir, `rollout-${fileStamp(timestamp)}-${sessionId}.jsonl`);
+  if (existsSync(path)) throw new Error("session id collision; try again");
+
+  const records = buildRecords(thread, { cwd, sessionId, version, timestamp });
+  writeFileSync(path, records.map((r) => JSON.stringify(r)).join("\n") + "\n", {
+    encoding: "utf8",
+    flag: "wx", // fail rather than clobber, even against a race
+  });
+
+  return { sessionId, path, messageCount: records.length };
+}

package/src/thread-session-codex.test.js

@@ -0,0 +1,136 @@
+import assert from "node:assert/strict";
+import { mkdtempSync, readFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import {
+  buildRecords,
+  fileStamp,
+  sessionDirFor,
+  uuidv7,
+  versionSupported,
+  writeSession,
+} from "./thread-session-codex.js";
+
+const thread = {
+  title: "Kickplate removal",
+  source: "perplexity_share",
+  origin_app: "Perplexity",
+  source_url: "https://www.perplexity.ai/search/x",
+  messages: [
+    { role: "user", blocks: [{ type: "text", text: "USER-TURN" }] },
+    {
+      role: "assistant",
+      blocks: [
+        { type: "thinking", text: "REASONING-TRACE" },
+        { type: "text", text: "ASSISTANT-TURN" },
+      ],
+    },
+    { role: "system", blocks: [{ type: "text", text: "SYSTEM-PREAMBLE" }] },
+  ],
+};
+
+// -- uuidv7 ---------------------------------------------------------------
+// Codex sorts its session picker by these ids. A random v4 would sort as if the session began
+// in 1970, so the timestamp prefix is not cosmetic.
+{
+  const when = Date.UTC(2026, 7, 9, 22, 15, 30);
+  const id = uuidv7(when);
+  assert.match(id, /^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/);
+  assert.equal(parseInt(id.slice(0, 8) + id.slice(9, 13), 16), when, "ms timestamp is encoded");
+  assert.notEqual(uuidv7(when), uuidv7(when), "the random tail still varies");
+  // Time-ordering is the property Codex depends on.
+  assert.ok(uuidv7(when) < uuidv7(when + 1000));
+}
+
+// -- paths ----------------------------------------------------------------
+{
+  const date = new Date(Date.UTC(2026, 7, 9, 22, 15, 30));
+  assert.ok(sessionDirFor(date).endsWith(join(".codex", "sessions", "2026", "08", "09")));
+  assert.equal(fileStamp(date), "2026-08-09T22-15-30");
+}
+
+// -- version gate ---------------------------------------------------------
+// `codex --version` prints "codex-cli 0.146.0", so the number has to be found, not assumed.
+assert.equal(versionSupported("codex-cli 0.146.0"), true);
+assert.equal(versionSupported("0.100.0"), true);
+assert.equal(versionSupported("0.99.0"), false);
+assert.equal(versionSupported("1.0.0"), false);
+assert.equal(versionSupported("not-a-version"), false);
+assert.equal(versionSupported(null), false);
+
+// -- record construction --------------------------------------------------
+{
+  const records = buildRecords(thread, {
+    cwd: "/tmp/ws",
+    sessionId: "sid-1",
+    version: "codex-cli 0.146.0",
+  });
+
+  // Every record is the {timestamp, type, payload} envelope.
+  for (const record of records) {
+    assert.deepEqual(Object.keys(record).sort(), ["payload", "timestamp", "type"]);
+  }
+
+  const [meta, ...rest] = records;
+  assert.equal(meta.type, "session_meta");
+  assert.equal(meta.payload.session_id, "sid-1");
+  assert.equal(meta.payload.cwd, "/tmp/ws");
+  assert.equal(meta.payload.cli_version, "0.146.0", "the bare number, not the whole string");
+
+  // Content key is role-dependent. Getting this wrong yields a rollout that loads and renders
+  // empty, which is the failure mode least likely to be noticed before a user hits it.
+  for (const record of rest) {
+    assert.equal(record.type, "response_item");
+    assert.equal(record.payload.type, "message");
+    const key = record.payload.content[0].type;
+    assert.equal(key, record.payload.role === "assistant" ? "output_text" : "input_text");
+    assert.match(record.payload.id, /^msg_/);
+  }
+
+  assert.deepEqual(
+    rest.map((r) => r.payload.role),
+    ["user", "assistant", "user", "assistant"],
+  );
+
+  const serialized = JSON.stringify(records);
+  assert.ok(!serialized.includes("REASONING-TRACE"), "thinking must never reach a handoff");
+  assert.ok(!serialized.includes("SYSTEM-PREAMBLE"), "system turns are not replayed");
+  assert.ok(serialized.includes("USER-TURN") && serialized.includes("ASSISTANT-TURN"));
+  assert.ok(rest[0].payload.content[0].text.includes("Perplexity"), "orientation names origin");
+}
+
+// -- writing --------------------------------------------------------------
+{
+  const home = mkdtempSync(join(tmpdir(), "pr-codex-home-"));
+  const originalHome = process.env.HOME;
+  process.env.HOME = home;
+  try {
+    const result = writeSession(thread, { cwd: "/tmp/ws", version: "codex-cli 0.146.0" });
+
+    // The filename carries both the stamp and the id; Codex's picker reads both.
+    assert.match(result.path, /rollout-\d{4}-\d{2}-\d{2}T\d{2}-\d{2}-\d{2}-[0-9a-f-]{36}\.jsonl$/);
+    assert.ok(result.path.includes(result.sessionId));
+
+    const lines = readFileSync(result.path, "utf8").trim().split("\n");
+    assert.equal(lines.length, result.messageCount);
+    const parsed = lines.map((l) => JSON.parse(l));
+    assert.equal(parsed[0].type, "session_meta");
+    assert.equal(parsed[0].payload.id, result.sessionId);
+
+    // Never overwrite an existing session.
+    const again = writeSession(thread, { cwd: "/tmp/ws", version: "codex-cli 0.146.0" });
+    assert.notEqual(again.sessionId, result.sessionId);
+    assert.notEqual(again.path, result.path);
+
+    assert.throws(
+      () => writeSession(thread, { cwd: "/tmp/ws", version: "codex-cli 2.0.0" }),
+      /outside the range/,
+    );
+    assert.throws(() => writeSession(thread, { cwd: "/tmp/ws", version: null }), /outside the range/);
+  } finally {
+    process.env.HOME = originalHome;
+  }
+}
+
+console.log("thread-session-codex tests passed");

package/src/thread-session.js

@@ -0,0 +1,204 @@
+/* Write a canonical thread into a Claude Code session file it will resume from.
+
+   `claude --resume` enumerates ~/.claude/projects/<flattened-cwd>/*.jsonl and offers what it
+   finds, so a synthesized file appears in the picker and resumes with the history in context.
+   Verified end-to-end on 2.1.226: a file written by this shape resumed and the model quoted back
+   a turn it never actually saw.
+
+   THE FORMAT IS UNDOCUMENTED. It is read from ~140 real local sessions, not from a spec, and
+   Claude Code updates itself. Three rules follow, and none of them are optional:
+
+     1. Never write over an existing session. Every synthesis gets a fresh uuid, so the worst
+        case is a stray file in the picker rather than a destroyed conversation.
+     2. Version-gate. Outside the range this was verified against, write the brief instead of a
+        session file and say so — a malformed session file is worse than no session file,
+        because the user finds out at resume time.
+     3. Records must chain. `parentUuid` is a linked list; a break in it truncates the history
+        silently, which looks like a working import that lost half the conversation.
+
+   Only `user` and `assistant` records are needed to reconstruct a conversation. Tool blocks are
+   deliberately NOT replayed as `tool_use`/`tool_result` pairs: those reference call ids the new
+   session's tools never issued, and a dangling pair is the one thing observed to make a resumed
+   session misbehave rather than merely look odd. They are rendered as prose instead. */
+
+import { randomUUID } from "node:crypto";
+import { mkdirSync, existsSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+/** Versions this writer has been verified against. */
+export const VERIFIED_MIN = "2.0.0";
+export const VERIFIED_MAX = "2.999.999";
+
+export function projectDirFor(cwd) {
+  // Claude Code flattens the workspace path into a single directory name: every separator and
+  // dot becomes "-". Confirmed against the real ~/.claude/projects listing.
+  return join(homedir(), ".claude", "projects", cwd.replace(/[/\\.]/g, "-"));
+}
+
+function compare(a, b) {
+  const pa = String(a).split(".").map((n) => parseInt(n, 10) || 0);
+  const pb = String(b).split(".").map((n) => parseInt(n, 10) || 0);
+  for (let i = 0; i < 3; i += 1) {
+    if ((pa[i] || 0) !== (pb[i] || 0)) return (pa[i] || 0) < (pb[i] || 0) ? -1 : 1;
+  }
+  return 0;
+}
+
+export function versionSupported(version) {
+  if (!version) return false;
+  const clean = String(version).trim().split(/\s+/)[0];
+  return compare(clean, VERIFIED_MIN) >= 0 && compare(clean, VERIFIED_MAX) <= 0;
+}
+
+/** One block rendered as the text a resumed model should read. */
+function renderBlock(block) {
+  switch (block?.type) {
+    case "text":
+      return block.text || "";
+    case "thinking":
+      // One model's reasoning trace is noise to a different model picking the work up.
+      return "";
+    case "tool_use": {
+      const input = block.input ? ` ${JSON.stringify(block.input)}` : "";
+      return `[used ${block.name}${input}]`.slice(0, 2000);
+    }
+    case "tool_result": {
+      const status = block.ok === false ? "failed" : "result";
+      return `[${block.name || "tool"} ${status}] ${block.output || ""}`.slice(0, 2000);
+    }
+    case "file":
+      return ["```" + (block.language || ""), block.text || "", "```"].join("\n");
+    case "diff":
+      return ["```diff", block.patch || "", "```"].join("\n");
+    case "image":
+      return `[image${block.alt ? `: ${block.alt}` : ""}]`;
+    default:
+      return "";
+  }
+}
+
+export function renderMessage(message) {
+  return (message.blocks || [])
+    .map(renderBlock)
+    .filter((t) => t && t.trim())
+    .join("\n\n")
+    .trim();
+}
+
+/** The record that tells the resumed agent what it is looking at. */
+export function orientation(thread) {
+  const origin = thread.origin_app || thread.source || "another assistant";
+  return [
+    `This session was imported by PennyRouter from a ${origin} conversation.`,
+    thread.source_url ? `Source: ${thread.source_url}` : null,
+    "",
+    "The turns that follow are that conversation, replayed as history. They are a record of",
+    "what was discussed elsewhere — not work this session performed. Tool calls in it were",
+    "rendered as text, so no file in this workspace has been touched on their account.",
+    "",
+    "Pick up from where it left off. Do not re-litigate decisions that were already settled.",
+  ]
+    .filter((line) => line !== null)
+    .join("\n");
+}
+
+/**
+ * Build the JSONL records for a thread. Exported separately from the write so the chain can be
+ * asserted in tests without touching the real ~/.claude directory.
+ */
+export function buildRecords(thread, { cwd, sessionId, version, gitBranch = "" }) {
+  const now = new Date().toISOString();
+  const base = {
+    isSidechain: false,
+    userType: "external",
+    cwd,
+    sessionId,
+    version,
+    gitBranch,
+  };
+
+  const records = [];
+  let parentUuid = null;
+  const push = (type, message) => {
+    const uuid = randomUUID();
+    records.push({ ...base, parentUuid, uuid, type, timestamp: now, message });
+    parentUuid = uuid;
+  };
+
+  push("user", { role: "user", content: orientation(thread) });
+  push("assistant", {
+    role: "assistant",
+    model: thread.origin_model || "claude-opus-4",
+    content: [
+      {
+        type: "text",
+        text: "Understood — I have the imported conversation and will continue from it.",
+      },
+    ],
+  });
+
+  for (const message of thread.messages || []) {
+    const text = renderMessage(message);
+    if (!text) continue;
+    if (message.role === "assistant") {
+      push("assistant", {
+        role: "assistant",
+        model: message.model || thread.origin_model || "claude-opus-4",
+        content: [{ type: "text", text }],
+      });
+    } else if (message.role === "user") {
+      push("user", { role: "user", content: text });
+    }
+    // `system` and `tool` roles carry no turn a resumed agent should replay as its own.
+  }
+
+  return records;
+}
+
+/** Assert the linked list is intact: one root, and every parent already seen before its child. */
+export function assertChained(records) {
+  const seen = new Set();
+  let roots = 0;
+  for (const record of records) {
+    if (record.parentUuid === null) roots += 1;
+    else if (!seen.has(record.parentUuid)) {
+      throw new Error(`session records are not chained (orphan ${record.uuid})`);
+    }
+    seen.add(record.uuid);
+  }
+  if (roots !== 1) throw new Error(`session must have exactly one root, found ${roots}`);
+}
+
+/**
+ * Write `thread` as a resumable Claude Code session in `cwd`.
+ * Returns { sessionId, path, messageCount }.
+ */
+export function writeSession(thread, { cwd, version, gitBranch = "" }) {
+  if (!versionSupported(version)) {
+    throw new Error(
+      `Claude Code ${version || "(unknown version)"} is outside the range this importer has ` +
+        `been verified against (${VERIFIED_MIN}–${VERIFIED_MAX}). Refusing to write a session ` +
+        `file that may not resume.`,
+    );
+  }
+
+  const dir = projectDirFor(cwd);
+  mkdirSync(dir, { recursive: true });
+
+  const sessionId = randomUUID();
+  const path = join(dir, `${sessionId}.jsonl`);
+  // A fresh uuid cannot collide in practice; checking anyway is what makes "never overwrite an
+  // existing session" a property of the code rather than a probability.
+  if (existsSync(path)) throw new Error("session id collision; try again");
+
+  const records = buildRecords(thread, { cwd, sessionId, version, gitBranch });
+  assertChained(records);
+
+  writeFileSync(path, records.map((r) => JSON.stringify(r)).join("\n") + "\n", {
+    encoding: "utf8",
+    flag: "wx", // fail rather than clobber, even against a race
+  });
+
+  return { sessionId, path, messageCount: records.length };
+}

package/src/thread-session.test.js

@@ -0,0 +1,140 @@
+import assert from "node:assert/strict";
+import { mkdtempSync, readFileSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import {
+  assertChained,
+  buildRecords,
+  orientation,
+  projectDirFor,
+  renderMessage,
+  versionSupported,
+  writeSession,
+} from "./thread-session.js";
+
+const thread = {
+  title: "Kickplate removal",
+  source: "perplexity_share",
+  origin_app: "Perplexity",
+  source_url: "https://www.perplexity.ai/search/x",
+  messages: [
+    { role: "user", blocks: [{ type: "text", text: "Can the kickplate be removed?" }] },
+    {
+      role: "assistant",
+      blocks: [
+        { type: "thinking", text: "REASONING-TRACE" },
+        { type: "text", text: "Yes, it is a snap-in base grille." },
+        { type: "file", language: "python", text: "print('hi')" },
+      ],
+    },
+    { role: "system", blocks: [{ type: "text", text: "SYSTEM-PREAMBLE" }] },
+    { role: "user", blocks: [] },
+  ],
+};
+
+// -- path flattening ------------------------------------------------------
+// Asserted against the real shape of ~/.claude/projects: separators AND dots collapse to "-",
+// which is why a nested path with a dotted segment doubles up its dashes.
+assert.ok(
+  projectDirFor("/Users/x/Documents/GitHub/penny-router").endsWith(
+    "-Users-x-Documents-GitHub-penny-router",
+  ),
+);
+assert.ok(projectDirFor("/tmp/a.b/c").endsWith("-tmp-a-b-c"));
+
+// -- version gate ---------------------------------------------------------
+// The format is undocumented, so writing outside the verified range is refused rather than
+// attempted: a malformed session file is discovered at resume time, when it is too late.
+assert.equal(versionSupported("2.1.226 (Claude Code)"), true);
+assert.equal(versionSupported("2.0.0"), true);
+assert.equal(versionSupported("1.9.9"), false);
+assert.equal(versionSupported("3.0.0"), false);
+assert.equal(versionSupported(null), false);
+
+// -- record construction --------------------------------------------------
+const records = buildRecords(thread, {
+  cwd: "/tmp/ws",
+  sessionId: "sid",
+  version: "2.1.226",
+});
+
+// Orientation pair, then one record per replayable turn. The empty user turn and the system
+// turn are dropped: neither is something a resumed agent should replay as its own.
+assert.deepEqual(
+  records.map((r) => r.type),
+  ["user", "assistant", "user", "assistant"],
+);
+
+const serialized = JSON.stringify(records);
+assert.ok(!serialized.includes("REASONING-TRACE"), "thinking must never reach a handoff");
+assert.ok(!serialized.includes("SYSTEM-PREAMBLE"), "system turns are not replayed");
+assert.ok(serialized.includes("print('hi')"), "code blocks survive as fenced text");
+assert.ok(records[0].message.content.includes("Perplexity"), "orientation names the origin");
+assert.ok(orientation(thread).includes("Do not re-litigate"));
+
+for (const record of records) {
+  assert.equal(record.sessionId, "sid");
+  assert.equal(record.cwd, "/tmp/ws");
+  assert.equal(record.isSidechain, false);
+  assert.equal(record.userType, "external");
+  assert.ok(record.uuid && record.timestamp);
+}
+
+// -- chain integrity ------------------------------------------------------
+// A break in the parentUuid list truncates history silently, which reads as a working import
+// that lost half the conversation. That has to fail loudly instead.
+assertChained(records);
+assert.equal(records[0].parentUuid, null);
+assert.equal(records[1].parentUuid, records[0].uuid);
+
+assert.throws(
+  () => assertChained([{ uuid: "a", parentUuid: "nope" }]),
+  /not chained/,
+);
+assert.throws(
+  () => assertChained([{ uuid: "a", parentUuid: null }, { uuid: "b", parentUuid: null }]),
+  /exactly one root/,
+);
+
+// -- writing --------------------------------------------------------------
+const home = mkdtempSync(join(tmpdir(), "pr-thread-"));
+const originalHome = process.env.HOME;
+process.env.HOME = home;
+try {
+  const workspace = mkdtempSync(join(tmpdir(), "pr-ws-"));
+  const result = writeSession(thread, { cwd: workspace, version: "2.1.226" });
+
+  const lines = readFileSync(result.path, "utf8").trim().split("\n");
+  assert.equal(lines.length, result.messageCount);
+  const parsed = lines.map((l) => JSON.parse(l));
+  assertChained(parsed);
+  assert.equal(parsed[0].sessionId, result.sessionId);
+  assert.ok(result.path.endsWith(`${result.sessionId}.jsonl`));
+
+  // Never overwrite an existing session: a second write of the same thread is a new file.
+  const again = writeSession(thread, { cwd: workspace, version: "2.1.226" });
+  assert.notEqual(again.sessionId, result.sessionId);
+  assert.notEqual(again.path, result.path);
+  // The first file is still intact and unmodified.
+  assert.equal(readFileSync(result.path, "utf8").trim().split("\n").length, lines.length);
+
+  assert.throws(
+    () => writeSession(thread, { cwd: workspace, version: "9.9.9" }),
+    /outside the range/,
+  );
+} finally {
+  process.env.HOME = originalHome;
+}
+
+// -- rendering ------------------------------------------------------------
+assert.equal(renderMessage({ blocks: [{ type: "text", text: "a" }] }), "a");
+assert.equal(renderMessage({ blocks: [{ type: "thinking", text: "x" }] }), "");
+assert.equal(renderMessage({ blocks: [] }), "");
+assert.ok(
+  renderMessage({ blocks: [{ type: "tool_use", name: "Bash", input: { cmd: "ls" } }] }).startsWith(
+    "[used Bash",
+  ),
+);
+
+console.log("thread-session tests passed");