create-evda 0.1.10 → 0.1.11

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,6 +46,7 @@
 // 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 { readManifest, checkVersion, unknownKeys, unknownLayers, holderOf, holderProblems, KNOWN_LAYERS, SCHEMA_VERSION } from "./manifest.mjs";
@@ -77,6 +78,7 @@ 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 { 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,7 +314,11 @@ 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
@@ -799,6 +822,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 "";

package/lib/person-folders.mjs

@@ -19,6 +19,7 @@
 
 import { readdirSync, readFileSync, statSync } from "node:fs";
 import { join } from "node:path";
+import { outsideRecord } from "./record-walk.mjs";
 
 export const PROCESSING_DIR = "Processing";
 export const README_NAME = "README.md";
@@ -64,7 +65,7 @@ export function personFolderProblems(dirs, { skip = new Set() } = {}) {
     let names;
     try { names = readdirSync(d).sort(); } catch { continue; }
     for (const name of names) {
-      if (name.startsWith(".") || name === "node_modules") continue;
+      if (name.startsWith(".") || outsideRecord(name)) continue;
       const p = join(d, name);
       let st;
       try { st = statSync(p); } catch { continue; }

package/lib/presets.mjs

@@ -44,6 +44,7 @@ import { ROUTINE_KEYS } from "./routines.mjs";
 import { onlyKeys, proposeCircle, refuse, PROPOSALS } from "./tools.mjs";
 import { EvdaError } from "./errors.mjs";
 import { PERSON_FOLDER_README, PROCESSING_DIR, README_NAME } from "./person-folders.mjs";
+import { outsideRecord } from "./record-walk.mjs";
 
 export const PRESETS_DIR = resolve(dirname(fileURLToPath(import.meta.url)), "..", "presets");
 export const PRESET_FILE = "preset.json";
@@ -66,7 +67,7 @@ function pathProblem(p) {
   if (p.startsWith("/")) return "is absolute; paths are relative to the record root";
   for (const seg of p.split("/")) {
     if (seg === "" || seg === "." || seg === "..") return `has an empty, . or .. segment`;
-    if (seg.startsWith(".") || seg === "node_modules") return `has the segment "${seg}", which doctor does not read`;
+    if (seg.startsWith(".") || outsideRecord(seg)) return `has the segment "${seg}", which doctor does not read`;
   }
   return null;
 }

package/lib/prompt-hook.mjs

@@ -23,10 +23,30 @@
 //
 // EVDA_CHAT_FALSIFY=ignore-filing files even when evda.json does not say "everything", for the test
 // that shows the hook reads the owner's answer.
+//
+// ON A MACHINE THAT DOES NOT WRITE THE DAY (HQ-2817). EVDA_DAY_WRITER set means another machine
+// writes the daily file, and a local append is the iCloud race HQ-2165 exists to stop (lib/
+// day-writer.mjs). There the hook never touches the day file. It hands the words to the command in
+// EVDA_DAY_WRITER_SEND, which receives evda_write's arguments as JSON on stdin and exits 0 once the
+// writer filed them (Mike's: ssh to Hestia and its evda-tool.mjs evda_write). Each message is first
+// saved as one JSON file in this machine's own outbox, outside the record and outside any synced
+// folder (EVDA_PROMPT_OUTBOX, default ~/.evda/outbox), then the outbox is sent oldest first and a
+// file is deleted only after its send exits 0. So a message said while the writer is unreachable
+// waits there and goes on the next message that reaches it, filed once:
+//   - one drainer: only this machine's hook reads its outbox, so no other machine can file it too;
+//   - one sender per file: a send first renames the file to `.sending`, an atomic claim, so two
+//     sessions submitting at once never send the same file; a claim older than SENDING_STALE_MS
+//     (a hook that was killed mid-send) is put back for the next run.
+// The whole send is bounded by EVDA_DAY_WRITER_SEND_MS (default 6000) because Claude Code holds the
+// owner's message until this hook returns. One case can still file twice: a send that reached the
+// writer and timed out before it answered. A connect timeout on the sender's side keeps that rare.
+// With EVDA_DAY_WRITER set and no EVDA_DAY_WRITER_SEND, nothing on this machine can reach the
+// writer, so nothing is queued and the hook tells the model to file the message with evda_write.
 
-import { existsSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readdirSync, readFileSync, realpathSync, renameSync, statSync, unlinkSync, writeFileSync } from "node:fs";
 import { dirname, join, relative } from "node:path";
-import { tmpdir } from "node:os";
+import { homedir, hostname, tmpdir } from "node:os";
+import { spawnSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
 import { dayRole, findRecord, filingOf, appendToDay, localDate } from "./day-file.mjs";
 import { secretShape } from "./secret-shape.mjs";
@@ -35,14 +55,100 @@ export const PROMPT_HOOK_NAME = "evda-file-prompt.mjs";
 
 const falsified = (mode) => (process.env.EVDA_CHAT_FALSIFY ?? "").split(",").map((s) => s.trim()).includes(mode);
 
+export const DAY_WRITER_SEND_ENV = "EVDA_DAY_WRITER_SEND";
+export const PROMPT_OUTBOX_ENV = "EVDA_PROMPT_OUTBOX";
+export const SEND_BUDGET_MS = 6000;
+export const SENDING_STALE_MS = 2 * 60 * 1000;
+
+export function promptOutboxDir(env = process.env) {
+  return env[PROMPT_OUTBOX_ENV] || join(homedir(), ".evda", "outbox");
+}
+
+const realOr = (p) => { try { return realpathSync(p); } catch { return p; } };
+
+// Save one message for the writer: a new file per message, never rewritten, in this machine's outbox.
+export function queuePrompt(root, { words, context, now = new Date(), env = process.env }) {
+  const dir = promptOutboxDir(env);
+  mkdirSync(dir, { recursive: true });
+  const at = now.toISOString();
+  const stamp = at.replace(/[-:.]/g, "");
+  let file = join(dir, `${stamp}-${process.pid}.json`);
+  for (let n = 2; existsSync(file); n++) file = join(dir, `${stamp}-${process.pid}-${n}.json`);
+  writeFileSync(file, JSON.stringify({ tool: "evda_write", record: realOr(root), words, context, at, host: hostname().split(".")[0] || "host" }, null, 1) + "\n", { flag: "wx" });
+  return file;
+}
+
+// Send this record's queued messages to the writer, oldest first, within `budgetMs`. Returns
+// { sent: [file...], left, error }. Stops at the first failure, so the order of the day is kept.
+// A claim's age is measured against the file system's own clock (the mtime of a file touched now),
+// never Date.now(): a claim's mtime is stamped by the file system, and the two clocks can disagree.
+export function drainPromptOutbox(root, { env = process.env, budgetMs = Number(env.EVDA_DAY_WRITER_SEND_MS) || SEND_BUDGET_MS, nowMs = null } = {}) {
+  const cmd = (env[DAY_WRITER_SEND_ENV] ?? "").trim();
+  const dir = promptOutboxDir(env);
+  const out = { sent: [], left: 0, error: null };
+  if (!cmd || !existsSync(dir)) return out;
+  if (nowMs === null) { const probe = join(dir, ".now"); writeFileSync(probe, ""); nowMs = statSync(probe).mtimeMs; }
+  const rec = realOr(root);
+  for (const f of readdirSync(dir).filter((n) => n.endsWith(".json.sending"))) {
+    const abs = join(dir, f);
+    try { if (nowMs - statSync(abs).mtimeMs > SENDING_STALE_MS) renameSync(abs, abs.replace(/\.sending$/, "")); } catch { /* another run took it back */ }
+  }
+  const mine = readdirSync(dir).filter((n) => n.endsWith(".json")).sort().filter((n) => {
+    try { return JSON.parse(readFileSync(join(dir, n), "utf8")).record === rec; } catch { return false; }
+  });
+  const deadline = Date.now() + budgetMs;
+  for (let i = 0; i < mine.length; i++) {
+    const abs = join(dir, mine[i]);
+    const claim = `${abs}.sending`;
+    try { renameSync(abs, claim); } catch { continue; } // another session claimed it
+    let entry;
+    try { entry = JSON.parse(readFileSync(claim, "utf8")); } catch { renameSync(claim, abs); continue; }
+    const left = deadline - Date.now();
+    const args = { words: entry.words, ...(entry.context ? { context: entry.context } : {}) };
+    const r = left > 200 ? spawnSync(cmd, { shell: true, input: JSON.stringify(args), encoding: "utf8", timeout: left, env }) : { status: null, error: { code: "ETIMEDOUT" } };
+    if (r.status === 0) { unlinkSync(claim); out.sent.push(abs); continue; }
+    try { renameSync(claim, abs); } catch { /* kept as a claim; the stale rule puts it back */ }
+    out.error = r.error ? (r.error.code === "ETIMEDOUT" ? `no answer in ${budgetMs}ms` : r.error.code ?? r.error.message) : `exited ${r.status ?? r.signal}: ${String(r.stderr ?? "").trim().split("\n").pop() ?? ""}`.trim();
+    out.left = mine.length - i;
+    break;
+  }
+  return out;
+}
+
+const timeOf = (d) => `${localDate(d)} ${String(d.getHours()).padStart(2, "0")}:${String(d.getMinutes()).padStart(2, "0")}`;
+
+// The non-writer path: queue, send, and say what happened. Never touches the day file.
+function viaWriter(root, prompt, now, env) {
+  const writer = env.EVDA_DAY_WRITER.trim();
+  if (!(env[DAY_WRITER_SEND_ENV] ?? "").trim()) {
+    return `evda: this machine does not write the daily file (EVDA_DAY_WRITER is ${writer}) and has no ${DAY_WRITER_SEND_ENV} to reach it, so the owner's message above is NOT filed yet. File it verbatim with evda_write this turn.`;
+  }
+  const file = queuePrompt(root, { words: prompt, context: `Claude Code on ${hostname().split(".")[0]}, said ${timeOf(now)}`, now, env });
+  const r = drainPromptOutbox(root, { env });
+  if (r.sent.includes(file)) {
+    const more = r.sent.length > 1 ? ` (with ${r.sent.length - 1} message(s) queued earlier)` : "";
+    return `evda: the owner's message above is already filed verbatim through the day writer (${writer})${more}. Do not file it again with evda_write.`;
+  }
+  return `evda: the day writer (${writer}) could not be reached (${r.error ?? "not sent"}), so the owner's message above is queued in ${dirname(file)} on this machine and goes to the writer with their next message. Do not file it again with evda_write; if you tell them, say it is queued, not filed.`;
+}
+
 function stateFile(sid) {
   const dir = process.env.EVDA_PROMPT_STATE_DIR || join(tmpdir(), "evda-file-prompt");
   mkdirSync(dir, { recursive: true });
   return join(dir, `${String(sid).replace(/[^A-Za-z0-9_-]/g, "_")}.json`);
 }
 
+// The keep hook reads this (HQ-2817): on a machine that does not write the day, the day file does
+// not change here when a message is filed, so the time it was handed over is the evidence.
+function markFiled(sid, now) {
+  const sf = stateFile(sid ?? "unknown");
+  let session = {};
+  try { session = JSON.parse(readFileSync(sf, "utf8")); } catch { /* none yet */ }
+  writeFileSync(sf, JSON.stringify({ ...session, filedAt: now.toISOString() }) + "\n");
+}
+
 // One UserPromptSubmit event in, the hook's stdout out ("" for nothing to say). Never throws.
-export function run(payload, { now = new Date() } = {}) {
+export function run(payload, { now = new Date(), env = process.env } = {}) {
   try {
     const prompt = typeof payload?.prompt === "string" ? payload.prompt : "";
     if (!prompt.trim() || /^\s*\//.test(prompt)) return "";
@@ -55,6 +161,11 @@ export function run(payload, { now = new Date() } = {}) {
     if (!role) return "";
     const shape = prompt.split("\n").map(secretShape).find(Boolean);
     if (shape) return `evda: this message was not filed, because it holds ${shape}. Keep that in a password manager; file the rest of what they said with evda_write if it is worth keeping.`;
+    if ((env.EVDA_DAY_WRITER ?? "").trim()) {
+      const said = viaWriter(root, prompt, now, env);
+      if ((env[DAY_WRITER_SEND_ENV] ?? "").trim()) markFiled(payload.session_id, now); // sent or queued to send
+      return said;
+    }
     const dayAbs = join(root, manifest.mapping[role].replace(/\/+$/, ""));
     mkdirSync(dayAbs, { recursive: true });
     const abs = join(dayAbs, `${localDate(now)}.md`);
@@ -62,7 +173,7 @@ export function run(payload, { now = new Date() } = {}) {
     let session = {};
     try { session = JSON.parse(readFileSync(sf, "utf8")); } catch { /* the first prompt of the session */ }
     appendToDay(abs, { now, words: prompt, session });
-    writeFileSync(sf, JSON.stringify(session) + "\n");
+    writeFileSync(sf, JSON.stringify({ ...session, filedAt: now.toISOString() }) + "\n");
     const rel = relative(root, abs).split("\\").join("/");
     return `evda: the owner's message above is already filed verbatim in ${rel}. Do not file it again with evda_write.`;
   } catch {

package/lib/readme.mjs

@@ -0,0 +1,145 @@
+// README.md, the owner-facing half of the operating layer (HQ-2812).
+//
+// AGENTS.md sends the agent to sections of README.md for the facts it must never give from memory:
+// the steps for turning training off, what each AI company says, and running a model locally. A
+// record create-evda makes has them, because it writes README.md from templates/README.md. A record
+// `evda adopt` makes keeps the owner's own README.md, which has none of them, so the privacy step
+// pointed at nothing. This module renders the README once, for both, and keeps those sections in an
+// adopted README as one marked block the owner's text never shares:
+//
+//   <the owner's README, byte for byte>
+//   <!-- evda:readme -->
+//   _lead line_
+//   ## Turning training off ... ## Running a model on your own computer ...
+//   <!-- /evda:readme -->
+//
+// `ensureReadme` writes the file when it is absent, appends the block when a cited section is
+// missing, and refreshes the block's content when it is there (`evda upgrade`). A README that already
+// holds every cited heading outside a block (create-evda's own) is left alone.
+
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { trainingSection, termsSection, INTRO } from "./setup.mjs";
+
+const PKG = join(dirname(fileURLToPath(import.meta.url)), "..");
+export const README_REL = "README.md";
+export const README_OPEN = "<!-- evda:readme -->";
+export const README_CLOSE = "<!-- /evda:readme -->";
+export const README_LEAD = "_EVÐA wrote this block and `evda upgrade` keeps it current. Everything above it is yours, and EVÐA never changes it._";
+// The first and the last heading of templates/README.md the block carries, in that file's order.
+const FIRST = "## Turning training off";
+const AFTER = "## Getting started";
+
+// The local-model doc as a README section: its title dropped and its headings one level down.
+export function localModelSection() {
+  const text = readFileSync(join(PKG, "docs", "local-model.md"), "utf8");
+  return text.split("\n").slice(1).join("\n").replace(/^## /gm, "### ").trim();
+}
+
+// The README create-evda writes into a new record.
+export function renderReadme() {
+  let text = readFileSync(join(PKG, "templates", "README.md"), "utf8");
+  const vars = { training: trainingSection(), terms: termsSection(), intro: INTRO, localModel: localModelSection() };
+  for (const [k, v] of Object.entries(vars)) text = text.replaceAll(`{{${k}}}`, v);
+  return text;
+}
+
+// The sections AGENTS.md cites, cut from the rendered README rather than written a second time.
+export function readmeSections() {
+  const text = renderReadme();
+  const from = text.indexOf(FIRST);
+  const to = text.indexOf(AFTER);
+  if (from === -1 || to === -1 || to < from) throw new Error(`templates/README.md no longer has "${FIRST}" before "${AFTER}", so the adopted README block cannot be cut from it.`);
+  return text.slice(from, to).trimEnd();
+}
+
+export function readmeBlock() {
+  return `${README_OPEN}\n${README_LEAD}\n\n${readmeSections()}\n${README_CLOSE}\n`;
+}
+
+// Every README.md section an operating layer sends the agent to: a quoted heading followed by
+// `section of` or `in`, then `README.md`, line breaks inside the quote allowed.
+export function readmeCitations(agentsText) {
+  const flat = String(agentsText).replace(/\s+/g, " ");
+  const out = [];
+  for (const m of flat.matchAll(/"([^"]{2,120})"(?: section)? (?:of|in) `?README\.md`?/g)) if (!out.includes(m[1])) out.push(m[1]);
+  return out;
+}
+
+const escape = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+export const hasHeading = (text, heading) => new RegExp(`^#{1,6}[ \\t]+${escape(heading)}[ \\t]*#*[ \\t]*$`, "m").test(text);
+
+// The cited headings README text lacks.
+export function missingHeadings(readmeText, citations) {
+  return citations.filter((h) => !hasHeading(readmeText ?? "", h));
+}
+
+// The block's place in README text: { start, end } around the markers (end past the closing line
+// break), or null when there is none. Two blocks, or an open with no close, is a problem, not a block.
+export function findBlock(text) {
+  const open = text.indexOf(README_OPEN);
+  const close = text.indexOf(README_CLOSE);
+  if (open === -1 && close === -1) return null;
+  if (open === -1 || close === -1 || close < open || text.indexOf(README_OPEN, open + 1) !== -1 || text.indexOf(README_CLOSE, close + 1) !== -1) {
+    throw new Error(`${README_REL} has a broken ${README_OPEN} block (one marker without the other, or two of them). Fix the markers by hand; nothing was changed.`);
+  }
+  let end = close + README_CLOSE.length;
+  if (text[end] === "\n") end += 1;
+  return { start: open, end };
+}
+
+// What the README should become. Returns { action, text, added }:
+//   "written"    absent: the whole README create-evda writes
+//   "appended"   a cited section was missing and there was no block: the block is added at the end
+//   "refreshed"  the block was there with other content: its content is replaced
+//   "current"    the block is there and matches
+//   "present"    no block, and every cited heading is already in the owner's text
+// `added` is exactly what "appended" put after the owner's bytes, so a revert can take it back out.
+export function planReadme(text, citations) {
+  if (text === null) return { action: "written", text: renderReadme(), added: null };
+  const block = readmeBlock();
+  const at = findBlock(text);
+  if (at) {
+    const next = text.slice(0, at.start) + block + text.slice(at.end);
+    return next === text ? { action: "current", text, added: null } : { action: "refreshed", text: next, added: null };
+  }
+  if (!missingHeadings(text, citations).length) return { action: "present", text, added: null };
+  const added = `${text === "" || text.endsWith("\n") ? "" : "\n"}\n${block}`;
+  return { action: "appended", text: text + added, added };
+}
+
+// Apply planReadme to <dir>/README.md. `citations` defaults to the record's AGENTS.md, or the shipped
+// template's when there is none.
+export function ensureReadme(dir, { citations = null, dry = false, agents = null } = {}) {
+  const abs = join(dir, README_REL);
+  const cites = citations ?? readmeCitations(agents ?? readFileSync(join(PKG, "templates", "AGENTS.md"), "utf8"));
+  const before = existsSync(abs) ? readFileSync(abs, "utf8") : null;
+  const plan = planReadme(before, cites);
+  if (!dry && plan.text !== before) writeFileSync(abs, plan.text);
+  return { ...plan, abs, rel: README_REL, citations: cites };
+}
+
+// README text with the block taken back out: exactly what was there before an "appended", when the
+// owner did not edit around the block. Null when there is no block to take.
+export function withoutBlock(text, added) {
+  if (added && text.endsWith(added)) return text.slice(0, -added.length);
+  let at;
+  try { at = findBlock(text); } catch { return null; }
+  if (!at) return null;
+  // The line breaks the adopt put in front of the block go with it.
+  const lead = added ? added.slice(0, added.indexOf(README_OPEN)) : "";
+  const start = lead && text.slice(at.start - lead.length, at.start) === lead ? at.start - lead.length : at.start;
+  return text.slice(0, start) + text.slice(at.end);
+}
+
+export function readmeLine(r) {
+  const names = r.citations.map((c) => `"${c}"`).join(", ");
+  switch (r.action) {
+    case "written": return `README.md: written, with ${names}`;
+    case "appended": return `README.md: EVÐA's block added at the end, with ${names}; your text above it is unchanged`;
+    case "refreshed": return "README.md: EVÐA's block refreshed to what this tool ships; your text around it is unchanged";
+    case "current": return "README.md: EVÐA's block already matches what this tool ships";
+    default: return `README.md: already has ${names}; left alone`;
+  }
+}

package/lib/record-walk.mjs

@@ -0,0 +1,9 @@
+// The one rule every walker over the record uses for what is outside it (HQ-2811): a folder named
+// node_modules (packages, not notes), and any name ending in .nosync, the iCloud convention for
+// "do not sync this". A .nosync folder is one the owner chose to keep out of sync, which is the same
+// as keeping it out of the record; Mike's vault keeps its packages in node_modules.nosync, and the
+// bears-on notice once named a vendored eslint doc in it as an existing entry. Dot-names and app
+// folders stay each walker's own choice, since they differ by what the walk is for.
+export function outsideRecord(name) {
+  return name === "node_modules" || name.endsWith(".nosync");
+}