gentle-pi 3.6.0 → 4.0.0

package/tests/history-search-caret-keys.test.ts

@@ -0,0 +1,142 @@
+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 promptHistoryExtension from "../extensions/history/index.ts";
+import { projectHash } from "../extensions/history/store.ts";
+
+// Home/End routing in the history selector: with text in the search box
+// they move the search caret (End never jumps or loads the list); with an
+// empty search box they keep the documented list jumps (§B2/§D7). The real
+// selector is driven through the history command with a fake overlay host;
+// every fixture lives under os.tmpdir(), never the user's real ~/.pi.
+
+const CWD = "/pi-history-fixtures/project-caret-keys";
+const HOME = "\x1b[H";
+const END = "\x1b[F";
+const LEFT = "\x1b[D";
+const ENTER = "\r";
+// 15 prompts, oldest p00 .. newest p14: more than the initial 10-row window.
+const PROMPT_COUNT = 15;
+
+interface Selector {
+  handleInput(data: string): void;
+}
+
+function makeRoot(): string {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), "pi-history-caret-"));
+  const dir = path.join(root, "projects", projectHash(CWD));
+  fs.mkdirSync(dir, { recursive: true });
+  const lines = Array.from({ length: PROMPT_COUNT }, (_, i) =>
+    JSON.stringify({
+      v: 1,
+      text: `p${String(i).padStart(2, "0")}`,
+      ts: 1_700_000_000_000 + i,
+    }),
+  );
+  fs.writeFileSync(path.join(dir, "store.jsonl"), `${lines.join("\n")}\n`);
+  return root;
+}
+
+/**
+ * Open the selector, feed `keys` one at a time, and return the prompt the
+ * selector pasted into the editor (null when it pasted nothing).
+ */
+async function selectAfter(keys: string[]): Promise<string | null> {
+  const root = makeRoot();
+  const commands: Array<[string, { handler: unknown }]> = [];
+  promptHistoryExtension(
+    {
+      on: () => {},
+      registerShortcut: () => {},
+      registerCommand: (name: string, def: { handler: unknown }) => {
+        commands.push([name, def]);
+      },
+    } as never,
+    {
+      env: { GENTLE_PI_HISTORY_CAPTURE: "1" },
+      gentlePiConfigHome: fs.mkdtempSync(
+        path.join(os.tmpdir(), "pi-history-caret-config-"),
+      ),
+      root,
+      cwd: CWD,
+      instanceId: "inst-caret",
+      agentDir: path.join(root, "agent"),
+      sessionsRoot: path.join(root, "sessions"),
+    },
+  );
+  const command = commands.find(([name]) => name === "history");
+  assert.ok(command, "the history command must be registered");
+  const handler = command[1].handler as (
+    args: unknown,
+    ctx: unknown,
+  ) => Promise<void>;
+
+  let pasted: string | null = null;
+  const plain = (_color: string, text: string) => text;
+  const ctx = {
+    ui: {
+      notify: (message: string) => {
+        assert.fail(`unexpected notification: ${message}`);
+      },
+      pasteToEditor: (text: string) => {
+        pasted = text;
+      },
+      custom: (
+        factory: (
+          tui: unknown,
+          theme: unknown,
+          keybindings: unknown,
+          done: (result: unknown) => void,
+        ) => Selector,
+      ) =>
+        new Promise((resolve) => {
+          const selector = factory(
+            { requestRender: () => {} },
+            { fg: plain, bg: plain, bold: (text: string) => text },
+            undefined,
+            resolve,
+          );
+          for (const key of keys) selector.handleInput(key);
+          // Enter selects the highlighted row; with no match it resolves
+          // nothing, so close explicitly to finish the command.
+          selector.handleInput(ENTER);
+          resolve(null);
+        }),
+    },
+  };
+  await handler([], ctx);
+  // The paste path schedules one render tick; let it drain.
+  await new Promise((resolve) => setTimeout(resolve, 0));
+  return pasted;
+}
+
+test("with a query, Home moves the search caret instead of the list", async () => {
+  // Typed "1", caret to the start, then "p": the query is "p1", whose
+  // newest match is p14. A list jump would leave the query as "1p".
+  assert.equal(await selectAfter(["1", HOME, "p"]), "p14");
+});
+
+test("with a query, End moves the search caret instead of the list", async () => {
+  // Caret moved to the start, End brings it back: "p1" + "3" = "p13".
+  // A list jump would leave the caret at 0 and type "3p1".
+  assert.equal(await selectAfter(["p", "1", LEFT, LEFT, END, "3"]), "p13");
+});
+
+test("with a query, End neither jumps to the last match nor loads the list", async () => {
+  // A real query: the highlighted row stays the newest match, not p00.
+  assert.equal(await selectAfter(["p", END]), "p14");
+  // A whitespace-only query filters nothing and keeps the 10-row window:
+  // End must not load every record and select the oldest one.
+  assert.equal(await selectAfter([" ", END]), "p14");
+});
+
+test("with an empty query, Home and End keep the list jumps", async () => {
+  // End loads every record and selects the oldest one (§D7).
+  assert.equal(await selectAfter([END]), "p00");
+  // Home jumps back to the newest.
+  assert.equal(await selectAfter([END, HOME]), "p14");
+  // Emptying the query hands Home/End back to the list.
+  assert.equal(await selectAfter(["p", "\x7f", END]), "p00");
+});

