create-evda 0.1.9 → 0.1.11

package/lib/connector-tools.mjs

@@ -0,0 +1,85 @@
+// New tools in a chat app (HQ-2205, the last step). A chat app keeps a connector's tool list and the
+// permission set on each tool, and the permissions a person set before do not cover a tool that came
+// later: a call to it can be refused, or held for approval, without the model being told why. Adding
+// or renaming a tool on this server is exactly that. So the server remembers, per record and per
+// chat app, every tool name it has offered that app, and the first time it offers a name the app has
+// never been offered, the next tool result says so once, in plain words, with where the permissions
+// are set. Then the name joins the remembered list and is never raised again in that app.
+//
+// Only names count. A permission belongs to a tool's name, so a changed description needs nothing,
+// and a tool that left the list (evda_every_chat once the owner answered it) needs nothing either.
+// One that comes back is not new: the app was offered it before.
+//
+// A first connection is told nothing: the person is setting permissions for the first time, and the
+// setup already says where (ALWAYS_ALLOW_LINE in lib/mcp.mjs). It only remembers what was offered.
+//
+// Where it is kept: `<record>/.evda/connector-tools.json`, the record's own state, which sync never
+// sends to another holder (sync-rules EXCLUDE_ROOT_NAMES) and nothing reads as the owner's words. It
+// is bookkeeping about what was offered an app, kept with the record rather than the computer because
+// an app's permissions belong to the owner's account in that app, whichever computer serves it. Lost,
+// it costs one notice: the next connection is taken for a first one and remembers the list again.
+//
+//   { "claude": { "tools": ["evda_read", ...], "date": "2026-10-18" } }
+
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { CHAT_APPS } from "./every-chat.mjs";
+
+export const CONNECTOR_TOOLS_FILE = "connector-tools.json";
+
+// Where each app sets a connector's tool permissions. Claude's is the one this package already gives
+// in setup (ALWAYS_ALLOW_LINE); an app whose page has not been read gets the general words, because
+// naming a menu that does not exist would send them hunting for it.
+export const PERMISSIONS_WHERE = {
+  claude: "claude.ai Settings, Connectors, EVÐA, tool permissions",
+};
+export const GENERIC_PERMISSIONS_WHERE = "the EVÐA connector's settings in their app, where each tool's permission is set";
+
+export const CONNECTOR_TOOLS = join(".evda", CONNECTOR_TOOLS_FILE);
+export function connectorToolsPath(evda) {
+  return typeof evda?.dir === "string" && evda.dir ? join(evda.dir, CONNECTOR_TOOLS) : null;
+}
+
+function readSeen(path) {
+  try {
+    const all = JSON.parse(readFileSync(path, "utf8"));
+    return all && typeof all === "object" && !Array.isArray(all) ? all : {};
+  } catch { return {}; }
+}
+
+function writeSeen(path, all) {
+  mkdirSync(join(path, ".."), { recursive: true });
+  const part = `${path}.${process.pid}.tmp`;
+  writeFileSync(part, `${JSON.stringify(all, null, 2)}\n`);
+  renameSync(part, path);
+}
+
+// Compare what this app is offered now against every name it was offered before, and remember the
+// union. Returns the names it has never been offered, or [] on a first connection, an unchanged
+// list, or no record to keep the list in.
+export function newToolsFor(evda, app, offered, { now = new Date() } = {}) {
+  if (!app) return [];
+  const path = connectorToolsPath(evda);
+  if (!path) return [];
+  const all = readSeen(path);
+  const before = Array.isArray(all[app]?.tools) ? all[app].tools.filter((n) => typeof n === "string") : null;
+  const names = [...new Set(offered)].sort();
+  const fresh = before ? names.filter((n) => !before.includes(n)) : [];
+  if (before && !fresh.length) return [];
+  all[app] = { tools: [...new Set([...(before ?? []), ...names])].sort(), date: now.toISOString().slice(0, 10) };
+  writeSeen(path, all);
+  return fresh;
+}
+
+// What the model reads, after the tool's own result, the once an app is offered new tools. `titles`
+// maps a tool name to the title the app shows the person beside its permission.
+export function newToolsNotice(app, names, titles = {}) {
+  const label = CHAT_APPS[app]?.label ?? "this app";
+  const where = PERMISSIONS_WHERE[app] ?? GENERIC_PERMISSIONS_WHERE;
+  const list = names.map((n) => (titles[n] ? `${titles[n]} (${n})` : n)).join(", ");
+  return [
+    `## New EVÐA tools in ${label}`,
+    "",
+    `EVÐA has tools ${label} was not offered before: ${list}. A chat app keeps the tool permissions the owner set when they connected, and those do not cover a tool added later, so a call to one of these can be refused or held without saying why. Once, after answering what they asked, tell them in a sentence or two: EVÐA added tools, and to use them they should open ${where} and set the new ones to allow. If a call to one of these tools fails in this chat, tell them this is the likely reason rather than trying it again. This is said once in ${label} and not again.`,
+  ].join("\n");
+}

