pi-odd-worktree 0.0.0-stage → 1.0.0

package/tools/worktree-close-herdr-async.test.js

@@ -0,0 +1,204 @@
+'use strict';
+// S6: `worktree_close` removes a checkout with `git worktree remove` and NOTHING
+// else. The Herdr workspace reconcile it used to run — closing every workspace
+// of the checkout's group and opening a fresh one at the principal — is gone:
+// this package never closes or opens a Herdr panel, and it never asks Herdr to
+// remove a worktree (that route retires the workspace behind the human's back).
+//
+// What is pinned here:
+//   - the removal argv is git's, fixed, with the absolute target and `--force`
+//     only when the caller asked for it;
+//   - the removal helper reports the backend's own reason and never throws;
+//   - the module exports no panel-mutating or session-evidence helper;
+//   - the extension's close surface contains no Herdr workspace action and no
+//     `herdr worktree remove`, and a real close spawns no Herdr process at all.
+
+const { test, describe, before, after } = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { spawnSync } = require('node:child_process');
+const { SRC, loadExtension, stubbedSource } = require('./fixtures/load-extension.js');
+
+const lib = require('../lib/worktree-close-herdr.js');
+
+const TARGET = '/tmp/repo-worktrees/feat-doomed';
+const PRINCIPAL = '/tmp/repo';
+
+const roots = [];
+after(() => {
+  for (const dir of roots) {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+function track(dir) {
+  roots.push(dir);
+  return dir;
+}
+
+describe('S6: the removal surface is git-only', () => {
+  test('the removal argv is git worktree remove with the absolute target', () => {
+    assert.deepEqual(lib.gitRemovalArgv(TARGET, false), ['worktree', 'remove', TARGET]);
+    assert.deepEqual(lib.gitRemovalArgv(TARGET, true), ['worktree', 'remove', '--force', TARGET]);
+    assert.throws(() => lib.gitRemovalArgv('relative/path', false), TypeError);
+  });
+
+  test('a removal asks git exactly once, with the caller root and timeout', async () => {
+    const calls = [];
+    const out = await lib.removeCheckout({
+      runAsync: async (bin, argv, options) => {
+        calls.push({ bin, argv, options });
+        return { status: 0, stdout: '', stderr: '' };
+      },
+      repoRoot: PRINCIPAL,
+      resolvedTarget: TARGET,
+      force: true,
+    });
+    assert.equal(calls.length, 1);
+    assert.equal(calls[0].bin, 'git');
+    assert.deepEqual(calls[0].argv, ['worktree', 'remove', '--force', TARGET]);
+    assert.equal(calls[0].options.cwd, PRINCIPAL);
+    assert.equal(calls[0].options.timeoutMs, lib.REMOVE_TIMEOUT_MS);
+    assert.deepEqual(out, { removed: true, removedBy: 'git' });
+  });
+
+  test('the backend reason travels back verbatim, and no failure ever throws', async () => {
+    const failed = await lib.removeCheckout({
+      runAsync: async () => ({ status: 1, stdout: '', stderr: "fatal: '/x' contains modified or untracked files\nsecond line\n" }),
+      repoRoot: PRINCIPAL,
+      resolvedTarget: TARGET,
+      force: false,
+    });
+    assert.equal(failed.removed, false);
+    assert.equal(failed.error, "fatal: '/x' contains modified or untracked files\nsecond line");
+
+    const noRunner = await lib.removeCheckout({ runAsync: null, repoRoot: PRINCIPAL, resolvedTarget: TARGET, force: false });
+    assert.equal(noRunner.removed, false);
+    assert.match(noRunner.error, /runner/);
+
+    const thrown = await lib.removeCheckout({
+      runAsync: () => { throw new Error('spawn exploded'); },
+      repoRoot: PRINCIPAL,
+      resolvedTarget: TARGET,
+      force: false,
+    });
+    assert.equal(thrown.removed, false);
+    assert.equal(thrown.error, 'spawn exploded');
+  });
+
+  test('no panel-mutating or session-evidence helper survives in the module', () => {
+    for (const gone of [
+      'reconcileHerdrWorkspace',
+      'reconcileHerdrWorkspaceAsync',
+      'workspaceEntryForPath',
+      'workspaceEntriesForPath',
+      'orderedGroupMembers',
+      'parseWorkspaceList',
+      'parseWorkspaceCreateId',
+      'agentsInCheckout',
+    ]) {
+      assert.equal(lib[gone], undefined, `${gone} is not part of the removal surface`);
+    }
+    assert.deepEqual(Object.keys(lib).sort(), ['REMOVE_TIMEOUT_MS', 'gitRemovalArgv', 'removeCheckout']);
+    const source = fs.readFileSync(path.resolve(__dirname, '../lib/worktree-close-herdr.js'), 'utf8');
+    for (const forbidden of ['workspace close', 'workspace create', "'workspace'", "'herdr'", '"herdr"']) {
+      assert.equal(source.includes(forbidden), false, `the module never names ${forbidden}`);
+    }
+  });
+
+  test('the extension contains no Herdr workspace action and no Herdr removal', () => {
+    const source = stubbedSource();
+    for (const gone of [
+      'reconcileHerdrWorkspace',
+      'herdrWorkspaceId',
+      'herdrArgv("remove"',
+      '"workspace", "close"',
+      '"workspace", "create"',
+      "'workspace close'",
+    ]) {
+      assert.equal(source.includes(gone), false, `${gone} is gone from the close surface`);
+    }
+    assert.ok(source.includes('libRequire("worktree-close-herdr.js")'), 'the git removal helper is the removal surface');
+    assert.ok(source.includes('removeCheckout'), 'the close uses the git-only removal');
+  });
+});
+
+describe('S6: a real close spawns no Herdr process', () => {
+  const savedEnv = { ...process.env };
+  const NO_HERDR = path.join(os.tmpdir(), 'odd-worktree-no-such-herdr-binary');
+  const HOOK_BIN = track(fs.mkdtempSync(path.join(os.tmpdir(), 'wt-close-hookbin-')));
+  fs.writeFileSync(path.join(HOOK_BIN, 'codegraph'), '#!/bin/sh\nexit 0\n', { mode: 0o755 });
+  const HERDR_LOG = path.join(track(fs.mkdtempSync(path.join(os.tmpdir(), 'wt-close-herdr-log-'))), 'argv.log');
+  const HERDR_SHIM = path.join(track(fs.mkdtempSync(path.join(os.tmpdir(), 'wt-close-herdr-bin-'))), 'herdr');
+  fs.writeFileSync(HERDR_SHIM, `#!/bin/sh\nprintf '%s\\n' "$*" >> ${JSON.stringify(HERDR_LOG)}\nexit 1\n`, { mode: 0o755 });
+  const AGENT_HOME = track(fs.mkdtempSync(path.join(os.tmpdir(), 'wt-close-agent-home-')));
+
+  let tools;
+  before(async () => {
+    process.env.HERDR_BIN_PATH = NO_HERDR;
+    delete process.env.GENTLE_PI_AGENT_HOME;
+    process.env.PI_CODING_AGENT_DIR = AGENT_HOME;
+    process.env.PATH = `${HOOK_BIN}${path.delimiter}${savedEnv.PATH || ''}`;
+    ({ tools } = await loadExtension({}));
+  });
+
+  after(() => {
+    for (const key of Object.keys(process.env)) {
+      if (!(key in savedEnv)) delete process.env[key];
+    }
+    for (const [key, value] of Object.entries(savedEnv)) process.env[key] = value;
+  });
+
+  function git(cwd, args) {
+    const out = spawnSync('git', args, { cwd, encoding: 'utf8' });
+    if (out.status !== 0) throw new Error(`git ${args.join(' ')} failed: ${out.stderr}`);
+    return out.stdout.trim();
+  }
+
+  function makeRepo() {
+    const dir = track(fs.mkdtempSync(path.join(os.tmpdir(), 'wt-close-repo-')));
+    git(dir, ['init', '-b', 'main']);
+    git(dir, ['config', 'user.email', 'test@example.test']);
+    git(dir, ['config', 'user.name', 'Test']);
+    fs.writeFileSync(path.join(dir, 'README.md'), '# fixture\n');
+    git(dir, ['add', 'README.md']);
+    git(dir, ['commit', '-m', 'init']);
+    return dir;
+  }
+
+  function makeCtx(repoRoot) {
+    return {
+      cwd: repoRoot,
+      hasUI: false,
+      mode: 'tui',
+      sessionManager: { getSessionId: () => 'close-session' },
+      ui: { confirm: async () => true, notify: () => {} },
+    };
+  }
+
+  function resultText(result) {
+    return (result.content || []).map((part) => (part && part.text) || '').join('\n');
+  }
+
+  test('closing a checkout never closes a panel, creates one, or asks Herdr to remove anything', async () => {
+    const repo = makeRepo();
+    const ctx = makeCtx(repo);
+    const created = await tools.get('worktree_create').execute('c1', { branch: 'feat/quiet', changes: 'none' }, undefined, undefined, ctx);
+    assert.notEqual(created.isError, true, resultText(created));
+    const target = path.join(path.dirname(repo), `${path.basename(repo)}-worktrees`, 'feat-quiet');
+
+    // From here on any Herdr spawn would leave a line in the log.
+    process.env.HERDR_BIN_PATH = HERDR_SHIM;
+    try {
+      const closed = await tools.get('worktree_close').execute('c2', { name: 'feat-quiet' }, undefined, undefined, ctx);
+      assert.notEqual(closed.isError, true, resultText(closed));
+    } finally {
+      process.env.HERDR_BIN_PATH = NO_HERDR;
+    }
+    assert.equal(fs.existsSync(target), false, 'git removed the checkout');
+    const log = fs.existsSync(HERDR_LOG) ? fs.readFileSync(HERDR_LOG, 'utf8').trim() : '';
+    assert.equal(log, '', `the close spawned no Herdr process at all: ${log}`);
+  });
+});

package/tools/worktree-odd-migration.test.js

@@ -0,0 +1,224 @@
+'use strict';
+// T8 / S8b migration regressions: a registry row written by an older version
+// carries `odd[]`. The entity rule keeps ONE document, so every read
+// normalizes it deterministically to its FIRST entry, and a write that
+// COLLAPSES an addressed row reports the entries left behind once
+// (`dropped: [...]`) — a stored association never disappears silently.
+//
+// S1 narrowed that further: the worktree no longer carries an association at
+// all, so the write paths that rewrite the whole file for an UNRELATED row
+// must not normalize anything on the way through. Those rows keep their
+// stored documents byte for byte, which is why no drop report reaches a
+// worktree output any more. This file pins both halves: preservation for the
+// rows a write does not address, and the one-document rule plus its report
+// for the row it does.
+//
+// These cases are independent of tools/worktree-registry-odd.test.js: they
+// pin the migration behaviour of the WRITE paths that rewrite the whole file
+// (unrelated upsert, every removal writer, prune, discovery), of addOddDoc,
+// and of the three ways `upsertWorktree` can talk about `odd` (omitted,
+// null, empty). They also pin that the non-enumerable migration marker can
+// never be serialized into the registry.
+//
+// Every test builds its own isolated fixture repository under os.tmpdir()
+// and asserts through the registry's public API plus the bytes on disk.
+
+const { test, describe, after } = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { spawnSync } = require('node:child_process');
+
+const registryLib = require('../lib/worktree-registry.js');
+
+const LEGACY = ['odd/tasks/first.md', 'odd/tasks/second.md', 'odd/tasks/third.md'];
+
+const roots = [];
+after(() => {
+  for (const dir of roots) {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+function track(dir) {
+  roots.push(dir);
+  return dir;
+}
+
+function git(cwd, args) {
+  const result = spawnSync('git', args, { cwd, encoding: 'utf8' });
+  assert.equal(result.status, 0, `git ${args.join(' ')} failed: ${result.stderr}`);
+  return (result.stdout || '').trim();
+}
+
+function makeRepo(tag) {
+  const dir = track(fs.mkdtempSync(path.join(os.tmpdir(), `wt-mig-${tag}-`)));
+  git(dir, ['init']);
+  git(dir, ['config', 'user.email', 'test@example.com']);
+  git(dir, ['config', 'user.name', 'Test']);
+  git(dir, ['commit', '--allow-empty', '-m', 'init']);
+  return fs.realpathSync(dir);
+}
+
+function checkoutPath(root, slug) {
+  return path.join(path.dirname(root), `${path.basename(root)}-${slug}`);
+}
+
+function row(branch, root) {
+  return { branch, path: checkoutPath(root, branch.replace(/[^a-z0-9]+/gi, '-')), thread: `thread-${branch}`, issues: [] };
+}
+
+function writeRegistryFile(root, rows) {
+  const file = registryLib.registryPath(root);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, `${JSON.stringify({ version: registryLib.REGISTRY_VERSION, worktrees: rows }, null, 2)}\n`);
+  return file;
+}
+
+// A legacy registry: one row carrying the old array, plus one unrelated row
+// the write paths can act on without touching the legacy row.
+function legacyRepo(tag) {
+  const root = makeRepo(tag);
+  const legacy = row('feat/legacy', root);
+  const other = row('feat/other', root);
+  const file = writeRegistryFile(root, [
+    { ...legacy, odd: LEGACY.slice() },
+    { ...other, odd: 'odd/tasks/other.md' },
+  ]);
+  return { root, legacy, other, file };
+}
+
+function storedRow(root, branch) {
+  const raw = fs.readFileSync(registryLib.registryPath(root), 'utf8');
+  return JSON.parse(raw).worktrees.find((entry) => entry.branch === branch);
+}
+
+function oddOf(root, branch) {
+  return registryLib.findByBranch(root, branch).odd;
+}
+
+describe('S8b migration: legacy odd[] rows normalize to ONE document', { concurrency: false }, () => {
+  test('a READ of a legacy row never rewrites the file and never fails', () => {
+    const { root, file } = legacyRepo('read');
+    const before = fs.readFileSync(file, 'utf8');
+
+    const read = registryLib.readRegistry(root);
+    assert.equal(read.ok, true, `a read never fails on a legacy array: ${read.error}`);
+    assert.equal(read.worktrees.find((entry) => entry.branch === 'feat/legacy').odd, LEGACY[0]);
+    assert.equal(oddOf(root, 'feat/legacy'), LEGACY[0], 'the lookups inherit the same first entry');
+    assert.equal(fs.readFileSync(file, 'utf8'), before, 'reading migrated nothing: the bytes are identical');
+  });
+
+  test('a write to an UNRELATED row leaves the legacy row byte for byte, with no report', () => {
+    const { root, other } = legacyRepo('unrelated');
+    // Nothing about the legacy row is supplied: the write still persists the
+    // whole file, and it must carry that row through untouched.
+    const written = registryLib.upsertWorktree(root, {
+      branch: 'feat/other', path: other.path, thread: 'thread-feat/other', issues: [7],
+    });
+    assert.equal(written.ok, true, `expected the write to succeed: ${JSON.stringify(written)}`);
+    assert.equal('dropped' in written, false, 'a row nobody addressed lost nothing, so nothing is reported');
+    assert.equal(oddOf(root, 'feat/legacy'), LEGACY[0], 'the in-memory view keeps ONE document');
+    assert.deepEqual(storedRow(root, 'feat/legacy').odd, LEGACY, 'the stored list survives verbatim');
+
+    const again = registryLib.updateWorktree(root, 'feat/other', { issues: [7, 8] });
+    assert.equal(again.ok, true);
+    assert.equal('dropped' in again, false, 'and still nothing to report');
+    assert.deepEqual(storedRow(root, 'feat/legacy').odd, LEGACY, 'after every write');
+  });
+
+  test('removeWorktree leaves the surviving legacy row byte for byte', () => {
+    const { root, other } = legacyRepo('remove');
+    const removed = registryLib.removeWorktree(root, 'feat/other');
+    assert.equal(removed.ok, true, `expected the removal to succeed: ${JSON.stringify(removed)}`);
+    assert.equal('dropped' in removed, false, 'removing one row destroys nothing of another');
+    assert.deepEqual(storedRow(root, 'feat/legacy').odd, LEGACY, 'every stored document survives');
+    assert.equal(registryLib.findByBranch(root, 'feat/other'), null, 'the removed row is gone');
+  });
+
+  test('removeWorktreeByPath leaves the surviving legacy row byte for byte', () => {
+    const { root, other } = legacyRepo('remove-path');
+    const removed = registryLib.removeWorktreeByPath(root, other.path);
+    assert.equal(removed.ok, true, `expected the removal to succeed: ${JSON.stringify(removed)}`);
+    assert.equal('dropped' in removed, false);
+    assert.deepEqual(storedRow(root, 'feat/legacy').odd, LEGACY);
+  });
+
+  test('removeWorktreeExact leaves the surviving legacy row byte for byte', () => {
+    const { root, other } = legacyRepo('remove-exact');
+    const removed = registryLib.removeWorktreeExact(root, other.branch, other.path);
+    assert.equal(removed.ok, true, `expected the removal to succeed: ${JSON.stringify(removed)}`);
+    assert.equal('dropped' in removed, false);
+    assert.deepEqual(storedRow(root, 'feat/legacy').odd, LEGACY);
+  });
+
+  test('pruneWorktrees leaves the surviving legacy row byte for byte', () => {
+    const { root, other } = legacyRepo('prune');
+    const pruned = registryLib.pruneWorktrees(root, [other.path]);
+    assert.equal(pruned.ok, true, `expected the prune to succeed: ${JSON.stringify(pruned)}`);
+    assert.deepEqual(pruned.pruned, [other.path], 'the dead row was pruned');
+    assert.equal('dropped' in pruned, false, 'the prune write destroys nothing of a row it kept');
+    assert.deepEqual(storedRow(root, 'feat/legacy').odd, LEGACY);
+  });
+
+  test('addOddDoc over a legacy row replaces it, reporting the drop and the replacement', () => {
+    const { root } = legacyRepo('add');
+    const added = registryLib.addOddDoc(root, 'feat/legacy', 'odd/tasks/chosen.md');
+    assert.equal(added.ok, true, `expected the association to succeed: ${JSON.stringify(added)}`);
+    assert.equal(added.entry.odd, 'odd/tasks/chosen.md', 'the chosen document is the ONLY association');
+    assert.equal(added.added, true);
+    assert.equal(added.replaced, LEGACY[0], 'the first entry lost the association, and that is reported');
+    assert.deepEqual(added.dropped, LEGACY.slice(1), 'and the entries the legacy array lost are reported too');
+    assert.equal(storedRow(root, 'feat/legacy').odd, 'odd/tasks/chosen.md');
+
+    const repeat = registryLib.addOddDoc(root, 'feat/legacy', 'odd/tasks/chosen.md');
+    assert.equal(repeat.added, false, 'a repeat association is idempotent');
+    assert.equal(repeat.replaced, null);
+    assert.equal('dropped' in repeat, false, 'a normalized row drops nothing');
+  });
+
+  test('upsert says nothing, null or an empty list: keep, clear, clear', () => {
+    const root = makeRepo('upsert-forms');
+    const target = row('feat/forms', root);
+    assert.equal(registryLib.upsertWorktree(root, { ...target, odd: 'odd/tasks/kept.md' }).ok, true);
+
+    const omitted = registryLib.upsertWorktree(root, { ...target, issues: [1] });
+    assert.equal(omitted.ok, true);
+    assert.equal(omitted.entry.odd, 'odd/tasks/kept.md', 'an omitted odd keeps the association');
+    assert.equal('dropped' in omitted, false, 'and reports nothing');
+
+    const cleared = registryLib.upsertWorktree(root, { ...target, odd: null });
+    assert.equal(cleared.ok, true);
+    assert.equal(cleared.entry.odd, null, 'null clears the association');
+    assert.equal(storedRow(root, 'feat/forms').odd, null);
+
+    assert.equal(registryLib.addOddDoc(root, 'feat/forms', 'odd/tasks/back.md').ok, true);
+    const emptied = registryLib.upsertWorktree(root, { ...target, odd: [] });
+    assert.equal(emptied.ok, true, 'an empty list is the legacy spelling of "none"');
+    assert.equal(emptied.entry.odd, null, 'and normalizes to null, never to []');
+    assert.equal(storedRow(root, 'feat/forms').odd, null);
+  });
+
+  test('no migration marker is ever serialized into the registry', () => {
+    const { root, other } = legacyRepo('serialize');
+    registryLib.upsertWorktree(root, { branch: 'feat/other', path: other.path, thread: 'thread-feat/other', issues: [2] });
+    registryLib.removeWorktree(root, 'feat/other');
+
+    const raw = fs.readFileSync(registryLib.registryPath(root), 'utf8');
+    assert.ok(!raw.includes('oddDropped'), `the non-enumerable marker never reaches the file:\n${raw}`);
+    assert.ok(!raw.includes('"dropped"'), 'and neither does the report');
+    const stored = JSON.parse(raw).worktrees.find((entry) => entry.branch === 'feat/legacy');
+    assert.deepEqual(stored.odd, LEGACY, 'the row still holds every stored document');
+    assert.equal('oddDropped' in stored, false);
+
+    // The marker exists only on the in-memory read, where a write that
+    // addresses this row can still find it; it never survives serialization
+    // and is never an observable field of the row.
+    const reread = registryLib.readRegistry(root).worktrees.find((entry) => entry.branch === 'feat/legacy');
+    assert.equal(Object.keys(reread).includes('oddDropped'), false, 'the stamp is invisible to a caller');
+    assert.equal(JSON.stringify(reread).includes('oddDropped'), false, 'and never serializes');
+    assert.equal(reread.odd, LEGACY[0], 'the in-memory view keeps ONE document');
+  });
+});
+

package/tools/worktree-registry-cache.test.js

@@ -0,0 +1,163 @@
+'use strict';
+// S22 (round 3): reading the registry must not spawn git.
+//
+// The reported symptom was a plugin that made every tool call and every
+// repaint feel heavy. `readRegistry` resolved the storage path through
+// `repoIdentity` — two `spawnSync` git probes, ~19 ms on this machine — on
+// EVERY call, and the interactive paths read the registry several times per
+// action (once per tool event, once per list/detail/selector read). The
+// resolution is cached per checkout and the parsed file per (inode, mtime,
+// size), so a repeated read costs no child and a write is still seen at once.
+
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const childProcess = require('node:child_process');
+
+function makeRepo() {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'registry-cache-'));
+  const run = (args) => {
+    const res = childProcess.spawnSync('git', args, { cwd: root, encoding: 'utf8' });
+    assert.equal(res.status, 0, `git ${args.join(' ')}: ${res.stderr}`);
+    return res.stdout;
+  };
+  run(['init', '-q', '-b', 'main']);
+  run(['config', 'user.email', 'test@example.com']);
+  run(['config', 'user.name', 'Test']);
+  fs.writeFileSync(path.join(root, 'README.md'), '# repo\n');
+  run(['add', '.']);
+  run(['commit', '-q', '-m', 'init']);
+  return root;
+}
+
+// A fresh module (no warm state) with every `spawnSync` counted, so the
+// assertions describe one process, not a previous test's cache.
+function loadWithCounter() {
+  const libPath = require.resolve('../lib/worktree-registry.js');
+  delete require.cache[libPath];
+  const seen = [];
+  const original = childProcess.spawnSync;
+  childProcess.spawnSync = (bin, args, opts) => {
+    seen.push({ bin: String(bin), args: Array.isArray(args) ? args.slice() : [] });
+    return original(bin, args, opts);
+  };
+  const registry = require('../lib/worktree-registry.js');
+  return {
+    registry,
+    seen,
+    gitSpawns: () => seen.filter((call) => call.bin === 'git').length,
+    restore: () => {
+      childProcess.spawnSync = original;
+    },
+  };
+}
+
+function entry(overrides = {}) {
+  return {
+    branch: 'feat/one',
+    path: '/tmp/one',
+    thread: 'test-thread',
+    issues: [],
+    odd: null,
+    createdAt: '2024-01-01T00:00:00.000Z',
+    updatedAt: '2024-01-01T00:00:00.000Z',
+    ...overrides,
+  };
+}
+
+test('five registry reads in one checkout resolve the repository once, not once per read', () => {
+  const root = makeRepo();
+  const loaded = loadWithCounter();
+  try {
+    for (let index = 0; index < 5; index += 1) {
+      const read = loaded.registry.readRegistry(root);
+      assert.equal(read.ok, true);
+    }
+    // `git rev-parse --show-toplevel` + `--git-common-dir`, the first time only.
+    assert.equal(loaded.gitSpawns(), 2,
+      `one resolution for the checkout, not one per read: ${JSON.stringify(loaded.seen)}`);
+  } finally {
+    loaded.restore();
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test('a write through the registry is visible to the very next read', () => {
+  const root = makeRepo();
+  const loaded = loadWithCounter();
+  try {
+    const written = loaded.registry.upsertWorktree(root, entry());
+    assert.equal(written.ok, true, `upsert: ${JSON.stringify(written)}`);
+    const read = loaded.registry.readRegistry(root);
+    assert.equal(read.ok, true);
+    assert.equal(read.worktrees.length, 1, 'the row written under the lock is read back');
+    assert.equal(read.worktrees[0].branch, 'feat/one');
+  } finally {
+    loaded.restore();
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test('another process writing the registry invalidates a cached read', () => {
+  const root = makeRepo();
+  const loaded = loadWithCounter();
+  try {
+    assert.equal(loaded.registry.readRegistry(root).worktrees.length, 0, 'nothing registered yet');
+    const file = path.join(fs.realpathSync(root), '.git', 'pi-worktrees.json');
+    // A different writer: same path, written in place, like a hand edit.
+    const doc = { version: 1, worktrees: [{ ...entry({ branch: 'feat/external', path: '/tmp/external' }) }] };
+    fs.writeFileSync(file, `${JSON.stringify(doc, null, 2)}\n`);
+    const read = loaded.registry.readRegistry(root);
+    assert.equal(read.worktrees.length, 1, 'the external write is seen, never a stale empty registry');
+    assert.equal(read.worktrees[0].branch, 'feat/external');
+  } finally {
+    loaded.restore();
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test('two checkouts of the same repository never share one cache slot, and a caller cannot mutate a cached doc', () => {
+  const root = makeRepo();
+  const other = fs.mkdtempSync(path.join(os.tmpdir(), 'registry-cache-wt-'));
+  const loaded = loadWithCounter();
+  try {
+    assert.equal(loaded.registry.upsertWorktree(root, entry()).ok, true);
+    const linked = path.join(other, 'linked');
+    const added = childProcess.spawnSync('git', ['worktree', 'add', '-q', '-b', 'feat/linked', linked, 'HEAD'],
+      { cwd: root, encoding: 'utf8' });
+    assert.equal(added.status, 0, added.stderr);
+    const first = loaded.registry.readRegistry(root);
+    first.worktrees.push(entry({ branch: 'feat/mutated' }));
+    const again = loaded.registry.readRegistry(root);
+    assert.equal(again.worktrees.length, 1, 'the cached document is never handed out for mutation');
+    const fromLinked = loaded.registry.readRegistry(linked);
+    assert.deepEqual(fromLinked.worktrees.map((row) => row.branch), ['feat/one'],
+      'both checkouts read the same shared registry file');
+  } finally {
+    loaded.restore();
+    fs.rmSync(root, { recursive: true, force: true });
+    fs.rmSync(other, { recursive: true, force: true });
+  }
+});
+
+test('a cached read still carries the hidden drop report a later write needs', () => {
+  const root = makeRepo();
+  const loaded = loadWithCounter();
+  try {
+    const file = path.join(fs.realpathSync(root), '.git', 'pi-worktrees.json');
+    const legacy = { version: 1, worktrees: [{ ...entry({ branch: 'feat/legacy' }), odd: ['odd/tasks/first.md', 'odd/tasks/second.md'] }] };
+    fs.writeFileSync(file, `${JSON.stringify(legacy, null, 2)}\n`);
+    // Read twice: the second one comes from the cache.
+    assert.equal(loaded.registry.readRegistry(root).worktrees[0].odd, 'odd/tasks/first.md');
+    assert.equal(loaded.registry.readRegistry(root).worktrees[0].odd, 'odd/tasks/first.md');
+    const updated = loaded.registry.updateWorktree(root, 'feat/legacy', { issues: [] });
+    assert.equal(updated.ok, true);
+    assert.deepEqual(updated.dropped, ['odd/tasks/second.md'],
+      'the collapsing write still names the document it dropped');
+  } finally {
+    loaded.restore();
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+});