create-evda 0.1.6 → 0.1.8

package/lib/organize.mjs

@@ -13,7 +13,9 @@
 // nothing is written into circles/ or grants/.
 //
 // The judgment part runs through the owner's own AI (`--with-ai`): `claude -p` with the evda skill
-// and read-only EVDA tools, given the report. Its answer is appended to the same report. EVDA holds
+// and read-only EVDA tools, given the last two weeks of entries. It hands back one thread across
+// days, quoted and dated, which leads the report; an answer whose quotes are not in the entries is
+// dropped, and with nothing across two days the report says nothing (HQ-1246). EVDA holds
 // no key and calls no model; `claude` is the owner's install, signed in as the owner.
 
 import { appendFileSync, existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
@@ -203,11 +205,113 @@ export function askOwnersAi(evda, prompt, { model = null, env = process.env, tim
   if (skill) argv.push("--append-system-prompt", skill);
   if (model) argv.push("--model", model);
   const r = spawnSync(bin, argv, { cwd: evda ? evda.dir : tmpdir(), env, encoding: "utf8", timeout: timeoutMs, maxBuffer: 16 * 1024 * 1024 });
-  if (r.error) return { ok: false, why: r.error.code === "ENOENT" ? `${bin} is not installed or not on PATH` : String(r.error.message) };
-  if (r.status !== 0) return { ok: false, why: `${bin} -p exited ${r.status}: ${(r.stderr || r.stdout || "").trim().split("\n").slice(-3).join(" ")}` };
-  const text = (r.stdout ?? "").trim();
-  if (!text) return { ok: false, why: `${bin} -p answered with nothing` };
-  return { ok: true, text };
+  const text = r.error || r.status !== 0 ? "" : (r.stdout ?? "").trim();
+  if (text) return { ok: true, text };
+  return { ok: false, why: aiFailure(r, { bin, env }) };
+}
+
+// Why the owner's AI did not answer, in words the owner can act on (HQ-1246). The report is read by
+// a person, not a developer, so it never says "claude -p exited 1". Claude's own last line follows
+// the plain sentence when it is the only clue. EVDA_ROUTINES_FALSIFY=raw-why gives the old text.
+export function aiFailure(r, { bin = "claude", env = process.env } = {}) {
+  const said = `${r.stderr ?? ""}\n${r.stdout ?? ""}`.trim().split("\n").map((l) => l.trim()).filter(Boolean);
+  if ((env.EVDA_ROUTINES_FALSIFY ?? "").split(",").map((m) => m.trim()).includes("raw-why")) {
+    if (r.error) return r.error.code === "ENOENT" ? `${bin} is not installed or not on PATH` : String(r.error.message);
+    return r.status !== 0 ? `${bin} -p exited ${r.status}: ${said.slice(-3).join(" ")}` : `${bin} -p answered with nothing`;
+  }
+  if (r.error?.code === "ENOENT") return "Claude Code is not on this computer. Install it from https://claude.com/claude-code, open it once and sign in, and the next run includes your AI's read.";
+  if (r.error?.code === "ETIMEDOUT" || r.signal === "SIGTERM") return "Claude took too long and was stopped. The next run tries again.";
+  if (r.error) return `Claude could not be started on this computer. The next run tries again. What the computer said: ${r.error.message}`;
+  if (said.some((l) => /not logged in|please run \/login|invalid api key|oauth token (has )?expired|authentication[_ ]error|\b401\b/i.test(l))) return "Claude is not signed in on this computer: open Claude and sign in, and the next run includes your AI's read.";
+  if (r.status === 0) return "Claude answered with nothing. The next run tries again.";
+  return `Claude stopped with an error before answering. The next run tries again.${said.length ? ` What it said: ${said.at(-1)}` : ""}`;
+}
+
+// How far back the AI part reads for a thread.
+export const PATTERN_DAYS = 14;
+export const NO_PATTERN = "NOTHING";
+
+// The owner's own words, one per dated daily entry in the last `days` days, as the AI part reads
+// them: a sealed or just-noted day is left out, a sealed section is cut, and evda's markers and any
+// secret-shaped line are dropped. Oldest first.
+export function entriesFor(evda, { now = new Date(), days = PATTERN_DAYS } = {}) {
+  const daily = resolveRole(evda, "record/daily");
+  if (!daily.mapped || !daily.exists) return [];
+  const start = new Date(now);
+  start.setDate(start.getDate() - (days - 1));
+  const from = localDate(start);
+  const to = localDate(now);
+  const out = [];
+  for (const abs of mdFiles(daily.abs)) {
+    const raw = readFileSync(abs, "utf8");
+    const date = fileDate(abs, raw);
+    if (!date || date < from || date > to) continue;
+    if (heldBy(frontmatterOf(raw), "organize")) continue;
+    const text = stripFrontmatter(withoutSealed(raw).text)
+      .split("\n")
+      .filter((l) => !/^<!-- evda:/.test(l.trim()) && !/^#{1,6} /.test(l) && !secretShape(l))
+      .join("\n").replace(/\n{3,}/g, "\n\n").trim();
+    if (text) out.push({ date, text });
+  }
+  return out.sort((a, b) => a.date.localeCompare(b.date));
+}
+
+// The prompt for the AI part. It carries the mechanism the answer rests on, the exact shape the
+// answer must take, and the entries themselves.
+export function patternPrompt(entries) {
+  return [
+    "Below are the owner's own entries from the last two weeks, each under its date.",
+    "",
+    "Find one thing that comes back across different days: a person, a question, a worry, a want, a phrase they keep using.",
+    "Why it is worth their reading: a conclusion handed to someone from outside tends not to take, and one they recognize in their own words does. So hand back their words, not your reading of them.",
+    "",
+    "Answer in exactly this shape:",
+    "one or two plain sentences naming what comes back, in their vocabulary",
+    "- YYYY-MM-DD: \"words copied exactly from that day's entry\"",
+    "- YYYY-MM-DD: \"words copied exactly from another day's entry\"",
+    "",
+    "Quote at least two different days. Copy each quote character for character from the entry under that date; a quote that is not there is dropped, and so is the whole answer.",
+    "Say only what the entries say. No advice, no question back to them, no score, no count, no praise, and no words like journey, transformation or growth.",
+    "Do not mention filing, organizing, this report or yourself.",
+    `If nothing honestly comes back across two or more days, answer with the single word ${NO_PATTERN}.`,
+    "",
+    ...entries.flatMap((e) => [`=== ${e.date} ===`, e.text, ""]),
+  ].join("\n");
+}
+
+const squash = (t) => t.replace(/[\u2018\u2019]/g, "'").replace(/[\u201c\u201d]/g, '"').replace(/\s+/g, " ").trim().toLowerCase();
+
+// The answer, kept only when it has the shape: prose first, then two or more quotes from two or more
+// dates, each found in the entry of its date. Returns { prose, quotes } or null (say nothing).
+// EVDA_ROUTINES_FALSIFY=no-quote-check keeps whatever came back.
+export function patternFrom(text, entries, { env = process.env } = {}) {
+  const t = String(text ?? "").trim();
+  if ((env.EVDA_ROUTINES_FALSIFY ?? "").split(",").map((m) => m.trim()).includes("no-quote-check")) return t ? { prose: t, quotes: [] } : null;
+  if (!t || t.replace(/[.\s]/g, "").toUpperCase() === NO_PATTERN) return null;
+  const lines = t.split("\n").map((l) => l.trim()).filter(Boolean);
+  const quoteRe = /^[-*] (\d{4}-\d{2}-\d{2}): ["\u201c](.+)["\u201d]$/;
+  const first = lines.findIndex((l) => quoteRe.test(l));
+  if (first < 1) return null;
+  const prose = lines.slice(0, first);
+  const rest = lines.slice(first);
+  if (prose.length > 3 || rest.some((l) => !quoteRe.test(l))) return null;
+  const byDate = new Map(entries.map((e) => [e.date, squash(e.text)]));
+  const quotes = [];
+  for (const l of rest) {
+    const [, date, words] = quoteRe.exec(l);
+    const q = squash(words);
+    if (q.length < 3 || !byDate.has(date) || !byDate.get(date).includes(q)) return null;
+    quotes.push({ date, words });
+  }
+  if (new Set(quotes.map((q) => q.date)).size < 2) return null;
+  return { prose: prose.join(" "), quotes };
+}
+
+// The pattern leads the run's section, before the filing list.
+export function withPattern(report, { prose, quotes }) {
+  const block = ["### Across your entries", "", prose, "", ...quotes.map((q) => `- ${q.date}: "${q.words}"`), ""].join("\n");
+  const at = report.indexOf("\n", report.indexOf("## Run")) + 1;
+  return `${report.slice(0, at)}\n${block}${report.slice(at)}`;
 }
 
 export async function organize(evda, { now = new Date(), window = 7, withAi = false, dryRun = false, model = null, env = process.env } = {}) {
@@ -234,19 +338,19 @@ export async function organize(evda, { now = new Date(), window = 7, withAi = fa
   }
   let exit = 0;
   if (withAi) {
-    const ai = askOwnersAi(evda, [
-      "Use the evda skill's Organizing section. Here is today's organize report for this record.",
-      "For each note that needs a place, answer in one line: the note's path, where it belongs, and the words from the note that say so, quoted.",
-      "Check against the record with the evda tools first. Write nothing. If nothing needs a place, say so in one line.",
-      "",
-      report,
-    ].join("\n"), { model, env });
-    if (ai.ok) {
-      const secret = secretLine(ai.text);
-      report += secret ? `\n### Your AI's read\n\nNot kept: the answer held ${secret}.\n` : `\n### Your AI's read (claude -p)\n\n${ai.text}\n`;
-    } else {
-      report += `\n### Your AI's read\n\nSKIPPED: ${ai.why}. Nothing else in this run depended on it.\n`;
-      exit = 1;
+    // The AI part hands back a thread across the owner's own entries, not a log of the filing above
+    // (HQ-1246). Its answer is kept only if every quote is in the entry of the date it names and the
+    // quotes span two days or more; otherwise the report says nothing about it.
+    const entries = entriesFor(evda, { now, days: PATTERN_DAYS });
+    if (entries.length) {
+      const ai = askOwnersAi(evda, patternPrompt(entries), { model, env });
+      if (ai.ok) {
+        const pattern = secretLine(ai.text) ? null : patternFrom(ai.text, entries, { env });
+        if (pattern) report = withPattern(report, pattern);
+      } else {
+        report += `\n### Your AI's read\n\nDid not run. ${ai.why}\n\nThe filing above ran without it.\n`;
+        exit = 1;
+      }
     }
   }
   const path = appendReport(evda, "organize", date, report);
@@ -258,7 +362,7 @@ export async function lookBack(evda, { now = new Date(), model = null, env = pro
   const date = localDate(now);
   const block = ai.ok
     ? (secretLine(ai.text) ? `## Run ${localTime(now)}\n\nNot kept: the answer held a secret-shaped line.\n` : `## Run ${localTime(now)}\n\n${ai.text}\n`)
-    : `## Run ${localTime(now)}\n\nSKIPPED: ${ai.why}.\n`;
+    : `## Run ${localTime(now)}\n\nDid not run. ${ai.why}\n`;
   const path = appendReport(evda, "look-back", date, block);
   return { path, exit: ai.ok ? 0 : 1, summary: `${block}\nAppended to ${path}.` };
 }

package/lib/pairing.mjs

@@ -0,0 +1,165 @@
+// Device pairing for the evda CLI and the MCP (HQ-1217): pair a phone, list and remove devices, sync.
+//
+// The pairing code itself is atlas-local's (atlas/block/atlas-local/src/node/pairing.ts), shipped
+// in this package as one bundled file, dist/pairing.mjs (scripts/build-pairing.mjs). It is loaded
+// only when a pairing command runs, because it needs node:sqlite, which the rest of this package
+// does not: an owner on an older Node still has every other command.
+//
+// Everything a person reads from here is plain words. The one credential shown is the pairing code,
+// because typing or scanning it on the phone is the point; no id, key or hash is printed.
+
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { EvdaError } from "./errors.mjs";
+import { openEvda } from "./manifest.mjs";
+
+const PKG = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+export const PAIRING_BUNDLE = join(PKG, "dist", "pairing.mjs");
+
+// node:sqlite is unflagged from Node 22.13 (and 23.4); before that it needs --experimental-sqlite.
+export const PAIRING_NODE = "22.13";
+
+/** Why pairing cannot run on this Node, in plain words, or null when it can. */
+export function pairingUnsupported(version = process.versions.node) {
+  const [major, minor] = String(version).split(".").map(Number);
+  const ok = major > 23 || (major === 23 && minor >= 4) || (major === 22 && minor >= 13);
+  return ok ? null : `Pairing a device needs Node ${PAIRING_NODE} or newer, and this is Node ${version}. Everything else in evda works on this Node; install a newer one to pair.`;
+}
+
+let loaded = null;
+
+/** The bundled pairing module, pointed at this package's own lib/. Throws in plain words when it cannot load. */
+export async function loadPairing({ bundle = PAIRING_BUNDLE, version = process.versions.node } = {}) {
+  const unsupported = pairingUnsupported(version);
+  if (unsupported) throw new EvdaError(unsupported, { code: "NODE_TOO_OLD", exit: 2 });
+  if (loaded?.bundle === bundle) return loaded.mod;
+  if (!existsSync(bundle)) {
+    throw new EvdaError("This copy of evda was installed without device pairing. Run it from the published package (npx -p create-evda evda pair), or build it here with `node scripts/build-pairing.mjs`.", { code: "NOT_BUILT", exit: 2 });
+  }
+  // Node 22 and 23 announce node:sqlite as experimental on stderr. That line is for developers, not
+  // for someone pairing a phone, so it is dropped while the bundle loads and nothing else is.
+  const emit = process.emitWarning;
+  process.emitWarning = function (warning, ...rest) {
+    if (/SQLite/i.test(String(warning?.message ?? warning))) return;
+    return emit.call(process, warning, ...rest);
+  };
+  try {
+    const mod = await import(pathToFileURL(bundle).href);
+    mod.usePersonRecord(PKG);
+    loaded = { bundle, mod };
+    return mod;
+  } catch (error) {
+    // A Node that has the version but not the module (started with --no-experimental-sqlite, or a
+    // build without it) fails here, and is told the same thing in the same words.
+    if (error?.code === "ERR_UNKNOWN_BUILTIN_MODULE") {
+      throw new EvdaError(`Pairing a device needs Node ${PAIRING_NODE} or newer with its built-in SQLite, and this Node cannot load it. Everything else in evda works on this Node.`, { code: "NODE_TOO_OLD", exit: 2 });
+    }
+    throw error;
+  } finally {
+    process.emitWarning = emit;
+  }
+}
+
+// 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)/;
+function asEvdaError(error) {
+  if (error instanceof EvdaError) return error;
+  const message = error instanceof Error ? error.message : String(error);
+  return new EvdaError(message, { code: "PAIRING", exit: REFUSALS.test(message) ? 2 : 1 });
+}
+
+/** Where the computer keeps its device state: `<home>/.evda/<record>/`, never inside the record. */
+export function ownerOptions(dir, { env = process.env, relay } = {}) {
+  return { record: dir, home: resolve(env.HOME || homedir()), relayUrl: relay || env.EVDA_RELAY || undefined };
+}
+
+const partsList = (value) => (Array.isArray(value) ? value : String(value ?? "").split(",")).map((s) => String(s).trim()).filter(Boolean);
+
+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") });
+  } catch (error) {
+    throw asEvdaError(error);
+  }
+}
+
+export const NO_DEVICES = "No devices are paired with this EVÐA.";
+
+// The computer's list of devices lives beside its device state (pairing.ts, paired-devices.json).
+// A record with no id, or no list there, has paired nothing: that is answered without loading the
+// bundle, so listing devices on a fresh record, or on a Node or a copy that cannot pair, is an
+// answer and not an error.
+function pairedList(dir, env) {
+  let id;
+  try { id = openEvda(dir).manifest.id; } catch { return null; }
+  if (typeof id !== "string" || !id || /[/\\]/.test(id)) return null;
+  return join(resolve(env.HOME || homedir()), ".evda", id, "paired-devices.json");
+}
+
+export async function devices(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.deviceLines(ownerOptions(dir, { env, relay }));
+  } catch (error) {
+    throw asEvdaError(error);
+  }
+}
+
+/** The devices as data, for an app (HQ-1925): `[{name, state, parts, since}]`, empty when nothing is paired. No id. */
+export async function deviceData(dir, { relay, env = process.env, bundle } = {}) {
+  const list = pairedList(dir, env);
+  if (!list || !existsSync(list)) return [];
+  const p = await loadPairing(bundle ? { bundle } : {});
+  try {
+    return await p.deviceList(ownerOptions(dir, { env, relay }));
+  } catch (error) {
+    throw asEvdaError(error);
+  }
+}
+
+/** One sync as data, for an app (HQ-1925): `{paired: [names], received, sent, refused}`. No id. */
+export async function syncData(dir, { relay, env } = {}) {
+  const p = await loadPairing();
+  try {
+    return await p.syncOnce(ownerOptions(dir, { env, relay }));
+  } catch (error) {
+    throw asEvdaError(error);
+  }
+}
+
+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());
+  } catch (error) {
+    throw asEvdaError(error);
+  }
+}
+
+export async function sync(dir, { relay, env } = {}) {
+  const p = await loadPairing();
+  try {
+    return await p.syncWords(ownerOptions(dir, { env, relay }));
+  } catch (error) {
+    throw asEvdaError(error);
+  }
+}
+
+/** The MCP tool's answer: the code, the QR link, and what to do on the phone, step by step. */
+export function pairText(r) {
+  return [
+    `Pairing code for ${r.name}: ${r.code}`,
+    `QR link (make it a QR code, or open it on the phone): ${r.qr}`,
+    "",
+    "On the phone:",
+    ...r.phoneSteps.map((s, i) => `${i + 1}. ${s}`),
+    "",
+    `${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

@@ -24,10 +24,43 @@
 //                                          laptop's .tmp/ (65 files, never on Hestia) reaches the
 //                                          shadow by the relay and could never match. NOT_CARRIED n.
 //
+// And one thing is not yet a difference, while the source is being heard from:
+//
+//   LAG          the record's copy on this device changed after the newest Change this device has
+//                received from the source (`settled`). During S1 the shadow is fed only by the
+//                source (the laptop) and the record here arrives by iCloud, so bytes the shadow
+//                device's own passes write reach the shadow only after iCloud carries them to the
+//                source and its next scan mints them. The source cannot have sent what it had not
+//                seen. Applies to DIFFERS and MISSING, never to EXTRA or FORBIDDEN, and each LAG
+//                file is named. Measured 2026-09-25: the Hestia daily record and the journal,
+//                written on Hestia at 02:10 ET, differed at 03:35 because the laptop's last Change
+//                had arrived at 05:35Z and the laptop was off the network from 06:57Z.
+//   STALE        a LAG file when the source's newest Change is older than `staleAfterMs` (24 h)
+//                at the run. A source that has not been heard from is not lagging, it is absent,
+//                and a week of LAG must not pass the gate. A failure.
+//
+//   LAG, per path  `settled` is the newest Change from the source for ANY file. A short wake of the
+//                source (a 21 s DarkWake on battery, 2026-09-27) can scan before iCloud has
+//                delivered a file's final bytes to it, mint a Change for some other file, and so
+//                move `settled` past a file whose bytes the source never saw. So when the source
+//                has sent a Change for this path (`pathSettled`, keyed by NFC path), the line is
+//                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.
+//                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
+//                it is, DIFFERS or MISSING.
+//
+// Without `settled` (the `evda parity` command) nothing is LAG: parity is byte for byte.
+// A clock skew between the two machines moves the line by the skew; a stamp-preserving edit made
+// before `settled` stays DIFFERS, which is the strict direction.
+//
 // It reads both trees and writes nothing.
 
 import { createHash } from "node:crypto";
-import { readFileSync } from "node:fs";
+import { readFileSync, statSync } from "node:fs";
 import { join } from "node:path";
 import { circleForPath } from "./filechanges.mjs";
 import { excluder, walk } from "./sync-rules.mjs";
@@ -49,7 +82,41 @@ function circleOf(index, rel) {
 
 // `index` is circleIndex(evda). `holds` and `never` are circle names. `exclude` is the plan's
 // excluder, the same one the scan used.
-export function parity({ source, shadow, index, holds, never = [], exclude = excluder() }) {
+export const STALE_AFTER_MS = 24 * 60 * 60 * 1000;
+
+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`
+//   "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 }) {
+  if (!finite(settled)) return "FAIL";
+  const line = finite(pathSettled) ? pathSettled : settled;
+  if (!(mtimeMs > line)) 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() }) {
+  const marked = finite(settled);
+  const lag = [];
+  const hours = Math.round(staleAfterMs / 3600000);
+  // Keyed by NFC here, whatever form the caller's change_log holds the names in.
+  const marks = new Map([...(pathSettled ?? [])].map(([rel, t]) => [nfc(rel), t]));
+  // 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 });
+    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 === "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 });
+  };
   const held = new Set(holds);
   const forbidden = new Set(never);
   const problems = [];
@@ -68,7 +135,8 @@ export function parity({ source, shadow, index, holds, never = [], exclude = exc
       problems.push({ code: "UNVERIFIABLE", rel: e.rel, circle: c.name, why: `a ${e.kind} on the record side` });
       continue;
     }
-    expected.set(nfc(e.rel), { rel: e.rel, circle: c.name, sha: sha(join(source, e.rel)) });
+    const abs = join(source, e.rel);
+    expected.set(nfc(e.rel), { rel: e.rel, circle: c.name, sha: sha(abs), mtimeMs: statSync(abs).mtimeMs });
   }
 
   const seen = new Set();
@@ -84,26 +152,31 @@ export function parity({ source, shadow, index, holds, never = [], exclude = exc
     if (!want) { problems.push({ code: "EXTRA", rel: e.rel, circle: c.name, why: "in the shadow and not in the record" }); continue; }
     seen.add(nfc(e.rel));
     if (e.kind !== "file" || sha(join(shadow, e.rel)) !== want.sha) {
-      problems.push({ code: "DIFFERS", rel: e.rel, circle: c.name, why: "the shadow's bytes are not the record's" });
+      late({ ...want, rel: e.rel }, "DIFFERS", "the shadow's bytes are not the record's");
       continue;
     }
     perCircle[want.circle] += 1;
   }
   for (const [key, want] of expected) {
-    if (!seen.has(key)) problems.push({ code: "MISSING", rel: want.rel, circle: want.circle, why: "in the record and not in the shadow" });
+    if (!seen.has(key)) late(want, "MISSING", "in the record and not in the shadow");
   }
 
   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, problems };
+  return { ok: problems.length === 0, checked, perCircle, expected: expected.size, shadowFiles, notHeld, excluded, notCarried: notCarriedCount, 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`);
+  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()}` : ""}`);
   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)`);
+    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}`);
   if (r.problems.length > limit) lines.push(`... and ${r.problems.length - limit} more`);
   lines.push(r.ok ? "PARITY OK" : `PARITY FAILED: ${Object.entries(byCode).map(([c, n]) => `${c} ${n}`).join(", ")}`);

package/lib/roles.mjs

@@ -26,6 +26,10 @@ export const ROLES = {
   // directory per owner and one subfolder per circle, so several circles from one owner are held
   // side by side. Unmapped, a record holds one circle per owner at `mounts/<owner record id>`.
   mounts: { layer: "circles", kind: "dir" },
+  // Where the owner's agent leaves messages for them and their replies come back (HQ-1246,
+  // lib/messages.mjs). Not part of any layer, like agents: a record without the mapping still has
+  // one, at `messages/`, which is what the phone app reads too.
+  messages: { layer: null, kind: "dir" },
   // The four roles every record has at any scale (Spec 07 section 2, "Four roles, at every scale",
   // HQ-1371). Each maps to one or more paths: the role's own key and any `<role>/<facet>` key, so a
   // record with three journal folders writes `journal`, `journal/captures`, `journal/dreams`. Every