package/lib/corrections.mjs

@@ -0,0 +1,34 @@
+// Where a correction lands (HQ-2325). By default it is one dated line in the operating layer's
+// "## What I have been taught". A record that keeps that list in its own file names it in evda.json:
+//
+//   "corrections": "<path to a Markdown file, relative to the record>"
+//
+// and evda_record_correction appends a dated section there instead. The owner's vault keeps its list
+// in a Schema Friction Log that CLAUDE.md names as its "What I have been taught", so without this
+// every correction from a chat app was refused and lost. Doctor reads the same setting through this
+// one function, so the tool and the check cannot disagree on what a valid setting is.
+
+import { existsSync, statSync } from "node:fs";
+import { isAbsolute, relative, resolve, sep } from "node:path";
+import { isSealed } from "./circles.mjs";
+
+export const CORRECTIONS_KEY = "corrections";
+
+// null when evda.json does not set it. Otherwise { rel, abs, problem }: problem is null when the
+// setting names an existing, unsealed Markdown file inside the record, and a plain sentence when not.
+export function correctionsTarget(evda) {
+  const value = evda.manifest?.[CORRECTIONS_KEY];
+  if (value === undefined) return null;
+  const bad = (problem, rel = String(value)) => ({ rel, abs: null, problem });
+  if (typeof value !== "string" || value.trim() === "") return bad(`"${CORRECTIONS_KEY}" must be the path of a Markdown file, relative to the record.`);
+  const want = value.trim();
+  if (isAbsolute(want)) return bad(`"${CORRECTIONS_KEY}" is ${want}, an absolute path; it names a file relative to the record.`, want);
+  const root = resolve(evda.dir);
+  const abs = resolve(root, want);
+  if (!abs.startsWith(root + sep)) return bad(`"${CORRECTIONS_KEY}" is ${want}, which is outside the record.`, want);
+  const rel = relative(root, abs).split("\\").join("/");
+  if (!/\.md$/i.test(abs)) return { rel, abs, problem: `"${CORRECTIONS_KEY}" names ${rel}, which is not a Markdown file.` };
+  if (!existsSync(abs) || !statSync(abs).isFile()) return { rel, abs, problem: `"${CORRECTIONS_KEY}" names ${rel}, and there is no file there, so a correction has nowhere to land.` };
+  if (isSealed(abs)) return { rel, abs, problem: `"${CORRECTIONS_KEY}" names ${rel}, which is sealed, so no agent writes a correction into it.` };
+  return { rel, abs, problem: null };
+}

package/lib/credentials-migrate.mjs

