create-evda 0.1.8 → 0.1.10

package/lib/touches.mjs

@@ -0,0 +1,427 @@
+// What a filing bears on (HQ-2631): after a write tool files words, the existing entries those words
+// name and the shared circles they, and the path just written, reach.
+//
+// Two failures came from one gap. A site feature landed and no public entry ever described it,
+// because nothing at the moment of filing said a public view was derived from that folder. And a
+// conversation about a topic the record already had a page for was filed into the day only, and the
+// page was written to after the owner asked. Code gathers the context; the agent judges. So this
+// returns information and never decides or writes anything: no entry, no share mark, no circle rule.
+//
+//   related   up to RELATED_MAX entries whose name the words contain: a person's page by full name
+//             (or a first name no other page shares), a topic or project entry by its title, its
+//             aliases, the head of a dashed title ("Sexual Health - Lasting and Presence" answers to
+//             "sexual health"), or a folder's README by the folder's name. Longest name first, so the
+//             most specific entry leads. An entry the caller may not read (sealed, just noted, a part
+//             set to be read by a different AI) is never listed, by the read tools' own mayRead.
+//   circles   for the written path and each related entry: a public home circle, a circle that
+//             gathers it by its share mark, a circle its home may release it to (a home that covers
+//             the whole record is the private default and says nothing), and every view entry a
+//             circle gathers whose derived_from names the path or a folder holding it. Only the
+//             shared circle's title and the entry path; nothing about any private circle.
+//
+//   tickets   when the record's work role is a board (`harlequin:` or `harlequin:<project>`, HQ-2798),
+//             up to TICKETS_MAX open tickets of that board the words reference: an `HQ-<n>` token
+//             naming an open ticket, in the order the words say them, and then a ticket whose title
+//             shares a run of at least SPAN_WORDS consecutive words with the words, SPAN_CONTENT of
+//             them not common words ("the greenhouse heater controller" names "Build the greenhouse
+//             heater controller with a thermostat"), longest run first. A four-word run more than
+//             SEED_MAX_TICKETS titles share is too common to point at one; a title shorter than
+//             SPAN_WORDS is reached by its number only. A done or obsolete ticket is never named,
+//             even by number. A miss is cheaper than noise, so the rule leans to missing.
+//
+// Cost: it runs on every filing, so the record's names are indexed once per INDEX_TTL_MS per record
+// and the path just written is re-read each time. Reading names needs only each file's frontmatter.
+// The board is read the way `evda work` reads it (lib/work.mjs: SUPABASE_URL and
+// SUPABASE_SERVICE_ROLE_KEY from the environment, or the env file $EVDA_WORK_ENV_FILE names), never
+// on the request: a filing is answered from the cached tickets, and a missing or stale cache starts a
+// read after the answer, bounded by BOARD_TIMEOUT_MS. An unreachable board keeps what was cached.
+
+import { closeSync, existsSync, openSync, readFileSync, readSync } from "node:fs";
+import { join, sep } from "node:path";
+import { resolveRole, workSource, fourRoleOf } from "./roles.mjs";
+import { harlequinEfforts } from "./work.mjs";
+import { markdownFiles, frontmatterOf, homesOf, matchesWhere, heldBy, SEALED, NOTED } from "./circles.mjs";
+import { readContext, mayRead, callerFrom } from "./readers.mjs";
+import { DERIVED_FROM, VIEW } from "./render.mjs";
+import { relatedLine, ticketsLine } from "./day-file.mjs";
+
+export const RELATED_MAX = 5;
+export const INDEX_TTL_MS = 5 * 60 * 1000;
+export const TICKETS_MAX = 5;
+// The statuses that end a ticket on the board.
+export const CLOSED_STATUSES = new Set(["done", "obsolete"]);
+const BOARD_TIMEOUT_MS = 10 * 1000;
+const SPAN_WORDS = 4;
+const SPAN_CONTENT = 3;
+const SEED_MAX_TICKETS = 2;
+// Words too common to make a run of a title distinctive.
+const COMMON = new Set("a an the and or but nor of to in on at by for with from into onto over under about as is are was were be been being it its this that these those not no so than then there their they them he she his her we our you your i me my do does did done has have had can could will would should may might must just only also when what which who whom how why where all any each every some more most other one two new now up out off too very own same such if else via per get gets got make makes made use uses used see way thing things".split(" "));
+// A name shorter than this is too common to mean an entry; a single word needs NAME_MIN_WORD.
+const NAME_MIN = 4;
+const NAME_MIN_WORD = 6;
+// A name more entries than this share is not specific enough to point at any of them.
+const NAME_MAX_ENTRIES = 3;
+// Stems that name a kind of file, not a subject.
+const GENERIC = new Set(["readme", "index", "notes", "note", "queue", "overview", "summary", "plan", "plans", "ideas", "todo", "inbox", "untitled", "draft", "drafts", "log", "logs", "synthesis", "template", "templates", "reference", "references", "archive", "status", "changelog", "agents", "claude", "gemini", "people", "family", "projects", "areas", "resources", "research", "design", "home", "daily", "weekly", "monthly", "journal", "printing", "setup", "questions", "answers", "tasks", "spec", "specs", "docs"]);
+// First names that are also ordinary words, so a lowercase message would hit them by accident.
+const WORD_NAMES = new Set(["will", "grace", "june", "may", "rose", "hope", "mark", "faith", "joy", "rich", "bill", "art", "frank", "sky", "summer", "april", "dawn", "jack", "pat", "sue", "ray", "iris", "max", "drew", "chase", "hunter", "lily", "ivy", "jade", "ruby", "amber", "pearl", "sage", "skye", "reed", "wade", "dean", "gene", "guy", "nick", "rob", "don", "ben", "sam", "tom", "lee", "kim", "bo", "eve", "ali", "joe"]);
+const FRONT_HEAD = 8192;
+const LETTER = /[\p{L}\p{N}]/u;
+const DATED = /^\d{4}-\d{2}-\d{2}(?:\s*[-\u2013\u2014]\s*)?/;
+
+const norm = (s) => String(s).toLowerCase().replace(/\s+/g, " ").trim();
+const relOf = (evda, abs) => abs.slice(evda.dir.length + 1).split(sep).join("/");
+
+// The frontmatter of a file from its head; the whole file only when the frontmatter runs past it.
+function frontOfHead(abs) {
+  let text;
+  try {
+    const fd = openSync(abs, "r");
+    try {
+      const buf = Buffer.alloc(FRONT_HEAD);
+      const n = readSync(fd, buf, 0, FRONT_HEAD, 0);
+      text = buf.toString("utf8", 0, n);
+    } finally { closeSync(fd); }
+  } catch { return null; }
+  if (!text.startsWith("---\n")) return null;
+  if (!/\n---(\n|$)/.test(text.slice(3))) {
+    try { text = readFileSync(abs, "utf8"); } catch { return null; }
+  }
+  return frontmatterOf(text);
+}
+
+// Whether a name is specific enough to stand for an entry.
+function usable(name, { person = false } = {}) {
+  const n = norm(name);
+  if (n.length < (person ? 3 : NAME_MIN)) return false;
+  if (!LETTER.test(n) || /^[\d\s\p{P}]+$/u.test(n)) return false;
+  if (GENERIC.has(n)) return false;
+  if (!n.includes(" ") && !person && n.length < NAME_MIN_WORD) return false;
+  return true;
+}
+
+// The names one entry answers to, from its path and frontmatter.
+function namesOf(rel, front) {
+  const parts = rel.split("/");
+  let stem = parts[parts.length - 1].replace(/\.md$/i, "");
+  // A folder's README or index stands for the folder.
+  if (/^(readme|index)$/i.test(stem) && parts.length > 1) stem = parts[parts.length - 2];
+  stem = stem.replace(DATED, "").trim();
+  const out = new Set();
+  const add = (s) => { if (typeof s === "string" && s.trim()) out.add(norm(s)); };
+  add(stem);
+  // The head of a dashed title, and the title without a trailing parenthetical.
+  const head = stem.split(/\s+[-\u2013\u2014]\s+/)[0];
+  if (head !== stem) add(head);
+  add(stem.replace(/\s*\([^)]*\)\s*$/, ""));
+  if (front) {
+    add(front.title);
+    if (front["kind"] === "person-profile") add(front.name);
+    const al = front.aliases ?? front.alias;
+    for (const a of Array.isArray(al) ? al : [al]) add(a);
+  }
+  return [...out].filter((n) => usable(n));
+}
+
+// The folders whose files are the day's flow, not entries a filing names.
+function skippedDirs(evda) {
+  const out = [];
+  for (const role of ["record/daily", "record/captures", "journal/dreams", "journal/inbox", "ledger", "circles", "grants", "collections/archive", "collections/attachments"]) {
+    try {
+      const r = resolveRole(evda, role);
+      if (r.mapped && r.abs && r.abs !== evda.dir) out.push(r.abs);
+    } catch { /* an unmapped or escaping role skips nothing */ }
+  }
+  return out;
+}
+
+function buildIndex(evda) {
+  const skip = skippedDirs(evda);
+  let people = null;
+  try { const r = resolveRole(evda, "record/people"); if (r.mapped && r.abs) people = r.abs; } catch { /* none */ }
+  const names = new Map(); // name -> Set(rel)
+  const fronts = new Map(); // rel -> frontmatter (only files that have one)
+  const derived = []; // { rel, view, from }
+  const firstNames = new Map(); // first name -> Set(rel)
+  const put = (name, rel) => { if (!names.has(name)) names.set(name, new Set()); names.get(name).add(rel); };
+  let files = [];
+  try { files = markdownFiles(evda.dir); } catch { files = []; }
+  for (const abs of files) {
+    if (skip.some((d) => abs.startsWith(d + sep))) continue;
+    const rel = relOf(evda, abs);
+    if (!rel.includes("/") && /^(agents|claude|gemini)\.md$/i.test(rel)) continue;
+    const front = frontOfHead(abs);
+    if (front) fronts.set(rel, front);
+    for (const n of namesOf(rel, front)) put(n, rel);
+    if (people && abs.startsWith(people + sep) && !abs.slice(people.length + 1).includes(sep)) {
+      const full = rel.split("/").pop().replace(/\.md$/i, "");
+      const first = norm(full.split(/\s+/)[0]);
+      if (full.includes(" ") && !WORD_NAMES.has(first) && usable(first, { person: true })) {
+        if (!firstNames.has(first)) firstNames.set(first, new Set());
+        firstNames.get(first).add(rel);
+      }
+    }
+    const from = front?.[DERIVED_FROM];
+    if (front && typeof front[VIEW] === "string" && Array.isArray(from)) derived.push({ rel, view: front[VIEW], from: from.filter((s) => typeof s === "string").map((s) => s.replace(/\/+$/, "")) });
+  }
+  // A first name is a person's only when no other person's page starts with it.
+  for (const [first, rels] of firstNames) if (rels.size === 1 && !names.has(first)) put(first, [...rels][0]);
+  for (const [n, rels] of [...names]) if (rels.size > NAME_MAX_ENTRIES) names.delete(n);
+  // Longest first, so a match on "sexual health - lasting and presence" outranks "sexual health".
+  const ordered = [...names.entries()].sort((a, b) => b[0].length - a[0].length);
+  return { names: ordered, fronts, derived, files: files.length };
+}
+
+const cache = new Map(); // evda.dir -> { at, index, rebuilding }
+const boardCache = new Map(); // evda.dir -> { at, board, loading }
+export function clearTouchesCache() { cache.clear(); boardCache.clear(); }
+
+// Build off the request path: setTimeout, so the answer that scheduled it is already sent.
+function rebuildLater(evda, now) {
+  const hit = cache.get(evda.dir);
+  if (hit?.rebuilding) return;
+  if (hit) hit.rebuilding = true;
+  const t = setTimeout(() => {
+    try { cache.set(evda.dir, { at: now, index: buildIndex(evda) }); } catch { cache.delete(evda.dir); }
+  }, 0);
+  t.unref?.();
+}
+
+// The record's names. Built once, synchronously, only when nothing is cached; a stale index is
+// served as it is while a fresh one builds after the answer, so a filing never waits on the walk
+// except the first in a process that was never warmed (warmTouches, at initialize).
+export function touchesIndex(evda, { now = Date.now(), ttl = INDEX_TTL_MS } = {}) {
+  const hit = cache.get(evda.dir);
+  if (hit) {
+    if (now - hit.at >= ttl) rebuildLater(evda, now);
+    return hit.index;
+  }
+  const index = buildIndex(evda);
+  cache.set(evda.dir, { at: now, index });
+  return index;
+}
+
+// Build the index after the current request, so the first filing in a session finds it ready.
+export function warmTouches(evda, { now = Date.now() } = {}) {
+  try { boardTickets(evda, { now }); } catch { /* the first filing starts it */ }
+  if (cache.has(evda.dir)) return;
+  const t = setTimeout(() => {
+    try { if (!cache.has(evda.dir)) cache.set(evda.dir, { at: now, index: buildIndex(evda) }); } catch { /* the first filing builds it */ }
+  }, 0);
+  t.unref?.();
+}
+
+// The board sources the record's work role names: every `work` or `work/<facet>` key whose value is
+// a `harlequin` source. Empty for a record whose work is a folder or unmapped.
+export function boardSources(evda) {
+  const out = [];
+  for (const [key, value] of Object.entries(evda.manifest?.mapping ?? {})) {
+    if (fourRoleOf(key) !== "work") continue;
+    const s = workSource(value);
+    if (s?.source === "harlequin") out.push({ project: s.project ?? null });
+  }
+  return out;
+}
+
+const words = (s) => String(s).toLowerCase().split(/[^\p{L}\p{N}]+/u).filter(Boolean);
+const isContent = (w) => w.length >= 3 && !COMMON.has(w) && !/^\d+$/.test(w);
+
+// The open tickets, by number and by the four-word runs of their titles.
+export function ticketIndex(efforts) {
+  const byNumber = new Map(); // "2791" -> ticket
+  const seeds = new Map(); // "w1 w2 w3 w4" -> [{ t, pos }]
+  for (const e of efforts) {
+    if (!e || CLOSED_STATUSES.has(e.status)) continue;
+    const n = /^HQ-(\d+)$/.exec(String(e.id ?? ""))?.[1];
+    if (!n || typeof e.title !== "string") continue;
+    const t = { id: `HQ-${n}`, title: e.title, status: e.status, words: words(e.title) };
+    byNumber.set(n, t);
+    for (let i = 0; i + SPAN_WORDS <= t.words.length; i++) {
+      const g = t.words.slice(i, i + SPAN_WORDS).join(" ");
+      if (!seeds.has(g)) seeds.set(g, []);
+      const list = seeds.get(g);
+      if (!list.some((h) => h.t === t)) list.push({ t, pos: i });
+    }
+  }
+  for (const [g, list] of [...seeds]) if (list.length > SEED_MAX_TICKETS) seeds.delete(g);
+  return { byNumber, seeds, open: byNumber.size };
+}
+
+// The open tickets the words reference, numbers first in the order said, then longest run first.
+export function ticketsIn(board, text) {
+  if (!board || !text) return [];
+  const out = [];
+  const seen = new Set();
+  for (const m of String(text).matchAll(/(?<![\p{L}\p{N}])hq[-\s]?(\d+)(?![\p{L}\p{N}])/giu)) {
+    const t = board.byNumber.get(String(Number(m[1])));
+    if (!t || seen.has(t)) continue;
+    seen.add(t);
+    out.push({ id: t.id, title: t.title, status: t.status, named: t.id });
+  }
+  const w = words(text);
+  const best = new Map(); // ticket -> { len, span }
+  for (let i = 0; i + SPAN_WORDS <= w.length; i++) {
+    const hits = board.seeds.get(w.slice(i, i + SPAN_WORDS).join(" "));
+    if (!hits) continue;
+    for (const { t, pos } of hits) {
+      let k = SPAN_WORDS;
+      while (i + k < w.length && pos + k < t.words.length && w[i + k] === t.words[pos + k]) k++;
+      const span = t.words.slice(pos, pos + k);
+      if (span.filter(isContent).length < SPAN_CONTENT) continue;
+      if ((best.get(t)?.len ?? 0) < k) best.set(t, { len: k, span: span.join(" ") });
+    }
+  }
+  const runs = [...best.entries()].filter(([t]) => !seen.has(t)).sort((a, b) => b[1].len - a[1].len || b[1].span.length - a[1].span.length || (a[0].id < b[0].id ? -1 : 1));
+  for (const [t, r] of runs) out.push({ id: t.id, title: t.title, status: t.status, named: r.span });
+  return out.slice(0, TICKETS_MAX);
+}
+
+function withTimeout(promise, ms) {
+  let timer;
+  return Promise.race([promise, new Promise((_, rej) => { timer = setTimeout(() => rej(new Error("timeout")), ms); timer.unref?.(); })]).finally(() => clearTimeout(timer));
+}
+
+// Read the board after the current request. A failure keeps what was cached and retries after the TTL.
+function loadBoard(evda, sources, now) {
+  const hit = boardCache.get(evda.dir) ?? { at: 0, board: null };
+  if (hit.loading) return;
+  hit.loading = true;
+  boardCache.set(evda.dir, hit);
+  const env = process.env;
+  const envFile = env.EVDA_WORK_ENV_FILE || null;
+  const t = setTimeout(() => {
+    withTimeout((async () => {
+      const efforts = [];
+      let read = false;
+      for (const s of sources) {
+        const r = await harlequinEfforts(evda.dir, { project: s.project, env, envFile });
+        if (r.status === "checked") { read = true; efforts.push(...r.efforts); }
+      }
+      return read ? ticketIndex(efforts) : null;
+    })(), BOARD_TIMEOUT_MS)
+      .then((board) => { boardCache.set(evda.dir, { at: now, board: board ?? hit.board }); })
+      .catch(() => { boardCache.set(evda.dir, { at: now, board: hit.board }); });
+  }, 0);
+  t.unref?.();
+}
+
+// The board's open tickets for a record whose work is a board, from the cache; null otherwise or
+// before the first read lands. A missing or stale cache starts a read after the answer.
+export function boardTickets(evda, { now = Date.now(), ttl = INDEX_TTL_MS } = {}) {
+  const sources = boardSources(evda);
+  if (!sources.length) return null;
+  const hit = boardCache.get(evda.dir);
+  if (!hit || (!hit.loading && now - hit.at >= ttl)) loadBoard(evda, sources, now);
+  return hit?.board ?? null;
+}
+
+// Whether `name` occurs in `text` (both lowercased) as whole words.
+function occurs(text, name) {
+  let i = text.indexOf(name);
+  while (i !== -1) {
+    const before = i === 0 ? "" : text[i - 1];
+    const after = text[i + name.length] ?? "";
+    if (!LETTER.test(before) && !LETTER.test(after)) return true;
+    i = text.indexOf(name, i + 1);
+  }
+  return false;
+}
+
+const titleOf = (c) => c.manifest?.title ?? c.name;
+
+// The shared circles one path reaches, as sentences naming only the shared circle and the path.
+function circlesFor(evda, ctx, rel, front, index) {
+  const abs = join(evda.dir, rel);
+  const out = [];
+  const homes = homesOf(evda, ctx.circles, abs);
+  const home = homes.length === 1 ? ctx.circles.find((c) => c.name === homes[0]) : null;
+  if (home?.manifest?.public === true) out.push(`${rel} is in the ${titleOf(home)} circle, which anyone can read.`);
+  const held = heldBy(front, "publish");
+  const sealedOrNoted = held === SEALED || held === NOTED;
+  if (home && home.manifest?.public !== true && !sealedOrNoted) {
+    for (const c of ctx.circles) {
+      if (c === home) continue;
+      const rules = Object.values(c.members).filter((m) => m.kind === "rule");
+      if (!front || !rules.some((m) => matchesWhere(front, m.where))) continue;
+      if (Array.isArray(home.release) && home.release.includes(c.name)) out.push(`${rel} is in the ${titleOf(c)} circle by its share mark.`);
+    }
+    // A home that covers the whole record is the private default; saying it may release everything
+    // would be said of every filing and tell the agent nothing.
+    const wholeRecord = Object.values(home.members).some((m) => m.kind === "path" && m.rel === "");
+    if (!wholeRecord && Array.isArray(home.release)) {
+      const targets = home.release.map((n) => ctx.circles.find((c) => c.name === n)).filter(Boolean).filter((c) => !out.some((l) => l.includes(`the ${titleOf(c)} circle by its share mark`)));
+      if (targets.length) out.push(`${rel} may be released to the ${targets.map(titleOf).join(", ")} circle${targets.length > 1 ? "s" : ""}; it is not there now.`);
+    }
+  }
+  for (const d of index.derived) {
+    const src = d.from.find((s) => s === rel || rel.startsWith(`${s}/`));
+    if (!src || d.rel === rel) continue;
+    const dFront = index.fronts.get(d.rel);
+    const dHeld = heldBy(dFront, "publish");
+    if (dHeld === SEALED || dHeld === NOTED) continue;
+    const gatherers = ctx.circles.filter((c) => {
+      const dHomes = homesOf(evda, ctx.circles, join(evda.dir, d.rel));
+      if (dHomes.length === 1 && dHomes[0] === c.name && c.manifest?.public === true) return true;
+      return Object.values(c.members).some((m) => m.kind === "rule" && matchesWhere(dFront ?? {}, m.where));
+    });
+    for (const c of gatherers) out.push(`the ${titleOf(c)} circle's entry ${d.rel} (view ${d.view}) is derived from ${src}${src === rel ? "" : `, which holds ${rel}`}.`);
+  }
+  return out;
+}
+
+// What the filing at `paths` (relative to the record) with `words` bears on. Returns
+// { related: [{ path, name }], circles: [sentence], tickets: [{ id, title, status, named }], ms }. Never throws: a filing is never failed by
+// what it would have been told.
+export function touches(evda, { paths = [], words = "", caller = callerFrom(), now = Date.now() } = {}) {
+  const t0 = performance.now();
+  try {
+    const index = touchesIndex(evda, { now });
+    const ctx = readContext(evda);
+    const written = new Set(paths.filter(Boolean));
+    const text = norm(words);
+    const related = [];
+    const seen = new Set();
+    if (text) {
+      for (const [name, rels] of index.names) {
+        if (related.length >= RELATED_MAX) break;
+        if (!occurs(text, name)) continue;
+        // One entry per name: the shallowest, then the shortest path, the readable one nearest the
+        // top of the record standing for the subject.
+        const depth = (r) => r.split("/").length;
+        for (const rel of [...rels].sort((a, b) => depth(a) - depth(b) || a.length - b.length || (a < b ? -1 : 1))) {
+          if (written.has(rel) || seen.has(rel)) continue;
+          const abs = join(evda.dir, rel);
+          if (!existsSync(abs)) continue;
+          if (!mayRead(ctx, abs, caller).ok) continue;
+          seen.add(rel);
+          related.push({ path: rel, name });
+          break;
+        }
+      }
+    }
+    const circles = [];
+    for (const rel of [...written, ...related.map((r) => r.path)]) {
+      const abs = join(evda.dir, rel);
+      // The path just written is read fresh: its share mark may be what this filing added.
+      const front = written.has(rel) ? frontOfHead(abs) : index.fronts.get(rel) ?? null;
+      for (const line of circlesFor(evda, ctx, rel, front, index)) if (!circles.includes(line)) circles.push(line);
+    }
+    let tickets = [];
+    try { tickets = ticketsIn(boardTickets(evda, { now }), words); } catch { tickets = []; }
+    return { related, circles, tickets, ms: performance.now() - t0 };
+  } catch {
+    return { related: [], circles: [], tickets: [], ms: performance.now() - t0 };
+  }
+}
+
+// The block a write tool's answer carries, or "" when there is nothing to say. Information for the
+// agent, never an instruction.
+export function touchesText(t) {
+  const tickets = t?.tickets ?? [];
+  if (!t || (!t.related.length && !t.circles.length && !tickets.length)) return "";
+  const lines = [];
+  if (t.related.length) lines.push(relatedLine(t.related));
+  if (tickets.length) lines.push(ticketsLine(tickets));
+  if (t.circles.length) lines.push(`Shared circles this reaches: ${t.circles.join(" ")}`);
+  return lines.join("\n");
+}

