gentle-pi 3.7.0 → 4.1.0

package/tests/history-legacy-migrate-v2.test.ts

@@ -0,0 +1,297 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { globalSeedPath, migrateLegacyStores } from "../extensions/history/store.ts";
+
+function makeDirs(): { root: string; agentDir: string } {
+  const base = fs.mkdtempSync(path.join(os.tmpdir(), "pi-history-mig-"));
+  const root = path.join(base, "pi-history");
+  const agentDir = path.join(base, "agent");
+  fs.mkdirSync(agentDir, { recursive: true });
+  return { root, agentDir };
+}
+
+function fileTexts(file: string): string[] {
+  if (!fs.existsSync(file)) return [];
+  return fs
+    .readFileSync(file, "utf8")
+    .trim()
+    .split("\n")
+    .filter((l) => l.length > 0)
+    .map((l) => (JSON.parse(l) as { text: string }).text);
+}
+
+test("no legacy files: migration is a no-op, nothing created", () => {
+  const { root, agentDir } = makeDirs();
+  const result = migrateLegacyStores(root, agentDir);
+  assert.deepEqual(result, { migrated: 0, ran: false });
+  assert.equal(fs.existsSync(globalSeedPath(root)), false);
+});
+
+test("v1 jsonl migrates into the global seed chronologically", () => {
+  const { root, agentDir } = makeDirs();
+  const v1 = path.join(agentDir, "editor-history.jsonl");
+  fs.writeFileSync(
+    v1,
+    `${[
+      JSON.stringify({ v: 1, text: "old" }),
+      JSON.stringify({ v: 1, text: "new" }),
+    ].join("\n")}\n`,
+    "utf8",
+  );
+  const result = migrateLegacyStores(root, agentDir);
+  assert.deepEqual(result, { migrated: 2, ran: true });
+  assert.deepEqual(fileTexts(globalSeedPath(root)), ["old", "new"]);
+  assert.equal(fs.existsSync(v1), true);
+  assert.equal(fs.existsSync(`${v1}.imported`), false);
+});
+
+test("competing migration cannot publish a partial seed over a complete one", () => {
+  const { root, agentDir } = makeDirs();
+  const array = path.join(agentDir, "editor-history.json");
+  const v1 = path.join(agentDir, "editor-history.jsonl");
+  fs.writeFileSync(array, JSON.stringify(["array prompt"]));
+  fs.writeFileSync(v1, `${JSON.stringify({ text: "v1 prompt" })}\n`);
+  const original = fs.readFileSync;
+  let competing: ReturnType<typeof migrateLegacyStores> | undefined;
+  fs.readFileSync = ((file: fs.PathOrFileDescriptor, ...args: unknown[]) => {
+    if (file === v1 && !competing) {
+      // The first migration has already read the array; the competing one
+      // must not publish a seed while that snapshot is incomplete.
+      competing = { migrated: -1, ran: true };
+      competing = migrateLegacyStores(root, agentDir);
+    }
+    return (original as (...args: unknown[]) => unknown)(file, ...args);
+  }) as typeof fs.readFileSync;
+  try {
+    migrateLegacyStores(root, agentDir);
+  } finally {
+    fs.readFileSync = original;
+  }
+  assert.deepEqual(competing, { migrated: 0, ran: false });
+  assert.deepEqual(fileTexts(globalSeedPath(root)), ["array prompt", "v1 prompt"]);
+});
+
+test("an ownerless crash lock fails closed without changing sources or seed", () => {
+  const { root, agentDir } = makeDirs();
+  const array = path.join(agentDir, "editor-history.json");
+  const v1 = path.join(agentDir, "editor-history.jsonl");
+  const seed = globalSeedPath(root);
+  const arrayBytes = JSON.stringify(["array prompt"]);
+  const v1Bytes = `${JSON.stringify({ text: "after crash" })}\n`;
+  const seedBytes = `${JSON.stringify({ text: "already seeded" })}\n`;
+  fs.writeFileSync(array, arrayBytes);
+  fs.writeFileSync(v1, v1Bytes);
+  fs.mkdirSync(root, { recursive: true });
+  fs.writeFileSync(seed, seedBytes);
+  // A process can die immediately after mkdir, before recording ownership.
+  // An ownerless lock needs manual recovery; do not claim automatic import.
+  const lock = `${seed}.migration-lock`;
+  fs.mkdirSync(lock);
+  assert.deepEqual(migrateLegacyStores(root, agentDir), { migrated: 0, ran: false });
+  assert.equal(fs.readFileSync(array, "utf8"), arrayBytes);
+  assert.equal(fs.readFileSync(v1, "utf8"), v1Bytes);
+  assert.equal(fs.existsSync(`${array}.imported`), false);
+  assert.equal(fs.existsSync(`${v1}.imported`), false);
+  assert.equal(fs.readFileSync(seed, "utf8"), seedBytes);
+  assert.equal(fs.existsSync(lock), true);
+});
+
+test("a live legacy writer remains reachable for prompts appended after migration", () => {
+  const { root, agentDir } = makeDirs();
+  const v1 = path.join(agentDir, "editor-history.jsonl");
+  fs.writeFileSync(v1, `${JSON.stringify({ text: "before" })}\n`);
+  const fd = fs.openSync(v1, "a");
+  try {
+    migrateLegacyStores(root, agentDir);
+    fs.writeSync(fd, `${JSON.stringify({ text: "after" })}\n`);
+    assert.deepEqual(migrateLegacyStores(root, agentDir), { migrated: 1, ran: true });
+    assert.deepEqual(fileTexts(globalSeedPath(root)), ["before", "after"]);
+  } finally {
+    fs.closeSync(fd);
+  }
+});
+
+test("prompts appended to an already archived live v1 file are recovered", () => {
+  const { root, agentDir } = makeDirs();
+  const archived = path.join(agentDir, "editor-history.jsonl.imported");
+  fs.writeFileSync(archived, `${JSON.stringify({ text: "archived" })}\n`);
+  migrateLegacyStores(root, agentDir);
+  fs.appendFileSync(archived, `${JSON.stringify({ text: "late" })}\n`);
+  assert.deepEqual(migrateLegacyStores(root, agentDir), { migrated: 1, ran: true });
+  assert.deepEqual(fileTexts(globalSeedPath(root)), ["archived", "late"]);
+});
+
+test("legacy array file also migrates (newest-first reversed)", () => {
+  const { root, agentDir } = makeDirs();
+  const legacy = path.join(agentDir, "editor-history.json");
+  fs.writeFileSync(legacy, JSON.stringify(["newest", "oldest"]), "utf8");
+  const result = migrateLegacyStores(root, agentDir);
+  assert.deepEqual(result, { migrated: 2, ran: true });
+  assert.deepEqual(fileTexts(globalSeedPath(root)), ["oldest", "newest"]);
+  assert.equal(fs.existsSync(`${legacy}.imported`), true);
+});
+
+test("both legacy files: v1 jsonl content appends after array content", () => {
+  const { root, agentDir } = makeDirs();
+  const legacy = path.join(agentDir, "editor-history.json");
+  const v1 = path.join(agentDir, "editor-history.jsonl");
+  fs.writeFileSync(legacy, JSON.stringify(["from-array"]), "utf8");
+  fs.writeFileSync(
+    v1,
+    `${JSON.stringify({ v: 1, text: "from-jsonl" })}\n`,
+    "utf8",
+  );
+  migrateLegacyStores(root, agentDir);
+  assert.deepEqual(fileTexts(globalSeedPath(root)), [
+    "from-array",
+    "from-jsonl",
+  ]);
+  assert.equal(fs.existsSync(`${legacy}.imported`), true);
+  assert.equal(fs.existsSync(v1), true);
+});
+
+test("existing global seed is preserved while new v1 prompts are imported", () => {
+  const { root, agentDir } = makeDirs();
+  fs.mkdirSync(path.dirname(globalSeedPath(root)), { recursive: true });
+  fs.writeFileSync(
+    globalSeedPath(root),
+    `${JSON.stringify({ v: 1, text: "already-here" })}\n`,
+    "utf8",
+  );
+  const v1 = path.join(agentDir, "editor-history.jsonl");
+  fs.writeFileSync(
+    v1,
+    `${JSON.stringify({ v: 1, text: "would-migrate" })}\n`,
+    "utf8",
+  );
+  const result = migrateLegacyStores(root, agentDir);
+  assert.deepEqual(result, { migrated: 1, ran: true });
+  assert.deepEqual(fileTexts(globalSeedPath(root)), ["already-here", "would-migrate"]);
+  assert.deepEqual(migrateLegacyStores(root, agentDir), { migrated: 0, ran: false });
+  assert.equal(fs.existsSync(v1), true);
+});
+
+test("unreadable legacy source leaves both sources for a complete retry", () => {
+  const { root, agentDir } = makeDirs();
+  const array = path.join(agentDir, "editor-history.json");
+  const v1 = path.join(agentDir, "editor-history.jsonl");
+  fs.writeFileSync(array, JSON.stringify(["array prompt"]));
+  fs.writeFileSync(v1, `${JSON.stringify({ text: "v1 prompt" })}\n`);
+  const original = fs.readFileSync;
+  fs.readFileSync = ((file: fs.PathOrFileDescriptor, ...args: unknown[]) => {
+    if (file === v1) throw new Error("injected read failure");
+    return (original as (...args: unknown[]) => unknown)(file, ...args);
+  }) as typeof fs.readFileSync;
+  try {
+    assert.throws(() => migrateLegacyStores(root, agentDir), /injected read failure/);
+    assert.equal(fs.existsSync(globalSeedPath(root)), false);
+    assert.equal(fs.existsSync(array), true);
+    assert.equal(fs.existsSync(v1), true);
+  } finally {
+    fs.readFileSync = original;
+  }
+  assert.deepEqual(migrateLegacyStores(root, agentDir), { migrated: 2, ran: true });
+  assert.deepEqual(fileTexts(globalSeedPath(root)), ["array prompt", "v1 prompt"]);
+});
+
+test("malformed legacy array cannot archive a readable v1 source", () => {
+  const { root, agentDir } = makeDirs();
+  const array = path.join(agentDir, "editor-history.json");
+  const v1 = path.join(agentDir, "editor-history.jsonl");
+  fs.writeFileSync(array, "{torn");
+  fs.writeFileSync(v1, `${JSON.stringify({ text: "survives" })}\n`);
+  assert.throws(() => migrateLegacyStores(root, agentDir), SyntaxError);
+  assert.equal(fs.existsSync(globalSeedPath(root)), false);
+  assert.equal(fs.existsSync(v1), true);
+  fs.writeFileSync(array, JSON.stringify(["repaired"]));
+  assert.deepEqual(migrateLegacyStores(root, agentDir), { migrated: 2, ran: true });
+  assert.deepEqual(fileTexts(globalSeedPath(root)), ["repaired", "survives"]);
+});
+
+test("malformed v1 jsonl lines are skipped, not fatal", () => {
+  const { root, agentDir } = makeDirs();
+  const v1 = path.join(agentDir, "editor-history.jsonl");
+  fs.writeFileSync(
+    v1,
+    `${["{torn", JSON.stringify({ v: 1, text: "good" })].join("\n")}\n`,
+    "utf8",
+  );
+  const result = migrateLegacyStores(root, agentDir);
+  assert.deepEqual(result, { migrated: 1, ran: true });
+  assert.deepEqual(fileTexts(globalSeedPath(root)), ["good"]);
+});
+
+// node:test has no test.skipIf (Bun-ism): root skips via the options
+// object — chmod 000 is invisible to the superuser.
+const sealedLegacyTest = (name: string, fn: () => void) =>
+  test(
+    name,
+    { skip: process.getuid?.() === 0 ? "requires non-root" : false },
+    fn,
+  );
+
+// chmod-based failure injection is also invisible to the superuser.
+const seedFailureTest = (name: string, fn: () => void) =>
+  test(
+    name,
+    { skip: process.getuid?.() === 0 ? "requires non-root" : false },
+    fn,
+  );
+
+seedFailureTest(
+  "a failed seed write leaves legacy sources untouched for retry",
+  () => {
+    const agentDir = fs.mkdtempSync(path.join(os.tmpdir(), "migrate-fail-"));
+    const v1 = path.join(agentDir, "editor-history.jsonl");
+    fs.writeFileSync(
+      v1,
+      `${JSON.stringify({ v: 1, text: "survives-retry" })}\n`,
+      "utf8",
+    );
+    const root = fs.mkdtempSync(path.join(os.tmpdir(), "migrate-fail-root-"));
+    // A read-only store root makes the seed write fail AFTER the sources
+    // have been read but BEFORE any rename.
+    fs.chmodSync(root, 0o555);
+    try {
+      assert.throws(() => migrateLegacyStores(root, agentDir));
+      // The source was NOT renamed: the retry path is intact.
+      assert.equal(fs.existsSync(v1), true);
+      assert.equal(fs.existsSync(`${v1}.imported`), false);
+      assert.equal(fs.existsSync(globalSeedPath(root)), false);
+    } finally {
+      fs.chmodSync(root, 0o755);
+    }
+    // Retry after the failure clears: full migration, then rename.
+    const result = migrateLegacyStores(root, agentDir);
+    assert.deepEqual(result, { migrated: 1, ran: true });
+    assert.equal(fs.existsSync(v1), true);
+    assert.deepEqual(fileTexts(globalSeedPath(root)), ["survives-retry"]);
+  },
+);
+
+sealedLegacyTest(
+  "an unreadable legacy file defers migration without archiving either source",
+  () => {
+    const { root, agentDir } = makeDirs();
+    const readable = path.join(agentDir, "editor-history.json");
+    fs.writeFileSync(readable, JSON.stringify(["from-array"]), "utf8");
+    const sealed = path.join(agentDir, "editor-history.jsonl");
+    fs.writeFileSync(
+      sealed,
+      `${JSON.stringify({ v: 1, text: "sealed-content" })}\n`,
+      "utf8",
+    );
+    fs.chmodSync(sealed, 0o000);
+    try {
+      assert.throws(() => migrateLegacyStores(root, agentDir));
+      assert.equal(fs.existsSync(globalSeedPath(root)), false);
+      assert.equal(fs.existsSync(readable), true);
+      assert.equal(fs.existsSync(sealed), true);
+    } finally {
+      fs.chmodSync(sealed, 0o644);
+    }
+  },
+);