@@ -0,0 +1,120 @@
+// One-time move of Credentials/ files written before HQ-1916 into the Keychain (HQ-2622).
+//
+// HQ-1916 made `evda gather apply` put each credential value into the login Keychain and leave a
+// pointer in the file. Files already sitting in a record's Credentials/ folder, sealed before that
+// shipped (or kept plain because the Keychain write failed then), still hold their values. This
+// walks Credentials/ once and gives each of those files the same treatment: every value goes into
+// the Keychain, and its line keeps its label with the value replaced by the pointer HQ-1916 writes:
+//   Password: in your Keychain (EVÐA, wifi.md, password)
+//
+// Safe to run again: a line that already holds a pointer is not a value (extractSecrets skips it),
+// so a migrated file has nothing left to move and is not rewritten.
+// All-or-nothing per file: a value is never removed from a file until every value in that file is
+// in the Keychain, and if any write fails, the items this run added for that file are removed again
+// and the file is left byte for byte as it was. Nothing is lost.
+// A Keychain item already at an account with a different value (another file of the same name, or
+// one the owner made by hand) is never overwritten: the value is filed under the next free label,
+// "password 2", and the pointer names that label. One already holding the same value is reused.
+//
+// The Keychain is reached only through lib/keychain.mjs, so EVDA_KEYCHAIN_FALSIFY and a throwaway
+// keychain path work here exactly as they do for gather apply.
+
+import { existsSync, readdirSync, readFileSync, renameSync, statSync, writeFileSync, chmodSync, unlinkSync } from "node:fs";
+import { join } from "node:path";
+import { CREDENTIALS } from "./gather.mjs";
+import { SERVICE, accountFor, addSecret, extractSecrets, keychainAvailable, pointerFor, readSecret, removeSecret } from "./keychain.mjs";
+
+// The label a value is filed under: its own, unless the Keychain already holds a different value
+// there or this file already used it, then "<label> 2", "<label> 3", ... until one is free or
+// already holds this exact value. Returns { label, exists }.
+function freeLabel(fileName, label, value, used, keychainPath) {
+  for (let n = 1; ; n++) {
+    const candidate = n === 1 ? label : `${label} ${n}`;
+    if (used.has(candidate)) continue;
+    let held;
+    try { held = readSecret({ account: accountFor(fileName, candidate), keychainPath }); } catch { return { label: candidate, exists: false }; }
+    if (held === value) return { label: candidate, exists: true };
+  }
+}
+
+// Move one file's values into the Keychain and return its new text, or say why it stays as it is.
+// Returns { status: "moved", text, added, labels } | { status: "unchanged" } | { status: "kept", why }.
+export function migrateText(text, fileName, { keychainPath = null, dry = false } = {}) {
+  const secrets = extractSecrets(text);
+  if (!secrets.length) return { status: "unchanged" };
+  if (dry) return { status: "moved", text: null, added: [], labels: secrets.map((s) => s.label), dry: true };
+  const used = new Set();
+  const added = [];
+  const labels = [];
+  try {
+    for (const s of secrets) {
+      const { label, exists } = freeLabel(fileName, s.label, s.value, used, keychainPath);
+      used.add(label);
+      labels.push(label);
+      if (exists) continue;
+      const account = accountFor(fileName, label);
+      addSecret({ account, value: s.value, keychainPath });
+      added.push(account);
+    }
+  } catch (e) {
+    for (const account of added) removeSecret({ account, keychainPath });
+    return { status: "kept", why: `the Keychain write failed (${String(e.message ?? e).split("\n")[0]})` };
+  }
+  const lines = text.split("\n");
+  secrets.forEach((s, i) => { lines[s.index] = s.whole ? pointerFor(fileName, labels[i]) : `${s.prefix}${pointerFor(fileName, labels[i])}`; });
+  return { status: "moved", text: lines.join("\n"), added, labels };
+}
+
+// Every file directly in <root>/Credentials/, migrated. Never throws for one file's failure.
+// Returns { folder, files: [{ name, status, why?, count? }], moved, unchanged, kept, skipped }.
+export function migrateCredentials(root, { keychainPath = null, dry = false } = {}) {
+  const folder = join(root, CREDENTIALS);
+  const r = { folder, exists: existsSync(folder), available: true, dry, files: [], moved: 0, unchanged: 0, kept: 0, skipped: 0 };
+  if (!r.exists) return r;
+  const names = readdirSync(folder).filter((n) => !n.startsWith(".")).sort();
+  r.available = keychainAvailable();
+  for (const name of names) {
+    const abs = join(folder, name);
+    const st = statSync(abs);
+    if (!st.isFile() || !/\.(md|txt)$/i.test(name)) { r.skipped += 1; r.files.push({ name, status: "skipped", why: st.isFile() ? "not a text note" : "a folder; only files directly in Credentials/ are read" }); continue; }
+    const text = readFileSync(abs, "utf8");
+    if (!extractSecrets(text).length) { r.unchanged += 1; r.files.push({ name, status: "unchanged" }); continue; }
+    if (!r.available) { r.kept += 1; r.files.push({ name, status: "kept", why: "not on macOS, or the Keychain is unavailable" }); continue; }
+    const m = migrateText(text, name, { keychainPath, dry });
+    if (m.status === "kept") { r.kept += 1; r.files.push({ name, status: "kept", why: m.why }); continue; }
+    if (!dry) {
+      // Written beside the original and renamed over it, so the file is never half written.
+      const tmp = join(folder, `.${name}.hq2622-${process.pid}.tmp`);
+      try {
+        writeFileSync(tmp, m.text, { mode: st.mode & 0o7777 });
+        chmodSync(tmp, st.mode & 0o7777);
+        renameSync(tmp, abs);
+      } catch (e) {
+        try { unlinkSync(tmp); } catch { /* never made */ }
+        for (const account of m.added) removeSecret({ account, keychainPath });
+        r.kept += 1;
+        r.files.push({ name, status: "kept", why: `the file could not be rewritten (${String(e.message ?? e).split("\n")[0]})` });
+        continue;
+      }
+    }
+    r.moved += 1;
+    r.files.push({ name, status: "moved", count: m.labels.length });
+  }
+  return r;
+}
+
+// What `evda secret migrate` prints, ending in one CHECKED or SKIPPED line.
+export function migrateLines(r) {
+  if (!r.exists) return [`SKIPPED Credentials: ${r.folder} does not exist, so there is nothing to move`];
+  const out = [];
+  for (const f of r.files) {
+    if (f.status === "moved") out.push(`  ${r.dry ? "would move" : "moved"}  ${f.name}: ${f.count} value(s) ${r.dry ? "would go" : "went"} to the Keychain (${SERVICE}); the file holds a pointer, not the value`);
+    else if (f.status === "kept") out.push(`  kept     ${f.name}: the value stays in the sealed file (${f.why})`);
+    else if (f.status === "skipped") out.push(`  skipped  ${f.name}: ${f.why}`);
+    else out.push(`  done     ${f.name}: no value left in the file`);
+  }
+  const n = r.files.length - r.skipped;
+  if (!n) out.push(`SKIPPED Credentials: ${r.folder} holds no credential file`);
+  else out.push(`CHECKED ${n} credential file(s)  ${r.moved} ${r.dry ? "would move" : "moved"} to the Keychain, ${r.unchanged} already holding no value, ${r.kept} kept in the sealed file`);
+  return out;
+}