package/lib/update-check.mjs

@@ -16,6 +16,9 @@
 
 import { readFileSync, writeFileSync, existsSync, mkdirSync } from "node:fs";
 import { join, dirname } from "node:path";
+import { openEvda } from "./manifest.mjs";
+import { agentsFile } from "./roles.mjs";
+import { splitFence } from "./agents.mjs";
 
 export const THROTTLE_MS = 60 * 60 * 1000; // one hour, per the plan doc
 const REGISTRY_URL = "https://registry.npmjs.org/create-evda/latest";
@@ -87,6 +90,12 @@ function higherVersion(a, b) {
   return a;
 }
 
+// True when version `a` is strictly newer than `b`, comparing components as numbers (0.10.0 > 0.9.0).
+// `evda update` uses it to refuse taking an update with a tool older than the version it would take.
+export function isNewer(a, b) {
+  return a !== b && higherVersion(a, b) === a;
+}
+
 // The one entry point. `now` is injected so a caller (or a test) can control throttling without
 // waiting an hour; callers outside a test pass Date.now().
 //
@@ -96,7 +105,10 @@ function higherVersion(a, b) {
 //   { status: "UP_TO_DATE", installed, latest }
 //   { status: "UPDATE_AVAILABLE", installed, latest }
 //   { status: "UNSTAMPED", latest }   -- this record predates package-version stamping
+//   { status: "OWNER_KEPT", agents }  -- the agents file has no installer block, so nothing to take
 export async function checkForUpdate(dir, { now = Date.now(), force = false } = {}) {
+  const kept = ownerKept(dir);
+  if (kept) return { status: "OWNER_KEPT", agents: kept };
   const sf = stateFile(dir);
   const state = readJsonSafe(sf);
 
@@ -127,6 +139,22 @@ export async function checkForUpdate(dir, { now = Date.now(), force = false } =
     : { status: "UP_TO_DATE", installed, latest: fetched.version };
 }
 
+// HQ-2333: what `evda upgrade` replaces is the evda:generated block in the agents file. A record
+// whose agents file has none (Mike's maps it to CLAUDE.md and builds its core from the spec itself)
+// has nothing an update can change, and upgrade refuses it. On 10/7 the check told him to run
+// upgrade anyway, inside a Claude app reply, so a record like that now reports so and asks nothing.
+// Returns the agents file's path when it has no block, else null (a block, no agents role, or a
+// directory that is not a record all go on to the registry as before).
+export function ownerKept(dir) {
+  try {
+    const a = agentsFile(openEvda(dir));
+    if (!a) return null;
+    return splitFence(readFileSync(a.abs, "utf8")) ? null : a.rel;
+  } catch {
+    return null;
+  }
+}
+
 // One line, for the preamble and for `evda check-update`'s own stdout. Never throws.
 export function summarize(result) {
   switch (result.status) {
@@ -136,6 +164,8 @@ export function summarize(result) {
       return `update check: CHECK_FAILED, update status UNKNOWN (${result.reason})`;
     case "UNSTAMPED":
       return `update check: this record predates version stamping; latest is ${result.latest}. Run "evda upgrade" once to start tracking it.`;
+    case "OWNER_KEPT":
+      return `update check: nothing to take; ${result.agents} has no installer block, so its owner keeps it, not evda upgrade`;
     case "UP_TO_DATE":
       return `update check: up to date (${result.installed})`;
     case "UPDATE_AVAILABLE":

package/lib/watch.mjs

@@ -0,0 +1,160 @@
+// Watching a record for saves (HQ-2068), so the computer sends a saved note in seconds instead of
+// at the next five-minute sync.
+//
+// macOS reports every change under a folder through FSEvents, which Node's recursive `fs.watch`
+// uses on darwin. This turns those reports into bursts: a run of saves close together is one burst,
+// said once it has been quiet for `quietMs`, or once it has run `maxWaitMs`, so an editor that
+// saves every keystroke still gets a sync every few seconds. What the scan would never send starts
+// nothing: the sync rules' exclusions (`.evda`, `.git`, `node_modules`, `.DS_Store`, an Office owner
+// file, the plan's own paths), an iCloud placeholder, and a dataless file iCloud has not brought
+// down (HQ-2017), or a folder (what changed inside it is reported on its own). A path that is gone
+// counts, since its removal is news.
+//
+// The watcher decides only WHEN a sync runs. The sync it starts is the ordinary bounded one, with
+// its own lock and guards (HQ-2041); the five-minute sync stays as the backstop for anything a
+// watcher misses (a change while the app was closed, an FSEvents drop).
+
+import { lstatSync, watch } from "node:fs";
+import { join, sep } from "node:path";
+import { datalessAmong, excluder, isPlaceholder } from "./sync-rules.mjs";
+
+export const WATCH_QUIET_MS = 1_000;
+export const WATCH_MAX_WAIT_MS = 5_000;
+
+/**
+ * Whether a change at `rel` (relative to `root`) is one a sync would act on: not excluded, not an
+ * iCloud placeholder, not a link or a folder, not a dataless file. A path that no longer exists counts.
+ */
+export function watchCounts(root, rel, { exclude = excluder(), env = process.env } = {}) {
+  const r = String(rel).split(sep).join("/").normalize("NFC");
+  if (r === "" || exclude(r)) return false;
+  if (isPlaceholder(r.slice(r.lastIndexOf("/") + 1))) return false;
+  let st;
+  try {
+    st = lstatSync(join(root, r));
+  } catch {
+    return true;
+  }
+  if (st.isSymbolicLink() || st.isDirectory()) return false;
+  if (st.isFile() && st.size > 0 && st.blocks === 0 && datalessAmong(root, [r], { env }).has(r)) return false;
+  return true;
+}
+
+/**
+ * Watch `root` and call `onBurst(paths)` once per burst of counted changes, with the paths in it.
+ * Returns `{ close() }`. `watchImpl` replaces `fs.watch` for a test that feeds it events.
+ */
+export function watchRecord(root, onBurst, { quietMs = WATCH_QUIET_MS, maxWaitMs = WATCH_MAX_WAIT_MS, exclude = excluder(), env = process.env, watchImpl = watch, now = () => Date.now() } = {}) {
+  let pending = new Set();
+  let first = 0;
+  let timer = null;
+  const fire = () => {
+    timer = null;
+    if (pending.size === 0) return;
+    const paths = [...pending];
+    pending = new Set();
+    first = 0;
+    onBurst(paths);
+  };
+  const watcher = watchImpl(root, { recursive: true, persistent: true }, (_event, name) => {
+    if (name == null) return;
+    const rel = String(name);
+    if (!watchCounts(root, rel, { exclude, env })) return;
+    pending.add(rel.split(sep).join("/").normalize("NFC"));
+    const t = now();
+    if (first === 0) first = t;
+    if (timer) clearTimeout(timer);
+    timer = setTimeout(fire, Math.max(0, Math.min(quietMs, first + maxWaitMs - t)));
+  });
+  return {
+    close() {
+      if (timer) clearTimeout(timer);
+      timer = null;
+      watcher.close();
+    },
+  };
+}
+
+// ─── A device's note, taken in within seconds (HQ-2068) ─────────────────────
+//
+// The file watcher sees only saves on this computer, so a note a phone sent waited for the
+// five-minute sync. This looks at the relay instead: every `everyMs` it asks each mailbox this
+// computer reads for its first waiting envelope, takes nothing and acknowledges nothing, and says
+// so once per envelope it has not seen at the head of that mailbox. The sync it starts drains the
+// box; an envelope the sync leaves where it is stays the head and starts nothing a second time.
+
+export const RELAY_PEEK_MS = 2_000;
+// The mailboxes are re-derived this often, so a device paired while the app was open is looked at too.
+export const RELAY_REFRESH_MS = 60_000;
+
+/**
+ * The seq of the first envelope waiting in one mailbox, or null when it is empty. Reads only:
+ * the relay's GET takes nothing off the box. Throws when the relay cannot be reached.
+ */
+export async function mailboxHead(box, { fetchImpl = fetch, timeoutMs = 10_000 } = {}) {
+  const res = await fetchImpl(`${box.relayUrl}/mailbox/${encodeURIComponent(box.address)}?limit=1`, {
+    headers: { authorization: `Bearer ${box.pollCredential}` },
+    signal: AbortSignal.timeout(timeoutMs),
+  });
+  if (!res.ok) throw new Error(`relay answered ${res.status}`);
+  const body = await res.json();
+  const first = (body.envelopes ?? [])[0];
+  if (!first) return null;
+  return String(first.seq ?? first.id);
+}
+
+/**
+ * Look at the relay every `everyMs` and call `onIncoming()` once per new envelope at the head of
+ * any mailbox. `mailboxes()` gives the boxes (null when it cannot look now, tried again next time).
+ * A relay that cannot be reached is skipped until the next look; the five-minute sync covers it.
+ * Returns `{ close(), look() }`; `look` runs one look now, for a test.
+ */
+export function watchRelay(mailboxes, onIncoming, { everyMs = RELAY_PEEK_MS, refreshMs = RELAY_REFRESH_MS, head = mailboxHead, now = () => Date.now() } = {}) {
+  let boxes = null;
+  let derivedAt = 0;
+  const seen = new Map();
+  let running = null;
+  let closed = false;
+  const once = async () => {
+    if (boxes === null || now() - derivedAt >= refreshMs) {
+      let next = null;
+      try {
+        next = await mailboxes();
+      } catch {
+        next = null;
+      }
+      if (next !== null) {
+        boxes = next;
+        derivedAt = now();
+      }
+    }
+    if (!boxes) return false;
+    let fresh = false;
+    for (const box of boxes) {
+      let h;
+      try {
+        h = await head(box);
+      } catch {
+        continue;
+      }
+      const prev = seen.get(box.address);
+      seen.set(box.address, h);
+      if (h !== null && h !== prev) fresh = true;
+    }
+    if (fresh && !closed) onIncoming();
+    return fresh;
+  };
+  const look = () => {
+    if (!running) running = once().finally(() => { running = null; });
+    return running;
+  };
+  const timer = setInterval(look, everyMs);
+  timer.unref?.();
+  return {
+    look,
+    close() {
+      closed = true;
+      clearInterval(timer);
+    },
+  };
+}