create-evda 0.1.8 → 0.1.9

package/lib/tools.mjs

@@ -25,17 +25,23 @@
 // making the circle, and granting anyone anything, stays the owner's explicit yes through
 // `evda grant` or their own hands.
 
-import { appendFileSync, existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { appendFileSync, existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
 import { dirname, join, relative, resolve, sep } from "node:path";
 import { resolveRole, rolesForLayer, agentsFile } from "./roles.mjs";
-import { mdFiles, fileDate } from "./record.mjs";
-import { readCircles, isSealed } from "./circles.mjs";
+import { mdFiles, fileDate, headings } from "./record.mjs";
+import { splitFence, FENCE_OPEN } from "./agents.mjs";
+import { datalessAmong } from "./sync-rules.mjs";
+import { readCircles, isSealed, frontmatterOf } from "./circles.mjs";
 import { secretShape } from "./references.mjs";
 import { doctor } from "./doctor.mjs";
-import { readContext, mayRead, heldBack, callerFrom, aiView, note as writeNote, releaseNote, SEALED_WHY } from "./readers.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, CONTEXT_LABEL, localDate, localTime } from "./day-file.mjs";
 import { writeMessage, unseenReplies } from "./messages.mjs";
+import { acknowledge as writeAcknowledgement, readAcknowledged, acknowledgementsFor } from "./acknowledge.mjs";
+import { openEvda, holderOf } from "./manifest.mjs";
+import { toYaml } from "./yaml.mjs";
+import { readEntry } from "./kinds.mjs";
 
 export { localDate, localTime, CONTEXT_LABEL };
 
@@ -99,12 +105,73 @@ export function operatingLayer(evda, args = {}) {
   const a = agentsFile(evda);
   if (!a) throw new EvdaError('this record maps no "agents" role, so it has no operating layer.', { code: "NO_ROLE" });
   if (isSealed(a.abs)) throw new EvdaError(`REFUSED: ${a.rel} ${SEALED_WHY.replace(/^It /, "is ")}`, { code: "SEALED", exit: 2 });
-  return { path: a.rel, text: aiView(readFileSync(a.abs, "utf8")).text };
+  const raw = readFileSync(a.abs, "utf8");
+  const found = coreBeside(evda, a, raw);
+  return { path: a.rel, text: aiView(raw).text, core: found.core, coreNote: found.note };
 }
 
-// 2. The last `days` days of the record, newest first, whole files, capped in size. A file is in the
-// window by its date (filename, then a date or created key), the same rule `evda moment` uses.
-export function recent(evda, args = {}, { now = new Date(), caller = callerFrom() } = {}) {
+// The generated core, when the agents file is only the owner layer (HQ-2203). A scaffolded record's
+// AGENTS.md carries the `evda:generated` fence itself, and then there is nothing to add. A record
+// that maps agents to an owner-only file (his: CLAUDE.md) keeps the core in another markdown file
+// in the same folder (his: IRIS.md, built from the vault's template), and Claude Code loads it
+// through its own prompt while a chat app gets only this tool. The rule is the one browse.mjs
+// uses to show operating files: the markdown file beside the agents file that carries the fence.
+// No name is assumed, so an owner who renamed their agent still gets theirs, and the core is read
+// from the record, never from the server's templates. Two candidates are not guessed between:
+// neither is served and the note names them. A sealed or noted file, or one still in the cloud
+// (reading it would start a download), is not a candidate.
+export function coreBeside(evda, agents, agentsText) {
+  try {
+    if (splitFence(agentsText)) return { core: null, note: null };
+  } catch {
+    return { core: null, note: null };
+  }
+  const folder = dirname(agents.abs);
+  let names;
+  try {
+    names = readdirSync(folder).filter((n) => /\.md$/i.test(n) && join(folder, n) !== agents.abs).sort();
+  } catch {
+    return { core: null, note: null };
+  }
+  const cloud = datalessAmong(folder, names);
+  const found = [];
+  for (const n of names) {
+    const abs = join(folder, n);
+    if (cloud.has(n)) continue;
+    let text;
+    try {
+      if (!statSync(abs).isFile()) continue;
+      text = readFileSync(abs, "utf8");
+    } catch {
+      continue;
+    }
+    if (!text.includes(FENCE_OPEN) || isSealedFile(abs) || isNotedFile(abs)) continue;
+    let parts;
+    try { parts = splitFence(text); } catch { continue; }
+    if (parts) found.push({ path: rel(evda, abs), text: aiView(parts.generated).text });
+  }
+  if (found.length === 1) return { core: found[0], note: null };
+  if (found.length > 1) return { core: null, note: `${found.map((f) => f.path).join(" and ")} both carry the generated core, so neither was served here. Read the one the owner means with evda_read.` };
+  return { core: null, note: null };
+}
+
+// 2. The last `days` days of the record, newest first, capped in size. A file is in the window by
+// its date (filename, then a date or created key), the same rule `evda moment` uses.
+//
+// Returns each file's headings, not the whole file (HQ-2163) and not its first line either
+// (HQ-2227): this tool is for triage across many files, and pulling every matching file whole into
+// a hosted chat put sensitive captures into it unread. A first line did the same at a smaller size:
+// a capture is often one line long, so on 2026-10-05 a claude.ai question about deadlines got the
+// text of a relationship capture and an edibles night through it. A heading is what the owner or
+// the filing tool chose to title an entry; the words under it are read by path, when the question
+// needs them. The whole text of one file is `evda_read`'s job, by path. `full: true` is
+// not part of the tool's args (onlyKeys refuses it there); it is an internal option for callers in
+// this process, such as the evda://today resource below, that still need one file's whole text.
+//
+// Each file carries what an earlier reader already acknowledged in it (HQ-2060, lib/acknowledge.mjs):
+// this is the one read path every reader uses at session start, so it is where a reader learns that
+// a weighty entry is already handled and it should stay quiet about it.
+export function recent(evda, args = {}, { now = new Date(), caller = callerFrom(), full = false } = {}) {
   onlyKeys("evda_recent", args, ["days"]);
   const days = args.days === undefined ? 3 : Number(args.days);
   if (!Number.isInteger(days) || days < 1 || days > 90) throw new EvdaError("evda_recent days must be a whole number from 1 to 90.", { code: "BAD_ARGUMENT", exit: 2 });
@@ -116,6 +183,7 @@ export function recent(evda, args = {}, { now = new Date(), caller = callerFrom(
   const ctx = readContext(evda);
   const refused = [];
   let sealed = false;
+  const marks = readAcknowledged(evda);
   for (const abs of recordFiles(evda)) {
     const raw = readFileSync(abs, "utf8");
     const date = fileDate(abs, raw);
@@ -124,18 +192,46 @@ export function recent(evda, args = {}, { now = new Date(), caller = callerFrom(
     if (!may.ok) { refused.push(may); continue; }
     const shown = aiView(raw);
     if (shown.sections) sealed = true;
-    files.push({ date, path: rel(evda, abs), text: shown.text });
+    const path = rel(evda, abs);
+    const acknowledged = acknowledgementsFor(path, marks);
+    files.push(full
+      ? { date, path, text: shown.text, acknowledged }
+      : { date, path, headings: headings(shown.text), acknowledged });
   }
   files.sort((a, b) => (a.date === b.date ? a.path.localeCompare(b.path) : b.date.localeCompare(a.date)));
   let used = 0;
   const out = [];
   let truncated = 0;
   for (const f of files) {
-    if (used + f.text.length > MAX_READ) { truncated += 1; continue; }
-    used += f.text.length;
+    const weight = full ? f.text.length : f.headings.join("\n").length;
+    if (used + weight > MAX_READ) { truncated += 1; continue; }
+    used += weight;
     out.push(f);
   }
-  return { from, to, files: out, omitted: truncated, refused: refused.filter((r) => r.kind !== "sealed"), heldBack: heldBack(refused, { sealed }) };
+  return {
+    from,
+    to,
+    files: out,
+    omitted: truncated,
+    acknowledged: out.reduce((n, f) => n + f.acknowledged.length, 0),
+    refused: refused.filter((r) => r.kind !== "sealed"),
+    heldBack: heldBack(refused, { sealed }),
+  };
+}
+
+// 2a. Record that this reader acted on one weighty entry, so no other reader acts on it again
+// (HQ-2060). The first reader to reach it writes the mark; a later one gets first: false and nothing
+// is written. Weight is the reader's judgment; this only remembers that one of them already did it.
+export function acknowledgeEntry(evda, args = {}, { now = new Date() } = {}) {
+  onlyKeys("evda_acknowledge", args, ["path", "section", "note", "by"], "It writes one mark beside the record and nothing else: it never edits the entry, and it never writes over a mark another reader left.");
+  return writeAcknowledgement(evda, args, { now });
+}
+
+// 2b. Every mark the record holds, for a reader that wants them without the files.
+export function acknowledgements(evda, args = {}) {
+  onlyKeys("evda_acknowledgements", args, []);
+  const all = readAcknowledged(evda);
+  return { count: Object.keys(all).length, marks: Object.entries(all).map(([key, m]) => ({ key, ...m })) };
 }
 
 // Every markdown file the record holds: each record-layer role, and the imports folder. Not the
@@ -155,6 +251,12 @@ function recordFiles(evda) {
   return out;
 }
 
+// Today's daily file, relative to the record, whether or not it exists yet: the one `write` appends
+// to. The app's Today's Journal (HQ-2038) shows it, and an empty page when it is not written yet.
+export function todayPath(evda, { now = new Date() } = {}) {
+  return rel(evda, join(dailyDir(evda).abs, `${localDate(now)}.md`));
+}
+
 // 3. Append the owner's words, verbatim, to today's daily file. Creates the file with a date heading
 // when it is the first write of the day. Returns the path.
 // `context` (HQ-1377) is one line on what the conversation was about, in the agent's words, written
@@ -162,25 +264,108 @@ function recordFiles(evda) {
 // `session` (HQ-1385) is the conversation: its first write opens `## HH:MM` with the context line,
 // and later writes append under it (lib/day-file.mjs, the one append path).
 export const CONTEXT_MAX = 240;
-export function write(evda, args = {}, { now = new Date(), session = null } = {}) {
-  onlyKeys("evda_write", 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.");
-  const words = text(args.words, "words", "evda_write");
-  refuseSecrets(words, "evda_write");
+// `toolName` (HQ-2164) is what an error names itself as: evda_write when called directly, or
+// 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.
+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.");
+  const words = text(args.words, "words", toolName);
+  refuseSecrets(words, toolName);
   let context = null;
   if (args.context !== undefined) {
-    if (typeof args.context !== "string" || args.context.trim() === "") throw refuse(`evda_write "context" is one line on what the conversation was about; leave it out rather than send it empty.`, "EMPTY");
-    if (/\n/.test(args.context.trim())) throw refuse(`evda_write "context" is one line. Their words go in "words"; the context is a single line on what the conversation was about.`, "CONTEXT_LINES");
-    if (args.context.trim().length > CONTEXT_MAX) throw refuse(`evda_write "context" is ${args.context.trim().length} characters; one line of context is at most ${CONTEXT_MAX}.`, "TOO_LONG");
-    refuseSecrets(args.context, "evda_write");
+    if (typeof args.context !== "string" || args.context.trim() === "") throw refuse(`${toolName} "context" is one line on what the conversation was about; leave it out rather than send it empty.`, "EMPTY");
+    if (/\n/.test(args.context.trim())) throw refuse(`${toolName} "context" is one line. Their words go in "words"; the context is a single line on what the conversation was about.`, "CONTEXT_LINES");
+    if (args.context.trim().length > CONTEXT_MAX) throw refuse(`${toolName} "context" is ${args.context.trim().length} characters; one line of context is at most ${CONTEXT_MAX}.`, "TOO_LONG");
+    refuseSecrets(args.context, toolName);
     context = args.context.trim();
   }
-  const r = dailyDir(evda);
-  mkdirSync(r.abs, { recursive: true });
-  const abs = join(r.abs, `${localDate(now)}.md`);
+  const abs = join(evda.dir, todayPath(evda, { now }));
+  mkdirSync(dirname(abs), { recursive: true });
   const w = appendToDay(abs, { now, words, context, session });
   return { path: rel(evda, abs), bytes: Buffer.byteLength(words), section: w.opened ? "opened" : "continued" };
 }
 
+// 3b. What `evda mcp`'s evda_write tool actually calls (HQ-2165). `write` above already appended
+// the words; this reads them back after a short real delay and refuses to report success if they
+// are gone, so a caller that overwrote the file in that gap is caught instead of the agent telling
+// the owner "Filed" about words that are no longer there (the night of 2026-10-03: the connector's
+// evda_write reported Filed at 03:40:46Z and the owner's words were gone by the time anyone looked).
+//
+// What this catches: a same-host writer (Hestia's journal-append.mjs doing a read-modify-write of
+// the whole file) that lands in the window between this function's append and its own read-back.
+// What this CANNOT catch: two different machines' local replicas of this file diverging and iCloud
+// picking one wholesale, which can resolve on any timescale and is not bounded by a short delay.
+// That class is why every writer but one host must stop touching this file's local copy at all --
+// see test/single-writer.test.mjs. This is a backstop for the class it can catch, not the fix for
+// the class that caused the incident; HQ-2165's "Done when" is the single-writer change, not this.
+const VERIFY_DELAY_MS = 400;
+const sleep = (ms) => new Promise((resolveSleep) => setTimeout(resolveSleep, ms));
+export async function writeVerified(evda, args = {}, { verifyDelayMs = VERIFY_DELAY_MS, ...rest } = {}) {
+  const r = write(evda, args, rest);
+  const abs = join(evda.dir, r.path);
+  if (verifyDelayMs > 0) await sleep(verifyDelayMs);
+  const expect = String(args.words).replace(/\n+$/, "");
+  const after = existsSync(abs) ? readFileSync(abs, "utf8") : "";
+  if (!after.includes(expect)) {
+    throw new EvdaError(
+      `evda_write: ${r.path} was written, then read back after ${verifyDelayMs}ms and the words were gone -- `
+      + "another writer overwrote the file in between. Tell the owner the write FAILED; never say \"Filed\" "
+      + "about this call.",
+      { code: "LOST_WRITE", exit: 1 },
+    );
+  }
+  return r;
+}
+
+// 3a. Append one dated correction to AGENTS.md's "What I have been taught" (HQ-1997). That section
+// is always outside the installer's fence (Spec 05 ruling 2, lib/agents.mjs splitFence), so a write
+// here never touches the generated block and survives `evda upgrade` untouched, the same way any
+// other owner edit below the fence does. Append only: an earlier entry is never edited or removed;
+// a correction that reverses one is a new entry with "supersedes" naming the date of the one it
+// replaces, exactly as the section's own instructions ask.
+const CHANGE_MAX = 400;
+const WORDS_MAX = 400;
+export function recordCorrection(evda, args = {}, { now = new Date() } = {}) {
+  onlyKeys("evda_record_correction", args, ["words", "change", "supersedes"], "It appends one dated line to \"What I have been taught\" and nothing else: it takes no path, and it never edits or replaces an earlier entry.");
+  if (typeof args.change !== "string" || args.change.trim() === "") throw refuse('evda_record_correction needs "change": what you do differently now, one line.', "NO_CHANGE");
+  const change = args.change.trim();
+  if (/\n/.test(change)) throw refuse('evda_record_correction "change" is one line.', "MULTILINE");
+  if (change.length > CHANGE_MAX) throw refuse(`evda_record_correction "change" is ${change.length} characters; at most ${CHANGE_MAX}.`, "TOO_LONG");
+  refuseSecrets(change, "evda_record_correction");
+  let words = null;
+  if (args.words !== undefined) {
+    if (typeof args.words !== "string" || args.words.trim() === "") throw refuse('evda_record_correction "words" is the owner\'s exact words; leave it out rather than send it empty.', "EMPTY");
+    words = args.words.trim();
+    if (/\n/.test(words)) throw refuse('evda_record_correction "words" is one line.', "MULTILINE");
+    if (words.length > WORDS_MAX) throw refuse(`evda_record_correction "words" is ${words.length} characters; at most ${WORDS_MAX}.`, "TOO_LONG");
+    refuseSecrets(words, "evda_record_correction");
+  }
+  let supersedes = null;
+  if (args.supersedes !== undefined) {
+    if (typeof args.supersedes !== "string" || !DATE.test(args.supersedes.trim())) throw refuse('evda_record_correction "supersedes" must be YYYY-MM-DD, the date of the earlier entry this one reverses.', "BAD_DATE");
+    supersedes = args.supersedes.trim();
+  }
+  const a = agentsFile(evda);
+  if (!a) throw refuse('this record maps no "agents" role, so it has no AGENTS.md to write the correction into.', "NO_ROLE");
+  if (isSealed(a.abs)) throw refuse(`${a.rel} ${SEALED_WHY.replace(/^It /, "is ")}`, "SEALED");
+  const raw = readFileSync(a.abs, "utf8");
+  const parts = splitFence(raw);
+  const owner = parts ? parts.after : raw;
+  if (!/(^|\n)## What I have been taught(\n|$)/.test(owner)) {
+    throw refuse(`${a.rel} has no "## What I have been taught" section outside the generated block, so a correction has nowhere to land. Add that heading first (templates/AGENTS.md has the wording); evda doctor names this too.`, "NO_SECTION");
+  }
+  const date = localDate(now);
+  const said = words ? `"${words}" -> ` : "";
+  const supersededNote = supersedes ? ` Supersedes ${supersedes}.` : "";
+  const line = `- ${date}: ${said}${change}${supersededNote}\n`;
+  const sep = owner.endsWith("\n") ? "" : "\n";
+  const newOwner = owner + sep + line;
+  const newRaw = parts ? parts.before + parts.generated + newOwner : newOwner;
+  writeFileSync(a.abs, newRaw);
+  return { path: a.rel, date, section: "What I have been taught" };
+}
+
 // The day file for a date, as { abs, rel }, for writers that are not evda_write (the chat-export
 // backstop in `evda gather`). Throws when the record maps no day role.
 export function dayFile(evda, date) {
@@ -188,6 +373,219 @@ export function dayFile(evda, date) {
   return { abs: join(r.abs, `${date}.md`), rel: rel(evda, join(r.abs, `${date}.md`)), dir: r.abs };
 }
 
+// 3b. Iris's own day log (HQ-2164): a fixed, named sub-record, exactly like AGENTS.md's "What I
+// have been taught" is a fixed, named section. Not a general path: this is the one place
+// evda_write_agent_log is ever allowed to write, and it is reused unchanged from `write` above
+// against that sub-record's own evda.json, so a section there opens and continues by the same
+// one-conversation rule as the owner's own daily file.
+const AGENT_LOG_REL = "01_Projects/Evda/Iris - Universal Thinking Partner/memory";
+function agentLogRecord(evda) {
+  const abs = join(evda.dir, AGENT_LOG_REL);
+  if (!existsSync(join(abs, "evda.json"))) {
+    throw refuse(`${AGENT_LOG_REL} has no evda.json, so there is no agent log sub-record to write into.`, "NO_ROLE");
+  }
+  return openEvda(abs);
+}
+
+// Whether this record has the agent log sub-record. A chat app is offered evda_write_agent_log only
+// when it does (HQ-2164), so a chat is never handed a tool that can only refuse.
+export function hasAgentLog(evda) {
+  return existsSync(join(evda.dir, AGENT_LOG_REL, "evda.json"));
+}
+
+export function writeAgentLog(evda, args = {}, { now = new Date(), session = null } = {}) {
+  const sub = agentLogRecord(evda);
+  const r = write(sub, args, { now, session, toolName: "evda_write_agent_log" });
+  return { path: `${AGENT_LOG_REL}/${r.path}`, bytes: r.bytes, section: r.section };
+}
+
+// 3c. Append one dated section to an EXISTING person page (HQ-2164), in the evda_record_correction
+// shape: one named target class (record/people), resolved by name rather than by path, and append
+// only. Never creates a page (CLAUDE.md: "Only docs that already exist. Do not auto-create a new
+// profile mid-conversation; offer it."); refuses a sealed page, and refuses when the name matches
+// more than one page rather than guessing. When the page's frontmatter is `kind: person-profile`,
+// the new section also gets a matching `observations` entry (CLAUDE.md / doctor's HQ-1397 rule:
+// "A People doc with kind: person-profile frontmatter gets an observation for each new dated
+// section"), so this write can never silently leave a profile failing that check. Everything else
+// in the file, including the rest of the frontmatter, is byte for byte what it was.
+const PERSON_CONTEXT_MAX = CONTEXT_MAX;
+function peopleDir(evda) {
+  const r = resolveRole(evda, "record/people");
+  if (!r.mapped) throw refuse('this record maps no "record/people" role, so it has no person pages to write into.', "NO_ROLE");
+  if (!r.exists || !r.isDir) throw refuse(`${r.rel} is mapped as "record/people" but is not a folder.`, "NO_ROLE");
+  return r;
+}
+
+// Files in `dir` whose name (without .md) matches `name`, case-insensitively, exact match first.
+// No folders (CLAUDE.md: one file per person), so this never recurses.
+function findPersonFiles(dir, name) {
+  const want = String(name).trim().toLowerCase().replace(/\s+/g, " ");
+  const all = readdirSync(dir.abs, { withFileTypes: true })
+    .filter((e) => e.isFile() && /\.md$/i.test(e.name) && e.name.toLowerCase() !== "readme.md")
+    .map((e) => e.name);
+  const stem = (f) => f.replace(/\.md$/i, "").toLowerCase();
+  const exact = all.filter((f) => stem(f) === want);
+  return exact.length ? exact : all.filter((f) => stem(f).startsWith(want));
+}
+
+export function recordPersonNote(evda, args = {}, { now = new Date() } = {}) {
+  onlyKeys("evda_record_person_note", args, ["person", "context", "words"], "It appends one dated section to an existing person page and nothing else: it takes no path, it never creates a page, and it never edits or removes an earlier section.");
+  if (typeof args.person !== "string" || args.person.trim() === "") throw refuse('evda_record_person_note needs "person": the name on their page.', "NO_PERSON");
+  if (typeof args.context !== "string" || args.context.trim() === "") throw refuse('evda_record_person_note needs "context": one line on what this section is.', "NO_CONTEXT");
+  const context = args.context.trim();
+  if (/\n/.test(context)) throw refuse('evda_record_person_note "context" is one line.', "MULTILINE");
+  if (context.length > PERSON_CONTEXT_MAX) throw refuse(`evda_record_person_note "context" is ${context.length} characters; at most ${PERSON_CONTEXT_MAX}.`, "TOO_LONG");
+  refuseSecrets(context, "evda_record_person_note");
+  const words = text(args.words, "words", "evda_record_person_note");
+  refuseSecrets(words, "evda_record_person_note");
+
+  const dir = peopleDir(evda);
+  const matches = findPersonFiles(dir, args.person);
+  if (matches.length === 0) throw refuse(`no page for "${args.person.trim()}" in ${dir.rel}. This tool never creates one; offer to make the page first.`, "MISSING");
+  if (matches.length > 1) throw refuse(`"${args.person.trim()}" matches more than one page in ${dir.rel} (${matches.join(", ")}). Say which one.`, "AMBIGUOUS");
+
+  const abs = join(dir.abs, matches[0]);
+  if (isSealed(abs)) throw refuse(`${rel(evda, abs)} ${SEALED_WHY.replace(/^It /, "is ")}`, "SEALED");
+
+  const raw = readFileSync(abs, "utf8");
+  const date = localDate(now);
+  const heading = `## ${context} (added ${date})`;
+  const lead = raw.endsWith("\n") ? "" : "\n";
+  const section = `${lead}\n${heading}\n\n${words.trim()}\n`;
+
+  const fm = frontmatterOf(raw);
+  let newRaw = raw + section;
+  let observationId = null;
+  if (fm && fm.kind === "person-profile") {
+    const lines = raw.split("\n");
+    const end = lines.indexOf("---", 1);
+    const body = lines.slice(end + 1).join("\n");
+    const obs = Array.isArray(fm.observations) ? fm.observations : [];
+    const stamp = `${date}-${localTime(now).replace(":", "")}`;
+    const ids = new Set(obs.map((o) => o.id));
+    let id = stamp;
+    for (let n = 2; ids.has(id); n++) id = `${stamp}-${n}`;
+    const observation = { id, since: date, text: context };
+    const nextFm = { ...fm, observations: [...obs, observation] };
+    const owner = holderOf(evda).id ?? holderOf(evda).name;
+    const before = readEntry("person-profile", fm, { owner });
+    const after = readEntry("person-profile", nextFm, { owner });
+    const introduced = after.dto === null ? [after.problems[0]] : after.problems.filter((p) => !before.problems.includes(p));
+    if (introduced.length) throw refuse(`writing this observation into ${rel(evda, abs)} would leave its frontmatter invalid: ${introduced[0]}`, "BAD_PROFILE");
+    const newFrontmatter = `---\n${toYaml(nextFm)}---\n`;
+    newRaw = newFrontmatter + body + section;
+    observationId = id;
+  }
+  writeFileSync(abs, newRaw);
+  return { path: rel(evda, abs), date, observation: observationId };
+}
+
+// 3d. "Entries grow on their own" (HQ-2228): one dated section on an entry that already exists, by
+// its path. In a chat app this is the only way the core's rule can be carried out, since the
+// connector is the only thing that writes. It never creates a file and never touches a byte already
+// there: the section goes at the end, `## YYYY-MM-DD`, and a second append the same day continues
+// that section instead of opening a second heading for the day. Who may write follows who may read
+// (lib/readers.mjs mayRead): a sealed entry, a noted one and a part read by a different AI are each
+// refused, since the core says those are not the agent's to add to. The files other tools own are
+// refused with the tool that does it: the operating layer, the day's file, a person's page, and the
+// record's own machinery (circles, grants, mounts, messages, the ledger, proposals, anything at the
+// root or in a dot-folder, which is where skills live).
+const APPEND_ELSEWHERE = [
+  ["record/daily", "is the day's file: the owner's words go there with evda_write."],
+  ["record/people", "is a person's page: add to it with evda_record_person_note, which also keeps its observations in step."],
+  ["circles", "is part of how the record is shared, which only the owner changes."],
+  ["grants", "is part of how the record is shared, which only the owner changes."],
+  ["mounts", "is part of how the record is shared, which only the owner changes."],
+  ["messages", "is a message file, which evda_message and the phone write."],
+  ["ledger", "is the hypothesis ledger, which has its own format and tools."],
+];
+export function appendEntry(evda, args = {}, { now = new Date(), caller = callerFrom() } = {}) {
+  onlyKeys("evda_append", args, ["path", "words"], "It adds one dated section to the end of an entry that already exists and nothing else: it never creates a file and never edits what is there.");
+  if (typeof args.path !== "string" || args.path.trim() === "") throw refuse('evda_append needs "path": the existing entry, relative to the record, as evda_search or evda_recent gave it.', "BAD_ARGUMENT");
+  const words = text(args.words, "words", "evda_append");
+  refuseSecrets(words, "evda_append");
+  const want = args.path.trim();
+  const abs = resolve(evda.dir, want);
+  if (!abs.startsWith(evda.dir + sep)) throw refuse(`${want} is outside the record.`, "OUTSIDE");
+  const where = rel(evda, abs);
+  if (!/\.md$/i.test(abs)) throw refuse(`${where} is not a Markdown entry; only a .md entry grows by a dated section.`, "NOT_AN_ENTRY");
+  if (!existsSync(abs) || !statSync(abs).isFile()) throw refuse(`no entry is at ${where}. This tool never creates one: say in one line that you can start a page, and start it only on their yes.`, "MISSING");
+  const a = agentsFile(evda);
+  if (a && resolve(a.abs) === abs) throw refuse(`${where} is the operating layer: a correction goes in with evda_record_correction, and a setup answer with evda_setup_answer.`, "NOT_AN_ENTRY");
+  if (!where.includes("/") || where.split("/").some((p) => p.startsWith("."))) throw refuse(`${where} is one of the record's own files, not an entry.`, "NOT_AN_ENTRY");
+  const top = where.split("/")[0];
+  if (top === PROPOSALS) throw refuse(`${where} is one of the record's own files, not an entry.`, "NOT_AN_ENTRY");
+  for (const [role, why] of APPEND_ELSEWHERE) {
+    const r = resolveRole(evda, role);
+    if (r.mapped && r.abs && (abs === r.abs || abs.startsWith(r.abs + sep))) throw refuse(`${where} ${why}`, "NOT_AN_ENTRY");
+  }
+  const may = mayRead(readContext(evda), abs, caller);
+  if (!may.ok) throw refuse(`${may.why} It is not yours to add to.`, may.kind === "sealed" ? "SEALED" : may.kind === "noted" ? "NOTED" : "NOT_THIS_READER");
+  const raw = readFileSync(abs, "utf8");
+  const fm = frontmatterOf(raw);
+  if (fm && fm.kind === "person-profile") throw refuse(`${where} is a person profile, and each new section there needs an observation: add to it with evda_record_person_note.`, "NOT_AN_ENTRY");
+  const date = localDate(now);
+  const heading = `## ${date}`;
+  const lastHeading = [...raw.matchAll(/^## .*$/gm)].pop()?.[0]?.trim();
+  const continued = lastHeading === heading;
+  const lead = raw === "" || raw.endsWith("\n") ? "" : "\n";
+  const add = continued ? `${lead}\n${words.trim()}\n` : `${lead}${raw === "" ? "" : "\n"}${heading}\n\n${words.trim()}\n`;
+  appendFileSync(abs, add);
+  return { path: where, date, section: continued ? "continued" : "opened" };
+}
+
+// 3e. The owner's setup answers (HQ-2228), into AGENTS.md's "What this EVÐA is", in the
+// evda_record_correction shape: one named section, one named line, and nothing else in the file
+// changes. The core's setup step asks each answer to be written there "in their exact words"; a chat
+// app had no tool to do it. A field is written once, when it is empty: a filled one is the owner's
+// to change, in their own file, so the agent never rewrites what they said.
+export const SETUP_FIELDS = ["Agent name", "Who I am", "What I want this for", "How I want it to talk to me", "The AI I use with it, and its training setting"];
+const SETUP_HEADING = /^## What this EV(?:Ð|D)A is[ \t]*$/m;
+export function setupAnswer(evda, args = {}) {
+  onlyKeys("evda_setup_answer", args, ["field", "words"], "It fills one empty field of \"What this EVÐA is\" and nothing else.");
+  if (!SETUP_FIELDS.includes(args.field)) throw refuse(`evda_setup_answer "field" is one of ${SETUP_FIELDS.map((f) => JSON.stringify(f)).join(", ")}.`, "BAD_FIELD");
+  if (typeof args.words !== "string" || args.words.trim() === "") throw refuse('evda_setup_answer needs "words": the owner\'s answer, exactly as they said it.', "EMPTY");
+  const words = args.words.trim();
+  if (/\n/.test(words)) throw refuse('evda_setup_answer "words" is one line: a field holds one line of their answer.', "MULTILINE");
+  if (words.length > WORDS_MAX) throw refuse(`evda_setup_answer "words" is ${words.length} characters; at most ${WORDS_MAX}.`, "TOO_LONG");
+  refuseSecrets(words, "evda_setup_answer");
+  const a = agentsFile(evda);
+  if (!a) throw refuse('this record maps no "agents" role, so it has no AGENTS.md to write the answer into.', "NO_ROLE");
+  if (isSealed(a.abs)) throw refuse(`${a.rel} ${SEALED_WHY.replace(/^It /, "is ")}`, "SEALED");
+  const raw = readFileSync(a.abs, "utf8");
+  // Only the owner's text: the installer's generated block is never written.
+  const parts = splitFence(raw);
+  const pieces = parts ? [["before", parts.before], ["after", parts.after]] : [["whole", raw]];
+  for (const [name, piece] of pieces) {
+    const h = SETUP_HEADING.exec(piece);
+    if (!h) continue;
+    const start = h.index + h[0].length;
+    const next = piece.slice(start).search(/^## /m);
+    const end = next < 0 ? piece.length : start + next;
+    const section = piece.slice(start, end);
+    const label = args.field.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    const line = new RegExp(`^- \\*\\*${label}:\\*\\*([ \\t]*)(.*)$`, "m").exec(section);
+    if (!line) throw refuse(`${a.rel}'s "What this EVÐA is" has no "${args.field}" line. Add "- **${args.field}:**" there first (templates/AGENTS.md has the wording).`, "NO_FIELD");
+    if (line[2].trim() !== "") throw refuse(`"${args.field}" already reads: ${line[2].trim()}. A filled field is the owner's to change, in their own file.`, "ALREADY_SET");
+    const at = start + line.index;
+    const newPiece = `${piece.slice(0, at)}- **${args.field}:** ${words}${piece.slice(at + line[0].length)}`;
+    const newRaw = !parts ? newPiece : name === "before" ? newPiece + parts.generated + parts.after : parts.before + parts.generated + newPiece;
+    writeFileSync(a.abs, newRaw);
+    return { path: a.rel, field: args.field };
+  }
+  throw refuse(`${a.rel} has no "## What this EVÐA is" section outside the generated block. Add it first (templates/AGENTS.md has the wording).`, "NO_SECTION");
+}
+
+// Whether setup is unfinished: some field of "What this EVÐA is" is there and empty.
+export function setupPending(agentsText) {
+  const h = SETUP_HEADING.exec(agentsText ?? "");
+  if (!h) return false;
+  const rest = agentsText.slice(h.index + h[0].length);
+  const next = rest.search(/^## /m);
+  const section = next < 0 ? rest : rest.slice(0, next);
+  return SETUP_FIELDS.some((f) => new RegExp(`^- \\*\\*${f.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}:\\*\\*[ \\t]*$`, "m").test(section));
+}
+
 // 4. File what another AI said about the owner, verbatim, under imports/, labeled with its source
 // and date. A second import from the same source on the same day is appended to that file.
 export function importText(evda, args = {}, { now = new Date() } = {}) {
@@ -298,7 +696,8 @@ export function releaseTool(evda, args = {}, { now = new Date() } = {}) {
 }
 
 // 5d. Tell the owner something (HQ-1246): one new message file under the messages role, which the
-// phone app shows as a card. Never edits one; refuses anything secret-shaped, like every write.
+// phone app shows as a card once paired and synced -- this call never confirms that part (HQ-2161).
+// Never edits one; refuses anything secret-shaped, like every write.
 export function message(evda, args = {}, { now = new Date() } = {}) {
   onlyKeys("evda_message", args, ["title", "body", "from"], "It writes one new message for the owner and nothing else: it takes no path, and it never edits a message once written.");
   return writeMessage(evda, args, { now, refuseSecrets });