create-evda 0.1.8 → 0.1.10

package/lib/pairing.mjs

@@ -14,6 +14,7 @@ import { dirname, join, resolve } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { EvdaError } from "./errors.mjs";
 import { openEvda } from "./manifest.mjs";
+import { SYNC_BUSY, acquireSyncLock, withSyncLock } from "./sync-lock.mjs";
 
 const PKG = resolve(dirname(fileURLToPath(import.meta.url)), "..");
 export const PAIRING_BUNDLE = join(PKG, "dist", "pairing.mjs");
@@ -63,7 +64,7 @@ export async function loadPairing({ bundle = PAIRING_BUNDLE, version = process.v
 }
 
 // A refusal wrote nothing and is exit 2; anything else (the relay unreachable) is exit 1.
-const REFUSALS = /^(Your EVÐA has no private|This record has no private part|There is already a device|There is no paired device|Give the device a name|Name at least one part)/;
+const REFUSALS = /^(Stopped: this disk has|Your EVÐA has no private|Your EVÐA is busy|Your EVÐA's keys|This record has no private part|This record has private parts|This record keeps its day folder|There is already a device|There is no paired device|Give the device a name|Name at least one part)/;
 function asEvdaError(error) {
   if (error instanceof EvdaError) return error;
   const message = error instanceof Error ? error.message : String(error);
@@ -80,7 +81,7 @@ const partsList = (value) => (Array.isArray(value) ? value : String(value ?? "")
 export async function pair(dir, { name, parts, relay, env } = {}) {
   const p = await loadPairing();
   try {
-    return await p.pairDevice(ownerOptions(dir, { env, relay }), { name: name ?? "phone", parts: partsList(parts ?? "journal") });
+    return await p.pairDevice(ownerOptions(dir, { env, relay }), { name: name ?? "phone", parts: partsList(parts) });
   } catch (error) {
     throw asEvdaError(error);
   }
@@ -126,26 +127,240 @@ export async function deviceData(dir, { relay, env = process.env, bundle } = {})
 export async function syncData(dir, { relay, env } = {}) {
   const p = await loadPairing();
   try {
-    return await p.syncOnce(ownerOptions(dir, { env, relay }));
+    return await withSyncLock(dir, () => p.syncOnce(ownerOptions(dir, { env, relay })), { env });
   } catch (error) {
     throw asEvdaError(error);
   }
 }
 
+// Finish a pairing whose code was used, without scanning the record (HQ-2017). It never waits: a
+// sync that holds the record answers `busy`, and that sync collects the code itself. The Mac app
+// runs this every few seconds while a code is waiting.
+async function finishWith(dir, fn, { env = process.env } = {}) {
+  let release;
+  try {
+    release = await acquireSyncLock(dir, { waitMs: 0, env });
+  } catch (error) {
+    if (error?.code === "SYNC_BUSY") return null;
+    throw error;
+  }
+  try {
+    return await fn();
+  } finally {
+    await release();
+  }
+}
+
+/** One finish as data, for an app: `{paired: [names], waiting: [names], busy?: line}`. No id. */
+export async function finishData(dir, { relay, env = process.env } = {}) {
+  const list = pairedList(dir, env);
+  if (!list || !existsSync(list)) return { paired: [], waiting: [] };
+  const p = await loadPairing();
+  try {
+    const r = await finishWith(dir, () => p.finishPairing(ownerOptions(dir, { env, relay })), { env });
+    return r ?? { paired: [], waiting: (await p.deviceList(ownerOptions(dir, { env, relay }))).filter((d) => d.state.startsWith("waiting")).map((d) => d.name), busy: SYNC_BUSY };
+  } catch (error) {
+    throw asEvdaError(error);
+  }
+}
+
+/** One finish, in plain words. */
+export async function finish(dir, { relay, env = process.env } = {}) {
+  const r = await finishData(dir, { relay, env });
+  if (r.busy) return [r.busy];
+  const lines = [
+    ...r.paired.map((n) => `${n} is now paired.`),
+    // What went to it (HQ-2106): a finish that paired a device says what it sent and what failed.
+    ...(r.paired.length ? [`Sent ${(r.sent ?? 0).toLocaleString("en-US")} change(s) of your record to it.`] : []),
+    ...(r.errors ?? []).map((e) => `Could not send everything yet: ${e}. The next sync sends the rest.`),
+    ...r.waiting.map((n) => `Waiting for ${n} to use its code.`),
+  ];
+  return lines.length ? lines : ["No device is waiting to be added."];
+}
+
+/**
+ * What is syncing on this computer now, as data for an app (HQ-2041): `{holder: {by, op, since} | null,
+ * owed}`, read from the state's lock and outbox. A record that never paired anything answers
+ * `{holder: null, owed: null}` without loading the bundle. No id.
+ */
+export async function statusData(dir, { relay, env = process.env, bundle } = {}) {
+  const list = pairedList(dir, env);
+  if (!list || !existsSync(list)) return { holder: null, owed: null };
+  const p = await loadPairing(bundle ? { bundle } : {});
+  try {
+    return await p.syncState(ownerOptions(dir, { env, relay }));
+  } catch (error) {
+    throw asEvdaError(error);
+  }
+}
+
+// Removing a device syncs at its end (the re-keyed parts go out at once), so it holds the record's
+// sync lock as a sync does (HQ-2040): a remove and a sync never talk to the relay for one record at once.
 export async function remove(dir, name, { relay, env } = {}) {
   if (!name || !String(name).trim()) throw new EvdaError("Say which device to remove: evda remove <device>. `evda devices` lists them.", { code: "USAGE", exit: 2 });
   const p = await loadPairing();
   try {
-    return await p.removeDeviceWords(ownerOptions(dir, { env, relay }), String(name).trim());
+    return await withSyncLock(dir, () => p.removeDeviceWords(ownerOptions(dir, { env, relay }), String(name).trim()), { env });
   } catch (error) {
     throw asEvdaError(error);
   }
 }
 
+/**
+ * What removing a device would do, in plain words, read only (HQ-2040): the MCP says this and asks
+ * before it removes anything. Refuses a name that is not a device here, naming the ones that are.
+ */
+export async function describeRemoval(dir, name, { env = process.env } = {}) {
+  const wanted = String(name ?? "").trim();
+  if (!wanted) throw new EvdaError("Say which device to remove. evda_devices lists them.", { code: "USAGE", exit: 2 });
+  const list = (await deviceData(dir, { env })).filter((d) => d.state !== "removed");
+  const d = list.find((x) => x.name === wanted);
+  if (!d) {
+    throw new EvdaError(`There is no device called ${wanted} to remove. ${list.length ? `The devices are: ${list.map((x) => x.name).join(", ")}.` : NO_DEVICES}`, { code: "NO_DEVICE", exit: 2 });
+  }
+  if (d.state !== "paired") {
+    return [`${wanted} has not used its code (${d.state}). Removing it cancels the code, so it can never be used. Nothing else changes.`];
+  }
+  return [
+    `Removing ${wanted} would:`,
+    `1. take away its access to ${d.parts.join(", ")}, so it can no longer add to your EVÐA;`,
+    "2. change the keys of those parts, so nothing written from now on reaches it;",
+    "3. sync, so the change goes out at once.",
+    `What ${wanted} already has stays on it; removing cannot reach a copy already opened. It cannot be undone: to use ${wanted} again, pair it anew.`,
+  ];
+}
+
+/**
+ * The relay mailboxes this computer reads, one per paired device, for the watcher that takes in a
+ * device's note within seconds (HQ-2068). Empty when nothing is paired; null when a sync holds the
+ * state, so the watcher looks again later instead of waiting on it. Held in memory, never printed.
+ */
+export async function inboundMailboxes(dir, { relay, env = process.env, bundle } = {}) {
+  const list = pairedList(dir, env);
+  if (!list || !existsSync(list)) return [];
+  const p = await loadPairing(bundle ? { bundle } : {});
+  return p.inboundMailboxes(ownerOptions(dir, { env, relay }));
+}
+
+/** Every device's sync state, in plain words (HQ-2040). */
+export async function syncStatus(dir, { relay, env = process.env, bundle } = {}) {
+  const list = pairedList(dir, env);
+  if (!list || !existsSync(list)) return [NO_DEVICES];
+  const p = await loadPairing(bundle ? { bundle } : {});
+  try {
+    return await p.syncStatusWords(ownerOptions(dir, { env, relay }));
+  } catch (error) {
+    throw asEvdaError(error);
+  }
+}
+
+/** Every device with when this computer last heard from it, naming the computer (HQ-2040). */
+export async function deviceContacts(dir, { relay, env = process.env, bundle } = {}) {
+  const list = pairedList(dir, env);
+  if (!list || !existsSync(list)) return [NO_DEVICES];
+  const p = await loadPairing(bundle ? { bundle } : {});
+  try {
+    return await p.deviceContactLines(ownerOptions(dir, { env, relay }));
+  } catch (error) {
+    throw asEvdaError(error);
+  }
+}
+
+// Finishing a pairing from the MCP (HQ-2040). Both forms poll finishData, which takes the record's
+// sync lock without waiting and the state's lock without waiting: a running sync answers busy and
+// collects the code itself. So nothing here ever holds a lock between polls, and nothing runs in
+// a child process.
+export const FINISH_POLL_MS = 2_000;
+export const FINISH_WAIT_MAX_S = 120;
+const pausing = (ms) => new Promise((ok) => setTimeout(ok, ms));
+
+/**
+ * Wait up to `seconds` for a device that has a code open to use it, adding it when it does. Returns
+ * plain lines. Stops as soon as no device is waiting, whatever the deadline.
+ */
+export async function finishWaiting(dir, { seconds = 60, relay, env = process.env, pollMs } = {}) {
+  const every = pollMs ?? (Number(env.EVDA_FINISH_POLL_MS) > 0 ? Number(env.EVDA_FINISH_POLL_MS) : FINISH_POLL_MS);
+  const wait = Math.max(0, Math.min(FINISH_WAIT_MAX_S, Number(seconds) || 0)) * 1000;
+  const deadline = Date.now() + wait;
+  const paired = [];
+  let r = await finishData(dir, { relay, env });
+  paired.push(...r.paired);
+  while (r.waiting.length && Date.now() + every <= deadline) {
+    await pausing(every);
+    r = await finishData(dir, { relay, env });
+    paired.push(...r.paired);
+  }
+  const lines = paired.map((n) => `${n} is now paired.`);
+  if (r.waiting.length) lines.push(`Still waiting for ${r.waiting.join(", ")} to use the code. It is added on its own when it does, while this server runs, until the code runs out.`);
+  if (lines.length === 0) lines.push("No device is waiting to be added.");
+  return lines;
+}
+
+// One watcher a record, in this process. It stops when nothing is waiting, when `until` passes, or
+// when stopWatching is called; its timer never keeps the process alive.
+const watchers = new Map();
+
+/**
+ * After a code is made, keep finishing in the background until the device uses it or the code runs
+ * out (HQ-2040): the MCP's evda_pair completes the join itself, bounded by the code's own expiry.
+ */
+export function watchPairing(dir, { until, relay, env = process.env, everyMs } = {}) {
+  const every = everyMs ?? (Number(env.EVDA_FINISH_POLL_MS) > 0 ? Number(env.EVDA_FINISH_POLL_MS) : FINISH_POLL_MS);
+  const key = resolve(dir);
+  const prior = watchers.get(key);
+  const w = { until: Math.max(until ?? 0, prior?.until ?? 0), timer: null, paired: [...(prior?.paired ?? [])], stopped: false };
+  if (prior) clearTimeout(prior.timer);
+  watchers.set(key, w);
+  const tick = async () => {
+    if (w.stopped) return;
+    try {
+      const r = await finishData(dir, { relay, env });
+      w.paired.push(...r.paired);
+      if (!r.waiting.length && !r.busy) return stop();
+    } catch {
+      // the relay unreachable for a moment: try again on the next tick, until the code runs out
+    }
+    if (Date.now() >= w.until) return stop();
+    schedule();
+  };
+  const schedule = () => {
+    w.timer = setTimeout(tick, every);
+    w.timer.unref?.();
+  };
+  const stop = () => {
+    w.stopped = true;
+    clearTimeout(w.timer);
+    if (watchers.get(key) === w) watchers.delete(key);
+  };
+  schedule();
+  return { paired: w.paired, stop, get running() { return !w.stopped; } };
+}
+
+/** Stop every watcher in this process (for tests, and a server that is closing). */
+export function stopWatching() {
+  for (const w of watchers.values()) { w.stopped = true; clearTimeout(w.timer); }
+  watchers.clear();
+}
+
+// Both syncs hold the record's sync lock (lib/sync-lock.mjs), so the Mac app, launchd, the MCP and a
+// terminal never sync one record at the same time.
 export async function sync(dir, { relay, env } = {}) {
   const p = await loadPairing();
   try {
-    return await p.syncWords(ownerOptions(dir, { env, relay }));
+    return await withSyncLock(dir, () => p.syncWords(ownerOptions(dir, { env, relay })), { env });
+  } catch (error) {
+    throw asEvdaError(error);
+  }
+}
+
+// Give back the space the computer's sync state holds for sealed copies nothing needs (HQ-2017):
+// media, which travels by name only, and copies no device is still owed. Prints what it would remove
+// unless `yes`. Holds the state's lock, as a sync does.
+export async function compact(dir, { yes = false, env = process.env } = {}) {
+  const p = await loadPairing();
+  try {
+    const { record, home } = ownerOptions(dir, { env });
+    return await p.compactWords({ record, home, yes: yes === true });
   } catch (error) {
     throw asEvdaError(error);
   }
@@ -163,3 +378,26 @@ export function pairText(r) {
     `${r.name} will be able to read and add to ${r.parts.join(", ")}, and nothing else. The code is a key until it is used: show it only to the owner.`,
   ].join("\n");
 }
+
+/**
+ * evda_pair's answer (HQ-2040): which computer the phone pairs to, the code, the QR as text, the
+ * steps, and that this server finishes the join on its own until the code runs out.
+ */
+export function pairToolText(r, { qrText, until } = {}) {
+  const clock = (ms) => new Date(ms).toLocaleTimeString([], { hour: "2-digit", minute: "2-digit" });
+  return [
+    `This pairs ${r.name} to ${r.computer}, the computer this EVÐA server runs on. ${r.name} will sync with the copy of the record on ${r.computer}, and ${r.computer} is where it shows up in the device list.`,
+    "",
+    `Pairing code for ${r.name}: ${r.code}`,
+    `QR link: ${r.qr}`,
+    ...(qrText ? ["", "The QR code to scan with the phone's camera (show it to the owner exactly as it is, in a code block):", "", qrText] : []),
+    "",
+    "On the phone:",
+    "1. Scan the QR code with the camera, or open the EVÐA app, choose to join an EVÐA, and paste the code.",
+    `2. Say yes to "Pair with ${r.computer}?". The code works once, until ${clock(r.expiresAt)}.`,
+    `3. Nothing to do here: this server adds ${r.name} on its own once it uses the code, until ${clock(until ?? r.expiresAt)}. evda_finish_pairing waits for it and says when it is in.`,
+    `4. ${r.name} then holds ${r.parts.join(", ")}, and what is written there lands in today's page on ${r.computer} on the next sync.`,
+    "",
+    `${r.name} will be able to read and add to ${r.parts.join(", ")}, and nothing else. The code is a key until it is used: show it only to the owner.`,
+  ].join("\n");
+}

package/lib/parity.mjs

@@ -47,7 +47,17 @@
 //                that path's newest Change, not the global one: a file written after the source
 //                last sent THIS path is LAG. Measured 2026-09-27 on Hestia: the two DIFFERS files'
 //                newest Changes were 06:20:41Z, their record mtime 06:48:41Z, the global newest
-//                Change 06:53:08Z. A path the source never sent keeps the global line.
+//                Change 06:53:08Z.
+//   LAG, first     a path the source has never sent has no mark of its own, and the global one says
+//   appearance     nothing about it: a file written on this device reaches the source as an iCloud
+//                placeholder, which the source skips, while it mints other paths and moves
+//                `settled` past it. Measured 2026-10-04 on Hestia (HQ-2169): Overnight's daily record
+//                written here 06:02:12Z, the laptop's 07:09:56Z tick logged it "in iCloud only" and
+//                minted four other paths, the newest 07:10:27.816Z, and the file read MISSING. So a
+//                MISSING path with no mark, when the marks were given, is judged against its own
+//                write time: LAG while the source's newest Change is within `staleAfterMs` of it,
+//                MISSING past that. An unmarked DIFFERS keeps the global line: the shadow holds the
+//                path, so its bytes came from somewhere the marks do not explain.
 //                The per-path excuse is bounded: once the source's newest Change is more than
 //                `staleAfterMs` past the file's mtime, the source has been scanning (the laptop's
 //                daily full pass reads every file) and still has not sent it, so it fails as what
@@ -63,7 +73,7 @@ import { createHash } from "node:crypto";
 import { readFileSync, statSync } from "node:fs";
 import { join } from "node:path";
 import { circleForPath } from "./filechanges.mjs";
-import { excluder, walk } from "./sync-rules.mjs";
+import { excluder, fileClass, walk } from "./sync-rules.mjs";
 
 const nfc = (rel) => rel.normalize("NFC");
 // A path iCloud Drive does not sync, so it cannot be compared across devices while iCloud carries
@@ -88,21 +98,36 @@ const finite = (n) => typeof n === "number" && Number.isFinite(n);
 
 // The rule for one DIFFERS or MISSING record file, pure so it can be property-tested:
 //   "FAIL"   it is the difference it looks like
-//   "LAG"    the source had not seen these bytes when it last sent this path (or anything, when it
-//            never sent this path), and the source was heard from within `staleAfterMs`
+//   "LAG"    the source had not seen these bytes when it last sent this path, or it never sent this
+//            path and its newest Change is within `staleAfterMs` of the write; and the source was
+//            heard from within `staleAfterMs`
 //   "STALE"  it would be LAG, but the source has been silent for longer than `staleAfterMs`
 //   "BOUND"  it would be LAG by its path's mark, but the source has sent other Changes for longer
 //            than `staleAfterMs` since the file was written, so it is a difference after all
-export function lateVerdict({ mtimeMs, settled, pathSettled, now, staleAfterMs = STALE_AFTER_MS }) {
+//
+// `neverSent` is true only when the caller holds the source's per-path marks and none is for this
+// path, and the file is MISSING from the shadow. Without it, an unmarked path keeps the global line.
+export function lateVerdict({ mtimeMs, settled, pathSettled, neverSent = false, now, staleAfterMs = STALE_AFTER_MS }) {
   if (!finite(settled)) return "FAIL";
-  const line = finite(pathSettled) ? pathSettled : settled;
-  if (!(mtimeMs > line)) return "FAIL";
+  if (finite(pathSettled)) {
+    if (!(mtimeMs > pathSettled)) return "FAIL";
+  } else if (neverSent) {
+    // The source's newest Change has been more than the window past the write without this path.
+    if (settled - mtimeMs > staleAfterMs) return "FAIL";
+  } else if (!(mtimeMs > settled)) {
+    return "FAIL";
+  }
   if (now - settled > staleAfterMs) return "STALE";
   if (settled - mtimeMs > staleAfterMs) return "BOUND";
   return "LAG";
 }
 
-export function parity({ source, shadow, index, holds, never = [], exclude = excluder(), settled, pathSettled, staleAfterMs = STALE_AFTER_MS, now = Date.now() }) {
+// `carry` is the manifest's `sync.carry` (sync-rules `carryList`). A file whose bytes do not travel
+// (a reference, HQ-2017) is compared on neither side and never read: counted as REFERENCED.
+export function parity({ source, shadow, index, holds, never = [], exclude = excluder(), settled, pathSettled, staleAfterMs = STALE_AFTER_MS, now = Date.now(), carry = [] }) {
+  const classOf = fileClass(carry);
+  let referenced = 0;
+  const references = new Set();
   const marked = finite(settled);
   const lag = [];
   const hours = Math.round(staleAfterMs / 3600000);
@@ -111,9 +136,12 @@ export function parity({ source, shadow, index, holds, never = [], exclude = exc
   // A DIFFERS or MISSING on a record file written after the source last sent it: LAG, or STALE.
   const late = (want, code, why) => {
     const mark = marked ? marks.get(nfc(want.rel)) : undefined;
-    const v = lateVerdict({ mtimeMs: want.mtimeMs, settled, pathSettled: mark, now, staleAfterMs });
+    // HQ-2169: a MISSING path the source has never sent, when its marks were given, is judged against
+    // its own write time rather than another path's Change.
+    const neverSent = marked && pathSettled != null && code === "MISSING" && !finite(mark);
+    const v = lateVerdict({ mtimeMs: want.mtimeMs, settled, pathSettled: mark, neverSent, now, staleAfterMs });
     if (v === "LAG") { lag.push({ rel: want.rel, circle: want.circle, was: code }); return; }
-    if (v === "STALE") { problems.push({ code: "STALE", rel: want.rel, circle: want.circle, why: `${why}, written after the source's newest Change of ${new Date(settled).toISOString()}, which is older than ${hours} h` }); return; }
+    if (v === "STALE") { problems.push({ code: "STALE", rel: want.rel, circle: want.circle, why: `${why}, written ${new Date(want.mtimeMs).toISOString()}, and the source's newest Change, ${new Date(settled).toISOString()}, is older than ${hours} h` }); return; }
     if (v === "BOUND") { problems.push({ code, rel: want.rel, circle: want.circle, why: `${why}; written ${new Date(want.mtimeMs).toISOString()}, after the source last sent this path (${new Date(mark).toISOString()}), but the source has sent Changes for more than ${hours} h since without it` }); return; }
     problems.push({ code, rel: want.rel, circle: want.circle, why });
   };
@@ -129,6 +157,9 @@ export function parity({ source, shadow, index, holds, never = [], exclude = exc
   for (const e of walk(source, { exclude })) {
     if (e.kind === "excluded") { excluded += 1; continue; }
     if (notCarried(e.rel)) { notCarriedCount += 1; continue; }
+    // A placeholder is judged by the file it stands for: `.x.m4a.icloud` is media, `.x.md.icloud` is not.
+    const named = e.kind === "placeholder" ? e.rel.replace(/(^|\/)\.([^/]+)\.icloud$/, "$1$2") : e.rel;
+    if (e.kind !== "symlink" && classOf(named) === "reference") { referenced += 1; references.add(nfc(e.rel)); continue; }
     const c = circleOf(index, e.rel);
     if (!c || !held.has(c.name)) { notHeld += 1; continue; }
     if (e.kind !== "file") {
@@ -144,6 +175,9 @@ export function parity({ source, shadow, index, holds, never = [], exclude = exc
   for (const e of walk(shadow, { exclude: excluder() })) {
     if (e.kind === "excluded") continue;
     if (notCarried(e.rel)) { notCarriedCount += 1; continue; }
+    // A reference the record holds may have bytes in a shadow from before HQ-2017; they are not
+    // compared. A reference-class file the record does not hold is still EXTRA.
+    if (references.has(nfc(e.rel))) continue;
     shadowFiles += 1;
     const c = circleOf(index, e.rel);
     if (c && forbidden.has(c.name)) { problems.push({ code: "FORBIDDEN", rel: e.rel, circle: c.name, why: `this device must never hold circle ${c.name}` }); continue; }
@@ -163,18 +197,18 @@ export function parity({ source, shadow, index, holds, never = [], exclude = exc
 
   const checked = Object.values(perCircle).reduce((a, b) => a + b, 0);
   if (checked === 0) problems.push({ code: "CHECKED_0", rel: "", why: "nothing was compared; zero is a broken discovery step, not a pass" });
-  return { ok: problems.length === 0, checked, perCircle, expected: expected.size, shadowFiles, notHeld, excluded, notCarried: notCarriedCount, settled: marked ? settled : null, lag, problems };
+  return { ok: problems.length === 0, checked, perCircle, expected: expected.size, shadowFiles, notHeld, excluded, notCarried: notCarriedCount, referenced, settled: marked ? settled : null, lag, problems };
 }
 
 // The lines a person or a log reads. The first line always says what was examined.
 export function formatParity(r, { limit = 20 } = {}) {
   const lines = [`CHECKED ${r.checked} files: ${Object.entries(r.perCircle).map(([n, k]) => `${n} ${k}`).join(", ")}`];
-  lines.push(`  record side: ${r.expected} expected, ${r.notHeld} in circles this device does not hold, ${r.excluded} excluded${r.notCarried ? `, NOT_CARRIED ${r.notCarried} (paths iCloud does not sync, both sides)` : ""}; shadow side: ${r.shadowFiles} files${r.settled ? `; source's newest Change ${new Date(r.settled).toISOString()}` : ""}`);
+  lines.push(`  record side: ${r.expected} expected, ${r.notHeld} in circles this device does not hold, ${r.excluded} excluded${r.referenced ? `, REFERENCED ${r.referenced} (named, not carried)` : ""}${r.notCarried ? `, NOT_CARRIED ${r.notCarried} (paths iCloud does not sync, both sides)` : ""}; shadow side: ${r.shadowFiles} files${r.settled ? `; source's newest Change ${new Date(r.settled).toISOString()}` : ""}`);
   const byCode = {};
   for (const p of r.problems) byCode[p.code] = (byCode[p.code] ?? 0) + 1;
   const lag = r.lag ?? [];
   if (lag.length) {
-    lines.push(`  LAG ${lag.length} (written on this device after the source last sent that path, or after its newest Change, ${new Date(r.settled).toISOString()}, for a path it never sent; the source has not seen them yet)`);
+    lines.push(`  LAG ${lag.length} (written on this device after the source last sent that path, or, for a path it never sent, within ${Math.round(STALE_AFTER_MS / 3600000)} h of its newest Change, ${new Date(r.settled).toISOString()}; the source has not seen them yet)`);
     for (const l of lag.slice(0, limit)) lines.push(`  LAG ${l.rel} [${l.circle}] (${l.was})`);
   }
   for (const p of r.problems.slice(0, limit)) lines.push(`FAIL ${p.code} ${p.rel}${p.circle ? ` [${p.circle}]` : ""}: ${p.why}`);

package/lib/person-folders.mjs

@@ -0,0 +1,89 @@
+// Person folders (HQ-2024): one file per person, named for the person, nothing beside it.
+//
+// A folder whose manifest says `type: person` holds one file per person, named `First Last.md`.
+// Timeline and patterns are sections of that file, never side files, and processing docs live in a
+// sibling `Processing/` folder that the profile links. A record that grows a folder for some people
+// and a file for others, two docs for one person, or a stub that says "redirects to" ends up with
+// updates landing in whichever copy a search hits first, while the other goes stale.
+//
+// The layout rules, read across every person folder in the record at once:
+//   1. no subfolder inside a person folder
+//   2. a parenthetical in a name only when another person file shares the base name
+//      (a short first name counts: Phil Rauch and Philip Rauch)
+//   3. no redirect stubs: a file whose text says it redirects is a second doc for one person
+// Doctor (section 12c) reports each as a failure. The README a preset writes says the same rule.
+//
+// FALSIFIED 2026-10-12: test/person-folders.test.mjs run against origin/main (6fc2610), which had
+// none of these rules -> 7 of 7 failed; the subfolder, lone-parenthetical and redirect-stub records
+// each got "OK  12 check(s)", exit 0 ("actual: 0, expected: 1").
+
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+
+export const PROCESSING_DIR = "Processing";
+export const README_NAME = "README.md";
+
+// The README a preset writes into a person folder it makes. Plain words; it is the rule doctor checks.
+export const PERSON_FOLDER_README = [
+  "# People",
+  "",
+  "One file per person, named `First Last.md`. No folder per person.",
+  "",
+  "- Timeline, patterns and anything else about someone are sections of their file, never side files.",
+  `- A parenthetical goes in a name only when two people share it: \`Sam Lee (school).md\` beside \`Sam Lee (work).md\`.`,
+  `- Processing docs (working through something about a person) go in \`${PROCESSING_DIR}/\` beside this folder, and the person's file links them.`,
+  "- No redirect stubs. When two files turn out to be one person, merge them into one and repoint the links.",
+  "- Each file opens with `kind: person-profile` frontmatter, so `evda doctor` reads it.",
+  "",
+  "`evda doctor` fails a record that breaks any of these.",
+  "",
+].join("\n");
+
+// "Sam Lee (work)" -> "Sam Lee".
+export const baseName = (stem) => stem.replace(/\s*\(.*\)\s*$/, "");
+
+// One name to a reader: the same surname, and one first name starting the other.
+export function sameName(a, b) {
+  const x = a.split(/\s+/).filter(Boolean);
+  const y = b.split(/\s+/).filter(Boolean);
+  if (!x.length || !y.length || x.slice(1).join(" ") !== y.slice(1).join(" ")) return false;
+  const [p, q] = [x[0].toLowerCase(), y[0].toLowerCase()];
+  return p.startsWith(q) || q.startsWith(p);
+}
+
+const REDIRECT = /^>?\s*\**redirect/im;
+const ENTRY = /\.(md|json|ya?ml)$/i;
+
+// The layout problems across `dirs` (absolute paths of every `type: person` folder), with `skip` a
+// set of absolute paths that are not person files (folder manifests, declared views). Returns
+// { problems: [{ path, kind, message }], files } where files counts the person files read.
+export function personFolderProblems(dirs, { skip = new Set() } = {}) {
+  const problems = [];
+  const people = [];
+  for (const d of dirs) {
+    let names;
+    try { names = readdirSync(d).sort(); } catch { continue; }
+    for (const name of names) {
+      if (name.startsWith(".") || name === "node_modules") continue;
+      const p = join(d, name);
+      let st;
+      try { st = statSync(p); } catch { continue; }
+      if (st.isDirectory()) {
+        problems.push({ path: p, kind: "folder", message: `is a folder inside a person folder. One file per person, named First Last; timeline and patterns are sections of that file, and processing docs go in ${PROCESSING_DIR}/ beside the person folder, linked from the profile.` });
+        continue;
+      }
+      if (skip.has(p) || name === README_NAME || !ENTRY.test(name)) continue;
+      people.push({ path: p, stem: name.replace(ENTRY, "") });
+    }
+  }
+  for (const { path, stem } of people) {
+    const base = baseName(stem);
+    if (base !== stem && !people.some((o) => o.path !== path && sameName(baseName(o.stem), base))) {
+      problems.push({ path, kind: "parenthetical", message: `carries a parenthetical and no other person file is named ${base}. A parenthetical only tells apart people who share a name; name it ${base}.` });
+    }
+    if (REDIRECT.test(readFileSync(path, "utf8"))) {
+      problems.push({ path, kind: "redirect", message: `is a redirect stub, a second doc for one person. Merge anything in it into the profile it points to, delete it, and repoint its links.` });
+    }
+  }
+  return { problems, files: people.length };
+}

package/lib/plugin-hook.mjs

@@ -0,0 +1,109 @@
+#!/usr/bin/env node
+// The hook entry point inside a Cowork plugin that `evda plugin` builds for one record (HQ-2802).
+//
+// Cowork reads no folder's .claude/settings.json, so the hooks `evda hook install` puts there never
+// run in it; a plugin's hooks/hooks.json does run there. This file is what that hooks.json names:
+//
+//   node evda-hook.mjs keep   <record>   Stop: the record's own keep-record hook
+//   node evda-hook.mjs prompt <record>   UserPromptSubmit: the record's own prompt-filing hook
+//   node evda-hook.mjs guard  <record>   PreToolUse: the read guard the record's settings name
+//
+// It holds no hook logic. It runs the copies `evda hook install` keeps current in the record
+// (.claude/hooks/evda-keep-record.mjs, .claude/hooks/evda-file-prompt.mjs) and the guard command
+// the record's settings register, so the plugin files exactly what a Claude Code session in the
+// record would, and a `evda hook install` or `evda update` reaches the plugin without a rebuild.
+//
+// ONLY IN COWORK. A plugin installed on a claude.ai account also loads in the owner's Claude Code
+// terminal sessions, in every project. There the record's project hooks already run in sessions
+// opened in it, and a session in another project is not the record's: filing it would put work
+// conversations in the day. So it acts only when CLAUDE_CODE_ENTRYPOINT is "local-agent", the
+// value the Claude desktop app gives the Claude Code process behind a Cowork task.
+// EVDA_PLUGIN_HOOKS=always acts everywhere (for tests and an owner who wants it); =never, nowhere.
+//
+// THE RECORD. The path baked in at build time, when it is there. A Cowork task can run in a VM
+// that sees the owner's folders mounted under another path, so when the baked path is missing the
+// record is the one at or above the task's cwd whose folder has the same name.
+//
+// Copied byte for byte into the plugin as scripts/evda-hook.mjs; node: built-ins only, because the
+// plugin is a zip with no packages. Any error of its own exits 0 with no output: a broken hook must
+// never block the owner's message or trap a session.
+
+import { existsSync, readFileSync, realpathSync } from "node:fs";
+import { basename, dirname, join, relative, resolve, isAbsolute } from "node:path";
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+
+export const HOOK_FILES = { keep: ".claude/hooks/evda-keep-record.mjs", prompt: ".claude/hooks/evda-file-prompt.mjs" };
+const GUARD_MARK = /evda-read-guard\.mjs|\bevda guard\b/;
+
+export function active(env = process.env) {
+  if (env.EVDA_PLUGIN_HOOKS === "never") return false;
+  return env.EVDA_PLUGIN_HOOKS === "always" || env.CLAUDE_CODE_ENTRYPOINT === "local-agent";
+}
+
+function recordAt(from) {
+  let d = resolve(from);
+  for (;;) {
+    if (existsSync(join(d, "evda.json"))) return d;
+    const up = dirname(d);
+    if (up === d) return null;
+    d = up;
+  }
+}
+
+// The record this plugin was built for, as this process sees it, or null.
+export function resolveRecord(baked, cwd) {
+  if (baked && existsSync(join(baked, "evda.json"))) return resolve(baked);
+  if (!cwd) return null;
+  const found = recordAt(cwd);
+  return found && baked && basename(found) === basename(baked) ? found : null;
+}
+
+const inside = (root, p) => { const r = relative(root, resolve(p)); return r === "" || (!r.startsWith("..") && !isAbsolute(r)); };
+
+// One hook event in; { stdout, stderr, code } out. Never throws.
+export function handle(mode, baked, input, env = process.env) {
+  const none = { stdout: "", stderr: "", code: 0 };
+  try {
+    if (!active(env)) return none;
+    let payload;
+    try { payload = JSON.parse(input); } catch { return none; }
+    const root = resolveRecord(baked, payload?.cwd);
+    if (!root) return none;
+    if (mode === "keep" || mode === "prompt") {
+      const hook = join(root, HOOK_FILES[mode]);
+      if (!existsSync(hook)) return none;
+      // The record's hooks find the record from cwd; a Cowork task's cwd may be anywhere.
+      const p = { ...payload, cwd: payload.cwd && inside(root, payload.cwd) ? payload.cwd : root };
+      const r = spawnSync(process.execPath, [hook], { input: JSON.stringify(p), encoding: "utf8", timeout: 25000 });
+      return { stdout: r.stdout ?? "", stderr: "", code: 0 };
+    }
+    if (mode === "guard") {
+      const settings = JSON.parse(readFileSync(join(root, ".claude", "settings.json"), "utf8"));
+      const cmd = (settings?.hooks?.PreToolUse ?? []).flatMap((m) => (m?.hooks ?? []).map((h) => h?.command)).find((c) => typeof c === "string" && GUARD_MARK.test(c));
+      if (!cmd) return none;
+      const r = spawnSync(cmd, { shell: true, input, encoding: "utf8", timeout: 25000 });
+      return { stdout: r.stdout ?? "", stderr: r.stderr ?? "", code: r.status === 2 ? 2 : 0 };
+    }
+    return none;
+  } catch {
+    return none;
+  }
+}
+
+const entry = (() => {
+  try { return process.argv[1] && realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url)); } catch { return false; }
+})();
+
+if (entry) {
+  const [mode, baked] = process.argv.slice(2);
+  let input = "";
+  process.stdin.setEncoding("utf8");
+  process.stdin.on("data", (d) => (input += d));
+  process.stdin.on("end", () => {
+    const r = handle(mode, baked, input);
+    if (r.stdout) process.stdout.write(r.stdout);
+    if (r.stderr) process.stderr.write(r.stderr);
+    process.exit(r.code);
+  });
+}