create-evda 0.1.8 → 0.1.10

package/lib/day-writer.mjs

@@ -0,0 +1,110 @@
+// 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;
+}
+
+// HQ-2596: where words wait when the writer cannot be reached. One JSON file per write in the daily
+// folder's `.outbox/`, so each file has one writer and no sync can drop it; the writer files them,
+// oldest first, once its own copy of the day has synced. A file in that folder is not a day file, so
+// this guard allows writing it.
+export const OUTBOX_DIR = ".outbox";
+
+function sentence(writer, file) {
+  const outbox = `${join(dirname(file), OUTBOX_DIR)}/`;
+  return `EVÐA: ${basename(file)} is the daily file, and this machine does not write it. ${DAY_WRITER_ENV} names the machine that does (${writer}). Two machines writing one daily file through a synced folder lose one of the writes with no conflict copy. Append the words with the evda MCP tool evda_write, which that machine serves. If evda_write is not connected or that machine cannot be reached, queue the words in the outbox instead: write one new file per message to ${outbox}<UTC timestamp>-<host>-evda_write.json holding {tool, words, context, at, host} (tool "evda_write", words verbatim, at in UTC ISO), and the writer files them into the day when it is back. Tell the owner the words are queued, not filed, and do not write the daily file here.`;
+}
+
+// The decision for one PreToolUse input. { decision: "allow" } or { decision: "deny", reason }.
+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

@@ -69,9 +69,12 @@ import { folderManifests, folderFor, viewNamedIn, FOLDER_MANIFEST } from "./fold
 import { referencesIn } from "./references.mjs";
 import { KIND_FOR_TYPE, PERSON_KINDS, entryFromFile, readEntry } from "./kinds.mjs";
 import { datedHeadings } from "./migrate-people.mjs";
+import { personFolderProblems, README_NAME } from "./person-folders.mjs";
 import { EvdaError } from "./errors.mjs";
 import { hookStatus, promptHookStatus, HOOK_REL, PROMPT_HOOK_REL, SETTINGS_REL } from "./hooks.mjs";
 import { FILING_MODES, filingOf } from "./day-file.mjs";
+import { correctionsTarget } from "./corrections.mjs";
+import { EVERY_CHAT_KEY } from "./every-chat.mjs";
 import { listSkills, SKILLS_REL } from "./skills.mjs";
 import { guardStatus } from "./connect.mjs";
 
@@ -236,7 +239,12 @@ export function doctor(dir, { out = console.log, via = "argument", depth = 0 } =
         fail(rel, e.message);
       }
       if (fence === null) warn(rel, "has no evda:generated fence. The owner has taken the whole file; `evda upgrade` has nothing it owns to replace.");
-      if (!/## What I have been taught/.test(agents)) warn(rel, 'has no "## What I have been taught" section, so a correction has nowhere to land.');
+      // HQ-2325: a record that keeps its corrections in their own file names it in evda.json, and
+      // then the heading is not where they land, so its absence is not a warning.
+      const corrections = correctionsTarget({ dir, manifest });
+      if (corrections?.problem) warn("evda.json", `${corrections.problem} evda_record_correction refuses until it does.`);
+      else if (corrections) ok(1, "corrections", `evda.json names ${corrections.rel}: a correction lands there as a dated section`);
+      else if (!/## What I have been taught/.test(agents)) warn(rel, 'has no "## What I have been taught" section, and evda.json names no "corrections" file, so a correction has nowhere to land.');
     }
     // Claude Code reads CLAUDE.md and nothing else. If the operating layer is elsewhere, CLAUDE.md
     // has to import it or a Claude Code session here starts with no instructions.
@@ -265,6 +273,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.
@@ -660,10 +680,21 @@ export function doctor(dir, { out = console.log, via = "argument", depth = 0 } =
           if (name === FOLDER_MANIFEST) continue;
           const rel = relative(dir, p);
           const read = entryFromFile(name, readFileSync(p, "utf8"));
-          if (read === null) continue;
+          // In a person folder every file directly inside is a person's profile (HQ-2024), so one
+          // with no kind is a profile doctor would otherwise never read, and fails. Its README, its
+          // manifest and its declared views are not people; Processing/ sits beside the folder.
+          const unread = want === "person-profile" && p.slice(0, p.lastIndexOf(sep)) === f.dir && name !== README_NAME;
+          if (read === null) {
+            if (unread && /\.md$/i.test(name)) fail(rel, `has no person-profile frontmatter, so doctor never reads it. ${where} declares type person: every file in it opens with kind: person-profile (scripts/migrate-people.mjs adds it).`);
+            continue;
+          }
           if (read.error) { fail(rel, `${read.error} ${where} holds ${want} entries.`); continue; }
           const kind = read.raw?.kind;
-          if (kind === undefined) { warn(rel, `has no "kind", so it is not read as a ${want}. ${where} declares type ${f.type}.`); continue; }
+          if (kind === undefined) {
+            if (unread) fail(rel, `has no "kind", so doctor never reads it as a person-profile. ${where} declares type person.`);
+            else warn(rel, `has no "kind", so it is not read as a ${want}. ${where} declares type ${f.type}.`);
+            continue;
+          }
           entries += 1;
           if (kind !== want) { fail(rel, `is a ${kind}, and ${where} declares type ${f.type}, whose entries are ${want}. Move it, or say what the folder holds.`); continue; }
           counts[want] = (counts[want] ?? 0) + 1;
@@ -682,6 +713,17 @@ export function doctor(dir, { out = console.log, via = "argument", depth = 0 } =
           }
         }
       }
+      // Person folders (HQ-2024, lib/person-folders.mjs): one file per person, named for the
+      // person, no subfolder, no lone parenthetical, no redirect stub. Read across every person
+      // folder at once, because two people who share a name can live in two folders.
+      const people = typed.filter((f) => f.type === "person");
+      if (people.length) {
+        const skipPaths = new Set(people.flatMap((f) => [join(f.dir, FOLDER_MANIFEST), ...f.views.map((v) => resolve(dir, v.path))]));
+        const layout = personFolderProblems(people.map((f) => f.dir), { skip: skipPaths });
+        for (const p of layout.problems) fail(relative(dir, p.path), p.message);
+        if (layout.files === 0) skip("person folder layout", `${people.length} person folder(s) hold no person files yet`);
+        else ok(layout.files, "person files", `across ${people.length} person folder(s): one file each, no subfolder, no lone parenthetical, no redirect stub`);
+      }
       if (entries === 0) skip("typed entries", `${typed.length} typed folder(s) hold no entry files yet`);
       else ok(entries, "typed entries", `across ${typed.length} folder(s): ${PERSON_KINDS.filter((k) => counts[k]).map((k) => `${counts[k]} ${k}`).join(", ") || "none of the declared kind"}`);
     }

package/lib/every-chat.mjs

@@ -0,0 +1,128 @@
+// 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.
+
+import { appLike } from "./connecting-apps.mjs";
+
+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 chat app is calling, from initialize's clientInfo.name: the every-chat key of the first row
+// in lib/connecting-apps.mjs (HQ-2218) whose pattern matches it. A coding agent's row has none
+// (null), and a name no row matches is "other", asked with GENERIC_WHERE rather than skipped.
+export function chatAppOf(clientName) {
+  const row = appLike(clientName);
+  return row ? row.chat : "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}`,
+  ];
+}