create-evda 0.1.10 → 0.1.12

package/lib/mcp.mjs

@@ -26,6 +26,7 @@ import * as gatherApply from "./gather-apply.mjs";
 import * as adoptLib from "./adopt.mjs";
 import { checkForUpdate, summarize } from "./update-check.mjs";
 import { callerFrom } from "./readers.mjs";
+import { correctionsForLayer, TAUGHT_HEADING } from "./corrections.mjs";
 import { listSkills, getSkill, writeSkill, noticeRepeat, SKILLS_REL } from "./skills.mjs";
 import { createSubrecord } from "./subrecord.mjs";
 import { FALSIFY } from "./mcp-auth.mjs";
@@ -296,16 +297,27 @@ export function coreBlock(r) {
   return [];
 }
 
-export function layerParts(evda, client = null) {
+// HQ-2818: the layer ends with what the owner taught the agent (lib/corrections.mjs), the newest
+// entries of the corrections file evda.json names, the same on every surface, counted in the chat
+// budget like the core. A record that keeps them in AGENTS.md's own section already serves them in
+// the owner text, so nothing is added unless a chat's budget listed that section by heading.
+export function layerParts(evda, client = null, caller = null) {
   const profile = clientProfile(client?.name);
+  const who = caller ?? callerFrom({ clientName: client?.name ?? null });
   const r = tools.operatingLayer(evda);
   const owner = forSurface(r.text, profile.surface);
   const head = [chatSection(evda, r.text, { app: profile.app }), dispatchSection(profile.surface), PRIVACY_SECTION].join("\n\n");
   const core = coreBlock(r);
   // Everything in the result but the owner sections: head, size line, core, and the joins between.
   const fixed = head.length + 2 + SIZE_LINE_RESERVE + 2 + core.reduce((n, c) => n + c.length + 2, 0);
-  const fit = profile.surface === "terminal" ? { text: owner.text, listed: [] } : fitChat(owner.text, fixed, profile.budget);
-  const body = [...core, fit.text].join("\n\n");
+  const fitWith = (extra) => (profile.surface === "terminal" ? { text: owner.text, listed: [] } : fitChat(owner.text, fixed + extra, profile.budget));
+  let taught = correctionsForLayer(evda, who, { agentsPath: r.path });
+  let fit = fitWith(taught ? taught.text.length + 2 : 0);
+  if (!taught && fit.listed.includes(TAUGHT_HEADING)) {
+    taught = correctionsForLayer(evda, who, { agentsPath: r.path, taughtListed: findSection(owner.text, TAUGHT_HEADING, profile.surface).text });
+    if (taught) fit = fitWith(taught.text.length + 2);
+  }
+  const body = [...core, fit.text, ...(taught ? [taught.text] : [])].join("\n\n");
   const max = profile.max;
   const pieces = packSections(body, max - PART_RESERVE - head.length, max - PART_RESERVE);
   const n = pieces.length;
@@ -316,7 +328,7 @@ export function layerParts(evda, client = null) {
     const end = i < n - 1 ? `\n\n(Part ${i + 1} of ${n} ends here. The layer continues: call evda_operating_layer with {"part": ${i + 2}} now, before answering.)` : "";
     return `${top}${p}${end}`;
   });
-  return { path: r.path, core: r.core?.path ?? null, parts, chars, surface: profile.surface, left: owner.left, listed: fit.listed };
+  return { path: r.path, core: r.core?.path ?? null, parts, chars, surface: profile.surface, left: owner.left, listed: fit.listed, corrections: taught ? { path: taught.path, served: taught.served, total: taught.total } : null };
 }
 
 // Split text into pieces of at most `max` characters (the first at most `first`), cutting where a
@@ -342,6 +354,8 @@ export function packSections(text, first, max) {
 }
 
 const str = (description) => ({ type: "string", description });