package/tests/history-seed-bootstrap.test.ts

@@ -0,0 +1,170 @@
+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 {
+  bootstrapProjectSeed,
+  projectHash,
+  seedFilePath,
+} from "../extensions/history/store.ts";
+
+// Fake project cwd (never created on disk): projectHash falls back to
+// raw-string hashing for nonexistent paths, and the transcript dirName
+// encoding derives from the same string.
+const CWD = "/pi-history-test/seed-project";
+const DIR = "--pi-history-test-seed-project--";
+
+function makeDirs(): { root: string; sessionsRoot: string } {
+  const base = fs.mkdtempSync(path.join(os.tmpdir(), "pi-history-seed-"));
+  return {
+    root: path.join(base, "pi-history"),
+    sessionsRoot: path.join(base, "sessions"),
+  };
+}
+
+function writeSession(
+  sessionsRoot: string,
+  dirName: string,
+  fileName: string,
+  userTexts: string[],
+  mtimeMs?: number,
+): string {
+  const dir = path.join(sessionsRoot, dirName);
+  fs.mkdirSync(dir, { recursive: true });
+  const file = path.join(dir, fileName);
+  const lines: string[] = [
+    JSON.stringify({
+      type: "session",
+      version: 1,
+      timestamp: "2026-01-01T00:00:00.000Z",
+    }),
+  ];
+  let ms = 1700000000000;
+  for (const text of userTexts) {
+    lines.push(
+      JSON.stringify({
+        type: "message",
+        timestamp: "2026-01-01T00:00:00.000Z",
+        message: { role: "user", content: text, timestamp: ms },
+      }),
+    );
+    ms += 1;
+  }
+  fs.writeFileSync(file, `${lines.join("\n")}\n`, "utf8");
+  if (mtimeMs !== undefined) {
+    fs.utimesSync(file, new Date(mtimeMs), new Date(mtimeMs));
+  }
+  return file;
+}
+
+function seedTexts(root: string): string[] {
+  const file = seedFilePath(root, CWD);
+  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 sessions and no project dir: bootstrap seeds nothing", () => {
+  const { root, sessionsRoot } = makeDirs();
+  const result = bootstrapProjectSeed(root, CWD, sessionsRoot, 500);
+  assert.deepEqual(result, { seeded: 0, ran: false });
+  assert.equal(fs.existsSync(seedFilePath(root, CWD)), false);
+});
+
+test("empty project dir bootstraps from the project's transcripts", () => {
+  const { root, sessionsRoot } = makeDirs();
+  writeSession(sessionsRoot, DIR, "s1.jsonl", [
+    "real prompt",
+    "/compact",
+    "   ",
+    "second prompt",
+  ]);
+  const result = bootstrapProjectSeed(root, CWD, sessionsRoot, 500);
+  assert.deepEqual(result, { seeded: 2, ran: true });
+  // Chronological order (oldest first) in the seed file.
+  assert.deepEqual(seedTexts(root), ["real prompt", "second prompt"]);
+});
+
+test("only the project's own session dir is scanned", () => {
+  const { root, sessionsRoot } = makeDirs();
+  writeSession(sessionsRoot, DIR, "s1.jsonl", ["mine"]);
+  writeSession(sessionsRoot, "--Other--", "s2.jsonl", ["not mine"]);
+  bootstrapProjectSeed(root, CWD, sessionsRoot, 500);
+  assert.deepEqual(seedTexts(root), ["mine"]);
+});
+
+test("caps at the target keeping the newest", () => {
+  const { root, sessionsRoot } = makeDirs();
+  const texts: string[] = [];
+  for (let i = 1; i <= 600; i++) texts.push(`p${i}`);
+  writeSession(sessionsRoot, DIR, "big.jsonl", texts);
+  const result = bootstrapProjectSeed(root, CWD, sessionsRoot, 500);
+  assert.deepEqual(result, { seeded: 500, ran: true });
+  const all = seedTexts(root);
+  assert.equal(all.length, 500);
+  assert.equal(all[0], "p101"); // oldest kept
+  assert.equal(all[499], "p600"); // newest
+});
+
+test("project dir already populated above target: no scan, seed untouched", () => {
+  const { root, sessionsRoot } = makeDirs();
+  const dir = path.join(root, "projects", projectHash(CWD));
+  fs.mkdirSync(dir, { recursive: true });
+  const existing = path.join(dir, "existing.jsonl");
+  fs.writeFileSync(
+    existing,
+    `${Array.from({ length: 500 }, (_, i) =>
+      JSON.stringify({ v: 1, text: `e${i}` }),
+    ).join("\n")}\n`,
+    "utf8",
+  );
+  const marker = writeSession(sessionsRoot, DIR, "s.jsonl", ["marker"]);
+  fs.utimesSync(
+    marker,
+    new Date(Date.now() + 5000),
+    new Date(Date.now() + 5000),
+  );
+  const result = bootstrapProjectSeed(root, CWD, sessionsRoot, 500);
+  assert.deepEqual(result, { seeded: 0, ran: false });
+  assert.deepEqual(seedTexts(root), []);
+  assert.equal(fs.readFileSync(existing, "utf8").includes("marker"), false);
+});
+
+// node:test has no test.skipIf (Bun-ism): root skips via the options
+// object — chmod 000 is invisible to the superuser.
+const sealedStoreTest = (name: string, fn: () => void) =>
+  test(
+    name,
+    { skip: process.getuid?.() === 0 ? "requires non-root" : false },
+    fn,
+  );
+sealedStoreTest(
+  "an unreadable existing store file is skipped during counting; seeding still runs from transcripts",
+  () => {
+    const { root, sessionsRoot } = makeDirs();
+    const dir = path.join(root, "projects", projectHash(CWD));
+    fs.mkdirSync(dir, { recursive: true });
+    const sealed = path.join(dir, "sealed.jsonl");
+    fs.writeFileSync(
+      sealed,
+      `${JSON.stringify({ v: 1, text: "sealed-entry" })}\n`,
+      "utf8",
+    );
+    fs.chmodSync(sealed, 0o000);
+    writeSession(sessionsRoot, DIR, "s1.jsonl", ["from transcript"]);
+    try {
+      // The unreadable file contributes zero to existingCount, so the count
+      // stays under target and the transcript scan still runs. No throw.
+      const result = bootstrapProjectSeed(root, CWD, sessionsRoot, 500);
+      assert.deepEqual(result, { seeded: 1, ran: true });
+      assert.deepEqual(seedTexts(root), ["from transcript"]);
+    } finally {
+      fs.chmodSync(sealed, 0o644); // restore before cleanup
+    }
+  },
+);

