create-evda 0.1.10 → 0.1.12

package/lib/circles.mjs

@@ -74,6 +74,7 @@ import { resolveRole } from "./roles.mjs";
 import { boundaries, insideAny } from "./records.mjs";
 import { parseYaml, toYaml } from "./yaml.mjs";
 import { EvdaError } from "./errors.mjs";
+import { outsideRecord } from "./record-walk.mjs";
 
 export const ECO_SCHEMA_VERSION = "0.1";
 // atlas-arch:yaml-encoding: the eco manifest is a config file the substrate names by its suffix, not an entity key
@@ -544,13 +545,14 @@ export function frontmatterOf(text) {
   }
 }
 
-// Every markdown file under the record root, skipping dot-directories and node_modules. The mark
+// Every markdown file under the record root, skipping dot-directories and what outsideRecord names
+// (node_modules, any *.nosync). The mark
 // walk reads the whole record, not only the record roles: a released fact may live anywhere.
 export function markdownFiles(root) {
   const out = [];
   const walk = (abs) => {
     for (const name of readdirSync(abs).sort()) {
-      if (name.startsWith(".") || name === "node_modules") continue;
+      if (name.startsWith(".") || outsideRecord(name)) continue;
       const p = join(abs, name);
       // A dangling symlink (target lives only on another machine, e.g. raw media kept
       // outside the synced vault) has nothing to stat. It is not markdown content either

package/lib/connect.mjs

@@ -34,50 +34,114 @@ export function serverCommand(recordDir, { execPath = process.execPath, bin = jo
   return { command: stableNode(execPath, env), args: [real, "mcp", dir] };
 }
 
-// The command Claude Code runs for the read guard (lib/guard.mjs), by the same rule as the server:
-// absolute paths when the package is installed somewhere stable, the npx form from an npx cache.
-export function guardCommand({ execPath = process.execPath, hook = join(PACKAGE_ROOT, "hooks", "evda-read-guard.mjs"), env = process.env } = {}) {
-  let real = hook;
-  try { real = realpathSync(hook); } catch { /* not on disk yet, as in a test */ }
-  const q = (s) => (/^[A-Za-z0-9_./:@=+-]+$/.test(s) ? s : `'${String(s).replace(/'/g, "'\\''")}'`);
-  if (/[\\/]_npx[\\/]/.test(real)) return "npx -y -p create-evda@latest evda guard";
-  return `${q(stableNode(execPath, env))} ${q(real)}`;
+// The read guard (lib/guard.mjs) runs from a copy inside the record, like the keep-record and prompt
+// hooks (lib/hooks.mjs), never from the package that installed it (HQ-2819). An absolute path into
+// the installer dies with it: the npx cache npm clears, a checkout or worktree that is removed. The
+// npx form (`npx -y -p create-evda@latest evda guard`) outlives the installer but asks the registry
+// before every Read, and an offline laptop then runs no guard, so it is not written either. The copy
+// is the entry point plus every lib/ file it imports, found by walking the imports at install time,
+// so a new import in lib/guard.mjs is copied without anyone listing it.
+export const GUARD_DIR_REL = ".claude/hooks/evda-guard";
+export const GUARD_REL = `${GUARD_DIR_REL}/evda-read-guard.mjs`;
+export const GUARD_COMMAND = `node "$CLAUDE_PROJECT_DIR/${GUARD_REL}"`;
+export const GUARD_MATCHER = "Read|Grep|Bash|NotebookRead";
+const SHIPPED_GUARD = join(PACKAGE_ROOT, "hooks", "evda-read-guard.mjs");
+const LIB_DIR = join(PACKAGE_ROOT, "lib");
+
+// Every file the record's copy of the guard holds, as [path in the record, bytes]. The entry point
+// is the shipped one with its one import pointed at the lib/ copied beside it; the lib files are
+// byte for byte. Throws if the shipped entry no longer imports ../lib/guard.mjs, so a change there
+// cannot install a copy that fails at load.
+export function guardFiles() {
+  const entry = readFileSync(SHIPPED_GUARD, "utf8");
+  const IMPORT = 'from "../lib/guard.mjs"';
+  if (!entry.includes(IMPORT)) throw new Error(`${SHIPPED_GUARD} no longer imports ../lib/guard.mjs, so the guard copy cannot be built`);
+  const files = [[GUARD_REL, Buffer.from(entry.replace(IMPORT, 'from "./lib/guard.mjs"'))]];
+  const seen = new Set();
+  const walk = (name) => {
+    if (seen.has(name)) return;
+    seen.add(name);
+    const bytes = readFileSync(join(LIB_DIR, name));
+    files.push([`${GUARD_DIR_REL}/lib/${name}`, bytes]);
+    for (const m of bytes.toString("utf8").matchAll(/\bfrom\s*["']\.\/([^"']+)["']|\bimport\s*\(?\s*["']\.\/([^"']+)["']/g)) walk(m[1] ?? m[2]);
+  };
+  walk("guard.mjs");
+  return files;
 }
 
-// Install the read guard into one record's .claude/settings.json, for Claude Code sessions opened
-// in that folder. Merges into a settings file that is already there: an existing PreToolUse entry
-// with the same command is left alone, and nothing else in the file is touched.
-export function installGuard(recordDir, { command = guardCommand() } = {}) {
-  const path = join(resolve(recordDir), ".claude", "settings.json");
+// The settings commands that run the guard, in any form an installer ever wrote: this copy, an
+// absolute path to some package's hooks/evda-read-guard.mjs, or the npx form.
+export const GUARD_MARK = /evda-read-guard\.mjs|\bevda guard\b/;
+const isGuard = (h) => typeof h?.command === "string" && GUARD_MARK.test(h.command);
+
+// Install the read guard into one record: copy its files into .claude/hooks/evda-guard/ and make
+// .claude/settings.json run that copy. Every guard entry already there (a stale absolute path, the
+// npx form, a duplicate from a second install) is removed, so exactly one remains. Nothing else in
+// the settings file is touched, and a file that already says exactly this is not rewritten.
+export function installGuard(recordDir) {
+  const dir = resolve(recordDir);
+  const path = join(dir, ".claude", "settings.json");
   let settings = {};
   if (existsSync(path)) {
     try { settings = JSON.parse(readFileSync(path, "utf8")); } catch { return { path, action: "left alone (not valid JSON):" }; }
+    if (settings === null || typeof settings !== "object" || Array.isArray(settings)) return { path, action: "left alone (not a JSON object):" };
+  }
+  let copied = false;
+  for (const [rel, bytes] of guardFiles()) {
+    const abs = join(dir, rel);
+    if (existsSync(abs) && readFileSync(abs).equals(bytes)) continue;
+    mkdirSync(dirname(abs), { recursive: true });
+    writeFileSync(abs, bytes);
+    copied = true;
   }
-  const pre = (settings.hooks ??= {}).PreToolUse ??= [];
-  if (pre.some((m) => (m.hooks ?? []).some((h) => h.command === command))) return { path, action: "already installed:" };
-  pre.push({ matcher: "Read|Grep|Bash|NotebookRead", hooks: [{ type: "command", command }] });
+  const pre = Array.isArray(settings.hooks?.PreToolUse) ? settings.hooks.PreToolUse : [];
+  const found = pre.flatMap((m) => (Array.isArray(m?.hooks) ? m.hooks : []).filter(isGuard).map((h) => h.command));
+  if (found.length === 1 && found[0] === GUARD_COMMAND) return { path, action: copied ? "updated the guard copy:" : "already installed:" };
+  const kept = pre
+    .map((m) => (Array.isArray(m?.hooks) && m.hooks.some(isGuard) ? { ...m, hooks: m.hooks.filter((h) => !isGuard(h)) } : m))
+    .filter((m) => !Array.isArray(m?.hooks) || m.hooks.length);
+  kept.push({ matcher: GUARD_MATCHER, hooks: [{ type: "command", command: GUARD_COMMAND }] });
+  if (settings.hooks === null || typeof settings.hooks !== "object" || Array.isArray(settings.hooks)) settings.hooks = {};
+  settings.hooks.PreToolUse = kept;
   mkdirSync(dirname(path), { recursive: true });
   writeFileSync(path, JSON.stringify(settings, null, 2) + "\n");
-  return { path, action: "installed" };
+  return { path, action: found.length ? `replaced ${found.length} older guard ${found.length === 1 ? "entry" : "entries"}:` : "installed" };
 }
 
-// Whether one record's .claude/settings.json runs the read guard, for doctor (HQ-1377):
-// { registered, target, file, problem }. `target` is the hook file the command names, `file` whether
-// it is on disk; the npx form names no file and is present whenever it is registered. Never throws.
-export const GUARD_MARK = /evda-read-guard\.mjs|\bevda guard\b/;
+// The hook file one guard command runs, resolved against the record ($CLAUDE_PROJECT_DIR is the
+// record, since the guard is registered in the record's own settings). Null for the npx form.
+export function guardTarget(command, recordDir) {
+  const dir = resolve(recordDir);
+  const m = /"([^"]*evda-read-guard\.mjs)"|'([^']*evda-read-guard\.mjs)'|(\S*evda-read-guard\.mjs)/.exec(command);
+  if (!m) return null;
+  return resolve(dir, (m[1] ?? m[2] ?? m[3]).replace(/\$\{CLAUDE_PROJECT_DIR\}|\$CLAUDE_PROJECT_DIR/g, () => dir));
+}
+
+// Whether one record's .claude/settings.json runs the read guard, for doctor (HQ-1377, HQ-2819):
+// { registered, target, file, missing, count, current, problem }. `target` is the hook file the
+// first entry names, `missing` every registered file not on disk (`file` is true when there is
+// none), `count` how many guard entries there are, `current` whether the record's copy matches what
+// ships. The npx form names no file and is present whenever it is registered. Never throws.
 // EVDA_HOOKS_FALSIFY=blind reports no guard at all, for the test that shows doctor's line is read
 // from the settings file.
 export function guardStatus(recordDir) {
-  if ((process.env.EVDA_HOOKS_FALSIFY ?? "").split(",").map((x) => x.trim()).includes("blind")) return { registered: false, target: null, file: false, problem: null };
-  const path = join(resolve(recordDir), ".claude", "settings.json");
-  if (!existsSync(path)) return { registered: false, target: null, file: false, problem: null };
+  const none = { registered: false, target: null, file: false, missing: [], count: 0, current: false, problem: null };
+  if ((process.env.EVDA_HOOKS_FALSIFY ?? "").split(",").map((x) => x.trim()).includes("blind")) return none;
+  const dir = resolve(recordDir);
+  const path = join(dir, ".claude", "settings.json");
+  if (!existsSync(path)) return none;
   let settings;
-  try { settings = JSON.parse(readFileSync(path, "utf8")); } catch (e) { return { registered: false, target: null, file: false, problem: `.claude/settings.json is not valid JSON (${e.message}), so no hook in it runs.` }; }
-  const commands = (settings?.hooks?.PreToolUse ?? []).flatMap((m) => (m?.hooks ?? []).map((h) => h?.command)).filter((c) => typeof c === "string" && GUARD_MARK.test(c));
-  if (!commands.length) return { registered: false, target: null, file: false, problem: null };
-  const m = /'([^']*evda-read-guard\.mjs)'|(\S*evda-read-guard\.mjs)/.exec(commands[0]);
-  const target = m ? (m[1] ?? m[2]) : null;
-  return { registered: true, target, file: target === null || existsSync(target), problem: null };
+  try { settings = JSON.parse(readFileSync(path, "utf8")); } catch (e) { return { ...none, problem: `.claude/settings.json is not valid JSON (${e.message}), so no hook in it runs.` }; }
+  const pre = settings?.hooks?.PreToolUse;
+  const commands = (Array.isArray(pre) ? pre : []).flatMap((m) => (Array.isArray(m?.hooks) ? m.hooks : []).filter(isGuard).map((h) => h.command));
+  if (!commands.length) return none;
+  const targets = commands.map((c) => guardTarget(c, dir));
+  const missing = targets.filter((t) => t !== null && !existsSync(t));
+  let current = true;
+  if (targets.includes(join(dir, GUARD_REL))) {
+    try { current = guardFiles().every(([rel, bytes]) => existsSync(join(dir, rel)) && readFileSync(join(dir, rel)).equals(bytes)); } catch { current = false; }
+  }
+  return { registered: true, target: targets[0], file: missing.length === 0, missing, count: commands.length, current, problem: null };
 }
 
 // A `node` on PATH that is this same binary, when there is one: Homebrew's /opt/homebrew/bin/node

package/lib/conversation.mjs

@@ -0,0 +1,68 @@
+// A conversation's section state kept between separate evda_write calls (HQ-2823).
+//
+// appendToDay (lib/day-file.mjs) keeps one conversation in one section through a `session` object,
+// and an MCP process holds that object in memory. A relay that spawns a fresh `evda mcp` for every
+// message (Hestia's evda-tool.mjs, which the prompt hook on a non-writer laptop sends through) has
+// no memory between calls, so on 2026-10-22 every message the owner sent from his laptop opened
+// its own `## HH:MM`. A caller that names its conversation (evda_write's `conversation`) gets the
+// section state loaded from and saved to one small file here instead.
+//
+// Where: EVDA_CONVERSATION_DIR, default ~/.evda/conversations: outside the record and outside any
+// synced folder, the way the prompt outbox is (lib/prompt-hook.mjs promptOutboxDir). What: the
+// `sections` appendToDay keeps, which hold the section's own text so the next write can find it.
+// That is the owner's words outside the record, so the folder is the owner's alone (0700) and a
+// file not written for CONVERSATION_KEEP_MS is deleted on the next save. A section lives in one
+// day's file, so a conversation older than that has nothing left to continue. Age is the
+// `savedAt` written inside each file by the same clock that judges it, never the file's mtime:
+// a clock the OS does not share (a shifted test clock, a restored backup) would otherwise read a
+// file saved a moment ago as old and delete a live conversation.
+
+import { mkdirSync, readdirSync, readFileSync, renameSync, statSync, unlinkSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import { isConversationId } from "./day-file.mjs";
+
+export const CONVERSATION_DIR_ENV = "EVDA_CONVERSATION_DIR";
+export const CONVERSATION_KEEP_MS = 2 * 24 * 60 * 60 * 1000;
+
+export function conversationDir(env = process.env) {
+  return env[CONVERSATION_DIR_ENV] || join(homedir(), ".evda", "conversations");
+}
+
+const fileOf = (id, env) => join(conversationDir(env), `${id}.json`);
+
+// The session object appendToDay takes for conversation `id`: { sections } as last saved, or {}.
+export function loadConversation(id, { env = process.env } = {}) {
+  if (!isConversationId(id)) throw new Error(`not a conversation id: ${JSON.stringify(id)}`);
+  try {
+    const s = JSON.parse(readFileSync(fileOf(id, env), "utf8"));
+    return s && typeof s.sections === "object" && s.sections ? { sections: s.sections } : {};
+  } catch { return {}; }
+}
+
+// Save it (written whole, then renamed into place, so a reader never sees half a file), and delete
+// every conversation not saved for CONVERSATION_KEEP_MS.
+export function saveConversation(id, session, { env = process.env, nowMs = Date.now() } = {}) {
+  if (!isConversationId(id)) throw new Error(`not a conversation id: ${JSON.stringify(id)}`);
+  const dir = conversationDir(env);
+  mkdirSync(dir, { recursive: true, mode: 0o700 });
+  const abs = fileOf(id, env);
+  const part = `${abs}.${process.pid}.part`;
+  writeFileSync(part, JSON.stringify({ sections: session.sections ?? {}, savedAt: nowMs }) + "\n", { mode: 0o600 });
+  renameSync(part, abs);
+  for (const n of readdirSync(dir)) {
+    const f = join(dir, n);
+    if (f === abs) continue;
+    try { if (nowMs - savedAtOf(f) > CONVERSATION_KEEP_MS) unlinkSync(f); } catch { /* gone already */ }
+  }
+}
+
+// When `f` was saved: its own savedAt, or its mtime for a file written without one (a leftover
+// .part, a file from before savedAt existed).
+function savedAtOf(f) {
+  try {
+    const t = JSON.parse(readFileSync(f, "utf8")).savedAt;
+    if (Number.isFinite(t)) return t;
+  } catch { /* not a whole conversation file */ }
+  return statSync(f).mtimeMs;
+}

package/lib/corrections.mjs

@@ -8,9 +8,11 @@
 // every correction from a chat app was refused and lost. Doctor reads the same setting through this
 // one function, so the tool and the check cannot disagree on what a valid setting is.
 
-import { existsSync, statSync } from "node:fs";
-import { isAbsolute, relative, resolve, sep } from "node:path";
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { basename, dirname, isAbsolute, relative, resolve, sep } from "node:path";
 import { isSealed } from "./circles.mjs";
+import { readContext, mayRead, aiView } from "./readers.mjs";
+import { datalessAmong } from "./sync-rules.mjs";
 
 export const CORRECTIONS_KEY = "corrections";
 
@@ -32,3 +34,76 @@ export function correctionsTarget(evda) {
   if (isSealed(abs)) return { rel, abs, problem: `"${CORRECTIONS_KEY}" names ${rel}, which is sealed, so no agent writes a correction into it.` };
   return { rel, abs, problem: null };
 }
+
+// What the owner taught the agent, served in the operating layer (HQ-2818). A chat app learns who
+// it is only from evda_operating_layer, so a correction written to a separate corrections file was
+// recorded and never read back on any chat surface. The layer now carries the newest entries, the
+// same selection on every surface, so a correction made in one app reaches the next chat in any.
+//
+// The size is fixed, not the whole file: his file measured 671,346 characters and 445 sections on
+// 2026-10-22, ten times a chat's whole budget. Entries are the file's `## ` sections in file order
+// (evda_record_correction appends, so the last is the newest); the newest are kept whole while they
+// fit, and the block says how many older ones the file holds and how to find one.
+export const CORRECTIONS_LAYER_MAX = 8_000;
+export const TAUGHT_HEADING = "What I have been taught";
+
+// A corrections file's entries: its `## ` sections, in file order. The text before the first one is
+// the file's own preamble, not an entry.
+export function fileEntries(text) {
+  return text.split(/^(?=## )/m).filter((sec) => sec.startsWith("## ")).map((sec) => sec.replace(/\s+$/, ""));
+}
+
+// The "What I have been taught" section's entries: its `- ` lines, each with any lines under it.
+export function sectionEntries(sec) {
+  const body = sec.split("\n").slice(1).join("\n");
+  return body.split(/^(?=- )/m).filter((e) => e.startsWith("- ")).map((e) => e.replace(/\s+$/, ""));
+}
+
+// The newest entries that fit in `max` characters joined by blank lines, oldest of them first.
+// When even the newest is longer, it is cut at a line and says where the rest is.
+export function newestEntries(entries, max, where) {
+  const kept = [];
+  let size = 0;
+  for (let i = entries.length - 1; i >= 0; i--) {
+    const grow = entries[i].length + (kept.length ? 2 : 0);
+    if (size + grow > max) break;
+    kept.unshift(entries[i]);
+    size += grow;
+  }
+  if (!kept.length && entries.length) {
+    const tail = `\n(This entry is cut here; it continues in ${where}.)`;
+    const e = entries[entries.length - 1];
+    let cut = e.slice(0, Math.max(0, max - tail.length));
+    const at = cut.lastIndexOf("\n");
+    if (at > 0) cut = cut.slice(0, at);
+    return { kept: [cut + tail], older: entries.length - 1 };
+  }
+  return { kept, older: entries.length - kept.length };
+}
+
+function block(path, entries, max) {
+  if (!entries.length) return null;
+  const { kept, older } = newestEntries(entries, max, path);
+  const more = older ? ` ${older} older ${older === 1 ? "entry is" : "entries are"} in ${path}; evda_search finds one by its words.` : "";
+  const head = `## ${TAUGHT_HEADING} (from ${path})\n\nWhat the owner corrected you on, newest last, word for word as ${path} keeps it: how they want you to work, learned from real misses.${more}`;
+  return { text: `${head}\n\n${kept.join("\n\n")}\n`, path, served: kept.length, total: entries.length };
+}
+
+// The corrections block for the layer, or null when there is nothing to add. `caller` is who reads
+// the layer: a file this caller may not read (sealed, noted, or a read_by that is not theirs) is not
+// served, by the same mayRead every read tool uses, and a sealed section inside it is never shown.
+// A file still in the cloud is not read, since reading it would start a download.
+//
+// With no "corrections" setting the entries live in AGENTS.md's own section, which the layer already
+// serves, so nothing is added; `taughtListed` is that section's text when a chat's budget listed it
+// by heading instead, and then its newest lines are served here so they still reach the chat.
+export function correctionsForLayer(evda, caller, { max = CORRECTIONS_LAYER_MAX, taughtListed = null, agentsPath = "AGENTS.md" } = {}) {
+  const target = correctionsTarget(evda);
+  if (!target) return taughtListed ? block(agentsPath, sectionEntries(taughtListed), max) : null;
+  if (target.problem) return null;
+  if (!mayRead(readContext(evda), target.abs, caller).ok) return null;
+  if (datalessAmong(dirname(target.abs), [basename(target.abs)]).size) return null;
+  let raw;
+  try { raw = readFileSync(target.abs, "utf8"); } catch { return null; }
+  return block(target.rel, fileEntries(aiView(raw).text), max);
+}

package/lib/day-file.mjs

@@ -61,6 +61,13 @@ 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())}`;
 
+// A conversation id a caller names so that separate evda_write calls continue one section (HQ-2823):
+// the prompt hook sends Claude Code's session_id. Short and opaque, letters, digits, `_` and `-`
+// only, because the writer names a state file after it. Checked here so the hook and evda_write
+// read one rule.
+export const CONVERSATION_MAX = 128;
+export const isConversationId = (v) => typeof v === "string" && v.length <= CONVERSATION_MAX && /^[A-Za-z0-9_-]+$/.test(v);
+
 export const contextLine = (context) => `*${CONTEXT_LABEL} ${String(context).trim().replace(/\*/g, "")}*`;
 
 // NAMED ENTRIES (HQ-2799). A write tool's answer names the existing entries the filed words bear on

package/lib/day-writer.mjs

@@ -17,12 +17,14 @@
 //
 // It refuses Write, Edit, MultiEdit and NotebookEdit of a file directly in the daily folder, and a
 // shell command that names such a file next to a write-shaped operator (>, >>, tee, sed -i, cp, mv,
-// rm and the rest). Like the read guard, it stops a cooperating agent on the ordinary paths; a
+// rm and the rest), after expanding the variables the command itself sets, $HOME and ~ (HQ-2817).
+// Like the read guard, it stops a cooperating agent on the ordinary paths; a
 // command built to hide its target gets past it. Anything it cannot parse is allowed.
 //
 //   EVDA_DAY_WRITER_FALSIFY=allow-all   every decision is allow, so the tests can be watched failing
 
 import { realpathSync } from "node:fs";
+import { homedir } from "node:os";
 import { basename, dirname, isAbsolute, join, resolve } from "node:path";
 import { openEvda } from "./manifest.mjs";
 import { dayRole, findRecord } from "./day-file.mjs";
@@ -35,9 +37,34 @@ export const DAY_WRITER_ENV = "EVDA_DAY_WRITER";
 const WRITERS = /((^|[\s;&|(`])(tee|cp|mv|rm|truncate|touch|install|ln|dd|ed|ex)(\s|$)|\b(sed|perl|ruby)\s+(-[A-Za-z]*\s+)*-[A-Za-z]*i)/;
 const REDIRECT = />>?\|?\s*("[^"]*"|'[^']*'|[^\s;&|<>()`]+)/g;
 
+// HQ-2817: a command that names the day file through a variable it set itself got past the guard
+// (2026-10-22: `V="<vault>"; ... cat >> "$V/06_Metadata/Daily Journal/<date>.md"`). This expands,
+// in order, every `NAME=value` the command assigns (bare, `export`, quoted or not) and then every
+// `$NAME` / `${NAME}` it names, plus `$HOME` and a leading `~`. A variable the command neither sets
+// nor HOME supplies is left as written. It is not a shell: a value built by `$(...)` stays unexpanded.
+const ASSIGN = /(^|[\s;&|(`]|\bexport\s+)([A-Za-z_][A-Za-z0-9_]*)=("([^"]*)"|'([^']*)'|[^\s;&|<>()`]*)/g;
+export function expandShellVars(command, { env = process.env } = {}) {
+  const vars = { HOME: env.HOME || homedir() };
+  const sub = (s) => s.replace(/\$\{([A-Za-z_][A-Za-z0-9_]*)\}|\$([A-Za-z_][A-Za-z0-9_]*)/g, (m, a, b) => (vars[a ?? b] ?? m));
+  const tilde = (s) => s.replace(/(^|[\s;&|(`=>"'])~(?=\/|[\s"';&|)]|$)/g, (m, lead) => `${lead}${vars.HOME}`);
+  let out = "";
+  let last = 0;
+  for (const m of String(command).matchAll(ASSIGN)) {
+    out += sub(tilde(String(command).slice(last, m.index)));
+    const raw = m[4] ?? m[5] ?? m[3];
+    const next = String(command)[m.index + m[0].length] ?? "";
+    // A value the shell computes (`$(...)`, backticks) is not known here: the name stays unexpanded.
+    if (/[$`]/.test(raw.replace(/\$\{?[A-Za-z_][A-Za-z0-9_]*\}?/g, "")) || next === "(" || next === "`") delete vars[m[2]];
+    else vars[m[2]] = m[5] !== undefined ? raw : sub(tilde(raw));
+    out += m[0].slice(0, m[0].length - m[3].length) + (m[5] !== undefined ? m[3] : sub(tilde(m[3])));
+    last = m.index + m[0].length;
+  }
+  return out + sub(tilde(String(command).slice(last)));
+}
+
 // The paths a shell command may write: every path when a writing command runs, else redirect targets.
-export function shellWriteTargets(command) {
-  const c = String(command);
+export function shellWriteTargets(command, { env = process.env } = {}) {
+  const c = expandShellVars(command, { env });
   if (WRITERS.test(c)) return shellPaths(c);
   return [...c.matchAll(REDIRECT)].map((m) => m[1].replace(/^["']|["']$/g, "")).filter((w) => w && !w.startsWith("&"));
 }
@@ -89,7 +116,7 @@ export function decide(input, { env = process.env } = {}) {
   let paths = [];
   if (FILE_TOOLS.has(tool)) paths = [args.file_path ?? args.notebook_path].filter((p) => typeof p === "string" && p);
   else if (tool === "Bash") {
-    paths = shellWriteTargets(args.command ?? "");
+    paths = shellWriteTargets(args.command ?? "", { env });
   } else return { decision: "allow" };
   const hit = paths.map(at).find(isDayFile);
   if (!hit) return { decision: "allow" };

package/lib/doctor.mjs

@@ -46,8 +46,9 @@
 // the same records print "FAIL  mounts  1 file(s) under the mount root mounts that no held circle
 // covers: mounts/ava.atlas/stray.md" and exit 1.
 
+import { checkoutFreshness } from "./checkout-freshness.mjs";
 import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
-import { join, relative, resolve, sep } from "node:path";
+import { isAbsolute, join, relative, resolve, sep } from "node:path";
 import { readManifest, checkVersion, unknownKeys, unknownLayers, holderOf, holderProblems, KNOWN_LAYERS, SCHEMA_VERSION } from "./manifest.mjs";
 import { readGrants } from "./grants.mjs";
 import { readDevices } from "./devices.mjs";
@@ -76,7 +77,8 @@ import { FILING_MODES, filingOf } from "./day-file.mjs";
 import { correctionsTarget } from "./corrections.mjs";
 import { EVERY_CHAT_KEY } from "./every-chat.mjs";
 import { listSkills, SKILLS_REL } from "./skills.mjs";
-import { guardStatus } from "./connect.mjs";
+import { guardStatus, GUARD_DIR_REL, GUARD_REL } from "./connect.mjs";
+import { readmeCitations, missingHeadings, README_REL } from "./readme.mjs";
 
 // The dated sections of a person-profile that no observation covers (HQ-1397). An observation
 // covers a section when its text is the heading's exactly, or else when it carries the heading's
@@ -99,7 +101,10 @@ export function uncoveredSections(headings, observations) {
 // A suffix after the date is allowed (`2026-01-19 - The Scale Question.md`); no date is not.
 const DAILY_NAME = /^\d{4}-\d{2}-\d{2}(?:[ .-]|$)/;
 
-export function doctor(dir, { out = console.log, via = "argument", depth = 0 } = {}) {
+// `checkout` (HQ-2736): the directory this doctor's code runs from. When given, the doctor says,
+// just before its verdict, whether that checkout is behind origin/main or not on main (see
+// lib/checkout-freshness.mjs). Only the CLI passes it; programmatic callers judge records, not tools.
+export function doctor(dir, { out = console.log, via = "argument", depth = 0, checkout = null } = {}) {
   const failures = [];
   const warnings = [];
   const checked = [];
@@ -254,6 +259,20 @@ export function doctor(dir, { out = console.log, via = "argument", depth = 0 } =
       if (!imports) warn("CLAUDE.md", `does not import ${rel}. Claude Code loads CLAUDE.md and not ${rel}, so a Claude Code session here would start with no operating layer.`);
     }
     ok(1, "operating layer", rel);
+
+    // 5a. README.md sections the operating layer cites (HQ-2812). AGENTS.md gives the training-off
+    // steps, each AI company's terms and the local-model walk-through only from README.md, never from
+    // memory, so a cited section that is not there is the privacy step pointing at nothing: a failure.
+    const cites = readmeCitations(agents);
+    if (!cites.length) skip("README.md sections", `${rel} cites no section of README.md`);
+    else {
+      const readmeAbs = join(dir, README_REL);
+      const readmeText = existsSync(readmeAbs) ? readFileSync(readmeAbs, "utf8") : null;
+      const missing = missingHeadings(readmeText, cites);
+      if (readmeText === null) fail(README_REL, `is missing, and ${rel} sends the agent there for ${cites.map((c) => `"${c}"`).join(", ")}, including the steps for turning training off. \`evda upgrade\` writes it.`);
+      else if (missing.length) fail(README_REL, `has no ${missing.map((c) => `"${c}"`).join(", ")} section, and ${rel} sends the agent there${missing.includes("Turning training off") ? " for the steps that turn training off before anything personal is written" : ""}. \`evda upgrade\` adds EVÐA's block with ${missing.length === 1 ? "it" : "them"} after your text, which it does not change.`);
+      ok(cites.length, "README.md sections", `cited by ${rel}, ${cites.length - (readmeText === null ? cites.length : missing.length)} present`);
+    }
   }
 
   // 5b. the keep-record Stop hook (HQ-1376): whether a Claude Code session opened here is asked to
@@ -295,16 +314,24 @@ export function doctor(dir, { out = console.log, via = "argument", depth = 0 } =
   else if (prompt.registered && !prompt.current) warn(PROMPT_HOOK_REL, "or a file copied beside it differs from what this tooling ships. `evda hook install` updates them.");
   else if (prompt.registered && !everything) warn(SETTINGS_REL, `registers the prompt hook, but evda.json does not say "filing": "everything", so it files nothing.`);
   else if (prompt.registered) ok(1, "prompt hook", `${SETTINGS_REL} runs ${PROMPT_HOOK_REL}, current: each message the owner sends is filed verbatim`);
-  else skip("prompt hook", everything ? `not installed. \`evda hook install\` adds it, and each message the owner sends in Claude Code is filed before the model sees it.` : `installed only for an owner whose evda.json says "filing": "everything".`);
+  // HQ-2817: "everything" with no prompt hook is a promise nothing keeps in Claude Code (his own vault
+  // filed nothing across four messages on 2026-10-22), so it warns. The keep-record Stop hook stays a
+  // skip: it asks once before a quiet stop, and evda.json promises nothing that rests on it alone.
+  else if (everything) warn("evda.json", `says "filing": "everything", and no prompt hook is installed, so a Claude Code session here files the owner's messages only if the model remembers to. \`evda hook install\` adds it to ${SETTINGS_REL}; on a machine that does not write the day it sends each message to the writer (EVDA_DAY_WRITER, EVDA_DAY_WRITER_SEND).`);
+  else skip("prompt hook", `installed only for an owner whose evda.json says "filing": "everything".`);
 
   // 5c. the read guard (HQ-1374), the other hook create-evda installs for a Claude owner (HQ-1377):
   // a PreToolUse hook in the record's own settings that stops a Claude Code session reading a noted
-  // entry. Reported present or missing, like the Stop hook above; a registered guard whose file is
-  // gone warns, because every read then runs a command that is not there.
+  // entry. A registered guard whose file is gone fails (HQ-2819): every read then runs a command
+  // that is not there, Claude Code lets the read through, and the owner was told it is guarded. The
+  // usual cause is an install that pointed into an npx cache or a checkout since removed.
   const guard = guardStatus(dir);
+  const posixRel = (root, abs) => { const r = relative(resolve(root), abs); return r && !r.startsWith("..") && !isAbsolute(r) ? r.split(sep).join("/") : abs; };
   if (guard.problem) warn(SETTINGS_REL, guard.problem);
-  else if (guard.registered && !guard.file) warn(SETTINGS_REL, `registers the read guard, but ${guard.target} is missing, so Claude Code cannot run it and a noted entry is not held back there. \`evda hook install\` restores it.`);
-  else if (guard.registered) ok(1, "read guard", `${SETTINGS_REL} runs ${guard.target ?? "the evda guard through npx"} before Read, Grep and shell reads`);
+  else if (guard.registered && !guard.file) fail(SETTINGS_REL, `registers the read guard, but ${guard.missing.join(" and ")} ${guard.missing.length === 1 ? "is" : "are"} missing, so Claude Code cannot run it and a noted entry is not held back there. \`evda hook install\` copies the guard into ${GUARD_DIR_REL}/ and replaces the entry.`);
+  else if (guard.registered && guard.count > 1) warn(SETTINGS_REL, `registers the read guard ${guard.count} times. \`evda hook install\` leaves one.`);
+  else if (guard.registered && !guard.current) warn(GUARD_REL, "or a file copied beside it differs from what this tooling ships. `evda hook install` updates them.");
+  else if (guard.registered) ok(1, "read guard", `${SETTINGS_REL} runs ${guard.target ? posixRel(dir, guard.target) : "the evda guard through npx"} before Read, Grep and shell reads`);
   else skip("read guard", `not installed. A Claude Code session here is not stopped before reading a just-noted entry (the MCP server still holds it back); \`evda hook install\` adds it to ${SETTINGS_REL}.`);
 
   // 6. record files
@@ -799,6 +826,9 @@ export function doctor(dir, { out = console.log, via = "argument", depth = 0 } =
   return finish(0);
 
   function finish(refusedExit) {
+    // The tool's own freshness, not the record's: printed, never counted as a failure or warning,
+    // so it cannot change the exit, which stays the record's verdict.
+    if (checkout && depth === 0) for (const line of checkoutFreshness(checkout).lines) out(`  CHECKOUT  ${line}`);
     if (refusedExit === 2) {
       out(`REFUSED  nothing was written`);
       return { failures, warnings, checked, exit: 2 };

package/lib/folders.mjs

@@ -25,6 +25,7 @@ import { join, relative, resolve, sep } from "node:path";
 import { resolveAll } from "./roles.mjs";
 import { SCHEMES } from "./references.mjs";
 import { EvdaError } from "./errors.mjs";
+import { outsideRecord } from "./record-walk.mjs";
 
 export const FOLDER_MANIFEST = "folder.evda.json";
 export const FOLDER_TYPES = ["record", "person", "project", "course", "source", "concept", "event", "log", "ticket", "capture", "piece", "blob", "rule", "hypothesis", "message"];
@@ -138,7 +139,7 @@ export function folderManifests(evda) {
     }
     const entries = readdirSync(dir, { withFileTypes: true }).sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
     for (const e of entries) {
-      if (e.name.startsWith(".") || e.name === "node_modules") continue;
+      if (e.name.startsWith(".") || outsideRecord(e.name)) continue;
       if (e.isDirectory()) walk(join(dir, e.name));
     }
   };

package/lib/gather.mjs

@@ -66,6 +66,7 @@ import { EvdaError } from "./errors.mjs";
 import { noteShape, htmlNoteToMarkdown } from "./html-notes.mjs";
 import { pairSidecars } from "./takeout.mjs";
 import { frontmatterOf, heldBy, withoutSealed, carries, NOTED } from "./circles.mjs";
+import { outsideRecord } from "./record-walk.mjs";
 
 export const GATHER_VERSION = 1;
 // The person-layer kinds an item is typed with, and the folder type each lives under.
@@ -219,7 +220,7 @@ const slugId = (s) => s.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-
 // added to its frontmatter, a finished status) no longer hashes like its source; this is how a
 // second gather still knows it.
 export const GATHERED = ".evda/gathered.jsonl";
-const WALK_SKIP = new Set([".git", "node_modules", ".evda", ".obsidian", ".trash", ".DS_Store"]);
+const WALK_SKIP = new Set([".git", ".evda", ".obsidian", ".trash", ".DS_Store"]); // plus outsideRecord
 
 // Every file in the record by the hash of its bytes, and the source hashes it has gathered.
 // Returns { byHash: Map<sha256, rel>, gathered: Map<sha256, rel> }.
@@ -229,7 +230,7 @@ export function presentIndex(dir) {
   if (falsified("reapply-resorts")) return { byHash, gathered };
   const go = (d) => {
     for (const name of readdirSync(d).sort()) {
-      if (WALK_SKIP.has(name)) continue;
+      if (WALK_SKIP.has(name) || outsideRecord(name)) continue;
       const abs = join(d, name);
       const st = lstatSync(abs);
       if (st.isDirectory()) go(abs);
@@ -277,7 +278,7 @@ function walk(root) {
       const abs = join(dir, name);
       const rel = posix(relative(root, abs));
       if (APP_DIRS[name]) apps.add(APP_DIRS[name]);
-      if (SKIP_NAMES.has(name)) { skipped.push({ rel, why: APP_DIRS[name] ? `${APP_DIRS[name]}'s own settings, not the owner's notes` : "app or system state" }); continue; }
+      if (SKIP_NAMES.has(name) || outsideRecord(name)) { skipped.push({ rel, why: APP_DIRS[name] ? `${APP_DIRS[name]}'s own settings, not the owner's notes` : "app or system state" }); continue; }
       const s = lstatSync(abs);
       if (s.isSymbolicLink()) { skipped.push({ rel, why: "a symlink; not followed" }); continue; }
       const junk = s.isDirectory() || s.isFile() ? junkWhy(name, s.size, s.isDirectory()) : null;

package/lib/keep-hook.mjs

@@ -127,7 +127,9 @@ export function classify(e, facts) {
 
 // The decision, pure. `lastBlock` is the event index this hook last blocked at (0 for never).
 // `fileMtime` is the day file's modification time in ms, or null when it does not exist.
-export function decide(evs, facts, { lastBlock = 0, fileMtime = null } = {}) {
+// `nonWriter` (HQ-2817) is the EVDA_DAY_WRITER value on a machine that does not write the day: the
+// block then says evda_write, because a direct write here is the iCloud race and the guard refuses it.
+export function decide(evs, facts, { lastBlock = 0, fileMtime = null, nonWriter = "" } = {}) {
   let lastWrite = 0;
   evs.forEach((e, i) => { if (classify(e, facts) === "write") lastWrite = i + 1; });
   const start = Math.max(lastWrite, lastBlock);
@@ -145,7 +147,9 @@ export function decide(evs, facts, { lastBlock = 0, fileMtime = null } = {}) {
   const why = reads && words >= OWNER_WORDS ? "read the record and the owner talked" : reads ? "read the record" : "the owner talked";
   const reason = [
     `evda: this conversation ${why}, and nothing from it is in today's record (${tools} tool call(s), ${writes} write(s), none to ${facts.fileRel}).`,
-    `Before you stop, file what the owner said that is worth keeping: their words verbatim, filler and typos intact, appended to ${facts.fileRel} under a "## HH:MM" heading or through evda_write.`,
+    nonWriter
+      ? `Before you stop, file what the owner said that is worth keeping: their words verbatim, filler and typos intact, through evda_write. This machine does not write ${facts.fileRel} (EVDA_DAY_WRITER names the one that does, ${nonWriter}), so never write that file directly here.`
+      : `Before you stop, file what the owner said that is worth keeping: their words verbatim, filler and typos intact, appended to ${facts.fileRel} under a "## HH:MM" heading or through evda_write.`,
     "Then tell them the path in the past tense. If a person, project or place with an entry came up, add a dated section to that entry too (never to a noted one); one with no entry, offer to start it and wait for their yes.",
     "If nothing they said is worth keeping, stop. This asks once per stretch.",
   ].join(" ");
@@ -189,6 +193,16 @@ function stateFile(sid) {
   return join(dir, `${String(sid).replace(/[^A-Za-z0-9_-]/g, "_")}.json`);
 }
 
+// When the prompt hook (lib/prompt-hook.mjs) last filed or queued a message of this session, in ms,
+// or null. Its state file is the one place both hooks can see without the record changing.
+function promptFiledAt(sid) {
+  const dir = process.env.EVDA_PROMPT_STATE_DIR || join(tmpdir(), "evda-file-prompt");
+  try {
+    const t = Date.parse(JSON.parse(readFileSync(join(dir, `${String(sid ?? "unknown").replace(/[^A-Za-z0-9_-]/g, "_")}.json`), "utf8")).filedAt);
+    return Number.isFinite(t) ? t : null;
+  } catch { return null; }
+}
+
 // One Stop event in, the hook's stdout out ("" for let it stop). Never throws.
 export function run(payload, { now = new Date() } = {}) {
   try {
@@ -207,8 +221,13 @@ export function run(payload, { now = new Date() } = {}) {
     try { state = JSON.parse(readFileSync(sf, "utf8")) ?? {}; } catch { /* first stop of the session */ }
     let lastBlock = Number(state.at) || 0;
     if (lastBlock > evs.length) { lastBlock = 0; state = {}; } // a different transcript under the same id
-    const fileMtime = existsSync(facts.fileAbs) ? statSync(facts.fileAbs).mtimeMs : null;
-    const d = decide(evs, facts, { lastBlock, fileMtime });
+    let fileMtime = existsSync(facts.fileAbs) ? statSync(facts.fileAbs).mtimeMs : null;
+    // HQ-2817: the prompt hook's last hand-off counts as a write to the day. On a machine that does
+    // not write the day the file here does not change when a message is filed through the writer.
+    const filedAt = promptFiledAt(payload.session_id);
+    if (filedAt !== null && (fileMtime === null || filedAt > fileMtime)) fileMtime = filedAt;
+    const nonWriter = (process.env.EVDA_DAY_WRITER ?? "").trim();
+    const d = decide(evs, facts, { lastBlock, fileMtime, nonWriter });
     const mtimeOf = (rel) => { try { return statSync(join(root, rel)).mtimeMs; } catch { return null; } };
     const e = d.block ? null : decideEntries(evs, facts, { asked: Boolean(state.entries), mtimeOf });
     if (!d.block && !e.block) return "";