create-evda 0.1.8 → 0.1.10

package/lib/qr.mjs

@@ -0,0 +1,317 @@
+// A QR code for the pairing link, drawn here (HQ-2040), so asking Claude to pair a phone can hand
+// the person something to scan. No network QR service sees the link (the code in it is a key until
+// it is used), and the package keeps its zero runtime dependencies (test/deps.test.mjs).
+//
+// Byte mode, versions 1 to 40, error correction L, M, Q or H, following ISO/IEC 18004 the way
+// Project Nayuki's reference encoder lays it out. test/qr.test.mjs holds the matrices against a
+// second, independent encoder's output, module for module.
+//
+// Out: the module matrix, a PNG (8-bit grey, deflated by node:zlib), and the same code as text in
+// half blocks, which a chat can show in a code block when it cannot show an image.
+
+import { deflateSync } from "node:zlib";
+
+const ECL = {
+  L: { bits: 1, i: 0 },
+  M: { bits: 0, i: 1 },
+  Q: { bits: 3, i: 2 },
+  H: { bits: 2, i: 3 },
+};
+
+// Error correction codewords per block, and the number of blocks, by level then version (index 0 unused).
+const ECC_PER_BLOCK = [
+  [-1, 7, 10, 15, 20, 26, 18, 20, 24, 30, 18, 20, 24, 26, 30, 22, 24, 28, 30, 28, 28, 28, 28, 30, 30, 26, 28, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30],
+  [-1, 10, 16, 26, 18, 24, 16, 18, 22, 22, 26, 30, 22, 22, 24, 24, 28, 28, 26, 26, 26, 26, 28, 28, 28, 28, 28, 28, 28, 28, 28, 28, 28, 28, 28, 28, 28, 28, 28, 28, 28],
+  [-1, 13, 22, 18, 26, 18, 24, 18, 22, 20, 24, 28, 26, 24, 20, 30, 24, 28, 28, 26, 30, 28, 30, 30, 30, 30, 28, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30],
+  [-1, 17, 28, 22, 16, 22, 28, 26, 26, 24, 28, 24, 28, 22, 24, 24, 30, 28, 28, 26, 28, 30, 24, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30],
+];
+const NUM_BLOCKS = [
+  [-1, 1, 1, 1, 1, 1, 2, 2, 2, 2, 4, 4, 4, 4, 4, 6, 6, 6, 6, 7, 8, 8, 9, 9, 10, 12, 12, 12, 13, 14, 15, 16, 17, 18, 19, 19, 20, 21, 22, 24, 25],
+  [-1, 1, 1, 1, 2, 2, 4, 4, 4, 5, 5, 5, 8, 9, 9, 10, 10, 11, 13, 14, 16, 17, 17, 18, 20, 21, 23, 25, 26, 28, 29, 31, 33, 35, 37, 38, 40, 43, 45, 47, 49],
+  [-1, 1, 1, 2, 2, 4, 4, 6, 6, 8, 8, 8, 10, 12, 16, 12, 17, 16, 18, 21, 20, 23, 23, 25, 27, 29, 34, 34, 35, 38, 40, 43, 45, 48, 51, 53, 56, 59, 62, 65, 68],
+  [-1, 1, 1, 2, 4, 4, 4, 5, 6, 8, 8, 11, 11, 16, 16, 18, 16, 19, 21, 25, 25, 25, 34, 30, 32, 35, 37, 40, 42, 45, 48, 51, 54, 57, 60, 63, 66, 70, 74, 77, 81],
+];
+
+const bit = (x, i) => ((x >>> i) & 1) !== 0;
+
+function rawDataModules(ver) {
+  let n = (16 * ver + 128) * ver + 64;
+  if (ver >= 2) {
+    const align = Math.floor(ver / 7) + 2;
+    n -= (25 * align - 10) * align - 55;
+    if (ver >= 7) n -= 36;
+  }
+  return n;
+}
+
+const dataCodewords = (ver, e) => Math.floor(rawDataModules(ver) / 8) - ECC_PER_BLOCK[e.i][ver] * NUM_BLOCKS[e.i][ver];
+
+function gfMul(x, y) {
+  let z = 0;
+  for (let i = 7; i >= 0; i--) {
+    z = (z << 1) ^ ((z >>> 7) * 0x11d);
+    z ^= ((y >>> i) & 1) * x;
+  }
+  return z;
+}
+
+function rsDivisor(degree) {
+  const r = new Array(degree).fill(0);
+  r[degree - 1] = 1;
+  let root = 1;
+  for (let i = 0; i < degree; i++) {
+    for (let j = 0; j < r.length; j++) {
+      r[j] = gfMul(r[j], root);
+      if (j + 1 < r.length) r[j] ^= r[j + 1];
+    }
+    root = gfMul(root, 0x02);
+  }
+  return r;
+}
+
+function rsRemainder(data, divisor) {
+  const r = divisor.map(() => 0);
+  for (const b of data) {
+    const factor = b ^ r.shift();
+    r.push(0);
+    divisor.forEach((coef, i) => { r[i] ^= gfMul(coef, factor); });
+  }
+  return r;
+}
+
+function alignmentPositions(ver) {
+  if (ver === 1) return [];
+  const size = ver * 4 + 17;
+  const n = Math.floor(ver / 7) + 2;
+  const step = Math.floor((ver * 8 + n * 3 + 5) / (n * 4 - 4)) * 2;
+  const out = [6];
+  for (let pos = size - 7; out.length < n; pos -= step) out.splice(1, 0, pos);
+  return out;
+}
+
+const MASKS = [
+  (x, y) => (x + y) % 2 === 0,
+  (x, y) => y % 2 === 0,
+  (x) => x % 3 === 0,
+  (x, y) => (x + y) % 3 === 0,
+  (x, y) => (Math.floor(x / 3) + Math.floor(y / 2)) % 2 === 0,
+  (x, y) => ((x * y) % 2) + ((x * y) % 3) === 0,
+  (x, y) => (((x * y) % 2) + ((x * y) % 3)) % 2 === 0,
+  (x, y) => (((x + y) % 2) + ((x * y) % 3)) % 2 === 0,
+];
+
+/**
+ * Encode `text` (UTF-8, byte mode) as a QR code. Returns `{ version, ecl, mask, size, modules }`,
+ * with `modules[y][x]` true for a dark module. Picks the smallest version that fits; picks the mask
+ * by the standard's penalty unless `mask` (0 to 7) is given. Throws when the text does not fit.
+ */
+export function encodeQr(text, { ecl = "M", mask = null, minVersion = 1 } = {}) {
+  const e = ECL[ecl];
+  if (!e) throw new Error(`QR error correction is L, M, Q or H, not ${ecl}.`);
+  if (mask !== null && !(Number.isInteger(mask) && mask >= 0 && mask <= 7)) throw new Error("A QR mask is 0 to 7.");
+  const bytes = [...Buffer.from(String(text), "utf8")];
+  let ver = Math.max(1, minVersion);
+  for (; ver <= 40; ver++) {
+    const countBits = ver <= 9 ? 8 : 16;
+    if (bytes.length < 2 ** countBits && 4 + countBits + bytes.length * 8 <= dataCodewords(ver, e) * 8) break;
+  }
+  if (ver > 40) throw new Error("That is too long for a QR code.");
+
+  // The data bits: mode, length, bytes, terminator, then pad to the capacity.
+  const bits = [];
+  const put = (val, len) => { for (let i = len - 1; i >= 0; i--) bits.push((val >>> i) & 1); };
+  put(0b0100, 4);
+  put(bytes.length, ver <= 9 ? 8 : 16);
+  for (const b of bytes) put(b, 8);
+  const capacity = dataCodewords(ver, e) * 8;
+  put(0, Math.min(4, capacity - bits.length));
+  put(0, (8 - (bits.length % 8)) % 8);
+  for (let pad = 0xec; bits.length < capacity; pad ^= 0xec ^ 0x11) put(pad, 8);
+  const data = [];
+  for (let i = 0; i < bits.length; i += 8) data.push(bits.slice(i, i + 8).reduce((a, b) => (a << 1) | b, 0));
+
+  // Split into blocks, add error correction to each, interleave.
+  const numBlocks = NUM_BLOCKS[e.i][ver];
+  const eccLen = ECC_PER_BLOCK[e.i][ver];
+  const rawCodewords = Math.floor(rawDataModules(ver) / 8);
+  const numShort = numBlocks - (rawCodewords % numBlocks);
+  const shortLen = Math.floor(rawCodewords / numBlocks);
+  const divisor = rsDivisor(eccLen);
+  const blocks = [];
+  for (let i = 0, k = 0; i < numBlocks; i++) {
+    const dat = data.slice(k, k + shortLen - eccLen + (i < numShort ? 0 : 1));
+    k += dat.length;
+    const ecc = rsRemainder(dat, divisor);
+    if (i < numShort) dat.push(0);
+    blocks.push(dat.concat(ecc));
+  }
+  const codewords = [];
+  for (let i = 0; i < blocks[0].length; i++) {
+    blocks.forEach((b, j) => {
+      if (i !== shortLen - eccLen || j >= numShort) codewords.push(b[i]);
+    });
+  }
+
+  const size = ver * 4 + 17;
+  const modules = Array.from({ length: size }, () => new Array(size).fill(false));
+  const fn = Array.from({ length: size }, () => new Array(size).fill(false));
+  const set = (x, y, dark) => { modules[y][x] = dark; fn[y][x] = true; };
+
+  for (let i = 0; i < size; i++) { set(6, i, i % 2 === 0); set(i, 6, i % 2 === 0); }
+  for (const [cx, cy] of [[3, 3], [size - 4, 3], [3, size - 4]]) {
+    for (let dy = -4; dy <= 4; dy++) for (let dx = -4; dx <= 4; dx++) {
+      const d = Math.max(Math.abs(dx), Math.abs(dy));
+      const x = cx + dx;
+      const y = cy + dy;
+      if (x >= 0 && x < size && y >= 0 && y < size) set(x, y, d !== 2 && d !== 4);
+    }
+  }
+  const al = alignmentPositions(ver);
+  for (let i = 0; i < al.length; i++) for (let j = 0; j < al.length; j++) {
+    if ((i === 0 && j === 0) || (i === 0 && j === al.length - 1) || (i === al.length - 1 && j === 0)) continue;
+    for (let dy = -2; dy <= 2; dy++) for (let dx = -2; dx <= 2; dx++) set(al[i] + dx, al[j] + dy, Math.max(Math.abs(dx), Math.abs(dy)) !== 1);
+  }
+  const drawFormat = (m) => {
+    const d = (e.bits << 3) | m;
+    let rem = d;
+    for (let i = 0; i < 10; i++) rem = (rem << 1) ^ ((rem >>> 9) * 0x537);
+    const b = ((d << 10) | rem) ^ 0x5412;
+    for (let i = 0; i <= 5; i++) set(8, i, bit(b, i));
+    set(8, 7, bit(b, 6));
+    set(8, 8, bit(b, 7));
+    set(7, 8, bit(b, 8));
+    for (let i = 9; i < 15; i++) set(14 - i, 8, bit(b, i));
+    for (let i = 0; i < 8; i++) set(size - 1 - i, 8, bit(b, i));
+    for (let i = 8; i < 15; i++) set(8, size - 15 + i, bit(b, i));
+    set(8, size - 8, true);
+  };
+  drawFormat(0);
+  if (ver >= 7) {
+    let rem = ver;
+    for (let i = 0; i < 12; i++) rem = (rem << 1) ^ ((rem >>> 11) * 0x1f25);
+    const b = (ver << 12) | rem;
+    for (let i = 0; i < 18; i++) {
+      const a = size - 11 + (i % 3);
+      const c = Math.floor(i / 3);
+      set(a, c, bit(b, i));
+      set(c, a, bit(b, i));
+    }
+  }
+
+  // The codewords, in the zigzag.
+  let n = 0;
+  for (let right = size - 1; right >= 1; right -= 2) {
+    if (right === 6) right = 5;
+    for (let v = 0; v < size; v++) for (let j = 0; j < 2; j++) {
+      const x = right - j;
+      const y = ((right + 1) & 2) === 0 ? size - 1 - v : v;
+      if (!fn[y][x] && n < codewords.length * 8) {
+        modules[y][x] = bit(codewords[n >>> 3], 7 - (n & 7));
+        n++;
+      }
+    }
+  }
+
+  const applyMask = (m) => {
+    for (let y = 0; y < size; y++) for (let x = 0; x < size; x++) if (!fn[y][x] && MASKS[m](x, y)) modules[y][x] = !modules[y][x];
+  };
+  let chosen = mask;
+  if (chosen === null) {
+    let best = Infinity;
+    for (let m = 0; m < 8; m++) {
+      applyMask(m);
+      drawFormat(m);
+      const p = penalty(modules);
+      if (p < best) { best = p; chosen = m; }
+      applyMask(m);
+    }
+  }
+  applyMask(chosen);
+  drawFormat(chosen);
+  return { version: ver, ecl, mask: chosen, size, modules };
+}
+
+// The standard's four penalty rules; the lowest total picks the mask.
+function penalty(m) {
+  const size = m.length;
+  let score = 0;
+  const lines = [];
+  for (let y = 0; y < size; y++) lines.push(m[y]);
+  for (let x = 0; x < size; x++) lines.push(m.map((row) => row[x]));
+  const finder = [true, false, true, true, true, false, true];
+  for (const line of lines) {
+    for (let i = 0, run = 1; i < size; i++) {
+      if (i + 1 < size && line[i + 1] === line[i]) { run++; continue; }
+      if (run >= 5) score += 3 + (run - 5);
+      run = 1;
+    }
+    for (let i = 0; i + 7 <= size; i++) {
+      if (!finder.every((v, k) => line[i + k] === v)) continue;
+      const lightBefore = i >= 4 && [1, 2, 3, 4].every((k) => !line[i - k]);
+      const lightAfter = i + 11 <= size && [0, 1, 2, 3].every((k) => !line[i + 7 + k]);
+      if (lightBefore || lightAfter) score += 40;
+    }
+  }
+  for (let y = 0; y + 1 < size; y++) for (let x = 0; x + 1 < size; x++) {
+    const c = m[y][x];
+    if (c === m[y][x + 1] && c === m[y + 1][x] && c === m[y + 1][x + 1]) score += 3;
+  }
+  const dark = m.reduce((a, row) => a + row.filter(Boolean).length, 0);
+  score += Math.floor(Math.abs(dark * 20 - size * size * 10) / (size * size)) * 10;
+  return score;
+}
+
+const CRC_TABLE = Array.from({ length: 256 }, (_, n) => {
+  let c = n;
+  for (let k = 0; k < 8; k++) c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+  return c >>> 0;
+});
+function crc32(buf) {
+  let c = 0xffffffff;
+  for (const b of buf) c = CRC_TABLE[(c ^ b) & 0xff] ^ (c >>> 8);
+  return (c ^ 0xffffffff) >>> 0;
+}
+function chunk(type, data) {
+  const len = Buffer.alloc(4);
+  len.writeUInt32BE(data.length);
+  const td = Buffer.concat([Buffer.from(type, "ascii"), data]);
+  const crc = Buffer.alloc(4);
+  crc.writeUInt32BE(crc32(td));
+  return Buffer.concat([len, td, crc]);
+}
+
+/** The code as a PNG: black on white, `scale` pixels a module, a quiet zone of `border` modules. */
+export function qrPng(qr, { scale = 8, border = 4 } = {}) {
+  const px = (qr.size + border * 2) * scale;
+  const raw = Buffer.alloc((px + 1) * px, 0xff);
+  for (let y = 0; y < px; y++) {
+    raw[y * (px + 1)] = 0; // filter: none
+    const my = Math.floor(y / scale) - border;
+    for (let x = 0; x < px; x++) {
+      const mx = Math.floor(x / scale) - border;
+      if (my >= 0 && my < qr.size && mx >= 0 && mx < qr.size && qr.modules[my][mx]) raw[y * (px + 1) + 1 + x] = 0;
+    }
+  }
+  const ihdr = Buffer.alloc(13);
+  ihdr.writeUInt32BE(px, 0);
+  ihdr.writeUInt32BE(px, 4);
+  ihdr[8] = 8; // bit depth
+  ihdr[9] = 0; // greyscale
+  return Buffer.concat([Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]), chunk("IHDR", ihdr), chunk("IDAT", deflateSync(raw)), chunk("IEND", Buffer.alloc(0))]);
+}
+
+/** The code as text, two rows a line in half blocks, dark modules drawn, with a quiet zone of `border`. */
+export function qrText(qr, { border = 2 } = {}) {
+  const at = (x, y) => x >= 0 && y >= 0 && x < qr.size && y < qr.size && qr.modules[y][x];
+  const lines = [];
+  for (let y = -border; y < qr.size + border; y += 2) {
+    let line = "";
+    for (let x = -border; x < qr.size + border; x++) {
+      const top = at(x, y);
+      const bottom = at(x, y + 1);
+      line += top && bottom ? "█" : top ? "▀" : bottom ? "▄" : " ";
+    }
+    lines.push(line);
+  }
+  return lines.join("\n");
+}