package/tests/history-seed-regen.test.ts

@@ -0,0 +1,129 @@
+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 { bootstrapProjectSeed, seedFilePath } from "../extensions/history/store.ts";
+
+// Fake project cwd (never created on disk): projectHash falls back to
+// raw-string hashing for nonexistent paths, and the transcript dirName
+// encoding derives from the same string.
+const CWD = "/pi-history-test/seed-regen-project";
+const DIR = "--pi-history-test-seed-regen-project--";
+
+function setup() {
+  const base = fs.mkdtempSync(path.join(os.tmpdir(), "seed2-"));
+  return {
+    root: path.join(base, "h"),
+    sessionsRoot: path.join(base, "sessions"),
+    stateDir: path.join(base, "state"),
+  };
+}
+
+function writeSession(sessionsRoot: string, texts: string[]): void {
+  const dir = path.join(sessionsRoot, DIR);
+  fs.mkdirSync(dir, { recursive: true });
+  const lines = [
+    JSON.stringify({
+      type: "session",
+      version: 1,
+      timestamp: "2026-01-01T00:00:00.000Z",
+    }),
+  ];
+  let ms = 1700000000000;
+  for (const text of texts) {
+    lines.push(
+      JSON.stringify({
+        type: "message",
+        timestamp: "2026-01-01T00:00:00.000Z",
+        message: { role: "user", content: text, timestamp: ms++ },
+      }),
+    );
+  }
+  fs.writeFileSync(path.join(dir, "s1.jsonl"), `${lines.join("\n")}\n`, "utf8");
+}
+
+test("an existing seed is never regenerated (deleted prompts stay gone)", () => {
+  const { root, sessionsRoot } = setup();
+  writeSession(sessionsRoot, ["keep", "delete-me"]);
+  bootstrapProjectSeed(root, CWD, sessionsRoot, 500);
+  // User deletes "delete-me" from the seed file (scope delete).
+  const seed = seedFilePath(root, CWD);
+  const kept = fs
+    .readFileSync(seed, "utf8")
+    .split("\n")
+    .filter((l) => !l.includes("delete-me"))
+    .join("\n");
+  fs.writeFileSync(seed, kept, "utf8");
+  // A NEW session bootstraps again -> must not resurrect from transcripts.
+  const again = bootstrapProjectSeed(root, CWD, sessionsRoot, 500);
+  assert.deepEqual(again, { seeded: 0, ran: false });
+  const texts = fs
+    .readFileSync(seed, "utf8")
+    .trim()
+    .split("\n")
+    .map((l) => (JSON.parse(l) as { text: string }).text);
+  assert.deepEqual(texts, ["keep"]);
+});
+
+test("untrusted tombstones defer seed until repaired, then suppress deleted prompts", () => {
+  const { root, sessionsRoot, stateDir } = setup();
+  writeSession(sessionsRoot, ["visible", "hidden-prompt"]);
+  fs.mkdirSync(stateDir, { recursive: true });
+  const hiddenFile = path.join(stateDir, "hidden.json");
+  fs.writeFileSync(hiddenFile, "{broken");
+  assert.deepEqual(bootstrapProjectSeed(root, CWD, sessionsRoot, 500, stateDir), {
+    seeded: 0, ran: false,
+  });
+  assert.equal(fs.existsSync(seedFilePath(root, CWD)), false);
+  fs.writeFileSync(hiddenFile, JSON.stringify(["hidden-prompt"]));
+  assert.deepEqual(bootstrapProjectSeed(root, CWD, sessionsRoot, 500, stateDir), {
+    seeded: 1, ran: true,
+  });
+  assert.deepEqual(
+    fs.readFileSync(seedFilePath(root, CWD), "utf8").trim().split("\n")
+      .map((line) => (JSON.parse(line) as { text: string }).text),
+    ["visible"],
+  );
+});
+
+test("a failed seed rename leaves no gate and retries with all prompts", () => {
+  const { root, sessionsRoot, stateDir } = setup();
+  writeSession(sessionsRoot, ["visible", "hidden-prompt"]);
+  fs.mkdirSync(stateDir, { recursive: true });
+  fs.writeFileSync(path.join(stateDir, "hidden.json"), JSON.stringify(["hidden-prompt"]));
+  const seed = seedFilePath(root, CWD);
+  const original = fs.renameSync;
+  fs.renameSync = ((from: fs.PathLike, to: fs.PathLike) => {
+    if (to === seed) throw new Error("injected seed rename failure");
+    return original(from, to);
+  }) as typeof fs.renameSync;
+  try {
+    assert.throws(() => bootstrapProjectSeed(root, CWD, sessionsRoot, 500, stateDir), /injected/);
+    assert.equal(fs.existsSync(seed), false);
+  } finally {
+    fs.renameSync = original;
+  }
+  assert.deepEqual(bootstrapProjectSeed(root, CWD, sessionsRoot, 500, stateDir), {
+    seeded: 1, ran: true,
+  });
+});
+
+test("tombstoned prompts are not seeded from transcripts", () => {
+  const { root, sessionsRoot, stateDir } = setup();
+  writeSession(sessionsRoot, ["visible", "hidden-prompt"]);
+  // Tombstone "hidden-prompt" (same key shape hide-prompts writes).
+  fs.mkdirSync(stateDir, { recursive: true });
+  fs.writeFileSync(
+    path.join(stateDir, "hidden.json"),
+    JSON.stringify(["hidden-prompt"]),
+    "utf8",
+  );
+  bootstrapProjectSeed(root, CWD, sessionsRoot, 500, stateDir);
+  const texts = fs
+    .readFileSync(seedFilePath(root, CWD), "utf8")
+    .trim()
+    .split("\n")
+    .map((l) => (JSON.parse(l) as { text: string }).text);
+  assert.deepEqual(texts, ["visible"]);
+});