+// evda_write's and evda_write_agent_log's `conversation` (HQ-2823), in one set of words for both.
+const CONVERSATION_ARG = str("Leave this out in a chat: the chat is already the conversation. A hook or relay that sends each message as a separate call (a new process each time) passes the same short id on every call (letters, digits, _ and -, at most 128 characters, e.g. Claude Code's session_id), so those calls continue one section under one heading instead of opening a new one each.");
 
 // summarize() already names the command for the two statuses that ask the owner to run one. Over
 // stdio the owner may have no shell in front of them at all (the Claude desktop app), and `evda
@@ -628,9 +642,9 @@ export const TOOLS = [
         if (!Number.isInteger(part) || part < 1 || part > s.parts.length) throw tools.refuse(`evda_operating_layer "part" is a whole number from 1 to ${s.parts.length}; this section has ${s.parts.length === 1 ? "one part" : `${s.parts.length} parts`}.`, "BAD_ARGUMENT");
         return { text: s.parts[part - 1], data: { path: s.path, section: s.heading, part, parts: s.parts.length } };
       }
-      const l = layerParts(evda, ctx.client);
+      const l = layerParts(evda, ctx.client, ctx.caller);
       if (!Number.isInteger(part) || part < 1 || part > l.parts.length) throw tools.refuse(`evda_operating_layer "part" is a whole number from 1 to ${l.parts.length}; this layer has ${l.parts.length === 1 ? "one part" : `${l.parts.length} parts`}.`, "BAD_ARGUMENT");
-      const data = { path: l.path, core: l.core, part, parts: l.parts.length, chars: l.chars, listed: l.listed };
+      const data = { path: l.path, core: l.core, part, parts: l.parts.length, chars: l.chars, listed: l.listed, corrections: l.corrections };
       if (!opening) return { text: l.parts[part - 1], data };
       const start = openChat(evda, args, ctx, { room: clientProfile(ctx.client?.name).max - l.parts[part - 1].length - 7 - AFTER_RUN_RESERVE });
       return { text: `${l.parts[part - 1]}\n\n---\n\n${start.text}`, data: { ...data, filed: start.filed } };
