create-evda 0.1.10 → 0.1.11

package/CHANGELOG.md

@@ -4,6 +4,29 @@ Plain-English notes on how Iris behaves differently after each version. Not a co
 
 ## Unreleased
 
+On a machine that does not write the day (`EVDA_DAY_WRITER` set), the Claude Code prompt hook no
+longer appends to the local day file. It sends each message to the writer through the command in
+`EVDA_DAY_WRITER_SEND` (evda_write's arguments as JSON on stdin), and a message the writer cannot take
+waits in this machine's own outbox (`EVDA_PROMPT_OUTBOX`, default `~/.evda/outbox`) and goes with the
+next one, filed once. The keep-record hook's reminder there names evda_write. The day-writer guard
+now sees a day file named through a variable the same command set, `$HOME` or `~`. `evda doctor`
+warns when evda.json says `"filing": "everything"` and no prompt hook is installed (HQ-2817).
+
+An EVÐA made with `evda adopt` now has the steps for turning training off. Iris gives those steps
+only from the "Turning training off" section of `README.md`, and an adopted folder kept its own
+README, which never had that section, or the ones on what each AI company says and running a model
+on your own computer. The adopt now adds those three sections after your README as one block marked
+as EVÐA's, leaving your text exactly as it was, or writes the whole README when you had none.
+`evda adopt --revert` takes the block back out, and `evda upgrade` keeps it current. `evda doctor`
+fails a record whose `AGENTS.md` sends Iris to a `README.md` section that is not there, and says to
+run `evda upgrade`, which adds it.
+
+`evda doctor` run from a git checkout now says, just before its verdict, when that checkout is behind
+origin/main or is not main, so a pass from an old branch no longer reads as main's pass. It fetches
+main first with a five-second limit; offline, with no origin, or from an installed copy it still runs
+every check and says it could not compare. On current main it says nothing extra, and the exit code is
+unchanged. `EVDA_DOCTOR_FETCH=0` skips the fetch.
+
 When a filing names pages your EVÐA already has (a person, a project, a topic) or open tickets on your
 board, and the conversation adds to none of them, Iris is now asked once, naming them, whether what you said adds to one; adding
 nothing is a fine answer. In Claude Code the record's Stop hook asks before the session stops, and in

package/README.md

@@ -178,7 +178,7 @@ Writes:
 
 The training instructions in the scaffolded README and in setup come from one table, `lib/setup.mjs`, with a link to each provider's page.
 
-The tree above is what the scaffolder creates and not a requirement. `evda.json` carries a `mapping` from roles to paths, and every tool reads roles. An existing folder of notes becomes an EVÐA by adding `evda.json` with a mapping that names where things already are, and nothing moves. `evda adopt <dir>` writes that mapping: an Iris Vault (`00_Inbox` through `06_Metadata`) maps without a question, any other folder is placed by its name or named back to the owner to answer with `--map <folder>=<role>`, and it adds `AGENTS.md`, `.evda/`, the Claude Code hooks and one `@AGENTS.md` line at the end of the owner's `CLAUDE.md`. Every other file stays byte for byte, and `evda adopt --revert <manifest>` puts the folder back exactly as it was. A chat app runs it through `evda_adopt`, which writes nothing without `confirmed: true`.
+The tree above is what the scaffolder creates and not a requirement. `evda.json` carries a `mapping` from roles to paths, and every tool reads roles. An existing folder of notes becomes an EVÐA by adding `evda.json` with a mapping that names where things already are, and nothing moves. `evda adopt <dir>` writes that mapping: an Iris Vault (`00_Inbox` through `06_Metadata`) maps without a question, any other folder is placed by its name or named back to the owner to answer with `--map <folder>=<role>`, and it adds `AGENTS.md`, `.evda/`, the Claude Code hooks, one `@AGENTS.md` line at the end of the owner's `CLAUDE.md`, and the `README.md` sections `AGENTS.md` sends the agent to (turning training off, what each AI company says, running a model locally) as one marked block after the owner's own `README.md`, which `evda upgrade` keeps current. Every other file stays byte for byte, and `evda adopt --revert <manifest>` puts the folder back exactly as it was. A chat app runs it through `evda_adopt`, which writes nothing without `confirmed: true`.
 
 ### Four roles, and records inside records
 

package/bin/evda.mjs

@@ -729,7 +729,8 @@ async function main(argv) {
 
     case "doctor": {
       const { dir, via } = pickDir(args);
-      return doctor(dir, { via }).exit;
+      // The package root this doctor runs from, so it can say whether that is current main (HQ-2736).
+      return doctor(dir, { via, checkout: fileURLToPath(new URL("..", import.meta.url)) }).exit;
     }
 
     case "guard":
@@ -946,6 +947,11 @@ async function main(argv) {
       const parts = splitFence(text);
       if (!parts) throw new EvdaError(`${a.rel} has no evda:generated fence. The owner has taken the whole file; there is nothing the installer owns to replace, and nothing was changed.`);
       const shipped = shippedGenerated();
+      // HQ-2812: the README.md sections the operating layer sends the agent to, kept as EVÐA's
+      // marked block (added when one is missing, refreshed when it is there); the owner's text is
+      // never touched.
+      const { ensureReadme, readmeLine } = await import("../lib/readme.mjs");
+      console.log(`upgrade: ${readmeLine(ensureReadme(dir, { agents: replaceFence(text, shipped) }))}`);
       if (parts.generated === shipped) {
         stampInstalledVersion(dir, packageVersion());
         console.log("upgrade: the generated block already matches what this tool ships. Nothing outside it was read.");

package/create-evda.mjs

@@ -40,8 +40,9 @@ import { applyPreset, listPresets, planLines, presetIds, NONE } from "./lib/pres
 import { FILING_MODES } from "./lib/day-file.mjs";
 import { installPromptHook } from "./lib/hooks.mjs";
 import { defaultParts } from "./lib/circle-plan.mjs";
-import { PLATFORMS, PLATFORM_KEYS, PARTS_LINE, LOADERS, DESKTOP_FILESYSTEM, DICTATION, DEFAULT_AGENT_NAME, platformKey, fillOwnerSection, aiLine, interview, trainingSection, termsSection, readerFor, INTRO } from "./lib/setup.mjs";
+import { PLATFORMS, PLATFORM_KEYS, PARTS_LINE, LOADERS, DESKTOP_FILESYSTEM, DICTATION, DEFAULT_AGENT_NAME, platformKey, fillOwnerSection, aiLine, interview, readerFor, INTRO } from "./lib/setup.mjs";
 import { describeReaders, parseReaders } from "./lib/readers.mjs";
+import { renderReadme } from "./lib/readme.mjs";
 
 const HERE = dirname(fileURLToPath(import.meta.url));
 const TEMPLATES = join(HERE, "templates");
@@ -188,7 +189,7 @@ export function scaffold(opts) {
   // agent asks at first connect.
   if (opts.filing) manifest.filing = opts.filing;
   writeIfAbsent(join(dir, "evda.json"), JSON.stringify(manifest, null, 2) + "\n");
-  writeIfAbsent(join(dir, "README.md"), render("README.md", { training: trainingSection(), terms: termsSection(), intro: INTRO, localModel: localModelSection() }));
+  writeIfAbsent(join(dir, "README.md"), renderReadme());
   // The owner section of AGENTS.md holds the setup answers in the owner's words. The AI line is
   // written only when training off was confirmed; empty, it is what makes the agent ask.
   const answers = {
@@ -231,12 +232,6 @@ export function scaffold(opts) {
   return { dir, manifest, pointer, guard, hook, promptHook };
 }
 
-// The local-model doc as a README section: its title dropped and its headings one level down.
-function localModelSection() {
-  const text = readFileSync(join(HERE, "docs", "local-model.md"), "utf8");
-  return text.split("\n").slice(1).join("\n").replace(/^## /gm, "### ").trim();
-}
-
 // Day one. The record's first daily file records the one true thing that has happened to it: it
 // was created. It says so in three lines and says where the owner's words go, then gets out of the
 // way. It is not an example note, it asks nothing, and it schedules nothing; every later file

package/lib/adopt.mjs

@@ -9,12 +9,16 @@
 //     does not is never guessed at: it is named back, and the owner answers with `--map`.
 //   - What is written: evda.json, AGENTS.md (the one create-evda ships), the GEMINI.md loader when
 //     absent, the `@AGENTS.md` line appended to the owner's CLAUDE.md (or the loader when there is
-//     none), folder manifests in the record folders, .evda/, and the Claude Code hooks in
-//     .claude/settings.json. Every other file that was there stays byte for byte.
+//     none), folder manifests in the record folders, .evda/, the Claude Code hooks in
+//     .claude/settings.json, and the README.md sections AGENTS.md sends the agent to (training off,
+//     what each AI company says, a local model: HQ-2812), as one marked block after the owner's
+//     README, or the whole README create-evda writes when there is none. Every other file that was
+//     there stays byte for byte.
 //   - Every write is listed in a reversal manifest outside the folder. `revertAdopt` restores the
 //     folder byte for byte, folder times included, and refuses when a file the adopt wrote or changed
-//     was edited since, unless forced. Two edits never block it: the owner's own edits to CLAUDE.md
-//     (only the added line is taken out) and `evda upgrade` replacing AGENTS.md's generated block.
+//     was edited since, unless forced. Edits that never block it: the owner's own edits to CLAUDE.md
+//     or README.md (only the added line, or the added block, is taken out), `evda upgrade` replacing
+//     AGENTS.md's generated block, and `evda upgrade` refreshing the README block.
 //
 // EVDA_ADOPT_FALSIFY=<mode,...>, for the tests: guess-unplaced places an unknown folder in
 // knowledge instead of asking; claude-rewrite writes CLAUDE.md as the loader instead of appending;
@@ -40,6 +44,8 @@ import { readPointer, setPointer, pointerPath } from "./locate.mjs";
 import { stampInstalledVersion } from "./update-check.mjs";
 import { doctor } from "./doctor.mjs";
 import { everyChatSetupLines } from "./every-chat.mjs";
+import { outsideRecord } from "./record-walk.mjs";
+import { ensureReadme, withoutBlock, README_REL } from "./readme.mjs";
 
 export const ADOPT_VERSION = 1;
 export const ADOPT_FALSIFY_MODES = ["guess-unplaced", "claude-rewrite", "revert-ignores-edits", "revert-not-exact"];
@@ -56,13 +62,13 @@ export const CLAUDE_LINE = "@AGENTS.md";
 // The starter kit's seven folders. Five or more of them at the top is an Iris Vault.
 export const IRIS_VAULT_DIRS = ["00_Inbox", "01_Projects", "02_Areas", "03_Resources", "04_Archive", "05_Attachments", "06_Metadata"];
 // Folders no one keeps notes in: tooling, never asked about.
-const IGNORED = new Set(["node_modules", "dist", "build"]);
+const IGNORED = new Set(["dist", "build"]); // plus outsideRecord: node_modules, any *.nosync
 // What the adopt writes under these is derived state, rebuilt by the tooling, so an edit there never
 // blocks a revert.
 const DERIVED = [".evda/"];
 // The files whose bytes are kept before the adopt runs, because the adopt (or an installer it calls)
 // may change them. Anything else that changes is a bug, and the adopt says so.
-const MAY_CHANGE = ["CLAUDE.md", "GEMINI.md", "AGENTS.md", "evda.json", ".claude/settings.json"];
+const MAY_CHANGE = ["CLAUDE.md", "GEMINI.md", "AGENTS.md", "evda.json", ".claude/settings.json", README_REL];
 
 // The Iris Vault mapping, as the reference instance (the starter kit's author's own vault) keeps it.
 // `make: true` is a folder the role needs that the starter kit does not ship.
@@ -119,7 +125,7 @@ export function parseMapArgs(values) {
 export function proposeAdoption(dirIn, { map = {} } = {}) {
   const dir = resolve(dirIn);
   if (!existsSync(dir) || !statSync(dir).isDirectory()) throw refuse(`${dir} is not a folder.`, "NOT_A_FOLDER");
-  const top = readdirSync(dir, { withFileTypes: true }).filter((d) => d.isDirectory() && !d.name.startsWith(".") && !IGNORED.has(d.name)).map((d) => d.name).sort();
+  const top = readdirSync(dir, { withFileTypes: true }).filter((d) => d.isDirectory() && !d.name.startsWith(".") && !IGNORED.has(d.name) && !outsideRecord(d.name)).map((d) => d.name).sort();
   const iris = IRIS_VAULT_DIRS.filter((d) => top.includes(d)).length >= 5;
   const entries = [];
   const problems = [];
@@ -181,7 +187,7 @@ export function proposalLines(p) {
 function walk(root, { files, dirs }, rel = "") {
   for (const d of readdirSync(join(root, rel), { withFileTypes: true })) {
     const r = rel ? `${rel}/${d.name}` : d.name;
-    if (d.name === ".git" || d.name === "node_modules") continue;
+    if (d.name === ".git" || outsideRecord(d.name)) continue;
     const abs = join(root, r);
     const st = lstatSync(abs);
     if (st.isDirectory()) { dirs.set(r, { atimeMs: st.atimeMs, mtimeMs: st.mtimeMs }); walk(root, { files, dirs }, r); }
@@ -233,8 +239,12 @@ export function adopt(dirIn, { map = {}, filing = null, owner = "", agentName =
   if (existsSync(join(dir, "evda.json"))) throw refuse(`${dir} already holds evda.json, so it is already an EVDA. Nothing was written. \`evda update\` keeps it current.`, "ALREADY_ADOPTED");
   const p = proposeAdoption(dir, { map });
   const questions = adoptQuestions(p);
+  const agentsText = fillOwnerSection(render("AGENTS.md"), { agentName, owner, purpose: "", voice: "", ai: "" });
   const result = { dir, dry, proposal: p, questions, lines: proposalLines(p) };
-  if (dry) return result;
+  if (dry) {
+    const rd = ensureReadme(dir, { agents: agentsText, dry: true });
+    return { ...result, readme: rd, lines: [...result.lines, `  ${dryReadmeLine(rd)}`] };
+  }
   if (questions.length) throw new EvdaError(["REFUSED: some folders need your answer before anything is written. Nothing was written.", ...questions.map((q) => `  ${q}`)].join("\n"), { code: "NEEDS_ANSWERS", exit: 2 });
   for (const f of ["AGENTS.md"]) if (existsSync(join(dir, f))) throw refuse(`${f} is already in ${dir}, and the adopt writes its own; it never overwrites a file of yours. Rename it, or map it by hand in evda.json. Nothing was written.`, "AGENTS_EXISTS");
 
@@ -267,7 +277,10 @@ export function adopt(dirIn, { map = {}, filing = null, owner = "", agentName =
   if (filing) manifest.filing = filing;
   writeNew("evda.json", JSON.stringify(manifest, null, 2) + "\n");
   // 3. The operating layer, the one create-evda ships, with the owner section filled from the answers.
-  writeNew("AGENTS.md", fillOwnerSection(render("AGENTS.md"), { agentName, owner, purpose: "", voice: "", ai: "" }));
+  writeNew("AGENTS.md", agentsText);
+  // 3b. The README sections AGENTS.md cites (HQ-2812): appended as one marked block, or the whole
+  // README when there is none. The owner's text is never touched.
+  const readme = ensureReadme(dir, { agents: agentsText });
   // 4. Loaders. The owner's CLAUDE.md is theirs: one line is added at its end and nothing else changes.
   const claude = join(dir, "CLAUDE.md");
   let claudeAdded = null;
@@ -313,7 +326,7 @@ export function adopt(dirIn, { map = {}, filing = null, owner = "", agentName =
     const kept = before.kept.get(rel);
     if (kept ? kept.equals(buf) : was.size === st.size && was.mtimeMs === st.mtimeMs) continue;
     if (!kept) { unexpected.push(rel); continue; }
-    modified.push({ path: rel, before: kept.toString("base64"), mode: was.mode, atimeMs: was.atimeMs, mtimeMs: was.mtimeMs, sha256: sha256(buf), ...(rel === "CLAUDE.md" && claudeAdded ? { added: claudeAdded } : {}) });
+    modified.push({ path: rel, before: kept.toString("base64"), mode: was.mode, atimeMs: was.atimeMs, mtimeMs: was.mtimeMs, sha256: sha256(buf), ...(rel === "CLAUDE.md" && claudeAdded ? { added: claudeAdded } : {}), ...(rel === README_REL && readme.added ? { added: readme.added, block: true } : {}) });
   }
   const dirs = [...after.dirs.keys()].filter((d) => !before.dirs.has(d));
   const dirTimes = [...before.dirs].filter(([d]) => existsSync(join(dir, d))).map(([d, t]) => ({ path: d, ...t }));
@@ -337,7 +350,7 @@ export function adopt(dirIn, { map = {}, filing = null, owner = "", agentName =
     `adopted ${dir} in place. Nothing moved.`,
     ...proposalLines(p).slice(1),
     `  wrote    ${created.length} new file(s): ${created.map((c) => c.path).join(", ")}`,
-    `  changed  ${modified.length} file(s) of yours: ${modified.map((m) => m.path + (m.added ? " (one line added at the end)" : "")).join(", ") || "none"}`,
+    `  changed  ${modified.length} file(s) of yours: ${modified.map((m) => m.path + (m.block ? ` (EVÐA's block added at the end: ${readme.citations.map((c) => `"${c}"`).join(", ")})` : m.added ? " (one line added at the end)" : "")).join(", ") || "none"}`,
     ...(dirs.length ? [`  made     ${dirs.length} folder(s): ${dirs.join(", ")}`] : []),
     ...hookLines.map((l) => `  ${l}`),
     `  filing:  ${filing === "everything" ? "everything you say is filed automatically" : filing === "asked" ? "only when you ask" : "not answered yet; your agent asks the first time you connect"}`,
@@ -360,6 +373,14 @@ export function connectLines(dir, filing) {
   return out;
 }
 
+// What a dry run says about README.md, naming the sections it would add.
+function dryReadmeLine(r) {
+  const names = r.citations.map((c) => `"${c}"`).join(", ");
+  if (r.action === "written") return `${README_REL}: would be written, with ${names}`;
+  if (r.action === "appended") return `${README_REL}: EVÐA's block would be added at the end, with ${names}; your text above it stays as it is`;
+  return `${README_REL}: already has ${names}; left alone`;
+}
+
 // ---- revert ----
 
 export function loadAdoptManifest(path) {
@@ -406,7 +427,14 @@ export function revertAdopt(path, { force = false, now = new Date(), env = proce
   for (const f of m.modified) {
     const a = join(root, f.path);
     if (hashOf(a) === f.sha256) continue;
-    if (f.added && existsSync(a) && withoutLine(readFileSync(a, "utf8"), f.added) !== null) { ownerEdits.push(f.path); continue; }
+    if (f.block && existsSync(a)) {
+      // The README block: refreshed by `evda upgrade` and nothing else, the bytes before come back
+      // whole; edited around by the owner, their edits stay and only the block goes.
+      const rest = withoutBlock(readFileSync(a, "utf8"), f.added);
+      if (rest !== null && Buffer.from(rest).equals(Buffer.from(f.before, "base64"))) continue;
+      if (rest !== null) { ownerEdits.push(f.path); continue; }
+    }
+    if (f.added && !f.block && existsSync(a) && withoutLine(readFileSync(a, "utf8"), f.added) !== null) { ownerEdits.push(f.path); continue; }
     edited.push(f.path);
   }
   if (edited.length && !force && !falsified("revert-ignores-edits")) {
@@ -421,7 +449,7 @@ export function revertAdopt(path, { force = false, now = new Date(), env = proce
       const st = existsSync(a) ? statSync(a) : null;
       if (ownerEdits.includes(f.path) && !force) {
         // Their edits stay: only the line the adopt added is taken out.
-        writeFileSync(a, withoutLine(readFileSync(a, "utf8"), f.added));
+        writeFileSync(a, f.block ? withoutBlock(readFileSync(a, "utf8"), f.added) : withoutLine(readFileSync(a, "utf8"), f.added));
         if (st) utimesSync(a, st.atimeMs / 1000, st.mtimeMs / 1000);
       } else {
         mkdirSync(dirname(a), { recursive: true });
@@ -460,7 +488,7 @@ export function revertAdopt(path, { force = false, now = new Date(), env = proce
 export function revertLines(r) {
   const out = [`Reverted the adopt of ${r.target}.`, `  removed  ${r.removed} file(s) the adopt wrote`, `  restored ${r.restored} file(s) of yours to their bytes before it`];
   if (r.derived) out.push(`  removed  .evda/, which the adopt made, with ${r.derived} file(s) the tooling wrote into it since`);
-  for (const f of r.ownerEdits) out.push(`  kept     your edits to ${f}; only the ${CLAUDE_LINE} line the adopt added was taken out`);
+  for (const f of r.ownerEdits) out.push(`  kept     your edits to ${f}; only the ${f === README_REL ? "EVÐA block" : `${CLAUDE_LINE} line`} the adopt added was taken out`);
   if (r.forced) out.push(`  forced   ${r.edited.length} file(s) edited since the adopt were reverted anyway: ${r.edited.join(", ")}`);
   for (const d of r.kept) out.push(`  kept     ${d}/, which holds files the adopt did not write`);
   if (r.gone.length) out.push(`  gone     ${r.gone.length} file(s) were already removed`);

package/lib/attested-host.mjs

@@ -9,13 +9,19 @@
 // The protocol, version 1. Over TLS to the host, on one connection:
 //   client -> host  POST /.well-known/evda-attestation  {"v":1,"nonce":"<base64, 32 bytes>"}
 //   host -> client  {"v":1,"platform":"tdx","quote":"<base64>","collateral":{tcbInfo,
-//                    tcbInfoIssuerChain,qeIdentity,qeIdentityIssuerChain}}
+//                    tcbInfoIssuerChain,qeIdentity,qeIdentityIssuerChain},
+//                    "wrapKey":"<base64, 32 bytes, optional>"}
 // The VM puts reportDataFor(nonce, its TLS public key) in the quote's REPORTDATA. The client takes the
 // TLS key from the connection it is holding, never from the response body, so a host cannot name a key
 // other than the one it is actually serving with. Delivery then goes over a connection pinned to that
 // key (SHA-256 of its SPKI DER); a connection presenting any other key is refused before anything is
 // written to it.
 //
+// A host that will receive circle keys also names `wrapKey`, the X25519 public key it made inside the
+// VM, and binds it into REPORTDATA beside the nonce and TLS key (reportDataFor's second form). The
+// client has to take that key from the body, so the binding is what makes it trustworthy: a key the
+// quote does not bind is refused as NOT_BOUND. lib/attested-wrap.mjs wraps circle keys to it.
+//
 // The pinned measurement is the client's own configuration, never something a host supplies. With no
 // pinned measurement the gate refuses: an unconfigured client is not a client that trusts everyone.
 //
@@ -45,6 +51,8 @@ export const REFUSAL = Object.freeze({
   NOT_PROVEN: "not-proven",
   WRONG_CONNECTION: "wrong-connection",
   NOT_DELIVERED: "not-delivered",
+  NO_WRAP_KEY: "no-wrap-key",
+  NOTHING_TO_WRAP: "nothing-to-wrap",
 });
 
 // What a person reads. Each says that nothing was sent and why, in words that need no TDX.
@@ -59,12 +67,14 @@ const SAID = {
   [REFUSAL.NOT_PROVEN]: "the server could not prove it is a locked, up to date part of the chip",
   [REFUSAL.WRONG_CONNECTION]: "the connection is not the one the server proved, so someone else could be in the middle",
   [REFUSAL.NOT_DELIVERED]: "the server was proven, and sending to it then failed",
+  [REFUSAL.NO_WRAP_KEY]: "the server did not prove it made a key of its own to receive your keys",
+  [REFUSAL.NOTHING_TO_WRAP]: "no keys were named to send",
 };
 
 const sha256Hex = (b) => createHash("sha256").update(b).digest("hex");
 
 /** A refusal: nothing was sent. `reason` is the detail for a log, `message` the sentence for a person. */
-function refuse(code, reason) {
+export function refuse(code, reason) {
   return { ok: false, sent: false, code, reason, message: `Nothing was sent: ${SAID[code]}.` };
 }
 
@@ -122,7 +132,13 @@ export function parseAttestationResponse(body) {
   if (r.platform !== "tdx") return { error: `the response is for platform ${JSON.stringify(r.platform ?? null)}, not tdx` };
   if (typeof r.quote !== "string" || r.quote.length === 0) return { error: "the response carries no quote", missing: true };
   if (!/^[A-Za-z0-9+/]+={0,2}$/.test(r.quote)) return { error: "the quote is not base64" };
-  return { quote: Buffer.from(r.quote, "base64"), collateral: r.collateral ?? null };
+  let wrapKey = null;
+  if (r.wrapKey != null) {
+    if (typeof r.wrapKey !== "string" || !/^[A-Za-z0-9+/]+={0,2}$/.test(r.wrapKey)) return { error: "the wrap key is not base64" };
+    wrapKey = Buffer.from(r.wrapKey, "base64");
+    if (wrapKey.length !== 32) return { error: `the wrap key is ${wrapKey.length} bytes, not 32` };
+  }
+  return { quote: Buffer.from(r.quote, "base64"), collateral: r.collateral ?? null, wrapKey };
 }
 
 // The verifier's reasons, sorted into what a person needs to know. The tests hold one case per code,
@@ -173,26 +189,28 @@ export function createAttestedHostGate({ policy, nonces = createNonceBook(), clo
       if (!answer.tlsPublicKey) return refuse(REFUSAL.WRONG_CONNECTION, "the transport did not report the TLS key of the connection the quote came over");
 
       const v = verifyTdxAttestation({
-        quote: parsed.quote, nonce, nonces, tlsPublicKey: answer.tlsPublicKey,
+        quote: parsed.quote, nonce, nonces, tlsPublicKey: answer.tlsPublicKey, wrapPublicKey: parsed.wrapKey ?? undefined,
         expected: policy.measurements, minTcb: policy.minTcb, collateral: parsed.collateral, now: clock(), trust,
       });
       if (!v.ok) return refuse(classify(v.reason), v.reason);
-      return session({ pin: v.tlsPublicKeySha256, measurements: v.measurements, tcb: v.tcb });
+      return session({ pin: v.tlsPublicKeySha256, measurements: v.measurements, tcb: v.tcb, wrapKey: v.wrapPublicKey ?? null });
     },
   };
 }
 
-function session({ pin, measurements, tcb }) {
+function session({ pin, measurements, tcb, wrapKey }) {
   return {
     ok: true,
     pin,
     measurements,
     tcb,
+    // The VM's key-wrapping key, only when the quote bound it; null when the host named none.
+    wrapKey,
     async send(payload, { deliver } = {}) {
       if (typeof deliver !== "function") return refuse(REFUSAL.NOT_DELIVERED, "no delivery transport was given");
       let bytes;
       try {
-        bytes = typeof payload === "function" ? await payload({ pin, measurements }) : payload;
+        bytes = typeof payload === "function" ? await payload({ pin, measurements, wrapKey }) : payload;
       } catch (err) {
         return refuse(REFUSAL.NOT_DELIVERED, `the payload could not be prepared: ${err?.message ?? err}`);
       }

package/lib/attested-wrap.mjs

@@ -0,0 +1,147 @@
+// Circle keys go to a hosted EVÐA only sealed to a key born inside the attested VM. (HQ-2083, Spec 08
+// section 8: the VM holds a person's circle keys and EVÐA's operators cannot read them.)
+//
+// The VM side, createEnclaveKey(): the VM makes an X25519 key pair when it starts, keeps the private
+// half in this closure (inside TDX-encrypted memory on a c3 VM), and puts the public half into every
+// quote's REPORTDATA beside the nonce and TLS key (tdx-attestation.mjs reportDataFor, second form). It
+// names the public half as `wrapKey` in its attestation answer (lib/attested-host.mjs).
+//
+// The client side, wrapCircleKeysTo(session, ...): `session` is what gate.open returned. Only a session
+// whose quote verified under the pinned measurement AND bound the wrap key gets anything; the client's
+// key holder is not asked to seal a single circle key before that. The holder is the HostCrypto shape
+// every EVÐA device already has (`sealCircleKeyTo(circleId, epoch, publicKey)`, contracts/src/host.ts),
+// so the raw scalar never passes through this file on a real device.
+//
+// The envelope is the circle key delivery wire (xania/seal/v1, the same bytes `sealCircleKeyTo` makes
+// and `importCircleKey` opens, pinned by ekati's circle-seal vectors):
+//   [version 0x01][ephemeral X25519 public:32][ChaCha20-Poly1305 ciphertext][tag:16]
+//   key||nonce = HKDF-SHA256(ECDH, salt empty, info "xania/seal/v1" || ephemeral public || recipient public, 44)
+//   AAD = the 33-byte header.
+// sealToKey and openSealed are the dependency-free copies person-record and the VM use; the test opens
+// the frozen vectors with them, so a drift from the wire fails there.
+//
+// The payload the client delivers, version 1:
+//   { "v": 1, "wrapKey": "<base64>", "keys": [{ "circleId", "epoch", "sealedKey": "<base64>" }] }
+//
+// Not here yet: the Swift port of the client side in iris-mobile, the VM's server that holds what it
+// unwrapped, and a signed key-delivery string (the relay path signs deliveries because a relay could
+// plant a key; here the gate's pinned TLS key carries the payload, so the host is already the proven VM).
+
+import { createCipheriv, createDecipheriv, createPublicKey, diffieHellman, generateKeyPairSync, hkdfSync } from "node:crypto";
+import { REFUSAL, refuse } from "./attested-host.mjs";
+import { reportDataFor } from "./tdx-attestation.mjs";
+
+/** The length of a key-wrapping public key: raw X25519. */
+export const WRAP_KEY_BYTES = 32;
+
+/** The version of the wrapped-keys payload. */
+export const WRAPPED_KEYS_VERSION = 1;
+
+const SEAL_VERSION = 1;
+const SEAL_KDF_DOMAIN = Buffer.from("xania/seal/v1", "utf8");
+const X25519_SPKI_PREFIX = Buffer.from("302a300506032b656e032100", "hex");
+
+const rawPublic = (keyObject) => keyObject.export({ type: "spki", format: "der" }).subarray(-32);
+const x25519Public = (raw) => {
+  const b = Buffer.from(raw);
+  if (b.length !== WRAP_KEY_BYTES) throw new Error(`an X25519 public key is 32 bytes, not ${b.length}`);
+  return createPublicKey({ key: Buffer.concat([X25519_SPKI_PREFIX, b]), format: "der", type: "spki" });
+};
+
+function sealDerive(shared, ephemeralPublic, recipientPublic) {
+  const okm = Buffer.from(hkdfSync("sha256", shared, Buffer.alloc(0), Buffer.concat([SEAL_KDF_DOMAIN, ephemeralPublic, recipientPublic]), 44));
+  return { key: okm.subarray(0, 32), nonce: okm.subarray(32, 44) };
+}
+
+/** Seals `plaintext` to the raw X25519 `recipientPublicKey`, with a fresh ephemeral key per call. */
+export function sealToKey(recipientPublicKey, plaintext) {
+  const recipient = Buffer.from(recipientPublicKey);
+  const ephemeral = generateKeyPairSync("x25519");
+  const ephemeralPublic = rawPublic(ephemeral.publicKey);
+  const shared = diffieHellman({ privateKey: ephemeral.privateKey, publicKey: x25519Public(recipient) });
+  const header = Buffer.concat([Buffer.from([SEAL_VERSION]), ephemeralPublic]);
+  const { key, nonce } = sealDerive(shared, ephemeralPublic, recipient);
+  const cipher = createCipheriv("chacha20-poly1305", key, nonce, { authTagLength: 16 });
+  cipher.setAAD(header, { plaintextLength: plaintext.length });
+  const body = Buffer.concat([cipher.update(Buffer.from(plaintext)), cipher.final()]);
+  return Buffer.concat([header, body, cipher.getAuthTag()]);
+}
+
+/** Opens an envelope with the X25519 private KeyObject it was sealed to. Throws when it does not open. */
+export function openSealed(privateKey, envelope) {
+  const buf = Buffer.from(envelope);
+  if (buf.length < 1 + 32 + 16) throw new Error(`the envelope is ${buf.length} bytes, too short to be one`);
+  if (buf[0] !== SEAL_VERSION) throw new Error(`unknown envelope version ${buf[0]}`);
+  const header = buf.subarray(0, 33);
+  const ephemeralPublic = buf.subarray(1, 33);
+  const ciphertext = buf.subarray(33, buf.length - 16);
+  const shared = diffieHellman({ privateKey, publicKey: x25519Public(ephemeralPublic) });
+  const { key, nonce } = sealDerive(shared, ephemeralPublic, rawPublic(createPublicKey(privateKey)));
+  const decipher = createDecipheriv("chacha20-poly1305", key, nonce, { authTagLength: 16 });
+  decipher.setAAD(header, { plaintextLength: ciphertext.length });
+  decipher.setAuthTag(buf.subarray(buf.length - 16));
+  return Buffer.concat([decipher.update(ciphertext), decipher.final()]);
+}
+
+// ─── the VM ──────────────────────────────────────────────────────────────────────────────────────
+
+/**
+ * The VM's key-wrapping key, made inside the VM. Returns a frozen object holding the public half and two
+ * functions; the private half is reachable only through them.
+ *   reportDataFor(nonce, tlsPublicKey): the REPORTDATA the VM asks the TDX module to sign.
+ *   unwrapAll(payload): opens a wrapped-keys payload addressed to this key. Throws when the payload
+ *     names another key or any envelope does not open. Returns [{ circleId, epoch, scalar }].
+ */
+export function createEnclaveKey() {
+  const pair = generateKeyPairSync("x25519");
+  const publicKey = rawPublic(pair.publicKey);
+  return Object.freeze({
+    publicKey,
+    reportDataFor: (nonce, tlsPublicKey) => reportDataFor(nonce, tlsPublicKey, publicKey),
+    unwrapAll(payload) {
+      if (payload?.v !== WRAPPED_KEYS_VERSION) throw new Error(`the payload speaks version ${JSON.stringify(payload?.v ?? null)}, not ${WRAPPED_KEYS_VERSION}`);
+      if (!Buffer.from(String(payload.wrapKey ?? ""), "base64").equals(publicKey)) throw new Error("the payload was wrapped to another key");
+      if (!Array.isArray(payload.keys)) throw new Error("the payload carries no keys");
+      return payload.keys.map((k) => {
+        const scalar = openSealed(pair.privateKey, Buffer.from(String(k.sealedKey ?? ""), "base64"));
+        if (scalar.length !== 32) throw new Error("a circle key is 32 bytes");
+        return { circleId: k.circleId, epoch: k.epoch, scalar };
+      });
+    },
+  });
+}
+
+// ─── the client ──────────────────────────────────────────────────────────────────────────────────
+
+function circlesProblem(circles) {
+  if (!Array.isArray(circles) || circles.length === 0) return "no circle keys were named";
+  for (const c of circles) {
+    if (typeof c?.circleId !== "string" || c.circleId.length === 0) return "a circle key was named without its circle";
+    if (!Number.isInteger(c.epoch) || c.epoch < 1) return `circle ${c.circleId} was named with epoch ${JSON.stringify(c.epoch ?? null)}, not a whole number from 1`;
+  }
+  return null;
+}
+
+/**
+ * Wraps the named circle keys to the attested VM's own key and delivers them once over the attested
+ * connection. `session` is gate.open's result; `crypto` has `sealCircleKeyTo(circleId, epoch, publicKey)`;
+ * `circles` is [{ circleId, epoch }]; `deliver` is the transport session.send takes.
+ * Returns session.send's result, or a refusal with nothing sealed and nothing sent.
+ */
+export async function wrapCircleKeysTo(session, { crypto, circles, deliver } = {}) {
+  if (!session?.ok) return session?.code ? session : refuse(REFUSAL.NOT_PROVEN, "no attested session was given");
+  const wrapKey = session.wrapKey;
+  if (!wrapKey) return refuse(REFUSAL.NO_WRAP_KEY, "the host's quote bound no key-wrapping key");
+  if (Buffer.from(wrapKey).length !== WRAP_KEY_BYTES) return refuse(REFUSAL.NO_WRAP_KEY, "the session's wrap key is not 32 bytes");
+  const problem = circlesProblem(circles);
+  if (problem) return refuse(REFUSAL.NOTHING_TO_WRAP, problem);
+  if (typeof crypto?.sealCircleKeyTo !== "function") return refuse(REFUSAL.NOTHING_TO_WRAP, "no key holder was given to seal the circle keys");
+  return session.send(async ({ wrapKey: bound }) => {
+    const keys = [];
+    for (const { circleId, epoch } of circles) {
+      const sealed = await crypto.sealCircleKeyTo(circleId, epoch, new Uint8Array(bound));
+      keys.push({ circleId, epoch, sealedKey: Buffer.from(sealed).toString("base64") });
+    }
+    return { v: WRAPPED_KEYS_VERSION, wrapKey: Buffer.from(bound).toString("base64"), keys };
+  }, { deliver });
+}

package/lib/checkout-freshness.mjs

@@ -0,0 +1,88 @@
+// Is the doctor that is about to give a verdict the doctor on origin/main? (HQ-2736)
+//
+// On 2026-10-19 a session checked a vault change with `evda doctor` from a checkout sitting on a
+// branch merged two weeks earlier, read exit 0, and the change broke every evda PR's Argus
+// baseline, because the doctor on origin/main refused what the stale one passed. The verdict was
+// true of the code that ran; nothing said that code was not main's.
+//
+// So the doctor says, before its verdict, when its own checkout is behind origin/main or not on
+// main. It says nothing on current main. It never changes the exit code: the exit is the record's
+// verdict, and Argus runs the doctor from PR branches, where "not on main" is the expected state.
+//
+// The comparison target is origin/main after one bounded `git fetch` (FETCH_TIMEOUT_MS, no
+// prompts, ssh in batch mode), because the local ref alone goes stale with the checkout: a
+// checkout nobody fetched in two weeks would compare equal to its own two-week-old origin/main
+// and read as current, which is the same false clean. A fetch only moves remote-tracking refs,
+// never the working tree. EVDA_DOCTOR_FETCH=0 skips it and compares against the ref as last
+// fetched, and says so. A failed fetch, no origin remote, or no git at all still lets every check
+// run; the doctor then says it could not compare, and why.
+
+import { spawnSync } from "node:child_process";
+
+export const FETCH_TIMEOUT_MS = 5000;
+const GIT_TIMEOUT_MS = 3000;
+
+function git(root, args, timeout = GIT_TIMEOUT_MS, env = process.env) {
+  const r = spawnSync("git", ["-C", root, ...args], { encoding: "utf8", timeout, env, stdio: ["ignore", "pipe", "pipe"] });
+  if (r.error) return { ok: false, out: "", err: r.error.code === "ETIMEDOUT" ? `timed out after ${timeout}ms` : String(r.error.message) };
+  // git's reason is its first `fatal:` line; the lines after it are advice ("and the repository exists.").
+  const errLines = (r.stderr ?? "").trim().split("\n").filter(Boolean);
+  const err = (errLines.find((l) => l.startsWith("fatal:")) ?? errLines[0] ?? "").replace(/^fatal:\s*/, "");
+  return { ok: r.status === 0, out: (r.stdout ?? "").trim(), err };
+}
+
+const short = (sha) => sha.slice(0, 7);
+
+// Returns { state, lines }. `lines` is what the doctor prints; it is empty exactly when the
+// checkout is main at origin/main as of a fetch that just succeeded.
+// state: "current" | "behind" | "off-main" | "not-compared" | "not-a-checkout"
+export function checkoutFreshness(root, { fetch = process.env.EVDA_DOCTOR_FETCH !== "0", fetchTimeoutMs = FETCH_TIMEOUT_MS } = {}) {
+  const top = git(root, ["rev-parse", "--show-toplevel"]);
+  if (!top.ok) {
+    return { state: "not-a-checkout", lines: [`could not compare this doctor against origin/main: ${root} is not a git checkout (an installed or copied doctor). Its verdict is this copy's.`] };
+  }
+  const head = git(root, ["rev-parse", "HEAD"]);
+  if (!head.ok) return { state: "not-compared", lines: [`could not compare this doctor against origin/main: the checkout has no commit (${head.err}).`] };
+  const branch = git(root, ["symbolic-ref", "--short", "-q", "HEAD"]).out || null;
+  const where = branch ? `branch ${branch}` : "a detached HEAD";
+
+  if (!git(root, ["remote", "get-url", "origin"]).ok) {
+    return { state: "not-compared", lines: [`could not compare this doctor against origin/main: the checkout has no origin remote. It runs from ${where} at ${short(head.out)}.`] };
+  }
+
+  let fetchNote = null;
+  if (fetch) {
+    const env = { ...process.env, GIT_TERMINAL_PROMPT: "0" };
+    if (!env.GIT_SSH_COMMAND) env.GIT_SSH_COMMAND = "ssh -o BatchMode=yes -o ConnectTimeout=3";
+    const f = git(root, ["fetch", "--quiet", "--no-tags", "origin", "main"], fetchTimeoutMs, env);
+    if (!f.ok) fetchNote = `git fetch failed (${f.err || "no reason given"})`;
+  } else {
+    fetchNote = "fetch skipped (EVDA_DOCTOR_FETCH=0)";
+  }
+
+  const ref = git(root, ["rev-parse", "--verify", "-q", "refs/remotes/origin/main"]);
+  if (!ref.ok) {
+    return { state: "not-compared", lines: [`could not compare this doctor against origin/main: ${fetchNote ?? "the fetch succeeded"} and there is no origin/main ref. It runs from ${where} at ${short(head.out)}.`] };
+  }
+  const behind = Number(git(root, ["rev-list", "--count", `HEAD..${ref.out}`]).out || 0);
+  const ahead = Number(git(root, ["rev-list", "--count", `${ref.out}..HEAD`]).out || 0);
+  const onMain = branch === "main";
+  const against = fetchNote ? `origin/main as last fetched (${short(ref.out)}; ${fetchNote}, so main may be further ahead)` : `origin/main ${short(ref.out)}`;
+
+  const lines = [];
+  let state;
+  if (behind > 0) {
+    state = "behind";
+    lines.push(`this doctor runs from ${where} at ${short(head.out)}, ${behind} commit(s) behind ${against}. Its verdict can differ from main's; rerun from an up-to-date main before trusting it.`);
+  } else if (!onMain) {
+    state = "off-main";
+    lines.push(`this doctor runs from ${where} at ${short(head.out)}, not main (${ahead} commit(s) ahead of ${against}). Its verdict is this branch's, which main may not share.`);
+  } else {
+    state = "current";
+  }
+  if (fetchNote && state === "current") {
+    state = "not-compared";
+    lines.push(`could not compare this doctor against current origin/main: ${fetchNote}. It matches ${against.replace(/ \(.*$/, "")} at ${short(ref.out)}.`);
+  }
+  return { state, lines };
+}

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