package/tests/history-selector-windowing.test.ts

@@ -0,0 +1,94 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import {
+  buildPromptRecords,
+  clampPreviewOffset,
+  clampSelectedIndex,
+  computeVisibleRange,
+  getVisiblePromptRecords,
+  moveSelectedIndex,
+  pageSelectedIndex,
+} from "../extensions/history/selector-helpers.ts";
+
+test("buildPromptRecords lowercases search text", () => {
+  assert.deepEqual(buildPromptRecords(["Hello"]), [
+    { text: "Hello", searchText: "hello" },
+  ]);
+});
+
+test("computeVisibleRange centers when possible", () => {
+  assert.deepEqual(computeVisibleRange(8, 30, 10), { start: 3, end: 13 });
+});
+
+test("computeVisibleRange pins near end", () => {
+  assert.deepEqual(computeVisibleRange(28, 30, 10), { start: 20, end: 30 });
+});
+
+test("computeVisibleRange handles small lists", () => {
+  assert.deepEqual(computeVisibleRange(1, 3, 10), { start: 0, end: 3 });
+});
+
+test("clampSelectedIndex stays within filtered record bounds", () => {
+  assert.equal(clampSelectedIndex(8, 3), 2);
+  assert.equal(clampSelectedIndex(1, 0), 0);
+});
+
+test("clampPreviewOffset clamps offsets past the last page", () => {
+  assert.equal(clampPreviewOffset(50, 47, 10), 37);
+  assert.equal(clampPreviewOffset(5, 47, 10), 5);
+});
+
+test("clampPreviewOffset pins to zero when content fits the viewport", () => {
+  assert.equal(clampPreviewOffset(3, 8, 10), 0);
+  assert.equal(clampPreviewOffset(7, 0, 10), 0);
+});
+
+test("moveSelectedIndex wraps around the list", () => {
+  assert.equal(moveSelectedIndex(0, 3, -1), 2);
+  assert.equal(moveSelectedIndex(2, 3, 1), 0);
+  assert.equal(moveSelectedIndex(0, 0, 1), 0);
+});
+
+test("pageSelectedIndex clamps within the list", () => {
+  assert.equal(pageSelectedIndex(8, 30, -10), 0);
+  assert.equal(pageSelectedIndex(2, 3, 10), 2);
+  assert.equal(pageSelectedIndex(0, 0, 10), 0);
+});
+
+test("pageSelectedIndex end-clamps a downward page at the last entry (AC-P2-1.1)", () => {
+  assert.equal(pageSelectedIndex(28, 30, 10), 29);
+  assert.equal(pageSelectedIndex(25, 30, 10), 29);
+});
+
+test("pageSelectedIndex clamps |pageSize| greater than total in both directions (AC-P2-1.2)", () => {
+  assert.equal(pageSelectedIndex(0, 3, 10), 2);
+  assert.equal(pageSelectedIndex(2, 3, -10), 0);
+  assert.equal(pageSelectedIndex(0, 30, -50), 0);
+});
+
+test("pageSelectedIndex never wraps past the ends (AC-P2-1.2)", () => {
+  assert.equal(pageSelectedIndex(29, 30, 10), 29);
+  assert.equal(pageSelectedIndex(0, 30, -10), 0);
+});
+
+test("getVisiblePromptRecords returns visible records with selection state", () => {
+  assert.deepEqual(
+    getVisiblePromptRecords(
+      buildPromptRecords(["one", "two", "three", "four"]),
+      2,
+      2,
+    ),
+    [
+      {
+        index: 1,
+        record: { text: "two", searchText: "two" },
+        isSelected: false,
+      },
+      {
+        index: 2,
+        record: { text: "three", searchText: "three" },
+        isSelected: true,
+      },
+    ],
+  );
+});

