create-evda 0.1.5 → 0.1.6

package/lib/subrecord.mjs

@@ -0,0 +1,121 @@
+// Making a record inside a record from a conversation (HQ-1377, the HQ-1371 shape): the owner asks
+// for a sub-EVÐA for a project, a company or an agent, and their AI makes it through the MCP server.
+//
+// What it makes, at a path inside the record: an evda.json with the four roles (journal from
+// record/daily and record/captures, work from work/, collections from record/people, knowledge from
+// the ledger), an AGENTS.md whose owner section carries what it is for, and everything else a new
+// record gets from create-evda. It is made by the same scaffold, so a sub-record is never a second
+// shape of record.
+//
+// The parent stays as it is. Its evda.json changes only when the owner opts into "subrecords":
+// "bounded" (the parent's circles stop at the sub-record), which changes what the parent syncs and
+// so waits for confirmed: true. Doctor runs on the parent before and after, walking the new
+// sub-record as its own record; when the parent was clean before and is not after, everything this
+// call made is removed again and the report says why.
+
+import { existsSync, readdirSync, readFileSync, rmSync, writeFileSync, mkdirSync } from "node:fs";
+import { isAbsolute, join, normalize, resolve, sep } from "node:path";
+import { parseArgs, scaffold, slug } from "../create-evda.mjs";
+import { readManifest, isBounded } from "./manifest.mjs";
+import { subRecords } from "./records.mjs";
+import { doctor } from "./doctor.mjs";
+import { EvdaError } from "./errors.mjs";
+
+export const WORK_DIR = "work";
+
+// EVDA_SUBRECORD_FALSIFY=<mode,...>, for the tests: no-doctor returns without running doctor after,
+// keep-broken leaves what it made in place when doctor fails on it.
+export const SUBRECORD_FALSIFY_MODES = ["no-doctor", "keep-broken"];
+const falsified = (mode) => (process.env.EVDA_SUBRECORD_FALSIFY ?? "").split(",").map((x) => x.trim()).includes(mode);
+
+function refuse(message, code) {
+  return new EvdaError(`REFUSED: ${message} Nothing was written.`, { code, exit: 2 });
+}
+
+function runDoctor(dir) {
+  const lines = [];
+  const r = doctor(dir, { out: (l) => lines.push(l) });
+  return { exit: r.exit, text: lines.join("\n") };
+}
+
+// Where the new record may go, as a relative path, or a refusal naming why not.
+export function placeFor(evda, path) {
+  if (typeof path !== "string" || path.trim() === "") throw refuse(`evda_create_subrecord needs "path": where in the record the new EVÐA goes, such as Projects/Garden.`, "NO_PATH");
+  if (isAbsolute(path)) throw refuse(`"path" ${JSON.stringify(path)} is absolute; it is relative to the record.`, "BAD_PATH");
+  const rel = normalize(path).split(sep).join("/").replace(/\/+$/, "");
+  const abs = resolve(evda.dir, rel);
+  if (abs === evda.dir || !abs.startsWith(evda.dir + sep)) throw refuse(`"path" ${JSON.stringify(path)} is not inside the record.`, "BAD_PATH");
+  if (rel.split("/").some((part) => part.startsWith("."))) throw refuse(`"path" ${JSON.stringify(path)} goes through a dot folder, which is the tooling's, not the record's.`, "BAD_PATH");
+  const inside = subRecords(evda.dir).find((s) => rel === s || rel.startsWith(`${s}/`));
+  if (inside !== undefined) throw refuse(`${rel} is inside the sub-record at ${inside}, which is a record of its own. Make it from that record's server.`, "INSIDE_SUBRECORD");
+  for (const [key, value] of Object.entries(evda.manifest.mapping)) {
+    if (typeof value !== "string" || /^[a-z][a-z0-9-]*:/.test(value)) continue;
+    const mapped = value.replace(/\/+$/, "");
+    if (mapped === rel || mapped.startsWith(`${rel}/`)) throw refuse(`${rel} would hold ${mapped}, which this record maps as "${key}". A parent's own folders never go inside a sub-record.`, "HOLDS_ROLE");
+    if (key === "agents" && rel.startsWith(`${mapped}/`)) throw refuse(`${rel} is under ${mapped}, a file.`, "BAD_PATH");
+  }
+  if (existsSync(abs) && readdirSync(abs).length) throw refuse(`${rel} already exists and is not empty. A sub-EVÐA starts in a new or empty folder; to make an existing folder a record of its own, ask the owner and run create-evda there with --force.`, "NOT_EMPTY");
+  return { rel, abs };
+}
+
+export function createSubrecord(evda, args = {}) {
+  const allowed = ["path", "name", "purpose", "kind", "bounded", "confirmed"];
+  const extra = Object.keys(args).filter((k) => !allowed.includes(k));
+  if (extra.length) throw refuse(`evda_create_subrecord does not take ${extra.map((k) => JSON.stringify(k)).join(", ")}.`, "UNKNOWN_ARGUMENT");
+  if (args.bounded === true && args.confirmed !== true) {
+    throw refuse(`bounded: true changes this record's evda.json so its circles stop at the new sub-record, which changes what it syncs. Pass confirmed: true only when the owner said yes to that in this conversation. Without bounded, the sub-EVÐA is made and the parent is left as it is.`, "NOT_CONFIRMED");
+  }
+  const { rel, abs } = placeFor(evda, args.path);
+  const name = typeof args.name === "string" && args.name.trim() ? args.name.trim() : rel.split("/").pop();
+  const kind = args.kind ?? "person";
+  const parentId = typeof evda.manifest.id === "string" && evda.manifest.id ? evda.manifest.id : "atlas";
+  const id = `${slug(name)}.${parentId}`;
+  const owner = evda.manifest.owner?.name ?? "";
+
+  const before = runDoctor(evda.dir);
+  const manifestFile = join(evda.dir, "evda.json");
+  const parentBefore = readFileSync(manifestFile, "utf8");
+  const existed = existsSync(abs);
+  // The outermost folder this call creates, so an undo leaves no empty parent behind.
+  const parts = rel.split("/");
+  let top = abs;
+  for (let i = 1; i <= parts.length; i++) {
+    const p = join(evda.dir, ...parts.slice(0, i));
+    if (!existsSync(p)) { top = p; break; }
+  }
+  let madeParentBounded = false;
+  try {
+    const argv = [abs, "--yes", "--no-pointer", "--no-guard", "--name", name, "--kind", kind, "--id", id, "--layers", "record,ledger"];
+    if (owner) argv.push("--owner", owner);
+    if (typeof args.purpose === "string" && args.purpose.trim()) argv.push("--purpose", args.purpose.trim());
+    scaffold({ ...parseArgs(argv), force: existed });
+    // The fourth role. record/daily and record/captures fill journal, record/people collections and
+    // the ledger knowledge; work is a folder of effort files until the owner points it at a board.
+    const m = readManifest(abs);
+    m.mapping.work = WORK_DIR;
+    if (evda.manifest.read_by !== undefined && m.read_by === undefined) m.read_by = evda.manifest.read_by;
+    mkdirSync(join(abs, WORK_DIR), { recursive: true });
+    writeFileSync(join(abs, "evda.json"), `${JSON.stringify(m, null, 2)}\n`);
+    if (args.bounded === true && !isBounded(evda.manifest)) {
+      const pm = JSON.parse(parentBefore);
+      pm.subrecords = "bounded";
+      writeFileSync(manifestFile, `${JSON.stringify(pm, null, 2)}\n`);
+      madeParentBounded = true;
+    }
+  } catch (e) {
+    undo();
+    throw e;
+  }
+  const after = falsified("no-doctor") ? { exit: 0, text: "" } : runDoctor(evda.dir);
+  if (before.exit === 0 && after.exit !== 0 && !falsified("keep-broken")) {
+    undo();
+    throw new EvdaError(`REFUSED: doctor was clean on this record before and failed with the sub-EVÐA at ${rel}, so what this call made was removed and the record is as it was.\n\n${after.text}`, { code: "DOCTOR_FAILED", exit: 2 });
+  }
+  return { path: rel, id, name, parentBounded: isBounded(readManifest(evda.dir)), madeParentBounded, doctor: after, doctorBefore: before.exit };
+
+  function undo() {
+    if (existed) for (const n of readdirSync(abs)) rmSync(join(abs, n), { recursive: true, force: true });
+    else rmSync(top, { recursive: true, force: true });
+    writeFileSync(manifestFile, parentBefore);
+  }
+}

