create-evda 0.1.8 → 0.1.9

package/lib/day-file.mjs

@@ -22,7 +22,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, writeSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 
 export const FILING_MODES = ["everything", "asked"];
@@ -77,17 +77,66 @@ 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 }.
 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 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) };
+  });
 }

package/lib/day-writer.mjs

@@ -0,0 +1,103 @@
+// One writer for the daily file (HQ-2165): a PreToolUse hook that refuses a direct write to the
+// record's daily file on any machine that is not the one writing it.
+//
+// iCloud (and any folder sync) gives each machine its own local copy of the daily file. When two
+// machines append to their own copies within one sync window, the sync keeps one whole copy and
+// drops the other, with no conflict copy (2026-10-03: the connector's evda_write on Hestia and a
+// laptop session's `cat >>` 35 seconds apart; the earlier words are in no file). No lock fixes it,
+// because taking a lock in the synced folder is itself a write with the same delay. What fixes it is
+// one machine doing every write to that file, and every other machine sending its words there:
+// through the evda MCP tool evda_write, which the writing machine serves (test/single-writer.test.mjs
+// test 2 is the proof that one replica keeps both writes).
+//
+// EVDA_DAY_WRITER names that machine's evda MCP endpoint. Set it on every machine that is NOT the
+// writer; leave it unset on the writer and on every install with one machine, where this allows
+// everything. The hook lives in the user's own Claude Code settings on that machine, never in the
+// record's synced .claude/settings.json, so the writer never sees it.
+//
+// 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
+// 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 { basename, dirname, isAbsolute, join, resolve } from "node:path";
+import { openEvda } from "./manifest.mjs";
+import { dayRole, findRecord } from "./day-file.mjs";
+import { shellPaths } from "./guard.mjs";
+
+export const DAY_WRITER_ENV = "EVDA_DAY_WRITER";
+
+// Shell commands that change the files they name, and the target of a redirect. A day file named
+// only by a reader (cat, grep, or a reader with 2>/dev/null) is a read, left to the read guard.
+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;
+
+// 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);
+  if (WRITERS.test(c)) return shellPaths(c);
+  return [...c.matchAll(REDIRECT)].map((m) => m[1].replace(/^["']|["']$/g, "")).filter((w) => w && !w.startsWith("&"));
+}
+const FILE_TOOLS = new Set(["Write", "Edit", "MultiEdit", "NotebookEdit"]);
+
+const real = (p) => { try { return realpathSync(p); } catch { return resolve(p); } };
+
+// The daily folder of the record holding `abs`, real path, or null when `abs` is in no record or the
+// record maps no daily role.
+function dailyDirOf(abs) {
+  const root = findRecord(dirname(abs));
+  if (!root) return null;
+  let evda;
+  try { evda = openEvda(real(root)); } catch { return null; }
+  const role = dayRole(evda.manifest.mapping);
+  if (!role) return null;
+  return real(join(evda.dir, evda.manifest.mapping[role]));
+}
+
+// True when `abs` is a markdown file directly in its record's daily folder. A file there need not
+// exist yet: creating today's file is the first write.
+export function isDayFile(abs) {
+  if (!/\.md$/i.test(abs)) return false;
+  const day = dailyDirOf(abs);
+  if (!day) return false;
+  return real(dirname(abs)) === day;
+}
+
+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.`;
+}
+
+// The decision for one PreToolUse input. { decision: "allow" } or { decision: "deny", reason }.
+export function decide(input, { env = process.env } = {}) {
+  const writer = (env[DAY_WRITER_ENV] ?? "").trim();
+  if (!writer) return { decision: "allow" };
+  if (env.EVDA_DAY_WRITER_FALSIFY === "allow-all") return { decision: "allow" };
+  const tool = input?.tool_name;
+  const args = input?.tool_input ?? {};
+  const cwd = typeof input?.cwd === "string" && input.cwd ? input.cwd : process.cwd();
+  const at = (p) => (isAbsolute(p) ? p : join(cwd, p));
+  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 ?? "");
+  } else return { decision: "allow" };
+  const hit = paths.map(at).find(isDayFile);
+  if (!hit) return { decision: "allow" };
+  return { decision: "deny", reason: sentence(writer, hit) };
+}
+
+// The hook's whole life: read stdin, answer on stdout, exit 0.
+export async function runHook({ stdin = process.stdin, stdout = process.stdout, env = process.env } = {}) {
+  let raw = "";
+  for await (const chunk of stdin) raw += chunk;
+  let input;
+  try { input = JSON.parse(raw); } catch { return 0; }
+  const d = decide(input, { env });
+  if (d.decision === "deny") {
+    stdout.write(JSON.stringify({ hookSpecificOutput: { hookEventName: "PreToolUse", permissionDecision: "deny", permissionDecisionReason: d.reason } }) + "\n");
+  }
+  return 0;
+}

package/lib/doctor.mjs

@@ -72,6 +72,7 @@ import { datedHeadings } from "./migrate-people.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 { EVERY_CHAT_KEY } from "./every-chat.mjs";
 import { listSkills, SKILLS_REL } from "./skills.mjs";
 import { guardStatus } from "./connect.mjs";
 
@@ -265,6 +266,18 @@ export function doctor(dir, { out = console.log, via = "argument", depth = 0 } =
   else if (manifest.filing) ok(1, "filing", `evda.json says "${manifest.filing}": ${manifest.filing === "everything" ? "every message the owner sends is filed without being asked" : "their words are filed only when they ask"}`);
   else skip("filing", "evda.json has no answer yet. The agent asks the owner once, at first connect, and records it with evda_filing.");
 
+  // 5b2b. every_chat (HQ-2205): per chat app, whether the owner put the every-chat line in its
+  // settings. An entry the server cannot read is asked about again, so it warns rather than fails.
+  const everyChat = manifest[EVERY_CHAT_KEY];
+  if (everyChat === undefined) skip("every-chat line", "evda.json records no app yet. The connector asks the owner once per chat app, the first time they connect from it, and records the answer with evda_every_chat.");
+  else if (!everyChat || typeof everyChat !== "object" || Array.isArray(everyChat)) warn("evda.json", `"${EVERY_CHAT_KEY}" must map each chat app to its answer, got ${JSON.stringify(everyChat)}. Every app is asked again until it does.`);
+  else {
+    const bad = Object.entries(everyChat).filter(([, e]) => !e || typeof e !== "object" || !["set", "declined"].includes(e.state));
+    if (bad.length) warn("evda.json", `"${EVERY_CHAT_KEY}" has an entry with no "state" of "set" or "declined" for ${bad.map(([k]) => k).join(", ")}, so that app is asked again.`);
+    const good = Object.entries(everyChat).filter(([k]) => !bad.some(([b]) => b === k));
+    if (good.length) ok(1, "every-chat line", good.map(([k, e]) => `${k}: ${e.state}${e.date ? ` ${e.date}` : ""}`).join("; "));
+  }
+
   // 5b3. the prompt hook (HQ-1385): a UserPromptSubmit hook that files each message, for an owner
   // who chose everything. Installed and current is a check; installed while filing says otherwise
   // warns, because it then files nothing and the settings say it does.

package/lib/every-chat.mjs

@@ -0,0 +1,132 @@
+// The every-chat line (HQ-2205, layer 4): the one sentence an owner puts in their chat app's
+// account-wide instructions so that every chat loads the operating layer before it answers.
+//
+// Why it exists. Hestia's evda-mcp log (2026-09-23 to 2026-10-05) holds 153 claude.ai sessions, and
+// 145 of them never called a single EVÐA tool. A chat that calls no tool never sees a tool
+// description, a tool result or the server's instructions (which claude.ai does not act on anyway),
+// so nothing the server does can reach it. The one thing every chat in an app reads is that app's
+// own account-wide setting. So the connector asks the owner once, at the moment it first sees them in
+// that app, to put this line there, and evda.json remembers the answer per app.
+//
+// One source. create-evda, `evda connect`, the shipped skill and the server all print the line from
+// here, so no surface can carry a different copy. No node: imports, because lib/clients.mjs is
+// rendered in the EVDA app's webview and reads this file.
+
+export const EVERY_CHAT_KEY = "every_chat";
+
+// Bumped when the line's meaning changes. An owner who set an older version is asked once more,
+// because the line in their app no longer says what the record needs; one who declined is not.
+export const EVERY_CHAT_VERSION = 1;
+
+// The line, by the owner's filing answer (evda.json "filing"). It is written in the first person
+// because the app shows it to the model as the owner's own words. Each clause carries its reason,
+// since a model follows a reason into cases a bare order did not foresee:
+//   - "before your first reply" is the whole point: a chat that answers first answers as a generic
+//     assistant, and the first message is the one most often lost.
+//   - the tool is named exactly, so an app that defers connector tools can search for it by name.
+//   - "if those tools are not in this chat, ignore this" keeps a chat with the connector switched
+//     off from stalling or apologizing.
+// An owner who chose "asked" gets the same load and no instruction to file everything (HQ-1385).
+export const EVERY_CHAT_LINE = {
+  everything:
+    "My EVÐA (my personal record) is connected through the evda tools. In every chat, before your first reply, call evda_operating_layer and follow it, because it says who you are for me and how my record is kept; then file each message I send with evda_write, in my exact words, in the same turn, so nothing I say is lost. If the evda tools are not in this chat, ignore this.",
+  asked:
+    "My EVÐA (my personal record) is connected through the evda tools. In every chat, before your first reply, call evda_operating_layer and follow it, because it says who you are for me and how my record is kept. Save something to my record only when I ask you to. If the evda tools are not in this chat, ignore this.",
+};
+
+export function everyChatLine(filing) {
+  return EVERY_CHAT_LINE[filing === "asked" ? "asked" : "everything"];
+}
+
+// Where each chat app keeps its every-chat setting, only as its own help page says it, with the
+// page and the date it was read. An app not listed here, or one whose page could not be read, gets
+// GENERIC_WHERE: naming a menu that does not exist would send the owner hunting for it.
+//   claude: support.claude.com 10185728, read 2026-10-05: "Click your initials in the lower left
+//     corner. Select 'Settings.' Under 'Instructions for Claude,' describe your instructions" and
+//     "Any instructions you add here will be applied to all of your conversations with Claude."
+//     One account setting, so claude.ai, the desktop app and the phone app share it.
+//   chatgpt: help.openai.com 8096356, read 2026-10-05: web and desktop, Settings, Personalization,
+//     Enable customization on, the Custom Instructions field; iOS and Android, Settings, Customize
+//     ChatGPT. Free and Go plans hold up to 1,500 characters, which the line fits inside.
+export const CHAT_APPS = {
+  claude: {
+    label: "Claude",
+    where: "Click your initials in the lower left corner, open Settings, and add it under \"Instructions for Claude\". It applies to every chat on claude.ai, the desktop app and the phone app.",
+    limit: null,
+    source: "https://support.claude.com/en/articles/10185728-understanding-claude-s-personalization-features",
+    checked: "2026-10-05",
+  },
+  chatgpt: {
+    label: "ChatGPT",
+    where: "On the web or desktop, open Settings, then Personalization, make sure Enable customization is on, and add it to the Custom Instructions field. On a phone it is Settings, then Customize ChatGPT.",
+    limit: 1500,
+    source: "https://help.openai.com/en/articles/8096356-chatgpt-custom-instructions",
+    checked: "2026-10-05",
+  },
+};
+export const GENERIC_WHERE = "Add it to your app's every-chat instructions: the setting that applies to all of your conversations, not just this one.";
+
+// Which app is calling, from initialize's clientInfo.name. Coding agents (Claude Code, Codex,
+// Cursor and the like) are left out, because their every-session file is AGENTS.md or CLAUDE.md,
+// which create-evda already writes into the record. Matched by pattern: the names claude.ai and
+// ChatGPT send are not yet measured (HQ-2207 measures them), and a name that matches nothing is
+// "other", which is asked with GENERIC_WHERE rather than skipped, so a new app still gets the line.
+const CODING = /claude[-_ ]?code|codex|cursor|copilot|vscode|windsurf|zed|opencode|cline|aider|gemini[-_ ]?cli|goose|mcp-inspector|inspector/i;
+export function chatAppOf(clientName) {
+  const n = String(clientName ?? "").trim();
+  if (CODING.test(n)) return null;
+  if (/claude|anthropic/i.test(n)) return "claude";
+  if (/openai|chatgpt/i.test(n)) return "chatgpt";
+  return "other";
+}
+
+// What evda.json says for one app: { state: "set" | "declined", form, version, date } or null.
+export function everyChatEntry(manifest, app) {
+  const all = (manifest?.manifest ?? manifest)?.[EVERY_CHAT_KEY];
+  const e = all && typeof all === "object" && !Array.isArray(all) ? all[app] : null;
+  return e && typeof e === "object" && !Array.isArray(e) ? e : null;
+}
+
+// Whether this app's owner still needs to be asked. A "declined" stands: the owner said no, and
+// asking again would be nagging. A "set" stands while the line they set says what the record needs
+// now: the same filing form and the same version.
+export function needsEveryChat(manifest, app, filing) {
+  if (!app) return false;
+  const e = everyChatEntry(manifest, app);
+  if (e?.state === "declined") return false;
+  if (e?.state === "set") return !(e.form === (filing === "asked" ? "asked" : "everything") && e.version === EVERY_CHAT_VERSION);
+  return true;
+}
+
+// The walkthrough the model gives the owner, in the result of the first tool it calls in a chat.
+// It is written to the model: what the setting is for, the line to hand over whole, where it goes in
+// this app, and how the answer is kept, so the owner is asked once per app and never again.
+export function everyChatWalkthrough(app, filing) {
+  const a = CHAT_APPS[app];
+  const line = everyChatLine(filing);
+  return [
+    `## One setting for every chat${a ? ` in ${a.label}` : ""}`,
+    "",
+    `Chats that never call an evda tool never reach this record: they answer as a generic assistant and keep nothing the owner says. The one thing every chat in ${a ? a.label : "their app"} reads is its every-chat setting, and nothing in the record shows that this owner has put the line there yet. So once, in this reply and after answering what they asked, tell them in a sentence or two why it matters and give them this line to copy, whole and exactly as written:`,
+    "",
+    "```",
+    line,
+    "```",
+    "",
+    `Where it goes: ${a ? a.where : GENERIC_WHERE}`,
+    "",
+    `When they say it is set, or that the line is already in place (set in an earlier chat, or added by hand), record it with evda_every_chat (app "${app}", state "set", confirmed: true), so no later chat in ${a ? a.label : "this app"} asks again. If they say they do not want it, record state "declined" the same way, and it is never raised again in ${a ? a.label : "this app"}. If they leave it for now, say nothing more about it in this chat.`,
+  ].join("\n");
+}
+
+// The line and where it goes in every app, for the setup surfaces: create-evda, `evda connect`.
+export function everyChatSetupLines(filing) {
+  return [
+    "So every chat starts as your agent, even one that never touches your record, add this line to your chat app's every-chat instructions:",
+    "",
+    `    ${everyChatLine(filing)}`,
+    "",
+    ...Object.values(CHAT_APPS).map((a) => `  ${a.label}: ${a.where}`),
+    `  Any other app: ${GENERIC_WHERE}`,
+  ];
+}