package/tests/history-load-shared-history.test.ts

@@ -0,0 +1,53 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { loadSharedHistory } from "../extensions/history/load-shared-history.ts";
+
+function makeTempFile(content: string): string {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), "history-load-"));
+  const file = path.join(dir, "editor-history.json");
+  fs.writeFileSync(file, content, "utf8");
+  return file;
+}
+
+test("returns empty array when file is missing", () => {
+  assert.deepEqual(loadSharedHistory("/definitely/missing.json"), []);
+});
+
+test("returns empty array for malformed json", () => {
+  const file = makeTempFile("{not-json");
+  assert.deepEqual(loadSharedHistory(file), []);
+});
+
+test("supports string entries", () => {
+  const file = makeTempFile(JSON.stringify(["one", "two"]));
+  assert.deepEqual(loadSharedHistory(file), ["one", "two"]);
+});
+
+test("supports object entries with text field", () => {
+  const file = makeTempFile(JSON.stringify([{ text: "one" }, { text: "two" }]));
+  assert.deepEqual(loadSharedHistory(file), ["one", "two"]);
+});
+
+test("ignores malformed object entries", () => {
+  const file = makeTempFile(
+    JSON.stringify([{ text: "one" }, { text: 2 }, { nope: "three" }]),
+  );
+  assert.deepEqual(loadSharedHistory(file), ["one"]);
+});
+
+test("ignores empty string entries", () => {
+  const file = makeTempFile(
+    JSON.stringify(["", "one", { text: "" }, { text: "two" }]),
+  );
+  assert.deepEqual(loadSharedHistory(file), ["one", "two"]);
+});
+
+test("keeps only valid strings from mixed arrays", () => {
+  const file = makeTempFile(
+    JSON.stringify(["one", null, false, 42, { text: "two" }, { text: 1 }]),
+  );
+  assert.deepEqual(loadSharedHistory(file), ["one", "two"]);
+});

