create-evda 0.1.8 → 0.1.10

package/lib/clients.mjs

@@ -1,13 +1,16 @@
 // How each AI client adds the EVDA MCP server, given the command that starts it. No node: imports,
 // so the EVDA app's webview renders the same text `evda connect` prints (lib/connect.mjs).
 
+import { everyChatLine, CHAT_APPS, GENERIC_WHERE } from "./every-chat.mjs";
+
 export const SERVER_NAME = "evda";
 
 const shellQuote = (s) => (/^[A-Za-z0-9_./:@=+-]+$/.test(s) ? s : `'${String(s).replace(/'/g, "'\\''")}'`);
 const tomlString = (s) => JSON.stringify(s);
 
-// `desktopConfig` is where claude_desktop_config.json lives on this machine, when known.
-export function clientsFor(command, args, { desktopConfig = null } = {}) {
+// `desktopConfig` is where claude_desktop_config.json lives on this machine, when known. `filing` is
+// the owner's answer in evda.json, which picks the form of the every-chat line (HQ-2205).
+export function clientsFor(command, args, { desktopConfig = null, filing = null } = {}) {
   const argv = [command, ...args].map(shellQuote).join(" ");
   return [
     {
@@ -37,6 +40,17 @@ export function clientsFor(command, args, { desktopConfig = null } = {}) {
       text: JSON.stringify({ mcpServers: { [SERVER_NAME]: { command, args } } }, null, 2),
       file: desktopConfig ?? "claude_desktop_config.json",
     },
+    {
+      // Cowork starts no server from claude_desktop_config.json and reads no folder's hooks; a plugin
+      // is the one way in (HQ-2802, lib/plugin.mjs). The same command as the server, with plugin for mcp.
+      key: "cowork",
+      label: "Claude Cowork",
+      steps: [
+        "Cowork does not use the desktop config above. Run this once to build a plugin for this record, then in the Claude app open Customize, then Plugins, then Add, then Upload plugin, and choose the zip it names.",
+      ],
+      text: [command, ...args.map((a, i) => (i === args.length - 2 && a === "mcp" ? "plugin" : a))].map(shellQuote).join(" "),
+      file: null,
+    },
     {
       key: "project",
       label: "One folder only (.mcp.json)",
@@ -44,5 +58,18 @@ export function clientsFor(command, args, { desktopConfig = null } = {}) {
       text: JSON.stringify({ mcpServers: { [SERVER_NAME]: { type: "stdio", command, args } } }, null, 2),
       file: ".mcp.json",
     },
+    {
+      // Not a way to add the server: the one line a chat app needs in its every-chat setting, because
+      // a chat that never calls an evda tool is reached by nothing else (lib/every-chat.mjs).
+      key: "every-chat",
+      label: "Every chat app (so each chat starts as your agent)",
+      steps: [
+        "Add this line to your chat app's every-chat instructions:",
+        ...Object.values(CHAT_APPS).map((a) => `${a.label}: ${a.where}`),
+        `Any other app: ${GENERIC_WHERE}`,
+      ],
+      text: everyChatLine(filing),
+      file: null,
+    },
   ];
 }

package/lib/connect.mjs

@@ -14,6 +14,7 @@ import { delimiter, dirname, join, resolve } from "node:path";
 import { homedir } from "node:os";
 import { fileURLToPath } from "node:url";
 import { clientsFor, SERVER_NAME } from "./clients.mjs";
+import { filingOf } from "./day-file.mjs";
 
 const HERE = dirname(fileURLToPath(import.meta.url));
 export const PACKAGE_ROOT = resolve(HERE, "..");
@@ -81,7 +82,7 @@ export function guardStatus(recordDir) {
 
 // A `node` on PATH that is this same binary, when there is one: Homebrew's /opt/homebrew/bin/node
 // survives an upgrade, and the versioned Cellar path process.execPath reports does not.
-function stableNode(execPath, env) {
+export function stableNode(execPath = process.execPath, env = process.env) {
   let target;
   try { target = realpathSync(execPath); } catch { return execPath; }
   for (const d of String(env.PATH ?? "").split(delimiter)) {
@@ -101,7 +102,13 @@ export function desktopConfigPath(platform = process.platform, env = process.env
 // Every client's setup for one record, as data. `text` fields are what a person copies.
 export function clients(recordDir, opts = {}) {
   const { command, args } = serverCommand(recordDir, opts);
-  return clientsFor(command, args, { desktopConfig: desktopConfigPath() });
+  return clientsFor(command, args, { desktopConfig: desktopConfigPath(), filing: opts.filing ?? filingIn(recordDir) });
+}
+
+// The owner's filing answer, for the form of the every-chat line. A record that cannot be read yet
+// (connect run before create-evda finished) gets the "everything" form, the default setup offers.
+function filingIn(recordDir) {
+  try { return filingOf(JSON.parse(readFileSync(join(resolve(recordDir), "evda.json"), "utf8"))); } catch { return null; }
 }
 
 export function connectText(recordDir, opts = {}) {

package/lib/connecting-apps.mjs

@@ -0,0 +1,56 @@
+// Which app is connecting, from initialize's clientInfo.name (HQ-2218). One table names each app once,
+// and both uses read it: clientProfile in lib/mcp.mjs (which sections, how large a part) by the exact
+// names in `names`, and chatAppOf in lib/every-chat.mjs (which every-chat setup words) by `like`.
+// Before this the two were separate tables (HQ-2207, HQ-2205) that agreed only by care.
+// No node: imports, because lib/every-chat.mjs reads this file and lib/clients.mjs, rendered in the
+// EVDA app's webview, reads that one.
+//
+// names: the exact clientInfo.name values, compared trimmed and case-insensitively. claude-code and
+// codex-mcp-client measured 2026-10-05 (a probe server logging clientInfo, driven by `claude -p` and
+// `codex exec`). claude.ai sends Anthropic/ClaudeAI, measured 2026-10-05 in the remote server's log
+// from a fresh web chat; claude-ai stays as the published form. openai-mcp is the name ChatGPT
+// publishes and is unmeasured until Hestia's evda-mcp log holds one (it held none on 2026-10-15).
+//
+// like: a pattern for names nobody has measured yet, read top to bottom, first match wins. Every
+// coding agent comes before the chat apps, because its every-session file is AGENTS.md or
+// CLAUDE.md, which create-evda already writes into the record, so it gets no every-chat words
+// (chat: null). A name no row matches is "other", asked with GENERIC_WHERE, so a new app still gets
+// the line.
+//
+// surface, max, budget: what clientProfile serves an app it knows by name. max null is the smallest
+// documented cap, LAYER_PART_MAX in lib/mcp.mjs; budget null is CHAT_LAYER_BUDGET there.
+// Limits: claude.ai and the desktop app take a tool result of about 150,000 characters
+// (claude.com/docs/connectors/building, "Design within the size and timeout limits"); Claude Code
+// 25,000 tokens (same page, MAX_MCP_OUTPUT_TOKENS); OpenAI publishes no figure for ChatGPT and
+// truncates an over-budget result at a line, so ChatGPT and every unknown app get the smallest
+// cap. Codex documents none either and gets the same.
+// claude.ai's budget is its own (HQ-2327): his chat layer measured 2026-10-07 at about 90,000
+// characters whole (head 5,000, core 28,717, owner sections 56,041), and at the shared 70,000 his
+// "Proactive Context Loading" (20,238, the Deep Work Queue, Weekends & Trips and friction rules)
+// reached claude.ai as one listed heading, fetched 0 times in 21 layer loads. 100,000 serves it
+// whole and leaves 40,000 of the 140,000 cap for what the first call adds after the layer
+// (openChat: replies, recent days, people).
+export const CLAUDE_AI_LAYER_BUDGET = 100_000;
+
+export const CONNECTING_APPS = [
+  { app: "Claude Code", names: ["claude-code"], like: /claude[-_ ]?code/i, chat: null, surface: "terminal", max: null, budget: null },
+  { app: "Codex", names: ["codex-mcp-client"], like: /codex/i, chat: null, surface: "terminal", max: null, budget: null },
+  // Coding agents nobody has measured. No exact name, so clientProfile treats them as unknown apps.
+  { app: "another coding agent", names: [], like: /cursor|copilot|vscode|windsurf|zed|opencode|cline|aider|gemini[-_ ]?cli|goose|mcp-inspector|inspector/i, chat: null, surface: null, max: null, budget: null },
+  { app: "claude.ai", names: ["claude-ai", "anthropic/claudeai"], like: /claude|anthropic/i, chat: "claude", surface: "chat", max: 140_000, budget: CLAUDE_AI_LAYER_BUDGET },
+  { app: "ChatGPT", names: ["openai-mcp"], like: /openai|chatgpt/i, chat: "chatgpt", surface: "chat", max: null, budget: null },
+];
+
+const clean = (name) => (typeof name === "string" ? name.trim() : "");
+
+// The row whose exact names include this one, or null.
+export function appNamed(name) {
+  const n = clean(name).toLowerCase();
+  return n ? CONNECTING_APPS.find((a) => a.names.includes(n)) ?? null : null;
+}
+
+// The first row whose pattern matches this name, or null.
+export function appLike(name) {
+  const n = String(name ?? "").trim();
+  return CONNECTING_APPS.find((a) => a.like.test(n)) ?? null;
+}

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, existsSync, readFileSync, statSync } 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 }.
@@ -77,17 +120,132 @@ export function sectionBytes({ current, date, time, words, context = null, conti
   return { text: `${lead}${head}\n## ${time}\n\n${ctx}${body}\n`, opened: true };
 }
 
+// EVDA_DAY_LOCK_PATH (HQ-2165): when set, every append below takes this lock first, with the same
+// protocol Hestia's own journal-append.mjs takes through /usr/bin/shlock on the same path: the file
+// is created exclusively and holds the holder's pid and a newline (shlock's own format, so each side
+// sees the other's lock as held), it is released by deleting it, and a lock older than 120s is
+// broken (a journal append is sub-second, so anything older is a dead process, not contention).
+// Done in node rather than by running shlock, which exists only on macOS: on Linux or Windows every
+// write with the lock set would wait 8s and fail.
+//
+// This exists because two processes on ONE host -- Hestia's passes (journal-append.mjs, writing the
+// pointer line and an agent's record with a read-the-whole-file-then-writeFileSync-the-whole-file
+// step) and `evda mcp`'s own evda_write (pure appendFileSync here) -- both touch the same local file
+// with no shared lock today. appendFileSync alone is atomic, so two appends never corrupt each
+// other; the loss happens when a read-modify-write like journal-append.mjs's runs with a stale read
+// that predates this function's append, and then overwrites the whole file including the words this
+// function just added. Hestia's evda-mcp-run.sh sets this to the same ~/.hestia/journal.lock its
+// passes already use, so the two processes serialize against each other.
+//
+// NOT a fix for two different HOSTS: a lock file inside the iCloud-synced vault cannot coordinate
+// two machines, because acquiring it is itself a write subject to the exact same sync delay as the
+// content it is meant to protect. That class has no file-level fix; see HQ-2165 and
+// test/single-writer.test.mjs. This lock only ever runs on one host.
+function takeLock(lockPath) {
+  let fd;
+  try { fd = openSync(lockPath, "wx"); } catch (e) { if (e.code === "EEXIST") return false; throw e; }
+  try { writeSync(fd, `${process.pid}\n`); } finally { closeSync(fd); }
+  return true;
+}
+
+const pause = (ms) => Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+
+function withDayLock(fn) {
+  const lockPath = process.env.EVDA_DAY_LOCK_PATH;
+  if (!lockPath) return fn();
+  const start = Date.now();
+  while (!takeLock(lockPath)) {
+    let age = 0;
+    try { age = Date.now() - statSync(lockPath).mtimeMs; } catch { continue; /* released between the two calls */ }
+    if (age > 120_000) {
+      try { unlinkSync(lockPath); } catch { /* raced another breaker */ }
+      continue;
+    }
+    if (Date.now() - start > 8000) throw new Error(`evda day-file: could not acquire ${lockPath} within 8s`);
+    pause(100);
+  }
+  try { return fn(); } finally { try { unlinkSync(lockPath); } catch { /* already gone */ } }
+}
+
 // 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 }) {
-  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) });
-  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) };
+  return withDayLock(() => {
+    const exists = existsSync(abs);
+    const current = exists ? readFileSync(abs, "utf8") : null;
+    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) {
+      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";
+  });
 }