package/lib/record.mjs

@@ -47,6 +47,26 @@ export function headings(text) {
   return text.split("\n").filter((l) => /^#{1,6} /.test(l)).map((l) => l.replace(/^#+ /, "").trim());
 }
 
+// The first line of the file's most recent section: past any frontmatter block, past heading
+// lines (those are already in `headings()`), and past every heading but the last. A day file
+// accumulates one heading per entry through the day, so the last heading is the newest entry --
+// a "recent" preview wants that one, not the file's opening paragraph, which for a fresh day file
+// is create-evda's own scaffold text and was never the owner's. A file with no heading at all uses
+// its first non-blank line, same as before.
+export function firstLine(text) {
+  let body = text;
+  if (body.startsWith("---")) {
+    const end = body.indexOf("\n---", 3);
+    if (end !== -1) body = body.slice(end + 4);
+  }
+  const lines = body.split("\n");
+  let lastHeadingAt = -1;
+  for (let i = 0; i < lines.length; i++) if (/^#{1,6} /.test(lines[i])) lastHeadingAt = i;
+  const after = lastHeadingAt === -1 ? lines : lines.slice(lastHeadingAt + 1);
+  const line = after.find((l) => l.trim() !== "" && !/^#{1,6} /.test(l));
+  return line ? line.trim() : "";
+}
+
 export function moment(evda, { from, to = from } = {}) {
   if (!DATE.test(from ?? "") || !DATE.test(to ?? "")) {
     throw new EvdaError(`moment needs YYYY-MM-DD dates, got ${from}..${to}`);
@@ -78,3 +98,57 @@ export function moment(evda, { from, to = from } = {}) {
   out.entries.sort((a, b) => (a.date === b.date ? a.path.localeCompare(b.path) : a.date.localeCompare(b.date)));
   return out;
 }
+
+// What a reader needs from each section of a file to know what it was about without opening it
+// (HQ-2324): its heading, its context line (the one line the filing agent wrote above the owner's
+// words, `Context, not their words:` or `*Context (Iris, ...): ...*`), and the opening of the
+// owner's words, cut at a word. A day file's headings are mostly times (`## 20:13`), so a heading
+// alone told a chat app nothing about his last days. Text before the first heading is a section
+// with no heading. Frontmatter, fences and the one-line marker a sealed part leaves are skipped.
+export const OPENING_MAX = 280;
+const CONTEXT_MAX = 240;
+const CONTEXT_LINE = /^\*{0,2}_?\s*Context\b[^:]*:/i;
+
+function cutAt(text, max) {
+  if (text.length <= max) return text;
+  const cut = text.slice(0, max);
+  const at = cut.lastIndexOf(" ");
+  return `${at > max / 2 ? cut.slice(0, at) : cut}...`;
+}
+
+export function sectionDigest(text, { openingMax = OPENING_MAX } = {}) {
+  let body = text;
+  if (body.startsWith("---")) {
+    const end = body.indexOf("\n---", 3);
+    if (end !== -1) body = body.slice(end + 4);
+  }
+  const out = [];
+  let cur = { heading: null, lines: [] };
+  let fence = false;
+  const flush = () => {
+    const lines = cur.lines.map((l) => l.trim()).filter((l) => l && !/^\[sealed[:\]]/i.test(l));
+    const ctxAt = lines.findIndex((l) => CONTEXT_LINE.test(l));
+    const context = ctxAt === -1 ? null : cutAt(lines[ctxAt].replace(/^[*_\s]+|[*_\s]+$/g, ""), CONTEXT_MAX);
+    const words = lines.filter((_, i) => i !== ctxAt)
+      .map((l) => l.replace(/^>\s?/, "").replace(/^>\s?/, "").trim())
+      .filter(Boolean)
+      .join(" ")
+      .replace(/\s+/g, " ")
+      .trim();
+    if (cur.heading !== null || context || words) out.push({ heading: cur.heading, context, opening: words ? cutAt(words, openingMax) : null });
+  };
+  for (const line of body.split("\n")) {
+    if (/^\s*(`{3,}|~{3,})/.test(line)) { fence = !fence; continue; }
+    if (fence) continue;
+    const h = /^#{1,6} (.*)$/.exec(line);
+    if (h) { flush(); cur = { heading: h[1].trim(), lines: [] }; continue; }
+    cur.lines.push(line);
+  }
+  flush();
+  return out;
+}
+
+// The date a heading names (`## 2026-10-02, morning: ...`, `## October 4 (added 2026-10-04)`), or null.
+export function headingDate(heading) {
+  return /\b(\d{4}-\d{2}-\d{2})\b/.exec(heading ?? "")?.[1] ?? null;
+}

package/lib/routines.mjs

@@ -13,7 +13,7 @@
 
 import { mkdirSync, writeFileSync, existsSync, realpathSync, rmSync, statSync } from "node:fs";
 import { delimiter, join, resolve, sep } from "node:path";
-import { homedir } from "node:os";
+import { homedir, tmpdir, userInfo } from "node:os";
 import { spawnSync } from "node:child_process";
 import { openEvda, holderOf } from "./manifest.mjs";
 import { serverCommand } from "./connect.mjs";
@@ -165,10 +165,42 @@ function bootout(target, env, launchctl) {
 // loaded job (113 when there is none).
 const isLoaded = (target, launchctl) => launchctl(["print", target]).status === 0;
 
+// Is this record under a temp folder? Such a folder goes away, and a job for it runs daily on
+// nothing (HQ-2006: the Mac app's Rust tests left two loaded in his launchd). Both the path as given
+// and its realpath are checked, since /var and /tmp are symlinks into /private on a Mac.
+const TEMP_ROOTS = ["/tmp", "/private/tmp", "/var/folders", "/private/var/folders"];
+export function underTempDir(dir) {
+  const paths = [resolve(dir)];
+  try { paths.push(realpathSync(dir)); } catch {}
+  const roots = [...TEMP_ROOTS, resolve(tmpdir())];
+  try { roots.push(realpathSync(tmpdir())); } catch {}
+  return paths.some((p) => roots.some((r) => p === r || p.startsWith(r.endsWith(sep) ? r : r + sep)));
+}
+
+// The owner's real home, from the account database rather than $HOME, which a test or a spawned
+// process can point anywhere.
+function accountHome() {
+  try { return userInfo().homedir; } catch { return homedir(); }
+}
+
+const samePath = (a, b) => {
+  const real = (p) => { try { return realpathSync(p); } catch { return resolve(p); } };
+  return resolve(a) === resolve(b) || real(a) === real(b);
+};
+
 // Write the launchd job and load it. `agentsDir`, `load` and `launchctl` exist so tests never touch
 // the real ~/Library/LaunchAgents or launchctl. A job already loaded under this label is unloaded
 // first, so a second install replaces it rather than failing to load a duplicate.
-export function installLaunchd(key, dir, { env = process.env, home = env.HOME ?? homedir(), agentsDir = env.EVDA_LAUNCH_AGENTS ?? process.env.EVDA_LAUNCH_AGENTS ?? join(home, "Library", "LaunchAgents"), load = !noLaunchctl(env), claude = findClaude(env), launchctl = (a) => runLaunchctl(a, env) } = {}) {
+//
+// A record under a temp folder is refused before anything is written when the job would land in the
+// real ~/Library/LaunchAgents or be loaded by the real launchctl, whoever the caller is. `realHome`
+// is the seam that lets a test name a stand-in for the real home.
+export function installLaunchd(key, dir, { env = process.env, home = env.HOME ?? homedir(), realHome = accountHome(), agentsDir = env.EVDA_LAUNCH_AGENTS ?? process.env.EVDA_LAUNCH_AGENTS ?? join(home, "Library", "LaunchAgents"), load = !noLaunchctl(env), claude = findClaude(env), launchctl } = {}) {
+  const realLaunchctl = !launchctl && !env.EVDA_LAUNCHCTL;
+  if (underTempDir(dir) && (samePath(agentsDir, join(realHome, "Library", "LaunchAgents")) || (load && realLaunchctl))) {
+    throw new EvdaError(`REFUSED: ${resolve(dir)} is in a temp folder, so no launchd job is scheduled for it (it would run daily on a folder that goes away). Nothing was written.`, { code: "TEMP_RECORD", exit: 2 });
+  }
+  launchctl ??= (a) => runLaunchctl(a, env);
   if (process.platform !== "darwin" && load && !env.EVDA_LAUNCHCTL) throw new EvdaError("REFUSED: launchd is macOS only. Use the Claude desktop routine instead. Nothing was written.", { exit: 2 });
   const evda = openEvda(dir);
   const plist = launchdPlist(key, dir, { home, claude });
@@ -211,13 +243,31 @@ export function uninstallLaunchd(key, dir, { env = process.env, home = env.HOME
 // What setup does with the routines it was given (HQ-1246). On a Mac each is installed as a launchd
 // job; elsewhere nothing can be scheduled from here, so it prints the Claude desktop steps and says
 // so. Returns the lines to print.
-export function installAtSetup(keys, dir, { env = process.env, platform = process.platform } = {}) {
+//
+// `say` prints a line at once, before anything is installed (HQ-1368): a run with --yes asks nothing,
+// so the line that a launchd job is about to be loaded into this Mac is said before launchctl runs,
+// not only in the summary after it. `launchctl` is the tests' stand-in, handed through to
+// installLaunchd with loading on, so a test can watch the order without the real launchctl.
+export function setupNotice(key, dir) {
+  const r = ROUTINES[key];
+  return `Installing a launchd job on this Mac: ${r.title}, ${r.when.toLowerCase()}, runs ${r.command.join(" ")} on ${resolve(dir)} with your own Claude. Not wanted: create-evda --no-routines, or afterwards evda routine ${key} ${resolve(dir)} --uninstall`;
+}
+
+export function installAtSetup(keys, dir, { env = process.env, platform = process.platform, say = null, launchctl = null } = {}) {
   const lines = [];
   for (const key of keys) {
     const r = ROUTINES[key];
     lines.push("");
     if (platform === "darwin") {
-      const done = installLaunchd(key, dir, { env });
+      let done;
+      try {
+        if (say && !falsified(env, "silent-install")) say(setupNotice(key, dir));
+        done = installLaunchd(key, dir, launchctl ? { env, launchctl, load: true } : { env });
+      } catch (e) {
+        if (e.code !== "TEMP_RECORD") throw e;
+        lines.push(e.message);
+        continue;
+      }
       const lead = key === "morning" ? "Organizing is on" : `${r.title} is on`;
       lines.push(`${lead}: ${r.when.toLowerCase()} your own Claude ${key === "morning" ? "files your notes into their day and writes what belongs where" : "reads your week back to you"}, in reports/. Turn it off: evda routine ${key} ${resolve(dir)} --uninstall`);
       lines.push(`  launchd job ${done.path}: ${done.loaded}. It runs while this computer is on; asleep at that hour, it runs when it wakes.`);

package/lib/sigstore-trust.json

@@ -0,0 +1,20 @@
+{
+  "source": "https://raw.githubusercontent.com/sigstore/root-signing/main/targets/trusted_root.json (Sigstore public-good instance), fetched 2026-10-04",
+  "tlogs": [
+    {
+      "baseUrl": "https://rekor.sigstore.dev",
+      "logId": "wNI9atQGlz+VWfO6LRygH4QUfY/8W4RFwiT5i5WRgB0=",
+      "publicKey": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE2G2Y+2tabdTV5BcGiBIx0a9fAFwrkBbmLSGtks4L3qX6yYY0zufBnhC8Ur/iy55GhWP/9A/bY2LhC30M9+RYtw==",
+      "keyDetails": "PKIX_ECDSA_P256_SHA_256",
+      "validFrom": "2021-01-12T11:53:27Z"
+    }
+  ],
+  "fulcio": {
+    "baseUrl": "https://fulcio.sigstore.dev",
+    "validFrom": "2022-04-13T20:06:15Z",
+    "chain": [
+      "MIICGjCCAaGgAwIBAgIUALnViVfnU0brJasmRkHrn/UnfaQwCgYIKoZIzj0EAwMwKjEVMBMGA1UEChMMc2lnc3RvcmUuZGV2MREwDwYDVQQDEwhzaWdzdG9yZTAeFw0yMjA0MTMyMDA2MTVaFw0zMTEwMDUxMzU2NThaMDcxFTATBgNVBAoTDHNpZ3N0b3JlLmRldjEeMBwGA1UEAxMVc2lnc3RvcmUtaW50ZXJtZWRpYXRlMHYwEAYHKoZIzj0CAQYFK4EEACIDYgAE8RVS/ysH+NOvuDZyPIZtilgUF9NlarYpAd9HP1vBBH1U5CV77LSS7s0ZiH4nE7Hv7ptS6LvvR/STk798LVgMzLlJ4HeIfF3tHSaexLcYpSASr1kS0N/RgBJz/9jWCiXno3sweTAOBgNVHQ8BAf8EBAMCAQYwEwYDVR0lBAwwCgYIKwYBBQUHAwMwEgYDVR0TAQH/BAgwBgEB/wIBADAdBgNVHQ4EFgQU39Ppz1YkEZb5qNjpKFWixi4YZD8wHwYDVR0jBBgwFoAUWMAeX5FFpWapesyQoZMi0CrFxfowCgYIKoZIzj0EAwMDZwAwZAIwPCsQK4DYiZYDPIaDi5HFKnfxXx6ASSVmERfsynYBiX2X6SJRnZU84/9DZdnFvvxmAjBOt6QpBlc4J/0DxvkTCqpclvziL6BCCPnjdlIB3Pu3BxsPmygUY7Ii2zbdCdliiow=",
+      "MIIB9zCCAXygAwIBAgIUALZNAPFdxHPwjeDloDwyYChAO/4wCgYIKoZIzj0EAwMwKjEVMBMGA1UEChMMc2lnc3RvcmUuZGV2MREwDwYDVQQDEwhzaWdzdG9yZTAeFw0yMTEwMDcxMzU2NTlaFw0zMTEwMDUxMzU2NThaMCoxFTATBgNVBAoTDHNpZ3N0b3JlLmRldjERMA8GA1UEAxMIc2lnc3RvcmUwdjAQBgcqhkjOPQIBBgUrgQQAIgNiAAT7XeFT4rb3PQGwS4IajtLk3/OlnpgangaBclYpsYBr5i+4ynB07ceb3LP0OIOZdxexX69c5iVuyJRQ+Hz05yi+UF3uBWAlHpiS5sh0+H2GHE7SXrk1EC5m1Tr19L9gg92jYzBhMA4GA1UdDwEB/wQEAwIBBjAPBgNVHRMBAf8EBTADAQH/MB0GA1UdDgQWBBRYwB5fkUWlZql6zJChkyLQKsXF+jAfBgNVHSMEGDAWgBRYwB5fkUWlZql6zJChkyLQKsXF+jAKBggqhkjOPQQDAwNpADBmAjEAj1nHeXZp+13NWBNa+EDsDP8G1WWg1tCMWP/WHPqpaVo0jhsweNFZgSs0eE7wYI4qAjEA2WB9ot98sIkoF3vZYdd3/VtWB5b9TNMea7Ix/stJ5TfcLLeABLE4BNJOsQ4vnBHJ"
+    ]
+  }
+}

package/lib/skills.mjs

@@ -226,7 +226,7 @@ export function writeSkill(evda, args = {}, { now = new Date(), env = process.en
 // Tools that are how a session starts or keeps itself, never a step of a process the owner asked
 // for. And the plain read-and-file loop: search, read, write is the record's ordinary use, not a
 // process worth a skill, so a run made only of those is never pointed at.
-const META = new Set(["evda_operating_layer", "evda_skills", "evda_write_skill", "evda_check_update"]);
+const META = new Set(["evda_operating_layer", "evda_skills", "evda_write_skill", "evda_check_update", "evda_acknowledge", "evda_acknowledgements"]);
 const ORDINARY = new Set(["evda_recent", "evda_search", "evda_read", "evda_write", "evda_note", "evda_circles", "evda_presets"]);
 export const MIN_STEPS = 3;
 export const MAX_STEPS = 8;

package/lib/sync-lock.mjs

@@ -0,0 +1,143 @@
+// One sync at a time per record, across processes (HQ-1925).
+//
+// The Mac app syncs on its own, a launchd job or a person at a terminal can run `evda sync`, and the
+// MCP's evda_sync_devices syncs too. Every one of them reaches the relay through lib/pairing.mjs, so
+// the lock is taken there and nowhere else.
+//
+// The lock is `<record>/.evda/sync.lock`: the record's derived state, which sync-rules never sends
+// to a device, never under record/. It holds the holder's pid and that process's start time. A lock
+// is stale only when its holder is gone: the pid runs no process, or the process running under that
+// pid started at a different time (the pid was reused). Its age never counts, because a sync over a
+// slow network is still a live sync.
+//
+
+import { execFileSync } from "node:child_process";
+import { mkdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import { randomBytes } from "node:crypto";
+import { join } from "node:path";
+import { EvdaError } from "./errors.mjs";
+
+export const SYNC_LOCK = join(".evda", "sync.lock");
+export const SYNC_BUSY = "A sync of this EVÐA is already running. Try again in a moment.";
+export const SYNC_WAIT_MS = 20_000;
+
+/** When the process with this pid started, as the system reports it, or null when no process has that pid. */
+export function processStart(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return null;
+  try {
+    process.kill(pid, 0);
+  } catch (error) {
+    if (error?.code !== "EPERM") return null; // EPERM: it runs, as someone else
+  }
+  if (process.platform === "win32") return ""; // no start time to read; the pid alone decides
+  try {
+    const out = execFileSync("ps", ["-o", "lstart=", "-p", String(pid)], {
+      env: { PATH: "/bin:/usr/bin", LC_ALL: "C" },
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+    }).trim();
+    return out || null;
+  } catch {
+    return null; // ps exits 1 when the pid is gone between the two checks
+  }
+}
+
+/** Is the holder named in a lock file still the process that wrote it? */
+export function holderAlive(holder, { startOf = processStart } = {}) {
+  if (!holder || !Number.isInteger(holder.pid)) return false;
+  const now = startOf(holder.pid);
+  if (now === null) return false;
+  if (now === "" || !holder.start) return true; // no start time on this system: the pid decides
+  return now === holder.start;
+}
+
+function readHolder(raw) {
+  try {
+    const h = JSON.parse(raw);
+    return h && typeof h === "object" ? h : null;
+  } catch {
+    return null;
+  }
+}
+
+function readRaw(path) {
+  try {
+    return readFileSync(path, "utf8");
+  } catch (error) {
+    if (error?.code === "ENOENT") return null;
+    throw error;
+  }
+}
+
+export const SYNC_GUARD = join(".evda", "sync.guard");
+
+// Judging a lock stale and taking it must be one step, or two processes that both read the same
+// stale lock can each take it. That step runs inside an exclusive SQLite transaction on
+// .evda/sync.guard: SQLite holds it with an OS file lock, which the OS drops when a process dies, so
+// the guard itself can never be left stale. It is held only for the few file operations below,
+// never for a sync. node:sqlite is loaded here and not at the top, because pairing (the only caller)
+// already needs it and every other evda command must still run on a Node without it.
+async function guarded(dir, fn) {
+  const { DatabaseSync } = await import("node:sqlite");
+  const db = new DatabaseSync(join(dir, SYNC_GUARD));
+  try {
+    db.exec("PRAGMA busy_timeout = 10000");
+    db.exec("BEGIN EXCLUSIVE");
+    try {
+      return fn();
+    } finally {
+      db.exec("COMMIT");
+    }
+  } finally {
+    db.close();
+  }
+}
+
+const pause = (ms) => new Promise((ok) => setTimeout(ok, ms));
+
+/**
+ * Take the record's sync lock, waiting up to `waitMs` for a running sync to finish. Returns a
+ * release function. When the wait runs out, throws SYNC_BUSY (exit 2: nothing was written).
+ * `beforeReclaim` is for tests: it runs, synchronously, between judging a lock stale and taking it.
+ */
+export async function acquireSyncLock(dir, { waitMs, pollMs = 100, startOf = processStart, env = process.env, beforeReclaim } = {}) {
+  const fromEnv = env.EVDA_SYNC_WAIT_MS ? Number(env.EVDA_SYNC_WAIT_MS) : NaN;
+  const wait = waitMs ?? (Number.isFinite(fromEnv) && fromEnv >= 0 ? fromEnv : SYNC_WAIT_MS);
+  const path = join(dir, SYNC_LOCK);
+  mkdirSync(join(dir, ".evda"), { recursive: true });
+  const mine = JSON.stringify({ pid: process.pid, start: startOf(process.pid) || null, n: randomBytes(4).toString("hex") });
+  const deadline = Date.now() + wait;
+  for (;;) {
+    const took = await guarded(dir, () => {
+      const raw = readRaw(path);
+      if (raw !== null) {
+        if (holderAlive(readHolder(raw), { startOf })) return false;
+        if (beforeReclaim) beforeReclaim();
+        unlinkSync(path);
+      }
+      writeFileSync(path, mine, { flag: "wx" });
+      return true;
+    });
+    if (took) break;
+    if (Date.now() >= deadline) throw new EvdaError(SYNC_BUSY, { code: "SYNC_BUSY", exit: 2 });
+    await pause(pollMs);
+  }
+  let released = false;
+  return async function release() {
+    if (released) return;
+    released = true;
+    await guarded(dir, () => {
+      if (readRaw(path) === mine) unlinkSync(path);
+    });
+  };
+}
+
+/** Run `fn` holding the record's sync lock; the lock is released however `fn` ends. */
+export async function withSyncLock(dir, fn, opts = {}) {
+  const release = await acquireSyncLock(dir, opts);
+  try {
+    return await fn();
+  } finally {
+    await release();
+  }
+}