package/tests/history-max-results-cap.test.ts

@@ -0,0 +1,76 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { filterPrompts } from "../extensions/history/selector-helpers.ts";
+
+/**
+ * WU5 tests (AC-S5-1, AC-S5-2): the MAX_RESULTS raise 1000 → 10000 is an
+ * OUTPUT cap only — filterPrompts caps both of its slice sites; the load
+ * path never snapshots. Pure import (no pi-tui graph) plus a source-parse
+ * pin on the selector-helpers slice sites.
+ *
+ * The dev suite's openHistorySelector body pin (no slice() on the load
+ * path) covers the slice-3 selector wiring in extensions/history/index.ts
+ * and ports with that slice — index.ts stays at its slice-1 surface here.
+ */
+
+interface CapRecord {
+  text: string;
+  searchText: string;
+}
+
+function record(text: string): CapRecord {
+  return { text, searchText: text.toLowerCase() };
+}
+
+// T29 — AC-S5-1: the cap value. More than 10,000 records → exactly 10,000 at
+// the empty-query slice AND at a filtered-query slice. NEW pin — no existing
+// test pins the old 1000 literal (design §D9; zero existing-test edits
+// repo-wide, so this file ADDS the pin instead of editing one).
+
+test("T29 (AC-S5-1): empty-query slice caps at the raised 10000", () => {
+  const records: CapRecord[] = [];
+  for (let i = 0; i < 10500; i++) {
+    records.push(record(`unique prompt number ${i}`));
+  }
+  const result = filterPrompts(records, "");
+  assert.equal(result.length, 10000);
+});
+
+test("T29 (AC-S5-1): filtered-query slice caps at the raised 10000", () => {
+  const records: CapRecord[] = [];
+  // 10,500 matches for the query token plus non-matching padding rows: the
+  // FILTERED set alone is above the cap, so the filtered slice site is the
+  // one being exercised here.
+  for (let i = 0; i < 10500; i++) {
+    records.push(record(`match me ${i}`));
+  }
+  records.push(record("unrelated row one"));
+  records.push(record("unrelated row two"));
+  const result = filterPrompts(records, "match");
+  assert.ok(result.length > 1000, "the filtered set must exceed the old cap");
+  assert.equal(result.length, 10000);
+  assert.ok(result.every((r) => r.searchText.includes("match")));
+});
+
+// T30 — AC-S5-2: output-cap-only semantics (source-parse). Selector-helpers
+// reads the constant at exactly the two sanctioned filterPrompts slice
+// sites — no other cap exists in the helper module.
+
+const helperSource = fs.readFileSync(
+  fileURLToPath(
+    new URL("../extensions/history/selector-helpers.ts", import.meta.url),
+  ),
+  "utf8",
+);
+
+test("T30 (AC-S5-2): filterPrompts hosts exactly the two sanctioned cap slice sites", () => {
+  const sliceSites = helperSource.split("slice(0, MAX_RESULTS)").length - 1;
+  assert.equal(
+    sliceSites,
+    2,
+    "filterPrompts hosts exactly the two sanctioned cap slice sites",
+  );
+});