package/tests/history-session-scan-directory.test.ts

@@ -0,0 +1,87 @@
+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 { listSessionFiles } from "../extensions/history/session-scan.ts";
+
+/**
+ * WU1b-carried T7 (AC-S1-7): the one-level directory exclusion matrix. The
+ * fixture tree mirrors the pi sessions root — encoded-cwd directories with
+ * top-level jsonl session files, nested run-N/session.jsonl subagent
+ * payloads, a subagent-artifacts subtree, and a stray root-level file.
+ * Fixture files carry garbage content: the scanner must LIST paths only, so
+ * exact path equality proves nested payloads are never ingested (a
+ * recursive scanner would emit them).
+ */
+function makeSessionsRoot(): string {
+  return fs.mkdtempSync(path.join(os.tmpdir(), "session-scan-dirs-"));
+}
+
+function writeFileAt(filePath: string): void {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, "garbage-not-json\n", "utf8");
+}
+
+test("one-level scan rule: only top-level jsonl of cwd dirs; nested payloads, subagent-artifacts, and stray root files never ingested (AC-S1-7)", () => {
+  const root = makeSessionsRoot();
+
+  // two cwd directories, each holding top-level jsonl session files
+  const cwdA = path.join(root, "--home-user-project-a--");
+  const cwdB = path.join(root, "--home-user-project-b--");
+  writeFileAt(path.join(cwdA, "2026-01-01t10-00-00aaa.jsonl"));
+  writeFileAt(path.join(cwdA, "2026-01-02t11-00-00bbb.jsonl"));
+  writeFileAt(path.join(cwdB, "2026-01-03t12-00-00ccc.jsonl"));
+
+  // nested run-N/session.jsonl subagent payloads — never descended
+  writeFileAt(path.join(cwdA, "run-1", "session.jsonl"));
+  writeFileAt(path.join(cwdB, "run-2", "session.jsonl"));
+
+  // a subagent-artifacts subtree holding a jsonl file — never descended
+  writeFileAt(path.join(cwdA, "subagent-artifacts", "artifact.jsonl"));
+
+  // one stray root-level FILE (not a directory) — skipped
+  writeFileAt(path.join(root, "stray.jsonl"));
+
+  const files = listSessionFiles(root);
+
+  // exactly the three top-level jsonl paths of the cwd directories,
+  // sorted, absolute
+  assert.deepEqual(files, [
+    path.join(cwdA, "2026-01-01t10-00-00aaa.jsonl"),
+    path.join(cwdA, "2026-01-02t11-00-00bbb.jsonl"),
+    path.join(cwdB, "2026-01-03t12-00-00ccc.jsonl"),
+  ]);
+  for (const file of files) {
+    assert.equal(path.isAbsolute(file), true);
+  }
+});
+
+// node:test has no test.skipIf (Bun-ism): root skips via the options
+// object — chmod 000 is invisible to the superuser.
+const sealedDirTest = (name: string, fn: () => void) =>
+  test(
+    name,
+    { skip: process.getuid?.() === 0 ? "requires non-root" : false },
+    fn,
+  );
+sealedDirTest(
+  "an unreadable child dir (chmod 000) is skipped; sibling dirs still list",
+  () => {
+    const root = makeSessionsRoot();
+    const sealed = path.join(root, "--sealed--");
+    const open = path.join(root, "--open--");
+    writeFileAt(path.join(sealed, "hidden-session.jsonl"));
+    writeFileAt(path.join(open, "visible-session.jsonl"));
+    fs.chmodSync(sealed, 0o000);
+    try {
+      // One directory whose readdir fails skips itself — never fatal — and
+      // the sibling directories still contribute their files.
+      assert.deepEqual(listSessionFiles(root), [
+        path.join(open, "visible-session.jsonl"),
+      ]);
+    } finally {
+      fs.chmodSync(sealed, 0o755); // restore before cleanup
+    }
+  },
+);