@@ -687,7 +701,7 @@ export const TOOLS = [
     name: "evda_write",
     title: "File the owner's words",
     description: WRITE_DESCRIPTION.everything,
-    inputSchema: { type: "object", properties: { words: str("The owner's words, verbatim: filler, hedges and typos intact. Never a summary."), context: str("One line, yours, on what the conversation was about. Written above their words and labeled as not theirs. Never their words.") }, required: ["words"], additionalProperties: false },
+    inputSchema: { type: "object", properties: { words: str("The owner's words, verbatim: filler, hedges and typos intact. Never a summary."), context: str("One line, yours, on what the conversation was about. Written above their words and labeled as not theirs. Never their words."), conversation: CONVERSATION_ARG }, required: ["words"], additionalProperties: false },
     annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
     run: async (evda, args, ctx) => {
       const dup = sameAsFiled(ctx.session, args?.words);
@@ -725,7 +739,7 @@ export const TOOLS = [
     name: "evda_write_agent_log",
     title: "File Iris's own day log",
     description: "Files the agent's own day log, separate from the owner's words. Call to record what you (the agent, not the owner) did, built, filed or found: appends to Iris's own day log, the one named sub-record at \"01_Projects/Evda/Iris - Universal Thinking Partner/memory/record/daily\", and returns the path. It takes no path. It also keeps the one pointer line to that log under the agent's heading in the owner's day for today (added, or refreshed in place, never a second line), and touches nothing else there. One section per conversation, exactly like evda_write: the first call in a conversation opens the time heading with its context line, and later calls in the same conversation continue it.",
-    inputSchema: { type: "object", properties: { words: str("What you did, in your own words."), context: str("One line on what the conversation was about. Written above the words and labeled as not the owner's.") }, required: ["words"], additionalProperties: false },
+    inputSchema: { type: "object", properties: { words: str("What you did, in your own words."), context: str("One line on what the conversation was about. Written above the words and labeled as not the owner's."), conversation: CONVERSATION_ARG }, required: ["words"], additionalProperties: false },
     annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
     run: (evda, args, ctx) => {
       const r = tools.writeAgentLog(evda, args, { session: ctx.session });

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/plugin-hook.mjs

@@ -82,7 +82,9 @@ export function handle(mode, baked, input, env = process.env) {
       const settings = JSON.parse(readFileSync(join(root, ".claude", "settings.json"), "utf8"));
       const cmd = (settings?.hooks?.PreToolUse ?? []).flatMap((m) => (m?.hooks ?? []).map((h) => h?.command)).find((c) => typeof c === "string" && GUARD_MARK.test(c));
       if (!cmd) return none;
-      const r = spawnSync(cmd, { shell: true, input, encoding: "utf8", timeout: 25000 });
+      // The record's settings name the guard under $CLAUDE_PROJECT_DIR (HQ-2819), and a Cowork task's
+      // project is not the record, so it is set to the record for this one command.
+      const r = spawnSync(cmd, { shell: true, input, encoding: "utf8", timeout: 25000, env: { ...process.env, CLAUDE_PROJECT_DIR: root } });
       return { stdout: r.stdout ?? "", stderr: r.stderr ?? "", code: r.status === 2 ? 2 : 0 };
     }
     return none;

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,28 +23,157 @@
 //
 // 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 { dayRole, findRecord, filingOf, appendToDay, localDate, isConversationId } from "./day-file.mjs";
 import { secretShape } from "./secret-shape.mjs";
 
 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.
+// `conversation` is the Claude Code session it was said in, kept with it so a message that waited
+// still continues its conversation's section when it is sent.
+export function queuePrompt(root, { words, context, conversation = null, 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, ...(conversation ? { conversation } : {}), 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 } : {}), ...(isConversationId(entry.conversation) ? { conversation: entry.conversation } : {}) };
+    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.
+//
+// Every send is a separate evda_write on the writer, so each names its conversation, Claude Code's
+// session_id, and the writer continues that conversation's section (HQ-2823, lib/conversation.mjs).
+// The context line goes with every send: the writer files it once, on the conversation's first
+// write, and again only if that section is gone (edited away, or its state older than two days),
+// so a continuing conversation never opens a bare heading. A session_id that is not an id's shape
+// is not sent, and that message opens its own section, as every message did before.
+function viaWriter(root, prompt, now, env, sid) {
+  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 conversation = isConversationId(sid) ? sid : null;
+  const file = queuePrompt(root, { words: prompt, context: `Claude Code on ${hostname().split(".")[0]}, said ${timeOf(now)}`, conversation, 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");
+}
+
+// Claude Code delivers some of its own text through UserPromptSubmit: a background task's
+// completion arrives as a <task-notification> block, and context it adds rides in <system-reminder>
+// blocks. Neither is the owner's, and filing them put whole subagent reports into an owner's day as
+// his words (HQ-2823). Strip those blocks; what is left is what the owner typed, or nothing.
+export const HARNESS_BLOCKS = ["task-notification", "system-reminder"];
+export function ownerWords(prompt) {
+  const text = String(prompt);
+  let out = text;
+  for (const tag of HARNESS_BLOCKS) out = out.replace(new RegExp(`<${tag}>[\\s\\S]*?</${tag}>`, "g"), "");
+  if (out === text) return text; // nothing of the harness's: the words stay byte for byte
+  return out.trim() === "" ? "" : out.replace(/^\s*\n/, "").replace(/\n\s*$/, "");
+}
+
 // 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 : "";
+    const prompt = ownerWords(typeof payload?.prompt === "string" ? payload.prompt : "");
     if (!prompt.trim() || /^\s*\//.test(prompt)) return "";
     const here = dirname(fileURLToPath(import.meta.url));
     const root = findRecord(payload.cwd || process.cwd()) ?? findRecord(here);
@@ -55,6 +184,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, payload.session_id);
+      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 +196,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");
+}

package/lib/tdx-attestation.mjs

@@ -23,12 +23,19 @@
 //   8. the nonce is one this phone issued, unused, and young enough;
 //   9. REPORTDATA equals reportDataFor(nonce, tlsPublicKey), which binds the quote to the TLS key the
 //      phone then pins.
+//  10. when the VM names a key-wrapping key (lib/attested-wrap.mjs), REPORTDATA also binds it, so the
+//      key a client wraps circle keys to is one the attested VM made, not one the host operator chose.
 //
 // The binding, exactly: REPORTDATA (64 bytes) = SHA-512( "EVDA-TDX-REPORTDATA-v1" || 0x00 ||
 // nonce (32 bytes) || SPKI DER of the TLS public key ). The nonce has a fixed length and SPKI DER
 // carries its own length, so the concatenation is unambiguous. The VM computes the same value with
 // the same function when it asks the TDX module for a quote.
 //
+// With a key-wrapping key, REPORTDATA = SHA-512( "EVDA-TDX-REPORTDATA-v2" || 0x00 || nonce (32 bytes) ||
+// SPKI DER of the TLS public key || the X25519 wrap public key (32 raw bytes) ). The wrap key has a fixed
+// length and comes last, after a self-delimiting SPKI, and the tag differs, so neither form can be read
+// as the other.
+//
 // Not checked here yet: certificate revocation (Intel's PCK and root CRLs), quote v5 (refused as
 // unknown rather than half-checked), the TD relaunch advice v5 quotes carry, and whether the expected
 // measurements are themselves in Sigstore's log (lib/measurement-log.mjs checks a digest; tying the
@@ -71,11 +78,20 @@ const spkiDer = (key) => {
   return createPublicKey(key).export({ type: "spki", format: "der" });
 };
 
-/** The 64 bytes a TD must put in REPORTDATA to bind `nonce` (32 bytes) and `tlsPublicKey` to its quote. */
-export function reportDataFor(nonce, tlsPublicKey) {
+/** The domain tag when REPORTDATA also binds the VM's key-wrapping key. */
+export const REPORTDATA_WRAP_TAG = "EVDA-TDX-REPORTDATA-v2";
+
+/**
+ * The 64 bytes a TD must put in REPORTDATA to bind `nonce` (32 bytes) and `tlsPublicKey` to its quote,
+ * and, when given, `wrapPublicKey` (the raw 32-byte X25519 key the VM made inside itself).
+ */
+export function reportDataFor(nonce, tlsPublicKey, wrapPublicKey) {
   const n = Buffer.from(nonce);
   if (n.length !== 32) throw new Error("the nonce must be 32 bytes");
-  return createHash("sha512").update(Buffer.concat([Buffer.from(REPORTDATA_TAG, "ascii"), Buffer.from([0]), n, spkiDer(tlsPublicKey)])).digest();
+  if (wrapPublicKey == null) return createHash("sha512").update(Buffer.concat([Buffer.from(REPORTDATA_TAG, "ascii"), Buffer.from([0]), n, spkiDer(tlsPublicKey)])).digest();
+  const w = Buffer.from(wrapPublicKey);
+  if (w.length !== 32) throw new Error("the wrap key must be 32 bytes");
+  return createHash("sha512").update(Buffer.concat([Buffer.from(REPORTDATA_WRAP_TAG, "ascii"), Buffer.from([0]), n, spkiDer(tlsPublicKey), w])).digest();
 }
 
 /**
@@ -381,8 +397,10 @@ function checkQuote({ quote, collateral, minTcb, now, trust }) {
  * nonce: the 32 bytes the phone sent; nonces: the createNonceBook that issued it (spent here, pass or fail).
  * tlsPublicKey: the TLS server key of this connection (KeyObject, PEM, or SPKI DER).
  * expected: { mrtd, rtmr0, rtmr1, rtmr2, rtmr3 } as hex. Every one must be named.
+ * wrapPublicKey: the VM's key-wrapping key as the host named it (32 raw bytes), or absent. When given,
+ * the quote must bind it too, and the result names it.
  */
-export function verifyTdxAttestation({ quote, nonce, nonces, tlsPublicKey, expected, minTcb, collateral, now, trust = TDX_TRUST } = {}) {
+export function verifyTdxAttestation({ quote, nonce, nonces, tlsPublicKey, wrapPublicKey, expected, minTcb, collateral, now, trust = TDX_TRUST } = {}) {
   try {
     if (!nonces?.take) return fail("no nonce book was given, so freshness cannot be checked");
     const at = now === undefined ? undefined : new Date(now).getTime();
@@ -400,12 +418,14 @@ export function verifyTdxAttestation({ quote, nonce, nonces, tlsPublicKey, expec
     // 7. The code is the code expected.
     for (const n of MEASUREMENT_NAMES) if (r.body[n] !== expected[n]) return fail(`${n.toUpperCase()} is ${r.body[n].slice(0, 16)}..., not the expected ${expected[n].slice(0, 16)}...`);
 
-    // 9. The quote is for this nonce and this TLS key.
-    const want = reportDataFor(nonce, tlsPublicKey);
-    if (!timingSafeEqual(want, r.body.reportData)) return fail("REPORTDATA does not bind this nonce and this TLS key");
+    // 9 and 10. The quote is for this nonce, this TLS key and, when named, this wrap key.
+    const want = reportDataFor(nonce, tlsPublicKey, wrapPublicKey);
+    if (!timingSafeEqual(want, r.body.reportData)) return fail(wrapPublicKey == null ? "REPORTDATA does not bind this nonce and this TLS key" : "REPORTDATA does not bind this nonce, this TLS key and this wrap key");
 
     const measurements = Object.fromEntries(MEASUREMENT_NAMES.map((n) => [n, r.body[n]]));
-    return { ok: true, measurements, tcb: r.tcb, tlsPublicKeySha256: sha256(spkiDer(tlsPublicKey)).toString("hex") };
+    const out = { ok: true, measurements, tcb: r.tcb, tlsPublicKeySha256: sha256(spkiDer(tlsPublicKey)).toString("hex") };
+    if (wrapPublicKey != null) out.wrapPublicKey = Buffer.from(wrapPublicKey);
+    return out;
   } catch (err) {
     return fail(`the attestation could not be checked: ${err.message}`);
   }

package/lib/tools.mjs

@@ -41,7 +41,8 @@ import { secretShape } from "./references.mjs";
 import { doctor } from "./doctor.mjs";
 import { readContext, mayRead, heldBack, callerFrom, aiView, note as writeNote, releaseNote, SEALED_WHY, isSealedFile, isNotedFile } from "./readers.mjs";
 import { EvdaError } from "./errors.mjs";
-import { dayRole, appendToDay, setPointerLine, CONTEXT_LABEL, localDate, localTime } from "./day-file.mjs";
+import { dayRole, appendToDay, setPointerLine, CONTEXT_LABEL, localDate, localTime, isConversationId, CONVERSATION_MAX } from "./day-file.mjs";
+import { loadConversation, saveConversation } from "./conversation.mjs";
 import { writeMessage, unseenReplies, agentName } from "./messages.mjs";
 import { acknowledge as writeAcknowledgement, readAcknowledged, acknowledgementsFor } from "./acknowledge.mjs";
 import { openEvda, holderOf } from "./manifest.mjs";
@@ -309,8 +310,13 @@ export const CONTEXT_MAX = 240;
 // another tool's own name when it reuses this same append-only logic against a different day
 // file (evda_write_agent_log, against Iris's own sub-record). The behavior is identical either
 // way; only what a refusal calls itself changes.
+//
+// `conversation` (HQ-2823) is an id a hook or relay names so that separate calls, each in a fresh
+// process with no `session` of its own, continue one section: its section state is loaded from and
+// saved to lib/conversation.mjs, outside the record. Given, it is the conversation, in place of
+// `session`. A chat app holds its session already and never sends it.
 export function write(evda, args = {}, { now = new Date(), session = null, toolName = "evda_write" } = {}) {
-  onlyKeys(toolName, 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.");
+  onlyKeys(toolName, args, ["words", "context", "conversation"], "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", toolName);
   refuseSecrets(words, toolName);
   let context = null;
@@ -321,6 +327,10 @@ export function write(evda, args = {}, { now = new Date(), session = null, toolN
     refuseSecrets(args.context, toolName);
     context = args.context.trim();
   }
+  const conversation = args.conversation;
+  if (conversation !== undefined && !isConversationId(conversation)) {
+    throw refuse(`${toolName} "conversation" is a short id a hook or relay sends so separate calls continue one section: letters, digits, "_" and "-" only, at most ${CONVERSATION_MAX} characters. A chat app leaves it out.`, "CONVERSATION");
+  }
   const abs = join(evda.dir, todayPath(evda, { now }));
   mkdirSync(dirname(abs), { recursive: true });
   // The owner's day only: evda_write, and the tools that file the owner's message along with them.
@@ -328,11 +338,15 @@ export function write(evda, args = {}, { now = new Date(), session = null, toolN
   if (toolName !== "evda_write_agent_log") {
     const held = dayWriteHeld(abs);
     if (held !== null) {
-      const q = queueToOutbox(abs, { now, words, context });
+      const q = queueToOutbox(abs, { now, words, context, conversation });
       return { path: rel(evda, q), bytes: Buffer.byteLength(words), queued: true, held };
     }
   }
-  const w = appendToDay(abs, { now, words, context, session });
+  const conv = conversation === undefined ? null : loadConversation(conversation);
+  const w = appendToDay(abs, { now, words, context, session: conv ?? session });
+  // The words are in the day by now: a save that fails costs the next call a new heading, never a
+  // refusal that would have the caller send the same words again.
+  if (conv) { try { saveConversation(conversation, conv); } catch { /* see above */ } }
   return { path: rel(evda, abs), bytes: Buffer.byteLength(words), section: w.opened ? "opened" : "continued" };
 }
 
@@ -354,10 +368,10 @@ function dayWriteHeld(abs) {
 }
 
 // Queue held words where the writer files them later (HQ-2596): one new JSON file per write in the
-// daily folder's .outbox/, {tool, words, context, at, host}, named `<UTC timestamp>-<host>-evda_write.json`
+// daily folder's .outbox/, {tool, words, context, at, host} and the caller's conversation when it named one, named `<UTC timestamp>-<host>-evda_write.json`
 // (the shape the day-writer guard's refusal names, lib/day-writer.mjs OUTBOX_DIR). One file per write,
 // so no two writers ever share one and no sync can drop either. Returns the file's absolute path.
-function queueToOutbox(abs, { now, words, context }) {
+function queueToOutbox(abs, { now, words, context, conversation }) {
   const box = join(dirname(abs), ".outbox");
   mkdirSync(box, { recursive: true });
   const at = now.toISOString().replace(/\.\d{3}Z$/, "Z");
@@ -365,7 +379,7 @@ function queueToOutbox(abs, { now, words, context }) {
   const stamp = at.replace(/[-:]/g, "").replace(/^(\d{8})T/, (_, d) => `${d.slice(0, 4)}-${d.slice(4, 6)}-${d.slice(6)}T`);
   let file = join(box, `${stamp}-${host}-evda_write.json`);
   for (let n = 2; existsSync(file); n++) file = join(box, `${stamp}-${host}-evda_write-${n}.json`);
-  writeFileSync(file, JSON.stringify({ tool: "evda_write", words: String(words), context: context ?? "", at, host }, null, 1), { flag: "wx" });
+  writeFileSync(file, JSON.stringify({ tool: "evda_write", words: String(words), context: context ?? "", at, host, ...(conversation === undefined ? {} : { conversation }) }, null, 1), { flag: "wx" });
   return file;
 }