package/lib/day-file.mjs

@@ -6,9 +6,10 @@
 // local time) with its one line of context; every later write in the same conversation appends
 // under it, as a new paragraph, with no heading. A conversation is whatever the caller passes as
 // `session`: one MCP session (a stdio process, or one Mcp-Session-Id over HTTP), or one Claude Code
-// session id in the prompt hook. When the file changed since this conversation last wrote to it
-// (another conversation wrote a section, or someone edited it by hand), the next write opens a new
-// heading, so words never land under a heading that is not theirs.
+// session id in the prompt hook. When another conversation wrote a section below this one since,
+// the next write still goes into this conversation's own section, above theirs (HQ-2330), so words
+// never land under a heading that is not theirs and one conversation stays one section. Only a hand
+// edit of the section itself makes the next write open a new heading.
 //
 // FILING. evda.json `filing` is the owner's answer to the one setup question: "everything" (file
 // every message they send, without being asked) or "asked" (only when they ask). Absent means they
@@ -22,7 +23,7 @@
 // EVDA_CHAT_FALSIFY=heading-per-write opens a new heading on every write, for the test that shows
 // one conversation is one section.
 
-import { appendFileSync, closeSync, existsSync, openSync, readFileSync, statSync, unlinkSync, writeSync } from "node:fs";
+import { appendFileSync, closeSync, existsSync, openSync, readFileSync, statSync, unlinkSync, writeFileSync, writeSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 
 export const FILING_MODES = ["everything", "asked"];
@@ -62,6 +63,48 @@ export const localTime = (d) => `${pad(d.getHours())}:${pad(d.getMinutes())}`;
 
 export const contextLine = (context) => `*${CONTEXT_LABEL} ${String(context).trim().replace(/\*/g, "")}*`;
 
+// NAMED ENTRIES (HQ-2799). A write tool's answer names the existing entries the filed words bear on
+// (lib/touches.mjs, HQ-2631), and a conversation named some and added to none of them is asked once.
+// The MCP server keeps what it named per chat; the Stop hook reads the same lines back out of the
+// Claude Code transcript. Both build and parse them here, so the line one writes is the line the
+// other reads, and nothing is stored in the owner's files: the transcript and the chat are the state.
+export const RELATED_LEAD = "These existing entries bear on what you just filed: ";
+export const TICKETS_LEAD = "These open tickets on the board bear on it: ";
+export const ENTRIES_ASK_LEAD = "This conversation was pointed at existing entries and added to none of them:";
+
+export const relatedLine = (related) => `${RELATED_LEAD}${related.map((r) => `${r.path} (named as "${r.name}")`).join("; ")}.`;
+
+export const ticketsLine = (tickets) => `${TICKETS_LEAD}${tickets.map((k) => `${k.id} "${k.title}" (named as "${k.named}")`).join("; ")}.`;
+
+// The open tickets a tool result's text names (HQ-2798's line), as ["HQ-<n>", ...].
+export function ticketsNamedIn(text) {
+  const out = [];
+  for (const line of String(text ?? "").split("\n")) {
+    if (!line.startsWith(TICKETS_LEAD)) continue;
+    for (const m of line.slice(TICKETS_LEAD.length).matchAll(/(?:^|; )(HQ-\d+) "/g)) if (!out.includes(m[1])) out.push(m[1]);
+  }
+  return out;
+}
+
+// The entries a tool result's text names, as [{ path, name }], from its RELATED_LEAD line.
+export function namedIn(text) {
+  const out = [];
+  for (const line of String(text ?? "").split("\n")) {
+    if (!line.startsWith(RELATED_LEAD)) continue;
+    const body = line.slice(RELATED_LEAD.length).replace(/\.$/, "");
+    for (const m of body.matchAll(/(?:^|; )(.+?) \(named as "([^"]*)"\)/g)) out.push({ path: m[1], name: m[2] });
+  }
+  return out;
+}
+
+// Whether a text already carries the ask, so neither surface asks a second time.
+export const askedIn = (text) => String(text ?? "").includes(ENTRIES_ASK_LEAD);
+
+// The ask, naming the entries and tickets. `how` says how this surface adds to an entry.
+export function entriesAsk(paths, how = "evda_append; a person's page with evda_record_person_note", tickets = []) {
+  return `${ENTRIES_ASK_LEAD} ${[...paths, ...tickets].join(", ")}. If what the owner said adds something to one of them, add a dated section to it now (${how})${tickets.length ? ", or update the ticket on the board" : ""}. If nothing new applies, adding nothing is fine. This is asked once.`;
+}
+
 // The bytes one write appends to a day file whose current text is `current` (null when it does not
 // exist yet). `continuing` is true when this conversation's section is the last thing in the file.
 // Returns { text, opened }.
@@ -125,18 +168,84 @@ function withDayLock(fn) {
 }
 
 // Append `words` to the day file at `abs`. `session` is the conversation's mutable state ({} to
-// start one, null for a write that belongs to no conversation, which always opens a heading); it
-// remembers which file this conversation's section is in and how long that file was after its last
-// write. Returns { opened, bytes }.
+// start one, null for a write that belongs to no conversation, which always opens a heading).
+//
+// HQ-2330: the conversation keeps its section, one per file, in `session.sections[abs]`: the
+// section's exact text as this conversation last wrote it (`tail`, from its heading to its last
+// words) and whether it carries a context line. A later write finds that text in the file and goes
+// straight after it: at the end of the file when nothing came after (a plain append, as before),
+// or above whatever another writer added below it since (a read-modify-write under the same lock).
+// Keyed by file, so the agent log and the owner's day each keep their own section in one chat
+// (measured 2026-10-07: a Claude Code session's evda_write_agent_log between two evda_writes left
+// the next write a bare `## 20:41`, and the agent log a bare heading per entry). When the section's
+// text is no longer in the file (edited by hand), the write opens a new heading, and that heading
+// repeats the conversation's context line, so a continuing conversation never has a bare heading.
+// Returns { opened, bytes, inserted }.
 export function appendToDay(abs, { now = new Date(), words, context = null, session = null }) {
   return withDayLock(() => {
     const exists = existsSync(abs);
     const current = exists ? readFileSync(abs, "utf8") : null;
-    const s = session?.section;
-    const continuing = Boolean(s && exists && s.abs === abs && statSync(abs).size === s.size);
-    const w = sectionBytes({ current, date: localDate(now), time: localTime(now), words, context, continuing, contextWritten: Boolean(s?.context) });
+    const mine = session ? sectionOf(session, abs) : null;
+    const at = mine && current !== null && !falsified("heading-per-write") ? current.lastIndexOf(mine.tail) : -1;
+    if (at >= 0) {
+      const body = String(words).replace(/\n+$/, "");
+      const ctx = context && !mine.context ? `${contextLine(context)}\n\n` : "";
+      const add = `\n${ctx}${body}\n`;
+      const end = at + mine.tail.length;
+      if (end === current.length) appendFileSync(abs, add);
+      else writeFileSync(abs, current.slice(0, end) + add + current.slice(end));
+      session.sections[abs] = { tail: mine.tail + add, context: mine.context || Boolean(ctx), line: mine.line ?? (context ? String(context).trim() : null) };
+      return { opened: false, bytes: Buffer.byteLength(add), inserted: end !== current.length };
+    }
+    // A new section. A conversation that already had one here and lost it keeps its context line.
+    const line = context ?? mine?.line ?? null;
+    const w = sectionBytes({ current, date: localDate(now), time: localTime(now), words, context: line, continuing: false });
     appendFileSync(abs, w.text);
-    if (session) session.section = { abs, size: statSync(abs).size, context: Boolean(context) || (continuing && Boolean(s?.context)) };
-    return { opened: w.opened, bytes: Buffer.byteLength(w.text) };
+    if (session) {
+      const start = w.text.indexOf("\n## ");
+      session.sections ??= {};
+      session.sections[abs] = { tail: w.text.slice(start + 1), context: Boolean(line), line: line === null ? null : String(line).trim() };
+    }
+    return { opened: true, bytes: Buffer.byteLength(w.text), inserted: false };
+  });
+}
+
+// This conversation's section in the file at `abs`, or null. A session saved before HQ-2330 kept
+// one `section` by size, not text; it is read as no section, so its next write opens a heading.
+function sectionOf(session, abs) {
+  const s = session.sections?.[abs];
+  return s && typeof s.tail === "string" && s.tail ? s : null;
+}
+
+// The one pointer line under `heading` in the day file at `abs` (HQ-2306): the line in the owner's
+// day that points at an agent's own log for that day. Exactly one line starting with `prefix` lives
+// in that section; this replaces it in place, inserts it under the heading, appends the heading
+// after everything else, or creates the day, and touches no other byte. Under the same lock as
+// appendToDay, because this is a read-modify-write and a stale read would drop an append.
+// Returns "created", "added", "inserted" or "refreshed".
+export function setPointerLine(abs, { date, heading, prefix, line }) {
+  return withDayLock(() => {
+    const existing = existsSync(abs) ? readFileSync(abs, "utf8") : "";
+    if (existing === "") {
+      writeFileSync(abs, `# ${date}\n\n${heading}\n\n${line}\n`);
+      return "created";
+    }
+    const lines = existing.split("\n");
+    const at = lines.findIndex((l) => l.trim() === heading);
+    if (at === -1) {
+      appendFileSync(abs, `${existing.endsWith("\n") ? "" : "\n"}\n${heading}\n\n${line}\n`);
+      return "added";
+    }
+    let end = lines.length;
+    for (let i = at + 1; i < lines.length; i++) if (/^#{1,6} /.test(lines[i])) { end = i; break; }
+    const idx = lines.slice(at + 1, end).findIndex((l) => l.startsWith(prefix));
+    if (idx === -1) {
+      lines.splice(at + 1, 0, "", line);
+      writeFileSync(abs, lines.join("\n"));
+      return "inserted";
+    }
+    lines[at + 1 + idx] = line;
+    writeFileSync(abs, lines.join("\n"));
+    return "refreshed";
   });
 }

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("&"));
 }
@@ -66,8 +93,15 @@ export function isDayFile(abs) {
   return real(dirname(abs)) === day;
 }
 
+// HQ-2596: where words wait when the writer cannot be reached. One JSON file per write in the daily
+// folder's `.outbox/`, so each file has one writer and no sync can drop it; the writer files them,
+// oldest first, once its own copy of the day has synced. A file in that folder is not a day file, so
+// this guard allows writing it.
+export const OUTBOX_DIR = ".outbox";
+
 function sentence(writer, file) {
-  return `EVÐA: ${basename(file)} is the daily file, and this machine does not write it. ${DAY_WRITER_ENV} names the machine that does (${writer}). Two machines writing one daily file through a synced folder lose one of the writes with no conflict copy. Append the words with the evda MCP tool evda_write, which that machine serves. If evda_write is not connected in this session, tell the owner in one plain sentence that the words were not filed and why, and do not write the file here.`;
+  const outbox = `${join(dirname(file), OUTBOX_DIR)}/`;
+  return `EVÐA: ${basename(file)} is the daily file, and this machine does not write it. ${DAY_WRITER_ENV} names the machine that does (${writer}). Two machines writing one daily file through a synced folder lose one of the writes with no conflict copy. Append the words with the evda MCP tool evda_write, which that machine serves. If evda_write is not connected or that machine cannot be reached, queue the words in the outbox instead: write one new file per message to ${outbox}<UTC timestamp>-<host>-evda_write.json holding {tool, words, context, at, host} (tool "evda_write", words verbatim, at in UTC ISO), and the writer files them into the day when it is back. Tell the owner the words are queued, not filed, and do not write the daily file here.`;
 }
 
 // The decision for one PreToolUse input. { decision: "allow" } or { decision: "deny", reason }.
@@ -82,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";
@@ -69,12 +70,15 @@ import { folderManifests, folderFor, viewNamedIn, FOLDER_MANIFEST } from "./fold
 import { referencesIn } from "./references.mjs";
 import { KIND_FOR_TYPE, PERSON_KINDS, entryFromFile, readEntry } from "./kinds.mjs";
 import { datedHeadings } from "./migrate-people.mjs";
+import { personFolderProblems, README_NAME } from "./person-folders.mjs";
 import { EvdaError } from "./errors.mjs";
 import { hookStatus, promptHookStatus, HOOK_REL, PROMPT_HOOK_REL, SETTINGS_REL } from "./hooks.mjs";
 import { FILING_MODES, filingOf } from "./day-file.mjs";
+import { correctionsTarget } from "./corrections.mjs";
 import { EVERY_CHAT_KEY } from "./every-chat.mjs";
 import { listSkills, SKILLS_REL } from "./skills.mjs";
 import { guardStatus } from "./connect.mjs";
+import { 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
@@ -97,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 = [];
@@ -237,7 +244,12 @@ export function doctor(dir, { out = console.log, via = "argument", depth = 0 } =
         fail(rel, e.message);
       }
       if (fence === null) warn(rel, "has no evda:generated fence. The owner has taken the whole file; `evda upgrade` has nothing it owns to replace.");
-      if (!/## What I have been taught/.test(agents)) warn(rel, 'has no "## What I have been taught" section, so a correction has nowhere to land.');
+      // HQ-2325: a record that keeps its corrections in their own file names it in evda.json, and
+      // then the heading is not where they land, so its absence is not a warning.
+      const corrections = correctionsTarget({ dir, manifest });
+      if (corrections?.problem) warn("evda.json", `${corrections.problem} evda_record_correction refuses until it does.`);
+      else if (corrections) ok(1, "corrections", `evda.json names ${corrections.rel}: a correction lands there as a dated section`);
+      else if (!/## What I have been taught/.test(agents)) warn(rel, 'has no "## What I have been taught" section, and evda.json names no "corrections" file, so a correction has nowhere to land.');
     }
     // Claude Code reads CLAUDE.md and nothing else. If the operating layer is elsewhere, CLAUDE.md
     // has to import it or a Claude Code session here starts with no instructions.
@@ -247,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
@@ -288,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
@@ -673,10 +703,21 @@ export function doctor(dir, { out = console.log, via = "argument", depth = 0 } =
           if (name === FOLDER_MANIFEST) continue;
           const rel = relative(dir, p);
           const read = entryFromFile(name, readFileSync(p, "utf8"));
-          if (read === null) continue;
+          // In a person folder every file directly inside is a person's profile (HQ-2024), so one
+          // with no kind is a profile doctor would otherwise never read, and fails. Its README, its
+          // manifest and its declared views are not people; Processing/ sits beside the folder.
+          const unread = want === "person-profile" && p.slice(0, p.lastIndexOf(sep)) === f.dir && name !== README_NAME;
+          if (read === null) {
+            if (unread && /\.md$/i.test(name)) fail(rel, `has no person-profile frontmatter, so doctor never reads it. ${where} declares type person: every file in it opens with kind: person-profile (scripts/migrate-people.mjs adds it).`);
+            continue;
+          }
           if (read.error) { fail(rel, `${read.error} ${where} holds ${want} entries.`); continue; }
           const kind = read.raw?.kind;
-          if (kind === undefined) { warn(rel, `has no "kind", so it is not read as a ${want}. ${where} declares type ${f.type}.`); continue; }
+          if (kind === undefined) {
+            if (unread) fail(rel, `has no "kind", so doctor never reads it as a person-profile. ${where} declares type person.`);
+            else warn(rel, `has no "kind", so it is not read as a ${want}. ${where} declares type ${f.type}.`);
+            continue;
+          }
           entries += 1;
           if (kind !== want) { fail(rel, `is a ${kind}, and ${where} declares type ${f.type}, whose entries are ${want}. Move it, or say what the folder holds.`); continue; }
           counts[want] = (counts[want] ?? 0) + 1;
@@ -695,6 +736,17 @@ export function doctor(dir, { out = console.log, via = "argument", depth = 0 } =
           }
         }
       }
+      // Person folders (HQ-2024, lib/person-folders.mjs): one file per person, named for the
+      // person, no subfolder, no lone parenthetical, no redirect stub. Read across every person
+      // folder at once, because two people who share a name can live in two folders.
+      const people = typed.filter((f) => f.type === "person");
+      if (people.length) {
+        const skipPaths = new Set(people.flatMap((f) => [join(f.dir, FOLDER_MANIFEST), ...f.views.map((v) => resolve(dir, v.path))]));
+        const layout = personFolderProblems(people.map((f) => f.dir), { skip: skipPaths });
+        for (const p of layout.problems) fail(relative(dir, p.path), p.message);
+        if (layout.files === 0) skip("person folder layout", `${people.length} person folder(s) hold no person files yet`);
+        else ok(layout.files, "person files", `across ${people.length} person folder(s): one file each, no subfolder, no lone parenthetical, no redirect stub`);
+      }
       if (entries === 0) skip("typed entries", `${typed.length} typed folder(s) hold no entry files yet`);
       else ok(entries, "typed entries", `across ${typed.length} folder(s): ${PERSON_KINDS.filter((k) => counts[k]).map((k) => `${counts[k]} ${k}`).join(", ") || "none of the declared kind"}`);
     }
@@ -770,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 };