create-evda 0.1.9 → 0.1.10

package/lib/attested-host.mjs

@@ -0,0 +1,269 @@
+// The gate a client goes through before it sends a hosted EVÐA anything: a record, a circle key, a
+// token. (HQ-2083, Spec 08 section 8: "If it doesn't match, your phone won't send anything.")
+//
+// lib/tdx-attestation.mjs answers "does this quote prove this VM?". This file is what makes that answer
+// decide whether bytes leave the device. A client gets a payload to a hosted EVÐA only through
+// `gate.open(...)` and then `session.send(...)`, and every path that is not a verified quote under a
+// pinned measurement ends in a refusal with nothing sent.
+//
+// The protocol, version 1. Over TLS to the host, on one connection:
+//   client -> host  POST /.well-known/evda-attestation  {"v":1,"nonce":"<base64, 32 bytes>"}
+//   host -> client  {"v":1,"platform":"tdx","quote":"<base64>","collateral":{tcbInfo,
+//                    tcbInfoIssuerChain,qeIdentity,qeIdentityIssuerChain}}
+// The VM puts reportDataFor(nonce, its TLS public key) in the quote's REPORTDATA. The client takes the
+// TLS key from the connection it is holding, never from the response body, so a host cannot name a key
+// other than the one it is actually serving with. Delivery then goes over a connection pinned to that
+// key (SHA-256 of its SPKI DER); a connection presenting any other key is refused before anything is
+// written to it.
+//
+// The pinned measurement is the client's own configuration, never something a host supplies. With no
+// pinned measurement the gate refuses: an unconfigured client is not a client that trusts everyone.
+//
+// Not here yet: tying the pinned measurement to EVÐA's Sigstore log (lib/measurement-log.mjs checks a
+// logged digest; the statement that carries MRTD and RTMRs is a later slice), SEV-SNP, and the Swift
+// port of this gate in iris-mobile, which follows this file and its test vectors.
+
+import { createHash, createPublicKey, KeyObject, timingSafeEqual, X509Certificate } from "node:crypto";
+import { request as httpsRequest } from "node:https";
+import { createNonceBook, MEASUREMENT_NAMES, TDX_TRUST, verifyTdxAttestation, parseTdxQuote } from "./tdx-attestation.mjs";
+
+/** Where a hosted EVÐA answers the attestation challenge. */
+export const ATTESTATION_PATH = "/.well-known/evda-attestation";
+
+/** The protocol version this client speaks. A response naming another version is refused. */
+export const ATTESTATION_PROTOCOL_VERSION = 1;
+
+/** Why the gate refused, as a stable code. `message` carries the same thing for a person. */
+export const REFUSAL = Object.freeze({
+  NO_POLICY: "no-policy",
+  UNREACHABLE: "unreachable",
+  NO_QUOTE: "no-quote",
+  UNREADABLE_QUOTE: "unreadable-quote",
+  WRONG_MEASUREMENT: "wrong-measurement",
+  NOT_FRESH: "not-fresh",
+  NOT_BOUND: "not-bound",
+  NOT_PROVEN: "not-proven",
+  WRONG_CONNECTION: "wrong-connection",
+  NOT_DELIVERED: "not-delivered",
+});
+
+// What a person reads. Each says that nothing was sent and why, in words that need no TDX.
+const SAID = {
+  [REFUSAL.NO_POLICY]: "this app has no published EVÐA code to compare the server against, so it cannot tell whether the server is safe",
+  [REFUSAL.UNREACHABLE]: "the server could not be reached to ask it for proof",
+  [REFUSAL.NO_QUOTE]: "the server did not send any proof of what code it is running",
+  [REFUSAL.UNREADABLE_QUOTE]: "the server's proof could not be read",
+  [REFUSAL.WRONG_MEASUREMENT]: "the server is not running the code EVÐA publishes",
+  [REFUSAL.NOT_FRESH]: "the server's proof answered a request this phone did not just make, so it could be an old proof played back",
+  [REFUSAL.NOT_BOUND]: "the server's proof was not made for this request on this connection, so it could be an old proof played back or someone in the middle",
+  [REFUSAL.NOT_PROVEN]: "the server could not prove it is a locked, up to date part of the chip",
+  [REFUSAL.WRONG_CONNECTION]: "the connection is not the one the server proved, so someone else could be in the middle",
+  [REFUSAL.NOT_DELIVERED]: "the server was proven, and sending to it then failed",
+};
+
+const sha256Hex = (b) => createHash("sha256").update(b).digest("hex");
+
+/** A refusal: nothing was sent. `reason` is the detail for a log, `message` the sentence for a person. */
+function refuse(code, reason) {
+  return { ok: false, sent: false, code, reason, message: `Nothing was sent: ${SAID[code]}.` };
+}
+
+const spkiDer = (key) => {
+  if (Buffer.isBuffer(key) || key instanceof Uint8Array) return createPublicKey({ key: Buffer.from(key), format: "der", type: "spki" }).export({ type: "spki", format: "der" });
+  if (key instanceof KeyObject && key.type === "public") return key.export({ type: "spki", format: "der" });
+  return createPublicKey(key).export({ type: "spki", format: "der" });
+};
+
+/** The pin for a TLS public key: SHA-256 of its SPKI DER, lowercase hex. The same value the verifier returns. */
+export function tlsKeyPin(tlsPublicKey) {
+  return sha256Hex(spkiDer(tlsPublicKey));
+}
+
+/** Whether `tlsPublicKey` is the key `pin` names. False for anything unreadable. */
+export function pinMatches(pin, tlsPublicKey) {
+  try {
+    const have = Buffer.from(tlsKeyPin(tlsPublicKey), "hex");
+    const want = Buffer.from(String(pin ?? ""), "hex");
+    return want.length === 32 && timingSafeEqual(have, want);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Why `policy` cannot gate anything, in words, or null when it can.
+ * policy: { platform: "tdx", measurements: { mrtd, rtmr0, rtmr1, rtmr2, rtmr3 }, minTcb: { tcbEvaluationDataNumber, statuses? } }
+ */
+export function hostPolicyProblem(policy) {
+  if (!policy) return "no pinned measurement is configured";
+  if (policy.platform !== "tdx") return `platform ${JSON.stringify(policy.platform ?? null)} is not one this client verifies (only tdx)`;
+  const m = policy.measurements;
+  const missing = MEASUREMENT_NAMES.filter((n) => !/^[0-9a-f]{96}$/.test(m?.[n] ?? ""));
+  if (missing.length) return `the pinned measurement does not name ${missing.join(", ")} as 96 lowercase hex characters each`;
+  if (!Number.isSafeInteger(policy.minTcb?.tcbEvaluationDataNumber)) return "the policy names no minimum TCB evaluation number";
+  return null;
+}
+
+/** The JSON body a client sends to ATTESTATION_PATH for `nonce` (32 bytes). */
+export function attestationRequest(nonce) {
+  const n = Buffer.from(nonce);
+  if (n.length !== 32) throw new Error("the nonce must be 32 bytes");
+  return { v: ATTESTATION_PROTOCOL_VERSION, nonce: n.toString("base64") };
+}
+
+/** Reads a host's answer. Returns { quote, collateral } or { error } in words; never throws. */
+export function parseAttestationResponse(body) {
+  let r = body;
+  if (typeof r === "string" || Buffer.isBuffer(r) || r instanceof Uint8Array) {
+    try { r = JSON.parse(Buffer.from(r).toString("utf8")); } catch { return { error: "the response is not JSON" }; }
+  }
+  if (!r || typeof r !== "object") return { error: "the response is empty" };
+  if (r.v !== ATTESTATION_PROTOCOL_VERSION) return { error: `the response speaks protocol ${JSON.stringify(r.v ?? null)}, not ${ATTESTATION_PROTOCOL_VERSION}` };
+  if (r.platform !== "tdx") return { error: `the response is for platform ${JSON.stringify(r.platform ?? null)}, not tdx` };
+  if (typeof r.quote !== "string" || r.quote.length === 0) return { error: "the response carries no quote", missing: true };
+  if (!/^[A-Za-z0-9+/]+={0,2}$/.test(r.quote)) return { error: "the quote is not base64" };
+  return { quote: Buffer.from(r.quote, "base64"), collateral: r.collateral ?? null };
+}
+
+// The verifier's reasons, sorted into what a person needs to know. The tests hold one case per code,
+// so a reworded reason in tdx-attestation.mjs that stops matching fails there, not silently here.
+function classify(reason) {
+  if (/^(MRTD|RTMR\d) is /.test(reason)) return REFUSAL.WRONG_MEASUREMENT;
+  if (/^REPORTDATA /.test(reason)) return REFUSAL.NOT_BOUND;
+  if (/nonce/.test(reason)) return REFUSAL.NOT_FRESH;
+  if (/could not be read|truncated|too short|shorter than|not understood/.test(reason)) return REFUSAL.UNREADABLE_QUOTE;
+  return REFUSAL.NOT_PROVEN;
+}
+
+/**
+ * The gate. `policy` is the client's pinned measurement (see hostPolicyProblem); `clock` returns the
+ * time certificates, collateral and the nonce are judged at.
+ *
+ * gate.open({ challenge }) asks the host to prove itself. `challenge(requestBody)` is the transport: it
+ * POSTs the body to ATTESTATION_PATH and resolves { body, tlsPublicKey }, the host's answer and the TLS
+ * public key of the connection that answer came over. It resolves to an attested session, or a refusal.
+ *
+ * session.send(payload, { deliver }) hands `payload` to `deliver(payload, { pin })` once. `deliver` must
+ * send only over a connection whose TLS key matches `pin` (httpsHostTransport does this for Node) and
+ * resolve { tlsPublicKey, result } naming the key it actually used; a key other than the attested one is
+ * reported, and a transport that refuses the wrong key throws an error with code EVDA_PIN_MISMATCH. `payload` may be a function, called only after the host is proven, so key
+ * material can be produced only for a host that passed.
+ */
+export function createAttestedHostGate({ policy, nonces = createNonceBook(), clock = () => Date.now(), trust = TDX_TRUST } = {}) {
+  return {
+    async open({ challenge } = {}) {
+      const problem = hostPolicyProblem(policy);
+      if (problem) return refuse(REFUSAL.NO_POLICY, problem);
+      if (typeof challenge !== "function") return refuse(REFUSAL.UNREACHABLE, "no transport was given to reach the host");
+
+      const nonce = nonces.issue(clock());
+      let answer;
+      try {
+        answer = await challenge(attestationRequest(nonce));
+      } catch (err) {
+        return refuse(REFUSAL.UNREACHABLE, `the attestation request failed: ${err?.message ?? err}`);
+      }
+      const parsed = parseAttestationResponse(answer?.body);
+      if (parsed.error) return refuse(parsed.missing || answer?.body == null ? REFUSAL.NO_QUOTE : REFUSAL.UNREADABLE_QUOTE, parsed.error);
+      try {
+        parseTdxQuote(parsed.quote);
+      } catch (err) {
+        return refuse(REFUSAL.UNREADABLE_QUOTE, `the quote could not be read: ${err.message}`);
+      }
+      if (!answer.tlsPublicKey) return refuse(REFUSAL.WRONG_CONNECTION, "the transport did not report the TLS key of the connection the quote came over");
+
+      const v = verifyTdxAttestation({
+        quote: parsed.quote, nonce, nonces, tlsPublicKey: answer.tlsPublicKey,
+        expected: policy.measurements, minTcb: policy.minTcb, collateral: parsed.collateral, now: clock(), trust,
+      });
+      if (!v.ok) return refuse(classify(v.reason), v.reason);
+      return session({ pin: v.tlsPublicKeySha256, measurements: v.measurements, tcb: v.tcb });
+    },
+  };
+}
+
+function session({ pin, measurements, tcb }) {
+  return {
+    ok: true,
+    pin,
+    measurements,
+    tcb,
+    async send(payload, { deliver } = {}) {
+      if (typeof deliver !== "function") return refuse(REFUSAL.NOT_DELIVERED, "no delivery transport was given");
+      let bytes;
+      try {
+        bytes = typeof payload === "function" ? await payload({ pin, measurements }) : payload;
+      } catch (err) {
+        return refuse(REFUSAL.NOT_DELIVERED, `the payload could not be prepared: ${err?.message ?? err}`);
+      }
+      let out;
+      try {
+        out = await deliver(bytes, { pin });
+      } catch (err) {
+        if (err?.code === "EVDA_PIN_MISMATCH") return refuse(REFUSAL.WRONG_CONNECTION, err.message);
+        return refuse(REFUSAL.NOT_DELIVERED, `delivery failed: ${err?.message ?? err}`);
+      }
+      // A transport that pins as it must never reaches this; one that does not has already sent, and says so.
+      if (!pinMatches(pin, out?.tlsPublicKey)) return { ok: false, sent: true, code: REFUSAL.WRONG_CONNECTION, reason: "the delivery went over a TLS key other than the attested one", message: `Sent over the wrong connection: ${SAID[REFUSAL.WRONG_CONNECTION]}. Treat what was sent as exposed.` };
+      return { ok: true, sent: true, pin, result: out.result };
+    },
+  };
+}
+
+// ─── the Node transport (the Mac client; the phone's is Swift) ──────────────────────────────────
+
+const keyOfCert = (cert) => (cert?.raw ? new X509Certificate(cert.raw).publicKey : null);
+
+function postJson(url, body, { pin } = {}) {
+  return new Promise((resolve, reject) => {
+    const u = new URL(url);
+    if (u.protocol !== "https:") return reject(new Error(`${u.origin} is not https`));
+    const data = Buffer.from(JSON.stringify(body));
+    const req = httpsRequest(u, { method: "POST", rejectUnauthorized: false, agent: false, headers: { "content-type": "application/json", "content-length": data.length } }, (res) => {
+      const chunks = [];
+      res.on("data", (c) => chunks.push(c));
+      res.on("end", () => resolve({ status: res.statusCode, body: Buffer.concat(chunks), tlsPublicKey }));
+      res.on("error", reject);
+    });
+    let tlsPublicKey = null;
+    req.on("error", reject);
+    // Nothing is written until the handshake is done and the key is read, so a pinned request to the
+    // wrong key leaves with no header and no body.
+    req.on("socket", (socket) => {
+      socket.once("secureConnect", () => {
+        try { tlsPublicKey = keyOfCert(socket.getPeerCertificate(true)); } catch { tlsPublicKey = null; }
+        if (pin !== undefined && !pinMatches(pin, tlsPublicKey)) {
+          const err = Object.assign(new Error("the server's TLS key is not the attested one"), { code: "EVDA_PIN_MISMATCH" });
+          req.destroy(err);
+          return;
+        }
+        req.end(data);
+      });
+    });
+  });
+}
+
+/**
+ * The Node transport for one hosted EVÐA at `origin` (https). challenge() for gate.open, and
+ * deliver(path) for session.send, which posts the payload (JSON-serializable) over a connection pinned
+ * to the attested key: a server presenting any other key is dropped after the handshake, before any
+ * header or body is written. The VM's certificate is self-signed inside the VM, so the CA check is
+ * replaced by the attestation and the pin, not by nothing.
+ */
+export function httpsHostTransport(origin) {
+  return {
+    async challenge(requestBody) {
+      const r = await postJson(new URL(ATTESTATION_PATH, origin), requestBody);
+      if (r.status !== 200) throw new Error(`the host answered ${r.status}`);
+      return { body: r.body, tlsPublicKey: r.tlsPublicKey };
+    },
+    deliver(path) {
+      return async (payload, { pin }) => {
+        if (!pin) throw new Error("no pin was given, so delivery cannot be bound to the attested key");
+        const r = await postJson(new URL(path, origin), payload, { pin });
+        if (r.status < 200 || r.status >= 300) throw new Error(`the host answered ${r.status}`);
+        return { tlsPublicKey: r.tlsPublicKey, result: r.body };
+      };
+    },
+  };
+}

package/lib/clients.mjs

@@ -40,6 +40,17 @@ export function clientsFor(command, args, { desktopConfig = null, filing = 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)",

package/lib/connect.mjs

@@ -82,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)) {

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;
+}