package/tests/history-multi-reader.test.ts

@@ -0,0 +1,203 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { writeJsonAtomic } from "../extensions/history/atomic-write.ts";
+import {
+  appendSessionCapture,
+  ensureRegistryEntry,
+  openSessionWriter,
+  parseStoreLine,
+  projectDir,
+  projectHash,
+  registryPath,
+  sessionFilePath,
+} from "../extensions/history/store.ts";
+
+// Slice-1 concurrency/recovery coverage. The dev-suite multi-reader drain
+// scenarios are re-expressed against the slice-1 surface (per-instance
+// writers, parseStoreLine, atomic writes): parallel writers on one project
+// dir, torn-line tolerance, and same-target atomic-write collisions. The
+// drain/read ordering scenarios themselves arrive with the slice-2 reader.
+
+const PROJECT_A = "/pi-history-test/project-a";
+const PROJECT_B = "/pi-history-test/project-b";
+
+function makeRoot(): string {
+  return fs.mkdtempSync(path.join(os.tmpdir(), "pi-history-multi-reader-"));
+}
+
+function storedTexts(file: string): string[] {
+  return fs
+    .readFileSync(file, "utf8")
+    .split("\n")
+    .filter((l) => l.trim().length > 0)
+    .map((l) => (JSON.parse(l) as { text: string }).text);
+}
+
+// --- parallel writers ---
+
+test("growth from a concurrent instance is visible on the next read", () => {
+  const root = makeRoot();
+  const a = openSessionWriter(root, PROJECT_A, "inst-a");
+  appendSessionCapture(a, "first");
+  const dirA = projectDir(root, PROJECT_A);
+  assert.deepEqual(fs.readdirSync(dirA), ["inst-a.jsonl"]);
+
+  // A second pi instance grows the SAME project dir through its OWN file;
+  // neither writer reads or rewrites the other's bytes.
+  const b = openSessionWriter(root, PROJECT_A, "inst-b");
+  appendSessionCapture(b, "from-other-instance");
+
+  assert.deepEqual(fs.readdirSync(dirA).sort(), [
+    "inst-a.jsonl",
+    "inst-b.jsonl",
+  ]);
+  assert.deepEqual(storedTexts(sessionFilePath(root, PROJECT_A, "inst-a")), [
+    "first",
+  ]);
+  assert.deepEqual(storedTexts(sessionFilePath(root, PROJECT_A, "inst-b")), [
+    "from-other-instance",
+  ]);
+  assert.equal(a.lineCount, 1);
+  assert.equal(b.lineCount, 1);
+});
+
+test("interleaved captures from multiple writers never clobber each other", () => {
+  const root = makeRoot();
+  const writers = [
+    openSessionWriter(root, PROJECT_A, "w0"),
+    openSessionWriter(root, PROJECT_A, "w1"),
+    openSessionWriter(root, PROJECT_A, "w2"),
+  ];
+  for (let i = 0; i < 10; i++) {
+    for (let w = 0; w < writers.length; w++) {
+      appendSessionCapture(writers[w], `w${w}-line-${i}`);
+    }
+  }
+  const dir = projectDir(root, PROJECT_A);
+  assert.deepEqual(fs.readdirSync(dir).sort(), [
+    "w0.jsonl",
+    "w1.jsonl",
+    "w2.jsonl",
+  ]);
+  for (let w = 0; w < writers.length; w++) {
+    assert.equal(writers[w].lineCount, 10);
+    assert.deepEqual(
+      storedTexts(writers[w].filePath),
+      Array.from({ length: 10 }, (_, i) => `w${w}-line-${i}`),
+    );
+  }
+});
+
+test("a high-volume burst on one writer keeps every line, in order", () => {
+  const root = makeRoot();
+  const writer = openSessionWriter(root, PROJECT_A, "burst");
+  const expected: string[] = [];
+  for (let i = 0; i < 100; i++) {
+    const text = `burst-${i}`;
+    expected.push(text);
+    appendSessionCapture(writer, text, 1000 + i);
+  }
+  assert.equal(writer.lineCount, 100);
+  const lines = fs.readFileSync(writer.filePath, "utf8").trim().split("\n");
+  assert.equal(lines.length, 100);
+  const parsed = lines.map((l) => JSON.parse(l) as { text: string; ts: number });
+  assert.deepEqual(
+    parsed.map((e) => e.text),
+    expected,
+  );
+  assert.equal(parsed[42].ts, 1042);
+});
+
+// --- torn-line / crash recovery ---
+
+test("torn and malformed lines parse to null (crash garbage never resurfaces)", () => {
+  // A torn final line (process died mid-write) is a truncated JSON doc.
+  const torn = JSON.stringify({ v: 1, text: "survivor" }).slice(0, 12);
+  const malformed: string[] = [
+    "",
+    "{torn",
+    torn,
+    "not json at all",
+    JSON.stringify([]),
+    JSON.stringify("scalar"),
+    JSON.stringify(null),
+    JSON.stringify({ v: 1 }),
+    JSON.stringify({ text: 42 }),
+    JSON.stringify({ text: "   " }),
+  ];
+  for (const line of malformed) {
+    assert.equal(parseStoreLine(line), null, JSON.stringify(line));
+  }
+  // Valid lines keep parsing: absent v defaults to 1, ts/v flow through.
+  assert.deepEqual(parseStoreLine(JSON.stringify({ v: 1, text: "survivor" })), {
+    v: 1,
+    text: "survivor",
+  });
+  assert.deepEqual(parseStoreLine(JSON.stringify({ text: "y" })), {
+    v: 1,
+    text: "y",
+  });
+  assert.deepEqual(parseStoreLine(JSON.stringify({ v: 2, text: "x", ts: 7 })), {
+    v: 2,
+    text: "x",
+    ts: 7,
+  });
+});
+
+test("a torn final line is tolerated: skipped by readers, later appends continue", () => {
+  const root = makeRoot();
+  const writer = openSessionWriter(root, PROJECT_A, "torn");
+  appendSessionCapture(writer, "before-crash");
+  // Crash mid-write: a partial line lands WITHOUT its trailing newline.
+  fs.appendFileSync(writer.filePath, `{"v":1,"text":"tor`, "utf8");
+  // parseStoreLine skips the torn tail instead of throwing...
+  assert.equal(parseStoreLine('{"v":1,"text":"tor'), null);
+  // ...and the instance keeps capturing. The first append after a
+  // newline-less torn tail merges with the fragment (one accepted lost
+  // entry — the same crash window the design documents for lost writes);
+  // the next full line parses cleanly again.
+  appendSessionCapture(writer, "after-crash");
+  appendSessionCapture(writer, "after-crash-2");
+  assert.equal(writer.lineCount, 3);
+  const lines = fs.readFileSync(writer.filePath, "utf8").trim().split("\n");
+  assert.equal(lines.length, 3);
+  assert.equal((JSON.parse(lines[0]) as { text: string }).text, "before-crash");
+  assert.equal(parseStoreLine(lines[1]), null); // torn fragment + merged entry
+  assert.equal(
+    (JSON.parse(lines[2]) as { text: string }).text,
+    "after-crash-2",
+  );
+});
+
+// --- atomic-write collisions ---
+
+test("rapid same-target atomic writes leave one valid document and no staging files", () => {
+  const root = makeRoot();
+  const target = path.join(root, "shared-state.json");
+  for (let i = 0; i < 25; i++) {
+    assert.equal(writeJsonAtomic(target, { writer: i }), true);
+  }
+  const final = JSON.parse(fs.readFileSync(target, "utf8")) as {
+    writer: number;
+  };
+  assert.ok(final.writer >= 0 && final.writer <= 24);
+  const leftovers = fs.readdirSync(root).filter((f) => f.includes(".tmp-"));
+  assert.deepEqual(leftovers, []);
+});
+
+test("interleaved registry updates from two instances keep both entries", () => {
+  const root = makeRoot();
+  for (let i = 0; i < 3; i++) {
+    ensureRegistryEntry(root, PROJECT_A);
+    ensureRegistryEntry(root, PROJECT_B);
+  }
+  const raw = JSON.parse(
+    fs.readFileSync(registryPath(root), "utf8"),
+  ) as Record<string, string>;
+  assert.equal(Object.keys(raw).length, 2);
+  assert.equal(raw[projectHash(PROJECT_A)], PROJECT_A);
+  assert.equal(raw[projectHash(PROJECT_B)], PROJECT_B);
+});