package/lib/sync-rules.mjs

@@ -0,0 +1,87 @@
+// Which files in a record sync, and which are left where they are (Spec 08, stages S0 and S1).
+//
+// One definition, read by three things that must agree: the circle plan (what a circle's members
+// are), the coverage check (every file in exactly one circle), and the shadow scan and parity check
+// (what is sent, and what the shadow must equal). Two copies of this list would be two answers to
+// "does this file sync", and parity would pass on a file both sides agreed to skip.
+//
+// Three kinds of thing never sync, and each is counted rather than dropped:
+//
+//   excluded      by name anywhere (.DS_Store, node_modules, .git), by name at the root (.evda, the
+//                 derived index every device rebuilds), or by a path the plan names. Reported as
+//                 EXCLUDED n.
+//   symlink       never followed and never carried: sync moves bytes, and a link's target may be
+//                 outside the record, missing, or itself. A symlink inside a circle fails the
+//                 coverage check until the plan excludes it.
+//   placeholder   an iCloud stub (`.name.icloud`) for a file whose bytes are not on this disk.
+//                 Syncing the stub would make parity pass while the file never moved, so a stub
+//                 inside a circle fails until it is downloaded.
+//
+// And one kind cannot sync yet: a file larger than the relay's blob lane takes (64 MB, less the
+// seal), which fails the coverage check until the plan excludes it.
+
+import { lstatSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+
+export const EXCLUDE_NAMES = [".DS_Store", "node_modules", ".git", ".Trash", "Icon\r"];
+export const EXCLUDE_ROOT_NAMES = [".evda"];
+// The relay refuses a blob over 64 MiB (`xania-relay/src/relay.mjs`, MAX_BLOB_BYTES); the seal adds
+// a nonce, a tag and an ephemeral key, so leave a margin.
+export const MAX_SYNC_BYTES = 64 * 1024 * 1024 - 64 * 1024;
+
+const PLACEHOLDER = /^\..+\.icloud$/;
+export const isPlaceholder = (name) => PLACEHOLDER.test(name);
+
+const norm = (rel) => rel.replace(/^\/+|\/+$/g, "");
+
+// A predicate over a relative path: is it (or something above it) excluded? `extra` is the plan's
+// own list of excluded paths, each covering itself and everything under it.
+export function excluder(extra = []) {
+  const paths = extra.map(norm).filter((p) => p !== "");
+  return (rel) => {
+    const parts = norm(rel).split("/");
+    if (parts.some((p) => EXCLUDE_NAMES.includes(p))) return true;
+    if (EXCLUDE_ROOT_NAMES.includes(parts[0])) return true;
+    const r = parts.join("/");
+    return paths.some((p) => r === p || r.startsWith(`${p}/`));
+  };
+}
+
+// Walk a directory without following links. Yields { rel, kind, size } for every entry that is not
+// a directory, where kind is file | symlink | placeholder | excluded | oversize. An excluded
+// directory is yielded once, as itself, and not entered.
+export function* walk(root, { exclude = excluder(), from = "" } = {}) {
+  const dir = from === "" ? root : join(root, from);
+  let names;
+  try {
+    names = readdirSync(dir).sort();
+  } catch (e) {
+    if (e.code === "ENOENT" || e.code === "ENOTDIR") return;
+    throw e;
+  }
+  for (const name of names) {
+    const rel = from === "" ? name : `${from}/${name}`;
+    const st = lstatSync(join(root, rel));
+    if (exclude(rel)) {
+      yield { rel, kind: "excluded", size: st.isDirectory() ? 0 : st.size, dir: st.isDirectory() };
+      continue;
+    }
+    if (st.isSymbolicLink()) { yield { rel, kind: "symlink", size: 0 }; continue; }
+    if (st.isDirectory()) { yield* walk(root, { exclude, from: rel }); continue; }
+    if (isPlaceholder(name)) { yield { rel, kind: "placeholder", size: st.size }; continue; }
+    yield { rel, kind: st.size > MAX_SYNC_BYTES ? "oversize" : "file", size: st.size };
+  }
+}
+
+// The same rules as a filter a scanner applies while it walks: true means do not list it and do not
+// enter it. Everything that is not a plain, syncable file is skipped, and `walk` is what counts them.
+export function scanSkip(extra = []) {
+  const exclude = excluder(extra);
+  return (rel, st) => {
+    if (exclude(rel)) return true;
+    if (st.isSymbolicLink()) return true;
+    if (st.isDirectory()) return false;
+    const name = rel.slice(rel.lastIndexOf("/") + 1);
+    return isPlaceholder(name) || st.size > MAX_SYNC_BYTES;
+  };
+}

package/lib/tools.mjs

@@ -11,22 +11,32 @@
 //      reference (lib/references.mjs secretShape) and a hit refuses the whole write.
 //   3. Every write says where it landed, as a path relative to the record.
 //
+// Who may read (HQ-1374). Every tool that returns the record's words asks lib/readers.mjs first, for
+// each file: a just-noted entry is returned to no AI, and a file whose circle (or evda.json) names a
+// reader that is not the caller is held back. What was held back is said in one plain sentence at
+// the end of the answer, so the agent declines out loud instead of going quiet. The caller is who
+// the MCP client said it was on initialize; $EVDA_READER overrides it.
+//
+// Sealed (HQ-1220) is stronger and holds for every caller: a sealed file is in no answer, and no
+// answer names it or says whether it matched; a sealed section is cut out of every file shown
+// (lib/readers.mjs aiView). Every tool below that returns words goes through both.
+//
 // A circle is never created here. `propose_circle` writes a proposal file for the owner to read;
 // making the circle, and granting anyone anything, stays the owner's explicit yes through
 // `evda grant` or their own hands.
 
 import { appendFileSync, existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
-import { dirname, join, relative } from "node:path";
+import { dirname, join, relative, resolve, sep } from "node:path";
 import { resolveRole, rolesForLayer, agentsFile } from "./roles.mjs";
 import { mdFiles, fileDate } from "./record.mjs";
-import { readCircles } from "./circles.mjs";
+import { readCircles, isSealed } from "./circles.mjs";
 import { secretShape } from "./references.mjs";
 import { doctor } from "./doctor.mjs";
+import { readContext, mayRead, heldBack, callerFrom, aiView, note as writeNote, releaseNote, SEALED_WHY } from "./readers.mjs";
 import { EvdaError } from "./errors.mjs";
+import { dayRole, appendToDay, CONTEXT_LABEL, localDate, localTime } from "./day-file.mjs";
 
-const pad = (n) => String(n).padStart(2, "0");
-export const localDate = (d) => `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}`;
-export const localTime = (d) => `${pad(d.getHours())}:${pad(d.getMinutes())}`;
+export { localDate, localTime, CONTEXT_LABEL };
 
 const DATE = /^\d{4}-\d{2}-\d{2}$/;
 const MAX_WORDS = 200_000;
@@ -63,10 +73,12 @@ function rel(evda, abs) {
   return relative(evda.dir, abs).split("\\").join("/");
 }
 
+// The day's record: `record/daily`, else the `journal` role (HQ-1371). keep-hook.mjs dayRole is the
+// one rule, so the Stop hook watches the same file this appends to.
 function dailyDir(evda) {
-  const r = resolveRole(evda, "record/daily");
-  if (!r.mapped) throw refuse('this record maps no "record/daily" role, so there is no daily file to append to.', "NO_ROLE");
-  return r;
+  const role = dayRole(evda.manifest.mapping);
+  if (!role) throw refuse('this record maps no "record/daily" or "journal" role, so there is no daily file to append to.', "NO_ROLE");
+  return resolveRole(evda, role);
 }
 
 // Where imports go: `imports/` beside the daily role, so `record/daily` gives `record/imports`, and
@@ -85,12 +97,13 @@ export function operatingLayer(evda, args = {}) {
   onlyKeys("evda_operating_layer", args, []);
   const a = agentsFile(evda);
   if (!a) throw new EvdaError('this record maps no "agents" role, so it has no operating layer.', { code: "NO_ROLE" });
-  return { path: a.rel, text: readFileSync(a.abs, "utf8") };
+  if (isSealed(a.abs)) throw new EvdaError(`REFUSED: ${a.rel} ${SEALED_WHY.replace(/^It /, "is ")}`, { code: "SEALED", exit: 2 });
+  return { path: a.rel, text: aiView(readFileSync(a.abs, "utf8")).text };
 }
 
 // 2. The last `days` days of the record, newest first, whole files, capped in size. A file is in the
 // window by its date (filename, then a date or created key), the same rule `evda moment` uses.
-export function recent(evda, args = {}, { now = new Date() } = {}) {
+export function recent(evda, args = {}, { now = new Date(), caller = callerFrom() } = {}) {
   onlyKeys("evda_recent", args, ["days"]);
   const days = args.days === undefined ? 3 : Number(args.days);
   if (!Number.isInteger(days) || days < 1 || days > 90) throw new EvdaError("evda_recent days must be a whole number from 1 to 90.", { code: "BAD_ARGUMENT", exit: 2 });
@@ -99,11 +112,18 @@ export function recent(evda, args = {}, { now = new Date() } = {}) {
   const from = localDate(start);
   const to = localDate(now);
   const files = [];
+  const ctx = readContext(evda);
+  const refused = [];
+  let sealed = false;
   for (const abs of recordFiles(evda)) {
-    const body = readFileSync(abs, "utf8");
-    const date = fileDate(abs, body);
+    const raw = readFileSync(abs, "utf8");
+    const date = fileDate(abs, raw);
     if (!date || date < from || date > to) continue;
-    files.push({ date, path: rel(evda, abs), text: body });
+    const may = mayRead(ctx, abs, caller);
+    if (!may.ok) { refused.push(may); continue; }
+    const shown = aiView(raw);
+    if (shown.sections) sealed = true;
+    files.push({ date, path: rel(evda, abs), text: shown.text });
   }
   files.sort((a, b) => (a.date === b.date ? a.path.localeCompare(b.path) : b.date.localeCompare(a.date)));
   let used = 0;
@@ -114,7 +134,7 @@ export function recent(evda, args = {}, { now = new Date() } = {}) {
     used += f.text.length;
     out.push(f);
   }
-  return { from, to, files: out, omitted: truncated };
+  return { from, to, files: out, omitted: truncated, refused: refused.filter((r) => r.kind !== "sealed"), heldBack: heldBack(refused, { sealed }) };
 }
 
 // Every markdown file the record holds: each record-layer role, and the imports folder. Not the
@@ -134,20 +154,37 @@ function recordFiles(evda) {
   return out;
 }
 
-// 3. Append the owner's words, verbatim, to today's daily file, under the local time. Creates the
-// file with a date heading when it is the first write of the day. Returns the path.
-export function write(evda, args = {}, { now = new Date() } = {}) {
-  onlyKeys("evda_write", args, ["words"], "It appends to today's daily file and nothing else: it takes no path, and it never replaces or edits what is already written.");
+// 3. Append the owner's words, verbatim, to today's daily file. Creates the file with a date heading
+// when it is the first write of the day. Returns the path.
+// `context` (HQ-1377) is one line on what the conversation was about, in the agent's words, written
+// above theirs and labeled as not theirs, so a later reader never mistakes it for something they said.
+// `session` (HQ-1385) is the conversation: its first write opens `## HH:MM` with the context line,
+// and later writes append under it (lib/day-file.mjs, the one append path).
+export const CONTEXT_MAX = 240;
+export function write(evda, args = {}, { now = new Date(), session = null } = {}) {
+  onlyKeys("evda_write", args, ["words", "context"], "It appends to today's daily file and nothing else: it takes no path, and it never replaces or edits what is already written.");
   const words = text(args.words, "words", "evda_write");
   refuseSecrets(words, "evda_write");
+  let context = null;
+  if (args.context !== undefined) {
+    if (typeof args.context !== "string" || args.context.trim() === "") throw refuse(`evda_write "context" is one line on what the conversation was about; leave it out rather than send it empty.`, "EMPTY");
+    if (/\n/.test(args.context.trim())) throw refuse(`evda_write "context" is one line. Their words go in "words"; the context is a single line on what the conversation was about.`, "CONTEXT_LINES");
+    if (args.context.trim().length > CONTEXT_MAX) throw refuse(`evda_write "context" is ${args.context.trim().length} characters; one line of context is at most ${CONTEXT_MAX}.`, "TOO_LONG");
+    refuseSecrets(args.context, "evda_write");
+    context = args.context.trim();
+  }
   const r = dailyDir(evda);
   mkdirSync(r.abs, { recursive: true });
-  const date = localDate(now);
-  const abs = join(r.abs, `${date}.md`);
-  const head = existsSync(abs) ? "" : `# ${date}\n`;
-  const lead = existsSync(abs) && !readFileSync(abs, "utf8").endsWith("\n") ? "\n" : "";
-  appendFileSync(abs, `${lead}${head}\n## ${localTime(now)}\n\n${words.replace(/\n+$/, "")}\n`);
-  return { path: rel(evda, abs), bytes: Buffer.byteLength(words) };
+  const abs = join(r.abs, `${localDate(now)}.md`);
+  const w = appendToDay(abs, { now, words, context, session });
+  return { path: rel(evda, abs), bytes: Buffer.byteLength(words), section: w.opened ? "opened" : "continued" };
+}
+
+// The day file for a date, as { abs, rel }, for writers that are not evda_write (the chat-export
+// backstop in `evda gather`). Throws when the record maps no day role.
+export function dayFile(evda, date) {
+  const r = dailyDir(evda);
+  return { abs: join(r.abs, `${date}.md`), rel: rel(evda, join(r.abs, `${date}.md`)), dir: r.abs };
 }
 
 // 4. File what another AI said about the owner, verbatim, under imports/, labeled with its source
@@ -184,7 +221,7 @@ export function importText(evda, args = {}, { now = new Date() } = {}) {
 
 // 5. Plain text search inside the record, on this machine. Case-insensitive substring over every
 // record file, the imports, and the ledger. Returns each matching line with its path and number.
-export function search(evda, args = {}) {
+export function search(evda, args = {}, { caller = callerFrom() } = {}) {
   onlyKeys("evda_search", args, ["query", "limit"]);
   if (typeof args.query !== "string" || args.query.trim() === "") throw new EvdaError('evda_search needs "query".', { code: "BAD_ARGUMENT", exit: 2 });
   const limit = args.limit === undefined ? 50 : Number(args.limit);
@@ -195,14 +232,68 @@ export function search(evda, args = {}) {
   if (ledger.mapped && ledger.fileExists) files.push(ledger.file);
   const matches = [];
   let more = 0;
+  const ctx = readContext(evda);
+  const refused = [];
+  // Whether any searched file is sealed or holds a sealed section, decided without the query, so
+  // the answer to a search whose only hit is sealed is the answer to one that hit nothing.
+  let sealed = false;
   for (const abs of files) {
-    readFileSync(abs, "utf8").split("\n").forEach((line, i) => {
+    const raw = readFileSync(abs, "utf8");
+    const may = mayRead(ctx, abs, caller);
+    if (!may.ok && may.kind === "sealed") { sealed = true; continue; }
+    if (!may.ok) {
+      // Only a held-back file that would have matched is named, and never the line it matched on.
+      // Matched on what the AI could be shown, so a hit inside a sealed section names nothing.
+      if (aiView(raw).text.toLowerCase().includes(needle)) refused.push(may);
+      continue;
+    }
+    const shown = aiView(raw);
+    if (shown.sections) sealed = true;
+    const body = shown.text;
+    body.split("\n").forEach((line, i) => {
       if (!line.toLowerCase().includes(needle)) return;
       if (matches.length >= limit) { more += 1; return; }
       matches.push({ path: rel(evda, abs), line: i + 1, text: line.length > 400 ? `${line.slice(0, 400)}...` : line });
     });
   }
-  return { query: args.query, searched: files.length, matches, more };
+  return { query: args.query, searched: files.length, matches, more, refused, heldBack: heldBack(refused, { sealed }) };
+}
+
+// 5a. One file of the record, whole, when the caller may read it; a refusal that says why when not.
+export function readFile(evda, args = {}, { caller = callerFrom() } = {}) {
+  onlyKeys("evda_read", args, ["path"]);
+  if (typeof args.path !== "string" || args.path.trim() === "") throw new EvdaError('evda_read needs "path", a file in the record.', { code: "BAD_ARGUMENT", exit: 2 });
+  const abs = resolve(evda.dir, args.path.trim());
+  if (!abs.startsWith(evda.dir + sep)) throw new EvdaError(`REFUSED: ${args.path} is outside the record.`, { code: "OUTSIDE", exit: 2 });
+  if (!existsSync(abs) || !statSync(abs).isFile()) throw new EvdaError(`Nothing is at ${args.path} in the record.`, { code: "MISSING", exit: 2 });
+  const may = mayRead(readContext(evda), abs, caller);
+  if (!may.ok) throw new EvdaError(`REFUSED: ${may.why}`, { code: may.kind === "sealed" ? "SEALED" : may.kind === "noted" ? "NOTED" : "NOT_THIS_READER", exit: 2 });
+  const text = aiView(readFileSync(abs, "utf8")).text;
+  if (text.length > MAX_READ) return { path: rel(evda, abs), text: text.slice(0, MAX_READ), truncated: true };
+  return { path: rel(evda, abs), text, truncated: false };
+}
+
+// 5b. "Just note this": the owner's words, verbatim, as a noted capture no AI reads. Refuses
+// anything secret-shaped, like every other write.
+export function noteTool(evda, args = {}, { now = new Date() } = {}) {
+  onlyKeys("evda_note", args, ["words"], "It writes one new noted capture and nothing else.");
+  const words = text(args.words, "words", "evda_note");
+  refuseSecrets(words, "evda_note");
+  return writeNote(evda, words, { now });
+}
+
+// 5c. "You can read that now": clear the flag on one noted entry. Only on the owner's yes in this
+// conversation, and only the flag: the words are not changed. The one tool that edits a file, and
+// it edits one frontmatter line.
+export function releaseTool(evda, args = {}, { now = new Date() } = {}) {
+  onlyKeys("evda_release_note", args, ["path", "confirmed"]);
+  // Sealed is not noted: no tool releases it, whatever was said. Unsealing is the owner's own edit.
+  if (typeof args.path === "string" && args.path.trim() !== "") {
+    const abs = resolve(evda.dir, args.path.trim());
+    if (existsSync(abs) && isSealed(abs)) throw new EvdaError(`REFUSED: ${args.path} is sealed: only its owner opens it, on their own devices, and no tool releases it. Unsealing is the owner editing the file themselves. Nothing was changed.`, { code: "SEALED", exit: 2 });
+  }
+  if (args.confirmed !== true) throw new EvdaError("REFUSED: evda_release_note needs confirmed: true, which means the owner said in this conversation that this entry can be read now. Ask them which one, and wait. Nothing was changed.", { code: "UNCONFIRMED", exit: 2 });
+  return releaseNote(evda, args.path, { now });
 }
 
 // 6. Circles and their policies, as the record declares them. Read only.

package/lib/update-check.mjs

@@ -0,0 +1,146 @@
+// Update-check hygiene (HQ-1242), from the three gstack rules the plan doc names for this
+// package (01_Projects/Evda/Evda/2026-09-15 - What EVDA Takes From gstack.md, section
+// "5. Update-check hygiene"):
+//
+//   1. A crash must not read as up to date. Any network or parse failure returns
+//      status: "CHECK_FAILED" with the reason attached, never a silent "you're current."
+//   2. The check is throttled and snoozable: at most once per THROTTLE_MS (one hour, per the
+//      plan doc's "throttled to once an hour," not gstack's escalating 24h/48h/7d scheme).
+//   3. Nothing destructive runs from here. This module only reads the registry and this
+//      record's own state file; it never writes AGENTS.md, never runs a migration.
+//
+// `.evda/package-version` (not `.evda/version`, which is the unrelated SCHEMA_VERSION marker
+// lib/manifest.mjs owns) records which npm version last replaced the AGENTS.md fence via
+// `evda upgrade`. `.evda/update-check.json` records when this module last asked the registry,
+// so re-running `evda check-update` inside the same hour is a local read, not a network call.
+
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from "node:fs";
+import { join, dirname } from "node:path";
+
+export const THROTTLE_MS = 60 * 60 * 1000; // one hour, per the plan doc
+const REGISTRY_URL = "https://registry.npmjs.org/create-evda/latest";
+const FETCH_TIMEOUT_MS = 5000;
+
+function stateFile(dir) {
+  return join(dir, ".evda", "update-check.json");
+}
+
+function packageVersionFile(dir) {
+  return join(dir, ".evda", "package-version");
+}
+
+function readJsonSafe(path) {
+  try {
+    return JSON.parse(readFileSync(path, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+// What this record's own AGENTS.md fence was last generated from. Absent means `evda upgrade`
+// has never stamped it (an install predating this feature, or a record adopted by hand); that
+// is reported as its own status rather than guessed at.
+export function installedVersion(dir) {
+  try {
+    return readFileSync(packageVersionFile(dir), "utf8").trim();
+  } catch {
+    return null;
+  }
+}
+
+export function stampInstalledVersion(dir, version) {
+  const f = packageVersionFile(dir);
+  mkdirSync(dirname(f), { recursive: true });
+  writeFileSync(f, version + "\n");
+}
+
+// Fetches the registry's `latest` dist-tag. Never throws: every failure mode (network, timeout,
+// a non-200, a body with no `version` field) becomes a returned CHECK_FAILED result, because a
+// thrown error from inside a session preamble is worse than a stale-looking check.
+async function fetchLatest() {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
+  try {
+    const res = await fetch(REGISTRY_URL, { signal: controller.signal });
+    if (!res.ok) {
+      return { ok: false, reason: `registry returned HTTP ${res.status}` };
+    }
+    const body = await res.json();
+    if (typeof body?.version !== "string" || !body.version) {
+      return { ok: false, reason: "registry response had no version field" };
+    }
+    return { ok: true, version: body.version };
+  } catch (err) {
+    return { ok: false, reason: err?.name === "AbortError" ? `timed out after ${FETCH_TIMEOUT_MS}ms` : String(err?.message ?? err) };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+function higherVersion(a, b) {
+  const pa = a.split(".").map(Number);
+  const pb = b.split(".").map(Number);
+  for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+    const da = pa[i] ?? 0, db = pb[i] ?? 0;
+    if (da !== db) return da > db ? a : b;
+  }
+  return 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().
+//
+// Returns one of:
+//   { status: "SKIPPED_THROTTLED", checkedAt: <ms of the last real check> }
+//   { status: "CHECK_FAILED", reason: "..." }
+//   { status: "UP_TO_DATE", installed, latest }
+//   { status: "UPDATE_AVAILABLE", installed, latest }
+//   { status: "UNSTAMPED", latest }   -- this record predates package-version stamping
+export async function checkForUpdate(dir, { now = Date.now(), force = false } = {}) {
+  const sf = stateFile(dir);
+  const state = readJsonSafe(sf);
+
+  if (!force && state?.lastCheckedAt && now - state.lastCheckedAt < THROTTLE_MS) {
+    return { status: "SKIPPED_THROTTLED", checkedAt: state.lastCheckedAt };
+  }
+
+  const fetched = await fetchLatest();
+
+  // Record the attempt either way: a failure that never updates lastCheckedAt would retry every
+  // single session until the registry recovers, defeating the throttle's whole purpose. The
+  // failure itself is still returned to the caller, never swallowed into a false pass.
+  mkdirSync(dirname(sf), { recursive: true });
+  writeFileSync(sf, JSON.stringify({ lastCheckedAt: now, lastResult: fetched.ok ? fetched.version : `CHECK_FAILED: ${fetched.reason}` }, null, 2) + "\n");
+
+  if (!fetched.ok) {
+    return { status: "CHECK_FAILED", reason: fetched.reason };
+  }
+
+  const installed = installedVersion(dir);
+  if (!installed) {
+    return { status: "UNSTAMPED", latest: fetched.version };
+  }
+
+  const newer = higherVersion(installed, fetched.version) === fetched.version && installed !== fetched.version;
+  return newer
+    ? { status: "UPDATE_AVAILABLE", installed, latest: fetched.version }
+    : { status: "UP_TO_DATE", installed, latest: fetched.version };
+}
+
+// One line, for the preamble and for `evda check-update`'s own stdout. Never throws.
+export function summarize(result) {
+  switch (result.status) {
+    case "SKIPPED_THROTTLED":
+      return `update check: skipped, checked within the last hour (${new Date(result.checkedAt).toISOString()})`;
+    case "CHECK_FAILED":
+      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 "UP_TO_DATE":
+      return `update check: up to date (${result.installed})`;
+    case "UPDATE_AVAILABLE":
+      return `update check: ${result.installed} -> ${result.latest} available. Run "npx -y -p create-evda@latest evda update" to take it.`;
+    default:
+      return `update check: CHECK_FAILED, update status UNKNOWN (unrecognized result shape)`;
+  }
+}