create-evda 0.1.5 → 0.1.7

package/lib/tools.mjs

@@ -11,22 +11,33 @@
 //      reference (lib/references.mjs secretShape) and a hit refuses the whole write.
 //   3. Every write says where it landed, as a path relative to the record.
 //
+// Who may read (HQ-1374). Every tool that returns the record's words asks lib/readers.mjs first, for
+// each file: a just-noted entry is returned to no AI, and a file whose circle (or evda.json) names a
+// reader that is not the caller is held back. What was held back is said in one plain sentence at
+// the end of the answer, so the agent declines out loud instead of going quiet. The caller is who
+// the MCP client said it was on initialize; $EVDA_READER overrides it.
+//
+// Sealed (HQ-1220) is stronger and holds for every caller: a sealed file is in no answer, and no
+// answer names it or says whether it matched; a sealed section is cut out of every file shown
+// (lib/readers.mjs aiView). Every tool below that returns words goes through both.
+//
 // A circle is never created here. `propose_circle` writes a proposal file for the owner to read;
 // making the circle, and granting anyone anything, stays the owner's explicit yes through
 // `evda grant` or their own hands.
 
 import { appendFileSync, existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
-import { dirname, join, relative } from "node:path";
+import { dirname, join, relative, resolve, sep } from "node:path";
 import { resolveRole, rolesForLayer, agentsFile } from "./roles.mjs";
 import { mdFiles, fileDate } from "./record.mjs";
-import { readCircles } from "./circles.mjs";
+import { readCircles, isSealed } from "./circles.mjs";
 import { secretShape } from "./references.mjs";
 import { doctor } from "./doctor.mjs";
+import { readContext, mayRead, heldBack, callerFrom, aiView, note as writeNote, releaseNote, SEALED_WHY } from "./readers.mjs";
 import { EvdaError } from "./errors.mjs";
+import { dayRole, appendToDay, CONTEXT_LABEL, localDate, localTime } from "./day-file.mjs";
+import { writeMessage, unseenReplies } from "./messages.mjs";
 
-const pad = (n) => String(n).padStart(2, "0");
-export const localDate = (d) => `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}`;
-export const localTime = (d) => `${pad(d.getHours())}:${pad(d.getMinutes())}`;
+export { localDate, localTime, CONTEXT_LABEL };
 
 const DATE = /^\d{4}-\d{2}-\d{2}$/;
 const MAX_WORDS = 200_000;
@@ -63,10 +74,12 @@ function rel(evda, abs) {
   return relative(evda.dir, abs).split("\\").join("/");
 }
 
+// The day's record: `record/daily`, else the `journal` role (HQ-1371). keep-hook.mjs dayRole is the
+// one rule, so the Stop hook watches the same file this appends to.
 function dailyDir(evda) {
-  const r = resolveRole(evda, "record/daily");
-  if (!r.mapped) throw refuse('this record maps no "record/daily" role, so there is no daily file to append to.', "NO_ROLE");
-  return r;
+  const role = dayRole(evda.manifest.mapping);
+  if (!role) throw refuse('this record maps no "record/daily" or "journal" role, so there is no daily file to append to.', "NO_ROLE");
+  return resolveRole(evda, role);
 }
 
 // Where imports go: `imports/` beside the daily role, so `record/daily` gives `record/imports`, and
@@ -85,12 +98,13 @@ export function operatingLayer(evda, args = {}) {
   onlyKeys("evda_operating_layer", args, []);
   const a = agentsFile(evda);
   if (!a) throw new EvdaError('this record maps no "agents" role, so it has no operating layer.', { code: "NO_ROLE" });
-  return { path: a.rel, text: readFileSync(a.abs, "utf8") };
+  if (isSealed(a.abs)) throw new EvdaError(`REFUSED: ${a.rel} ${SEALED_WHY.replace(/^It /, "is ")}`, { code: "SEALED", exit: 2 });
+  return { path: a.rel, text: aiView(readFileSync(a.abs, "utf8")).text };
 }
 
 // 2. The last `days` days of the record, newest first, whole files, capped in size. A file is in the
 // window by its date (filename, then a date or created key), the same rule `evda moment` uses.
-export function recent(evda, args = {}, { now = new Date() } = {}) {
+export function recent(evda, args = {}, { now = new Date(), caller = callerFrom() } = {}) {
   onlyKeys("evda_recent", args, ["days"]);
   const days = args.days === undefined ? 3 : Number(args.days);
   if (!Number.isInteger(days) || days < 1 || days > 90) throw new EvdaError("evda_recent days must be a whole number from 1 to 90.", { code: "BAD_ARGUMENT", exit: 2 });
@@ -99,11 +113,18 @@ export function recent(evda, args = {}, { now = new Date() } = {}) {
   const from = localDate(start);
   const to = localDate(now);
   const files = [];
+  const ctx = readContext(evda);
+  const refused = [];
+  let sealed = false;
   for (const abs of recordFiles(evda)) {
-    const body = readFileSync(abs, "utf8");
-    const date = fileDate(abs, body);
+    const raw = readFileSync(abs, "utf8");
+    const date = fileDate(abs, raw);
     if (!date || date < from || date > to) continue;
-    files.push({ date, path: rel(evda, abs), text: body });
+    const may = mayRead(ctx, abs, caller);
+    if (!may.ok) { refused.push(may); continue; }
+    const shown = aiView(raw);
+    if (shown.sections) sealed = true;
+    files.push({ date, path: rel(evda, abs), text: shown.text });
   }
   files.sort((a, b) => (a.date === b.date ? a.path.localeCompare(b.path) : b.date.localeCompare(a.date)));
   let used = 0;
@@ -114,7 +135,7 @@ export function recent(evda, args = {}, { now = new Date() } = {}) {
     used += f.text.length;
     out.push(f);
   }
-  return { from, to, files: out, omitted: truncated };
+  return { from, to, files: out, omitted: truncated, refused: refused.filter((r) => r.kind !== "sealed"), heldBack: heldBack(refused, { sealed }) };
 }
 
 // Every markdown file the record holds: each record-layer role, and the imports folder. Not the
@@ -134,20 +155,37 @@ function recordFiles(evda) {
   return out;
 }
 
-// 3. Append the owner's words, verbatim, to today's daily file, under the local time. Creates the
-// file with a date heading when it is the first write of the day. Returns the path.
-export function write(evda, args = {}, { now = new Date() } = {}) {
-  onlyKeys("evda_write", args, ["words"], "It appends to today's daily file and nothing else: it takes no path, and it never replaces or edits what is already written.");
+// 3. Append the owner's words, verbatim, to today's daily file. Creates the file with a date heading
+// when it is the first write of the day. Returns the path.
+// `context` (HQ-1377) is one line on what the conversation was about, in the agent's words, written
+// above theirs and labeled as not theirs, so a later reader never mistakes it for something they said.
+// `session` (HQ-1385) is the conversation: its first write opens `## HH:MM` with the context line,
+// and later writes append under it (lib/day-file.mjs, the one append path).
+export const CONTEXT_MAX = 240;
+export function write(evda, args = {}, { now = new Date(), session = null } = {}) {
+  onlyKeys("evda_write", args, ["words", "context"], "It appends to today's daily file and nothing else: it takes no path, and it never replaces or edits what is already written.");
   const words = text(args.words, "words", "evda_write");
   refuseSecrets(words, "evda_write");
+  let context = null;
+  if (args.context !== undefined) {
+    if (typeof args.context !== "string" || args.context.trim() === "") throw refuse(`evda_write "context" is one line on what the conversation was about; leave it out rather than send it empty.`, "EMPTY");
+    if (/\n/.test(args.context.trim())) throw refuse(`evda_write "context" is one line. Their words go in "words"; the context is a single line on what the conversation was about.`, "CONTEXT_LINES");
+    if (args.context.trim().length > CONTEXT_MAX) throw refuse(`evda_write "context" is ${args.context.trim().length} characters; one line of context is at most ${CONTEXT_MAX}.`, "TOO_LONG");
+    refuseSecrets(args.context, "evda_write");
+    context = args.context.trim();
+  }
   const r = dailyDir(evda);
   mkdirSync(r.abs, { recursive: true });
-  const date = localDate(now);
-  const abs = join(r.abs, `${date}.md`);
-  const head = existsSync(abs) ? "" : `# ${date}\n`;
-  const lead = existsSync(abs) && !readFileSync(abs, "utf8").endsWith("\n") ? "\n" : "";
-  appendFileSync(abs, `${lead}${head}\n## ${localTime(now)}\n\n${words.replace(/\n+$/, "")}\n`);
-  return { path: rel(evda, abs), bytes: Buffer.byteLength(words) };
+  const abs = join(r.abs, `${localDate(now)}.md`);
+  const w = appendToDay(abs, { now, words, context, session });
+  return { path: rel(evda, abs), bytes: Buffer.byteLength(words), section: w.opened ? "opened" : "continued" };
+}
+
+// The day file for a date, as { abs, rel }, for writers that are not evda_write (the chat-export
+// backstop in `evda gather`). Throws when the record maps no day role.
+export function dayFile(evda, date) {
+  const r = dailyDir(evda);
+  return { abs: join(r.abs, `${date}.md`), rel: rel(evda, join(r.abs, `${date}.md`)), dir: r.abs };
 }
 
 // 4. File what another AI said about the owner, verbatim, under imports/, labeled with its source
@@ -184,7 +222,7 @@ export function importText(evda, args = {}, { now = new Date() } = {}) {
 
 // 5. Plain text search inside the record, on this machine. Case-insensitive substring over every
 // record file, the imports, and the ledger. Returns each matching line with its path and number.
-export function search(evda, args = {}) {
+export function search(evda, args = {}, { caller = callerFrom() } = {}) {
   onlyKeys("evda_search", args, ["query", "limit"]);
   if (typeof args.query !== "string" || args.query.trim() === "") throw new EvdaError('evda_search needs "query".', { code: "BAD_ARGUMENT", exit: 2 });
   const limit = args.limit === undefined ? 50 : Number(args.limit);
@@ -195,14 +233,82 @@ export function search(evda, args = {}) {
   if (ledger.mapped && ledger.fileExists) files.push(ledger.file);
   const matches = [];
   let more = 0;
+  const ctx = readContext(evda);
+  const refused = [];
+  // Whether any searched file is sealed or holds a sealed section, decided without the query, so
+  // the answer to a search whose only hit is sealed is the answer to one that hit nothing.
+  let sealed = false;
   for (const abs of files) {
-    readFileSync(abs, "utf8").split("\n").forEach((line, i) => {
+    const raw = readFileSync(abs, "utf8");
+    const may = mayRead(ctx, abs, caller);
+    if (!may.ok && may.kind === "sealed") { sealed = true; continue; }
+    if (!may.ok) {
+      // Only a held-back file that would have matched is named, and never the line it matched on.
+      // Matched on what the AI could be shown, so a hit inside a sealed section names nothing.
+      if (aiView(raw).text.toLowerCase().includes(needle)) refused.push(may);
+      continue;
+    }
+    const shown = aiView(raw);
+    if (shown.sections) sealed = true;
+    const body = shown.text;
+    body.split("\n").forEach((line, i) => {
       if (!line.toLowerCase().includes(needle)) return;
       if (matches.length >= limit) { more += 1; return; }
       matches.push({ path: rel(evda, abs), line: i + 1, text: line.length > 400 ? `${line.slice(0, 400)}...` : line });
     });
   }
-  return { query: args.query, searched: files.length, matches, more };
+  return { query: args.query, searched: files.length, matches, more, refused, heldBack: heldBack(refused, { sealed }) };
+}
+
+// 5a. One file of the record, whole, when the caller may read it; a refusal that says why when not.
+export function readFile(evda, args = {}, { caller = callerFrom() } = {}) {
+  onlyKeys("evda_read", args, ["path"]);
+  if (typeof args.path !== "string" || args.path.trim() === "") throw new EvdaError('evda_read needs "path", a file in the record.', { code: "BAD_ARGUMENT", exit: 2 });
+  const abs = resolve(evda.dir, args.path.trim());
+  if (!abs.startsWith(evda.dir + sep)) throw new EvdaError(`REFUSED: ${args.path} is outside the record.`, { code: "OUTSIDE", exit: 2 });
+  if (!existsSync(abs) || !statSync(abs).isFile()) throw new EvdaError(`Nothing is at ${args.path} in the record.`, { code: "MISSING", exit: 2 });
+  const may = mayRead(readContext(evda), abs, caller);
+  if (!may.ok) throw new EvdaError(`REFUSED: ${may.why}`, { code: may.kind === "sealed" ? "SEALED" : may.kind === "noted" ? "NOTED" : "NOT_THIS_READER", exit: 2 });
+  const text = aiView(readFileSync(abs, "utf8")).text;
+  if (text.length > MAX_READ) return { path: rel(evda, abs), text: text.slice(0, MAX_READ), truncated: true };
+  return { path: rel(evda, abs), text, truncated: false };
+}
+
+// 5b. "Just note this": the owner's words, verbatim, as a noted capture no AI reads. Refuses
+// anything secret-shaped, like every other write.
+export function noteTool(evda, args = {}, { now = new Date() } = {}) {
+  onlyKeys("evda_note", args, ["words"], "It writes one new noted capture and nothing else.");
+  const words = text(args.words, "words", "evda_note");
+  refuseSecrets(words, "evda_note");
+  return writeNote(evda, words, { now });
+}
+
+// 5c. "You can read that now": clear the flag on one noted entry. Only on the owner's yes in this
+// conversation, and only the flag: the words are not changed. The one tool that edits a file, and
+// it edits one frontmatter line.
+export function releaseTool(evda, args = {}, { now = new Date() } = {}) {
+  onlyKeys("evda_release_note", args, ["path", "confirmed"]);
+  // Sealed is not noted: no tool releases it, whatever was said. Unsealing is the owner's own edit.
+  if (typeof args.path === "string" && args.path.trim() !== "") {
+    const abs = resolve(evda.dir, args.path.trim());
+    if (existsSync(abs) && isSealed(abs)) throw new EvdaError(`REFUSED: ${args.path} is sealed: only its owner opens it, on their own devices, and no tool releases it. Unsealing is the owner editing the file themselves. Nothing was changed.`, { code: "SEALED", exit: 2 });
+  }
+  if (args.confirmed !== true) throw new EvdaError("REFUSED: evda_release_note needs confirmed: true, which means the owner said in this conversation that this entry can be read now. Ask them which one, and wait. Nothing was changed.", { code: "UNCONFIRMED", exit: 2 });
+  return releaseNote(evda, args.path, { now });
+}
+
+// 5d. Tell the owner something (HQ-1246): one new message file under the messages role, which the
+// phone app shows as a card. Never edits one; refuses anything secret-shaped, like every write.
+export function message(evda, args = {}, { now = new Date() } = {}) {
+  onlyKeys("evda_message", args, ["title", "body", "from"], "It writes one new message for the owner and nothing else: it takes no path, and it never edits a message once written.");
+  return writeMessage(evda, args, { now, refuseSecrets });
+}
+
+// 5e. The owner's replies to messages, the ones not seen yet, marked seen unless peek is true.
+export function replies(evda, args = {}, { caller = callerFrom() } = {}) {
+  onlyKeys("evda_replies", args, ["peek"]);
+  if (args.peek !== undefined && typeof args.peek !== "boolean") throw new EvdaError("evda_replies peek is true or false.", { code: "BAD_ARGUMENT", exit: 2 });
+  return unseenReplies(evda, { peek: args.peek === true }, { caller });
 }
 
 // 6. Circles and their policies, as the record declares them. Read only.

package/lib/update-check.mjs

@@ -0,0 +1,146 @@
+// Update-check hygiene (HQ-1242), from the three gstack rules the plan doc names for this
+// package (01_Projects/Evda/Evda/2026-09-15 - What EVDA Takes From gstack.md, section
+// "5. Update-check hygiene"):
+//
+//   1. A crash must not read as up to date. Any network or parse failure returns
+//      status: "CHECK_FAILED" with the reason attached, never a silent "you're current."
+//   2. The check is throttled and snoozable: at most once per THROTTLE_MS (one hour, per the
+//      plan doc's "throttled to once an hour," not gstack's escalating 24h/48h/7d scheme).
+//   3. Nothing destructive runs from here. This module only reads the registry and this
+//      record's own state file; it never writes AGENTS.md, never runs a migration.
+//
+// `.evda/package-version` (not `.evda/version`, which is the unrelated SCHEMA_VERSION marker
+// lib/manifest.mjs owns) records which npm version last replaced the AGENTS.md fence via
+// `evda upgrade`. `.evda/update-check.json` records when this module last asked the registry,
+// so re-running `evda check-update` inside the same hour is a local read, not a network call.
+
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from "node:fs";
+import { join, dirname } from "node:path";
+
+export const THROTTLE_MS = 60 * 60 * 1000; // one hour, per the plan doc
+const REGISTRY_URL = "https://registry.npmjs.org/create-evda/latest";
+const FETCH_TIMEOUT_MS = 5000;
+
+function stateFile(dir) {
+  return join(dir, ".evda", "update-check.json");
+}
+
+function packageVersionFile(dir) {
+  return join(dir, ".evda", "package-version");
+}
+
+function readJsonSafe(path) {
+  try {
+    return JSON.parse(readFileSync(path, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+// What this record's own AGENTS.md fence was last generated from. Absent means `evda upgrade`
+// has never stamped it (an install predating this feature, or a record adopted by hand); that
+// is reported as its own status rather than guessed at.
+export function installedVersion(dir) {
+  try {
+    return readFileSync(packageVersionFile(dir), "utf8").trim();
+  } catch {
+    return null;
+  }
+}
+
+export function stampInstalledVersion(dir, version) {
+  const f = packageVersionFile(dir);
+  mkdirSync(dirname(f), { recursive: true });
+  writeFileSync(f, version + "\n");
+}
+
+// Fetches the registry's `latest` dist-tag. Never throws: every failure mode (network, timeout,
+// a non-200, a body with no `version` field) becomes a returned CHECK_FAILED result, because a
+// thrown error from inside a session preamble is worse than a stale-looking check.
+async function fetchLatest() {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
+  try {
+    const res = await fetch(REGISTRY_URL, { signal: controller.signal });
+    if (!res.ok) {
+      return { ok: false, reason: `registry returned HTTP ${res.status}` };
+    }
+    const body = await res.json();
+    if (typeof body?.version !== "string" || !body.version) {
+      return { ok: false, reason: "registry response had no version field" };
+    }
+    return { ok: true, version: body.version };
+  } catch (err) {
+    return { ok: false, reason: err?.name === "AbortError" ? `timed out after ${FETCH_TIMEOUT_MS}ms` : String(err?.message ?? err) };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+function higherVersion(a, b) {
+  const pa = a.split(".").map(Number);
+  const pb = b.split(".").map(Number);
+  for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+    const da = pa[i] ?? 0, db = pb[i] ?? 0;
+    if (da !== db) return da > db ? a : b;
+  }
+  return a;
+}
+
+// The one entry point. `now` is injected so a caller (or a test) can control throttling without
+// waiting an hour; callers outside a test pass Date.now().
+//
+// Returns one of:
+//   { status: "SKIPPED_THROTTLED", checkedAt: <ms of the last real check> }
+//   { status: "CHECK_FAILED", reason: "..." }
+//   { status: "UP_TO_DATE", installed, latest }
+//   { status: "UPDATE_AVAILABLE", installed, latest }
+//   { status: "UNSTAMPED", latest }   -- this record predates package-version stamping
+export async function checkForUpdate(dir, { now = Date.now(), force = false } = {}) {
+  const sf = stateFile(dir);
+  const state = readJsonSafe(sf);
+
+  if (!force && state?.lastCheckedAt && now - state.lastCheckedAt < THROTTLE_MS) {
+    return { status: "SKIPPED_THROTTLED", checkedAt: state.lastCheckedAt };
+  }
+
+  const fetched = await fetchLatest();
+
+  // Record the attempt either way: a failure that never updates lastCheckedAt would retry every
+  // single session until the registry recovers, defeating the throttle's whole purpose. The
+  // failure itself is still returned to the caller, never swallowed into a false pass.
+  mkdirSync(dirname(sf), { recursive: true });
+  writeFileSync(sf, JSON.stringify({ lastCheckedAt: now, lastResult: fetched.ok ? fetched.version : `CHECK_FAILED: ${fetched.reason}` }, null, 2) + "\n");
+
+  if (!fetched.ok) {
+    return { status: "CHECK_FAILED", reason: fetched.reason };
+  }
+
+  const installed = installedVersion(dir);
+  if (!installed) {
+    return { status: "UNSTAMPED", latest: fetched.version };
+  }
+
+  const newer = higherVersion(installed, fetched.version) === fetched.version && installed !== fetched.version;
+  return newer
+    ? { status: "UPDATE_AVAILABLE", installed, latest: fetched.version }
+    : { status: "UP_TO_DATE", installed, latest: fetched.version };
+}
+
+// One line, for the preamble and for `evda check-update`'s own stdout. Never throws.
+export function summarize(result) {
+  switch (result.status) {
+    case "SKIPPED_THROTTLED":
+      return `update check: skipped, checked within the last hour (${new Date(result.checkedAt).toISOString()})`;
+    case "CHECK_FAILED":
+      return `update check: CHECK_FAILED, update status UNKNOWN (${result.reason})`;
+    case "UNSTAMPED":
+      return `update check: this record predates version stamping; latest is ${result.latest}. Run "evda upgrade" once to start tracking it.`;
+    case "UP_TO_DATE":
+      return `update check: up to date (${result.installed})`;
+    case "UPDATE_AVAILABLE":
+      return `update check: ${result.installed} -> ${result.latest} available. Run "npx -y -p create-evda@latest evda update" to take it.`;
+    default:
+      return `update check: CHECK_FAILED, update status UNKNOWN (unrecognized result shape)`;
+  }
+}

package/lib/work.mjs

@@ -0,0 +1,180 @@
+// The `work` role, read (Spec 07 section 2, "work is live data", HQ-1371).
+//
+// A record's work is its efforts, each with a status and a date. The role names where they are:
+//
+//   "work": "harlequin:"            THE HARLEQUIN, every board project whose `dev_projects.vault_path`
+//                                   lies in this record (and not in one of its sub-records)
+//   "work": "harlequin:<project>"   THE HARLEQUIN, that one project
+//   "work": { "source": "harlequin", "project": "<id>" }   the same, as an object
+//   "work": "<folder>"              a folder of effort files, one per effort, whose frontmatter
+//                                   carries `status` (required) and `planned_for` (YYYY-MM-DD, optional)
+//
+// One view reads either and prints `CHECKED <n> efforts`. Status is a field, never a move: a
+// finished effort is a value of `status`, not a file somewhere else.
+//
+// The board is read, never written: two GETs against Supabase's REST interface with the service
+// key from the environment (SUPABASE_URL, SUPABASE_SERVICE_ROLE_KEY) or an env file the caller
+// names. Nothing about the credentials is printed or kept. Without them, or offline, the view says
+// SKIPPED and why; it never prints a pass it did not earn.
+//
+// `vault_path` is relative to the board owner's outermost record, so a sub-record's projects are
+// found by its offset from that root: the Iris record's projects are those whose vault_path lies
+// under 01_Projects/Evda/Iris... and in none of Iris's own sub-records.
+//
+// EVDA_WORK_FALSIFY=<mode,...> breaks one guarantee on purpose, for the tests:
+//   all-projects     every board project is this record's, whatever its vault_path says
+//   drop-efforts     the source is read and its efforts are thrown away
+//   skip-as-pass     no credentials is reported as CHECKED 0 and a pass
+//   no-status        a folder effort with no status is counted as one
+
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join, relative, sep } from "node:path";
+import { fourRoles, workSource } from "./roles.mjs";
+import { findRoot } from "./manifest.mjs";
+import { subRecords } from "./records.mjs";
+import { mdFiles } from "./record.mjs";
+import { frontmatterOf } from "./circles.mjs";
+import { FOLDER_MANIFEST } from "./folders.mjs";
+
+export const FALSIFY_MODES = ["all-projects", "drop-efforts", "skip-as-pass", "no-status"];
+const falsified = (mode, env) => [env.EVDA_WORK_FALSIFY, process.env.EVDA_WORK_FALSIFY].join(",").split(",").map((s) => s.trim()).includes(mode);
+const DAY = /^\d{4}-\d{2}-\d{2}$/;
+const posix = (p) => p.split(sep).join("/");
+
+// The outermost record above `dir` (itself when there is none), and `dir`'s path inside it.
+export function offsetInTop(dir) {
+  let top = dir;
+  for (let up = findRoot(dirname(top)); up && up !== top; up = findRoot(dirname(up))) top = up;
+  return { top, offset: posix(relative(top, dir)) };
+}
+
+// The board projects that belong to the record at `dir`: named, or matched by vault_path.
+export function projectsFor(dir, projects, { project = null, env = process.env } = {}) {
+  if (project) return projects.filter((p) => p.id === project).map((p) => ({ ...p, by: "named" }));
+  if (falsified("all-projects", env)) return projects.map((p) => ({ ...p, by: "vault_path" }));
+  const { top, offset } = offsetInTop(dir);
+  const subs = subRecords(dir).map((s) => (offset ? `${offset}/${s}` : s));
+  const under = (v, root) => root === "" || v === root || v.startsWith(`${root}/`);
+  return projects
+    // A vault_path names a place in the owner's outermost record; one that is not there belongs to
+    // no record, since nothing on disk says whose it is.
+    .filter((p) => typeof p.vault_path === "string" && p.vault_path !== "" && existsSync(join(top, p.vault_path)))
+    .filter((p) => under(p.vault_path, offset) && !subs.some((s) => under(p.vault_path, s)))
+    .map((p) => ({ ...p, by: "vault_path" }));
+}
+
+// KEY=VALUE lines, quotes stripped. Only the two keys the connector needs are kept.
+export function readEnvFile(path) {
+  const out = {};
+  for (const raw of readFileSync(path, "utf8").split("\n")) {
+    const line = raw.trim();
+    if (!line || line.startsWith("#") || !line.includes("=")) continue;
+    const at = line.indexOf("=");
+    const k = line.slice(0, at).trim();
+    if (k === "SUPABASE_URL" || k === "SUPABASE_SERVICE_ROLE_KEY") out[k] = line.slice(at + 1).trim().replace(/^["']|["']$/g, "");
+  }
+  return out;
+}
+
+async function getAll(fetchFn, url, key, path) {
+  const rows = [];
+  for (let from = 0; ; from += 1000) {
+    const res = await fetchFn(`${url}/rest/v1/${path}`, { headers: { apikey: key, Authorization: `Bearer ${key}`, Range: `${from}-${from + 999}`, "Range-Unit": "items" } });
+    if (!res.ok && res.status !== 206) throw new Error(`the board answered ${res.status} for ${path.split("?")[0]}`);
+    const page = await res.json();
+    rows.push(...page);
+    if (page.length < 1000) return rows;
+  }
+}
+
+// Efforts from THE HARLEQUIN. Returns { status: "checked" | "skipped" | "failed", ... }.
+export async function harlequinEfforts(dir, { project = null, env = process.env, envFile = null, fetchFn = globalThis.fetch } = {}) {
+  let creds = { SUPABASE_URL: env.SUPABASE_URL, SUPABASE_SERVICE_ROLE_KEY: env.SUPABASE_SERVICE_ROLE_KEY };
+  if (envFile) {
+    if (!existsSync(envFile)) return { status: "skipped", why: `the env file ${envFile} does not exist` };
+    creds = { ...creds, ...readEnvFile(envFile) };
+  }
+  if (!creds.SUPABASE_URL || !creds.SUPABASE_SERVICE_ROLE_KEY) {
+    if (falsified("skip-as-pass", env)) return { status: "checked", efforts: [], projects: [] };
+    return { status: "skipped", why: "THE HARLEQUIN is read with SUPABASE_URL and SUPABASE_SERVICE_ROLE_KEY, and neither the environment nor --env-file gave both" };
+  }
+  if (typeof fetchFn !== "function") return { status: "skipped", why: "this runtime has no fetch" };
+  const url = creds.SUPABASE_URL.replace(/\/+$/, "");
+  const key = creds.SUPABASE_SERVICE_ROLE_KEY;
+  let all;
+  try {
+    all = await getAll(fetchFn, url, key, "dev_projects?select=id,vault_path&order=id");
+  } catch (e) {
+    return { status: "skipped", why: `the board could not be read (${e.cause?.code ?? e.message}); offline or unreachable` };
+  }
+  const mine = projectsFor(dir, all, { project, env });
+  if (project && mine.length === 0) return { status: "failed", why: `the board has no project "${project}"` };
+  if (mine.length === 0) return { status: "failed", why: `no board project's vault_path lies in this record (${offsetInTop(dir).offset || "the root"}); name one with "harlequin:<project>" or map work to a folder` };
+  let items;
+  try {
+    items = await getAll(fetchFn, url, key, `dev_items?select=number,title,status,planned_for,project_id&project_id=in.(${mine.map((p) => p.id).join(",")})&order=number`);
+  } catch (e) {
+    return { status: "skipped", why: `the board's tickets could not be read (${e.cause?.code ?? e.message})` };
+  }
+  let efforts = items.map((i) => ({ id: `HQ-${i.number}`, title: i.title, status: i.status, planned_for: i.planned_for ?? null, project: i.project_id }));
+  if (falsified("drop-efforts", env)) efforts = [];
+  return { status: "checked", efforts, projects: mine };
+}
+
+// Efforts from a folder of effort files. Every problem is a sentence; an effort with no status is
+// a problem, never an effort.
+export function folderEfforts(evda, entry, { env = process.env } = {}) {
+  const efforts = [];
+  const problems = [];
+  if (!entry.exists || !entry.isDir) return { status: "failed", why: `${entry.rel} is not a folder`, efforts, problems };
+  for (const abs of mdFiles(entry.abs)) {
+    if (abs.endsWith(`/${FOLDER_MANIFEST}`)) continue;
+    const rel = posix(relative(evda.dir, abs));
+    const text = readFileSync(abs, "utf8");
+    const front = frontmatterOf(text) ?? {};
+    const status = typeof front.status === "string" ? front.status.trim() : "";
+    if (!status && !falsified("no-status", env)) { problems.push(`${rel} is in the work folder ${entry.rel} and has no status. An effort carries its status as a field.`); continue; }
+    const planned = front.planned_for ?? null;
+    if (planned !== null && !(typeof planned === "string" && DAY.test(planned))) { problems.push(`${rel} has planned_for ${JSON.stringify(planned)}; it is a date, YYYY-MM-DD.`); continue; }
+    const title = /^# (.+)$/m.exec(text)?.[1]?.trim() ?? rel.split("/").pop().replace(/\.md$/, "");
+    efforts.push({ id: rel, title, status: status || "(none)", planned_for: planned, project: null });
+  }
+  return { status: "checked", efforts, problems };
+}
+
+const tally = (efforts) => {
+  const by = {};
+  for (const e of efforts) by[e.status] = (by[e.status] ?? 0) + 1;
+  return Object.entries(by).sort((a, b) => b[1] - a[1]).map(([s, n]) => `${n} ${s}`).join(", ");
+};
+
+// The view: every work entry read, one CHECKED or SKIPPED line each, and FAIL lines. Returns
+// { lines, efforts, exit }. exit 0 when every entry printed CHECKED n > 0 or SKIPPED with its reason
+// (zero efforts is a SKIPPED, never a CHECKED 0), 1 on a failure, 2 when the record declares no work.
+export async function readWork(evda, { env = process.env, envFile = null, fetchFn = globalThis.fetch } = {}) {
+  const four = fourRoles(evda, { subRecords: subRecords(evda.dir) });
+  const lines = [];
+  const efforts = [];
+  let failed = false;
+  if (four.roles.work.length === 0) return { lines: [`SKIPPED efforts: this record maps no "work" role`], efforts, exit: 2 };
+  for (const p of four.problems.filter((x) => /^"work/.test(x))) { lines.push(`FAIL  ${p}`); failed = true; }
+  for (const entry of four.roles.work) {
+    if (entry.source) {
+      const r = await harlequinEfforts(evda.dir, { project: entry.source.project, env, envFile, fetchFn });
+      if (r.status === "skipped") { lines.push(`SKIPPED efforts from ${entry.source.source}: ${r.why}`); continue; }
+      if (r.status === "failed") { lines.push(`FAIL  ${entry.key}  ${r.why}`); failed = true; continue; }
+      const names = r.projects.map((p) => `${p.id}${p.by === "vault_path" ? ` (${p.vault_path})` : ""}`).join(", ");
+      if (r.efforts.length === 0) { lines.push(`SKIPPED efforts from ${entry.source.source}: ${r.projects.length} project(s) (${names}) and the board holds no ticket in them. Nothing was checked, so nothing passed.`); continue; }
+      lines.push(`CHECKED ${r.efforts.length} efforts  from ${entry.source.source}, ${r.projects.length} project(s) ${r.projects[0]?.by === "named" ? "named" : "by vault_path"}: ${names}; ${tally(r.efforts)}`);
+      efforts.push(...r.efforts);
+    } else {
+      const r = folderEfforts(evda, entry, { env });
+      for (const p of r.problems) { lines.push(`FAIL  ${p}`); failed = true; }
+      if (r.status === "failed") { lines.push(`FAIL  ${entry.key}  ${r.why}`); failed = true; continue; }
+      if (r.efforts.length === 0) { lines.push(`SKIPPED efforts from the folder ${entry.rel}: it holds no effort file yet. Nothing was checked, so nothing passed.`); continue; }
+      lines.push(`CHECKED ${r.efforts.length} efforts  from the folder ${entry.rel}: ${tally(r.efforts)}`);
+      efforts.push(...r.efforts);
+    }
+  }
+  return { lines, efforts, exit: failed ? 1 : 0 };
+}