cortad 0.3.9 → 0.3.11

package/lib/env-files.mjs

@@ -0,0 +1,124 @@
+import { readFileSync } from "node:fs";
+import { basename, dirname, join, sep } from "node:path";
+import { listingUrl } from "./listing.mjs";
+
+// An env file read the way dotenv and python-dotenv read one: comments and `export` dropped, a quoted
+// value kept whole across lines, an unquoted one cut at " #", ${NAME} filled from the names above it
+// and then from `outer`. A bare $ is kept as written, as dotenv keeps it: "pa$$word" and a bcrypt hash
+// are values, not references. A quote that never closes is the line as written. A line-by-line read
+// handed an app the first line of a quoted PEM key and an unquoted value with its comment still on it.
+export function parseEnv(text, outer = {}) {
+  const out = {};
+  const fill = (value) => value.replace(/(\\?)\$\{([A-Za-z_][A-Za-z0-9_]*)\}/g, (whole, escaped, name) => (escaped ? whole.slice(1) : out[name] ?? outer[name] ?? ""));
+  const lines = text.replace(/\r\n?/g, "\n").split("\n");
+  for (let i = 0; i < lines.length; i++) {
+    const m = /^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)$/.exec(lines[i]);
+    if (!m) continue;
+    const rest = m[2];
+    const quote = rest[0];
+    if (quote === '"' || quote === "'") {
+      let body = rest.slice(1);
+      let j = i;
+      while (!closes(body, quote) && j + 1 < lines.length) body += `\n${lines[++j]}`;
+      const end = closes(body, quote);
+      if (end) {
+        i = j;
+        const raw = body.slice(0, end - 1);
+        out[m[1]] = quote === "'" ? raw : fill(raw).replace(/\\n/g, "\n").replace(/\\(["\\$])/g, "$1");
+        continue;
+      }
+    }
+    out[m[1]] = fill(rest.replace(/\s+#.*$/, "").trim());
+  }
+  return out;
+}
+// One past the closing quote, or 0 when the value has none yet. A double quote escaped by a backslash
+// does not close it.
+function closes(body, quote) {
+  for (let i = 0; i < body.length; i++) {
+    if (quote === '"' && body[i] === "\\") { i++; continue; }
+    if (body[i] === quote) return i + 1;
+  }
+  return 0;
+}
+
+const read = (file, outer) => { try { return parseEnv(readFileSync(file, "utf8"), outer); } catch { return {}; } };
+const PLACEHOLDERS = /\.(?:example|sample)$/;
+
+// The folders from the app's own up to the repository root, nearest first.
+const upFrom = (appDir, root) => {
+  const dirs = [];
+  for (let d = appDir; ; d = dirname(d)) {
+    dirs.push(d);
+    if (d === root || !d.startsWith(root + sep) || dirname(d) === d) return dirs;
+  }
+};
+
+// What a start by hand gives the app from its env files: the `.env` nearest the app, as `source .env`
+// does for an app with no loader of its own. A name another env file there sets to another value is
+// left to the app's own loader, which reads its files by its own mode and order: put in the process,
+// it outranks that loader (the process wins in dotenv, python-dotenv, pydantic-settings, Next and
+// Vite). Nitham's app reads .env.test then .env.local; the test file's key, handed over this way,
+// was refused on every call it made under Cortad and on none started by hand.
+export function appEnv(envFiles, appDir, root, outer = {}) {
+  const base = upFrom(appDir, root).map((d) => join(d, ".env")).find((f) => envFiles.includes(f));
+  if (!base) return {};
+  const values = read(base, outer);
+  const beside = envFiles.filter((f) => f !== base && !PLACEHOLDERS.test(f) && (dirname(f) === dirname(base) || dirname(f) === appDir));
+  for (const file of beside) {
+    for (const [name, value] of Object.entries(read(file, outer))) if (name in values && values[name] !== value) delete values[name];
+  }
+  return values;
+}
+
+// The real env files in the app's folders, lowest first, the way dotenv-flow, Next and Vite rank them
+// in development: .env, then the development file, then .env.local, and the file of the mode the shell
+// names above all. A test, staging or stage file of another mode goes under them all and still counts:
+// Nitham's app reads .env.test in its local mode, and a store only it names is a store the app writes
+// into. Placeholders are left out.
+const RANK = { ".env": 1, ".env.development": 2, ".env.dev": 2, ".env.local": 3, ".env.development.local": 4 };
+const MODE_FILE = /^\.env\.(test|staging|stage)$/;
+export function rankedFiles(envFiles, appDir, root, mode = "") {
+  const dirs = upFrom(appDir, root).reverse();
+  const want = mode.toLowerCase() === "staging" ? "stage" : mode.toLowerCase();
+  const rank = (f) => {
+    const name = basename(f);
+    const m = MODE_FILE.exec(name);
+    if (m) return (m[1] === "staging" ? "stage" : m[1]) === want ? 5 : 0;
+    return RANK[name] ?? -1;
+  };
+  return envFiles.filter((f) => dirs.includes(dirname(f)) && !PLACEHOLDERS.test(f) && rank(f) >= 0)
+    .sort((a, b) => dirs.indexOf(dirname(a)) - dirs.indexOf(dirname(b)) || rank(a) - rank(b));
+}
+
+// The values the app's settings could settle on, ranked as above: for reading which stores and ports
+// the app names, and for a shell that cannot read the files itself. `outer` names the mode and fills ${NAME}.
+export function localEnv(envFiles, appDir, root, outer = {}) {
+  const mode = outer.ENV ?? outer.APP_ENV ?? outer.NODE_ENV ?? outer.ENVIRONMENT ?? "";
+  return Object.assign({}, ...rankedFiles(envFiles, appDir, root, mode).map((f) => read(f, outer)));
+}
+
+// Each real env file in the app's folders, read whole: a key is only ever sent with the address the
+// same file gives it, or one the app's development files give every key.
+export function fileValues(envFiles, appDir, root, outer = {}) {
+  const dirs = upFrom(appDir, root);
+  return envFiles.filter((f) => dirs.includes(dirname(f)) && !PLACEHOLDERS.test(f)).map((f) => read(f, outer));
+}
+
+// The values a development start reads whatever its mode: .env, the development files and .env.local,
+// never a test, staging or stage file.
+export function devEnv(envFiles, appDir, root, outer = {}) {
+  return Object.assign({}, ...rankedFiles(envFiles, appDir, root).filter((f) => !MODE_FILE.test(basename(f))).map((f) => read(f, outer)));
+}
+
+// The key and address pairs a provider's model listing is asked with: the shell's key, else each
+// distinct key a file holds. A key goes only to the address the shell or its own file names, else the
+// one the development files name, else the provider's own; where only a test or staging file names
+// an address, which the app may not use, the key is not sent at all.
+export function keyTries(name, canonical, { shell, files, dev }) {
+  const prefix = name.replace(/_API_KEY$/, "");
+  const named = (v) => Boolean(v[`${prefix}_BASE_URL`] || v[`${prefix}_API_BASE`]);
+  const addressFor = (own) => (named(shell) || named(own) || named(dev) || !files.some(named) ? listingUrl(name, canonical, { ...dev, ...own, ...shell }) : null);
+  return [...new Map((shell[name] ? [shell] : files.filter((v) => v[name]))
+    .map((v) => ({ key: v[name], url: addressFor(v) })).filter((t) => t.url).map((t) => [`${t.url} ${t.key}`, t])).values()];
+}

package/lib/env-secrets.mjs

@@ -1,5 +1,6 @@
 import { readFileSync } from "node:fs";
 import { StringDecoder } from "node:string_decoder";
+import { parseEnv } from "./env-files.mjs";
 
 // A model's or provider's name is how the app is configured, not a credential: status names it and
 // prices the run by it. A value under such a name that looks like a key stays masked all the same.
@@ -7,18 +8,25 @@ const NAMES_A_MODEL = /(?:^|_)(?:MODEL|MODELS|MODEL_NAME|MODEL_ID|PROVIDER)$/i;
 const KEY_LIKE = /[A-Za-z0-9]{24,}/;
 
 // Values from your env files, read here and only here, so nothing a command prints can carry one.
+// Each value as the line holds it and as the app's own loader reads it (lib/env-files.mjs parseEnv),
+// and each line of one that spans lines: the app is handed the parsed value, so a value that differs
+// from its line (a trailing comment, an escaped quote, a key across lines) must be masked as parsed.
 export function secretValues(envFiles) {
   const values = new Set();
+  const add = (name, v) => {
+    if (NAMES_A_MODEL.test(name) && !KEY_LIKE.test(v)) return;
+    for (const one of v.includes("\n") ? [v, ...v.split("\n").map((l) => l.trim()).filter((l) => l.length >= 12)] : [v]) {
+      if (one.length >= 8 && !/^(true|false|localhost|development|production|\d+)$/i.test(one)) values.add(one);
+    }
+  };
   for (const file of envFiles) {
     let text = "";
     try { text = readFileSync(file, "utf8"); } catch { continue; }
     for (const line of text.split("\n")) {
       const m = /^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)$/.exec(line);
-      if (!m) continue;
-      const v = m[2].trim().replace(/^(['"])(.*)\1$/, "$2");
-      if (NAMES_A_MODEL.test(m[1]) && !KEY_LIKE.test(v)) continue;
-      if (v.length >= 8 && !/^(true|false|localhost|development|production|\d+)$/i.test(v)) values.add(v);
+      if (m) add(m[1], m[2].trim().replace(/^(['"])(.*)\1$/, "$2"));
     }
+    for (const [name, v] of Object.entries(parseEnv(text))) add(name, v);
   }
   return [...values].sort((a, b) => b.length - a.length);
 }

package/lib/intel-text.mjs

@@ -0,0 +1,47 @@
+// What the agent reads back from the Intelligence Layer's tools, as plain lines: numbers, ids and
+// the cause, never a user's words.
+
+const n = (v) => (typeof v === "number" ? v.toLocaleString("en-US") : String(v ?? 0));
+const when = (iso) => (iso ? new Date(iso).toISOString().replace("T", " ").slice(0, 16) + "Z" : "");
+
+export function incidentLine(i) {
+  const where = i.segment ? (i.segment.kind === "country" ? ` from ${i.segment.value}` : ` on release ${i.segment.value}`) : "";
+  const cause = i.cause ? `; the change was ${i.cause.kind} ${i.cause.value ?? ""}`.trimEnd() + (i.cause.at ? ` at ${when(i.cause.at)}` : "") : "";
+  return `Since ${when(i.since)}, ${i.kind === "reaction" ? `people${where} reacted "${i.key}" after` : `replies${where} broke "${i.key}" in`} ${n(i.now.broke)} of ${n(i.now.of)}; before, ${n(i.before.broke)} of ${n(i.before.of)}${cause}.`;
+}
+
+export function intelligenceText(d) {
+  const lines = [];
+  lines.push(d.wrong?.length ? `Wrong now: ${d.wrong.length}.` : "Nothing is wrong right now.");
+  for (const i of d.wrong ?? []) lines.push(`- ${incidentLine(i)}`);
+  const t = d.conversations ?? {};
+  lines.push(`Last ${d.days} days: ${n(t.n)} conversations, ${n(t.read)} read, ${n(t.heldEvery)} kept every rule, ${n(t.got)} got what they came for, ${n(t.frustrated)} frustrated, ${n(t.wantsHuman)} asked for a person.`);
+  if (d.visits?.n) {
+    const r = d.visits.reactions ?? {};
+    lines.push(`Visits: ${n(d.visits.n)}; after answers people ${Object.entries(r).filter(([k]) => k !== "waited").map(([k, v]) => `${k} ${n(v)}`).join(", ") || "reacted to nothing yet"} (of ${n(r.waited)} answers seen).`);
+  }
+  if (d.checks?.length) lines.push(`Checks broken most: ${d.checks.filter((c) => c.broke).sort((a, b) => b.broke - a.broke).slice(0, 5).map((c) => `${c.id} ${n(c.broke)} of ${n(c.held + c.broke)}`).join("; ") || "none"}.`);
+  lines.push(`The page: ${d.url}`);
+  return lines.join("\n");
+}
+
+export function incidentsText(d) {
+  if (!d.open?.length) return `${d.said ?? "Nothing is wrong right now."}\n${d.url}`;
+  return [...d.open.map((i) => `${incidentLine(i)} Conversations: ${(i.conversations ?? []).join(", ")}`), d.said, d.url].filter(Boolean).join("\n");
+}
+
+const ruleWords = (r) => r.kind === "path" ? `a page ${r.match} ${r.value}` : r.kind === "click" ? `a click on ${r.text ? `"${r.text}"` : r.selector}` : r.kind === "event" ? `the page's event "${r.name}"` : `the backend's outcome "${r.name}"`;
+
+export function outcomesText(d) {
+  if (d.proposed !== undefined) return `${n(d.proposed)} proposed. ${d.awaiting}`;
+  if (!d.outcomes?.length) return `No outcome is defined yet. Propose what the code treats as a good ending (a signup route, a checkout, a "done" button) with outcomes {proposals: [{name, rules, why}]}; ${d.shape}`;
+  return [...d.outcomes.map((o) => `${o.approved ? "Counted" : "Proposed, awaiting the person"}: ${o.name}: ${o.rules.map(ruleWords).join(", or ")}${o.why ? ` (${o.why})` : ""}`), d.url].join("\n");
+}
+
+export function queryText(d) {
+  if (d.error) return `${d.error}${d.sql ? `\n${d.sql}` : ""}`;
+  const rows = d.rows ?? [];
+  if (rows.length === 0) return `No rows.\n${d.sql}`;
+  const keys = Object.keys(rows[0]);
+  return [keys.join("\t"), ...rows.slice(0, 200).map((r) => keys.map((k) => String(r[k] ?? "")).join("\t")), rows.length > 200 ? `${rows.length - 200} more rows` : "", d.scannedBytes != null ? `Scanned ${n(d.scannedBytes)} bytes.` : ""].filter(Boolean).join("\n");
+}

package/lib/keeping.mjs

@@ -1,7 +1,7 @@
 // What one session keeps out of the run's way and brings up for it: the app's database files and
 // servers, copied before it starts (lib/data.mjs, lib/stores.mjs), and the stores and services it
 // reaches, started when nothing answers there (lib/backing.mjs). Every sentence goes to the terminal
-// and, through lines(), to the run: what trials write into for real first.
+// and to the run: the copies made through lines(), and each store with none through blocked().
 import { createHash } from "node:crypto";
 import { localAddresses, makeBacking, tcpOpen } from "./backing.mjs";
 import { keepData } from "./data.mjs";
@@ -14,7 +14,7 @@ const addressed = (s) => Boolean(s.host) && !s.host.startsWith("/") && Boolean(s
 // One nothing answers at is left for later: trials cannot write into it.
 const isDown = async (s) => addressed(s) && !(await tcpOpen(s.host, s.port));
 // The stores the settings name on this machine, as ports to bring up; a compose image may serve them.
-const localStores = (k) => k.stores.filter((s) => addressed(s) && onThisMachine(s.host)).map((s) => ({ port: s.port, names: s.names, store: true }));
+const localStores = (k) => k.named.filter((s) => addressed(s) && onThisMachine(s.host)).map((s) => ({ port: s.port, names: s.names, store: true }));
 // The API keeps eight stores that hold Run. Past that, the rest travel as one row, and a yes to that
 // row is a yes to each of them; a row more changes its id, so an old yes no longer covers it.
 const BLOCKED_MAX = 8;
@@ -37,48 +37,51 @@ function blockedRows(blocked) {
 // `typed`: the person gave the start command. It is run as it is, with the settings and the stores
 // that command gives the app: a legal research API typed ENV=staging and was started on copies of
 // the test databases its default settings file names, where its library is empty.
+// `chosen`: the store settings of the file the person chose for the run (--data). Those stores are
+// the ones copied, and the app is handed all of those settings, so it reaches the server they name.
 const AS_TYPED = "Your app is started with your own command as it is, on the databases that command gives it. Nothing is copied: a run writes into them once you say yes to each on the card.";
-export function makeKeeping({ root, work, ledgerFile, onPath, say, settings, launch, connections, copies = () => [], hold = () => {}, typed = false }) {
+export function makeKeeping({ root, work, ledgerFile, onPath, say, settings, launch, connections, copies = () => [], hold = () => {}, typed = false, chosen = {} }) {
   let pending = null;
   let now = null;
   let backing = null;
   let backedUp = false;
   let seen = 0;
   const tell = (lines) => { for (const line of lines) say(lower(line)); };
-  const held = (blocked) => tell(blocked.map((b) => `Run waits for your yes on the card in the browser: ${lower(b.why)}`));
+  const held = (blocked) => tell(blocked.map((b) => `One question for the person on the card in the browser: ${lower(b.why)}`));
 
   async function keepAll(started) {
-    if (typed) {
-      const none = async () => ({ env: {}, risks: [], copies: [], blocked: [], pass: [] });
-      // The app's own command may still reach a Qdrant: the copies the hook makes there are dropped too.
-      const keeper = storeKeeper({ ledgerFile, values: {}, dirs: [] });
-      now = { env: {}, risks: [], notes: [AS_TYPED], blocked: [], pass: [], stores: [], keeper: { keep: none, drop: async () => {}, dropCopies: (c, s) => keeper.dropCopies(c, s) }, values: {}, started };
-      tell(now.notes);
-      return now;
-    }
     const { values, from, appDir, sources } = settings();
-    const disk = keepData({ values, from, appDir, root, work, sources, started });
+    // Which stores a typed command gives the app is its own: only those chosen for the run are copied,
+    // and each other store it reaches holds Run once the hook sees it (watch). A store it reaches for
+    // and finds nothing at is still brought up: a session that ended stopped the ones it had started,
+    // and the app started next with its own command met "connection refused".
+    const disk = typed ? { env: {}, said: Object.keys(chosen).length ? [] : [AS_TYPED], held: [], values: chosen } : keepData({ values, from, appDir, root, work, sources, started });
     const stores = storesOf(disk.values);
     const keeper = storeKeeper({ ledgerFile, values: disk.values, dirs: [...new Set([appDir, root])] });
     const got = await keeper.keep(stores, { started, down: isDown });
-    backing ??= makeBacking({ root, appDir, values: disk.values, onPath, ledgerFile, launch, adopt: started });
-    now = { env: { ...disk.env, ...got.env }, risks: got.risks, notes: [...disk.said, ...got.copies], blocked: got.blocked, pass: got.pass, stores, keeper, values: disk.values, started };
-    tell([...now.risks, ...now.notes]);
+    backing ??= makeBacking({ root, appDir, values: typed ? values : disk.values, onPath, ledgerFile, launch, adopt: started });
+    now = { env: { ...chosen, ...disk.env, ...got.env }, notes: [...disk.said, ...got.copies], blocked: [...disk.held, ...got.blocked], pass: got.pass, stores, named: stores, keeper, values: disk.values, started };
+    tell(now.notes);
     held(now.blocked);
     return now;
   }
   // A read that failed is tried again on the next ask, never handed back as the same failure.
   const once = (started) => (pending ??= keepAll(started).catch((e) => { pending = null; throw e; }));
+  // The store ids the person's yes covers: a yes to the row the rest travel as is a yes to each.
+  const yesOf = (stores) => {
+    const yes = new Set(stores);
+    const rest = now && now.blocked.length > BLOCKED_MAX ? overflow(now.blocked) : [];
+    if (rest.length && yes.has(overflowId(rest))) for (const b of rest) yes.add(b.id);
+    return yes;
+  };
 
   // Brings up what is wanted, copies each store that now answers, and says both.
   async function bringUp(wants) {
-    if (typed) return { changed: false, came: false, copied: false };
     const k = await once(true);
     hold();
     const up = await backing.up(wants);
     const got = await k.keeper.keep(k.stores, { started: k.started, down: isDown });
     Object.assign(k.env, got.env);
-    k.risks.unshift(...got.risks);
     // Said once: every look brings the same lines back, and status printed one hold four times.
     k.notes.push(...[...up.lines, ...got.copies].filter((l) => !k.notes.includes(l)));
     // A service a setting names that answers nothing holds Run until it does; one that answers now
@@ -89,7 +92,7 @@ export function makeKeeping({ root, work, ledgerFile, onPath, say, settings, lau
     for (const d of up.down) if (!k.blocked.some((b) => b.down && b.port === d.port)) k.blocked.push({ id: downId(d.port), names: d.names, why: d.why, down: true, port: d.port });
     k.blocked.push(...got.blocked.filter((b) => !k.blocked.some((x) => x.id === b.id)));
     k.pass.push(...got.pass);
-    const said = [...got.risks, ...up.lines, ...got.copies];
+    const said = [...up.lines, ...got.copies];
     tell(said);
     held(got.blocked);
     return { changed: said.length > 0 || got.blocked.length > 0, came: up.ports.length > 0, copied: Object.keys(got.env).length > 0 };
@@ -103,20 +106,24 @@ export function makeKeeping({ root, work, ledgerFile, onPath, say, settings, lau
     env: async (started) => (await once(started)).env,
     // The copies so far, for a service of the repository started beside the app.
     envNow: () => now?.env ?? {},
-    // What trials write into for real first; the API keeps eight sentences of 400 characters.
-    lines: async (started) => { const k = await once(started); return [...k.risks, ...k.notes].map((l) => l.slice(0, 400)).slice(0, 8); },
-    // The stores off this machine no copy could be made of: each holds Run until the person says yes.
+    // The copies trials write into; the API keeps eight sentences of 400 characters.
+    lines: async (started) => (await once(started)).notes.map((l) => l.slice(0, 400)).slice(0, 8),
+    // The stores no copy could be made of: each holds Run until the person says yes.
     blocked: async (started) => blockedRows((await once(started)).blocked),
     // The hosts a trial's writes may reach: the copies made off this machine, and the hosts and
     // stores the person said yes to (setup.consent). Before the copies are made, or after the app
     // was attached to instead, only the hosts.
     outbound: ({ hosts = [], stores = [] } = {}) => {
       if (!now) return [...new Set(hosts)];
-      const yes = new Set(stores);
-      const rest = now.blocked.length > BLOCKED_MAX ? overflow(now.blocked) : [];
-      if (rest.length && yes.has(overflowId(rest))) for (const b of rest) yes.add(b.id);
+      const yes = yesOf(stores);
       return [...new Set([...hosts, ...now.pass, ...now.stores.filter((s) => yes.has(storeId(s)) && !onThisMachine(s.host)).map((s) => String(s.host).toLowerCase())])];
     },
+    // The stores with no copy the person has not said yes to writing into. A service that is down
+    // holds Run too, but nothing can be written into it.
+    holding: ({ stores = [] } = {}) => {
+      const yes = yesOf(stores);
+      return now?.blocked.filter((b) => !b.down && !yes.has(b.id)) ?? [];
+    },
     // The app stopped before it answered: each store its settings name and each port it reached that
     // is down is brought up, once. True when the app is worth starting again.
     async backUp(appPort) {
@@ -151,7 +158,7 @@ export function makeKeeping({ root, work, ledgerFile, onPath, say, settings, lau
       const bypassed = [...bypassedOf(live, k.stores, k.blocked), ...unnamedHeld(live, k.stores, k.blocked)];
       k.blocked.push(...bypassed);
       held(bypassed);
-      const got = typed ? { changed: false, copied: false } : await bringUp(reached(appPort));
+      const got = await bringUp(reached(appPort));
       return { changed: bypassed.length > 0 || got.changed, copied: got.copied };
     },
     // An app attached to instead of started keeps its own connections: its copies are of no use.

package/lib/keys.mjs

@@ -1,3 +1,4 @@
+import { parseEnv } from "./env-files.mjs";
 // A file that carries a key stays on this machine, whatever git thinks of it: a catalogue that keeps
 // an AES key per video is tracked like code and is no more shareable than a .env.
 // The header alone is code that looks for keys; a key has its body after it.
@@ -21,18 +22,21 @@ export function holdsKeys(text, values = []) {
 const SECRET_NAME = /KEY|SECRET|TOKEN|PASSW|PRIVATE|CREDENTIAL/i;
 const EXAMPLE = /\.(example|sample|template|dist)$/i;
 export function secretEnvValues(envFiles, read) {
-  const values = [];
+  const values = new Set();
+  // A value of few distinct characters is a placeholder or a published test key, not a secret.
+  const add = (v) => { if (v.length >= 12 && !/\s/.test(v) && new Set(v).size >= 8) values.add(v); };
   for (const file of envFiles) {
     if (EXAMPLE.test(file)) continue;
     let text = "";
     try { text = read(file); } catch { continue; }
     for (const line of text.split("\n")) {
       const m = /^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)$/.exec(line);
-      if (!m || !SECRET_NAME.test(m[1])) continue;
-      const v = m[2].trim().replace(/^(['"])(.*)\1$/, "$2");
-      // A value of few distinct characters is a placeholder or a published test key, not a secret.
-      if (v.length >= 12 && !/\s/.test(v) && new Set(v).size >= 8) values.push(v);
+      if (m && SECRET_NAME.test(m[1])) add(m[2].trim().replace(/^(['"])(.*)\1$/, "$2"));
+    }
+    // As the app's loader reads it too, each line of a value that spans lines on its own.
+    for (const [name, v] of Object.entries(parseEnv(text))) {
+      if (SECRET_NAME.test(name)) for (const one of v.split("\n")) add(one.trim());
     }
   }
-  return values;
+  return [...values];
 }

package/lib/lock.mjs

@@ -3,8 +3,9 @@
 // bubblewrap. Inside it a shell line can read your project and run your tests, and it can write
 // only where your own .gitignore already says files are disposable (caches, build output, coverage)
 // and in temp. It cannot write a tracked file, cannot read your keys or environment files, and on a
-// Mac cannot read what other programs left in /tmp or reach the network beyond this machine. With
-// neither tool present there is no shell.
+// Mac cannot read what other programs left in /tmp or reach the network beyond this machine, unless
+// it runs as the app (a world's command): then it keeps the app's reach, since it runs the app's own
+// AI, which calls the app's model provider. With neither tool present there is no shell.
 import { execFile, execFileSync } from "node:child_process";
 import { existsSync, realpathSync } from "node:fs";
 import { homedir, tmpdir } from "node:os";
@@ -58,7 +59,7 @@ export async function makeLock({ root, work }) {
     // Later rules win: home is shut, the project and the toolchains are opened again inside it, and
     // what the project ignores and your keys are shut last.
     const hide = ignored.hidden.map(({ path, dir }) => `(${dir ? "subpath" : "literal"} ${q(real(path) ?? path)})`);
-    const profile = [
+    const rules = ({ network }) => [
       "(version 1)(allow default)",
       `(deny file-read-data (subpath ${q(real(home) ?? home)}))`,
       // /tmp holds what other programs on this machine logged; a shell line may write there, never read it.
@@ -67,17 +68,17 @@ export async function makeLock({ root, work }) {
       '(allow file-read-data (regex #"^/private/tmp/sh-thd"))',
       `(allow file-read-data (subpath ${q(project)}) ${[work, ...tools].map((p) => `(subpath ${q(p)})`).join(" ")})`,
       ...(hide.length ? [`(deny file-read-data file-write* ${hide.join(" ")})`] : []),
-      "(deny network*)",
       // This machine only. Unix sockets stay shut: through one, a request rides out to the internet
       // by name on a system network helper even with every direct connection refused.
-      '(allow network-outbound (remote ip "localhost:*"))(allow network-inbound (local ip "localhost:*"))',
+      ...(network ? [] : ['(deny network*)(allow network-outbound (remote ip "localhost:*"))(allow network-inbound (local ip "localhost:*"))']),
       "(deny file-write*)",
       `(allow file-write* ${writable.map((p) => `(subpath ${q(p)})`).join(" ")} (literal "/dev/null") (literal "/dev/stdout") (literal "/dev/stderr") (literal "/dev/tty") (subpath "/dev/fd"))`,
       // The same operation the project is opened with: a rule naming file-read-data outranks one naming
       // file-read*, so a wildcard deny here let every .env be read again.
       `(deny file-read* file-read-data ${SECRET_DIRS.map((d) => `(subpath ${q(join(home, d))})`).join(" ")} ${SECRET_FILES.map((f) => `(literal ${q(join(home, f))})`).join(" ")} (regex #"\\.env$") (regex #"/\\.env\\.(local|staging|stage|development|dev|test|production|prod)$"))`,
     ].join("");
-    return { name: "seatbelt", wrap: (cmd) => ({ file: "/usr/bin/sandbox-exec", args: ["-p", profile, "/bin/sh", "-c", cmd] }) };
+    const locked = rules({ network: false }), asApp = rules({ network: true });
+    return { name: "seatbelt", wrap: (cmd, { network = false } = {}) => ({ file: "/usr/bin/sandbox-exec", args: ["-p", network ? asApp : locked, "/bin/sh", "-c", cmd] }) };
   }
   const bwrap = process.platform === "linux" ? ["/usr/bin/bwrap", "/bin/bwrap"].find(existsSync) : null;
   if (bwrap) {

package/lib/mcp.mjs

@@ -10,8 +10,8 @@ export const PROTOCOL = "2025-06-18";
 // Codex keeps only the first 512 characters self-contained and Claude Code shares about 4 KB across
 // every server, so the first paragraph stands alone and the whole stays under 1,500 characters.
 export const instructions = (spec = "cortad") => [
-  "Cortad tests the AI in this repository: simulated users written from the app's code talk to the app running on this machine, and every reply is checked. Cortad sends each AI endpoint a test request itself. status shows the app's port, what the reviews of the prompts and of the code around the model found, which endpoints answered and which failed at what file and line, and what a run would play and cost. The first run starts by itself; later runs when the person presses Run or asks.",
-  `Tell the person what status found in a few plain lines. Before you stop, start \`npx -y ${spec} wait\` as a background command: it returns when the next run or verify ends, with what it found. After a run, call findings and tell the person what it found and what you would change, worst first; the person then says which fix to make, and nothing is edited before their go. On their go, one fix at a time: verify replays the failing conversations and says whether the failure is gone, and a further round plays only when verify is called again. findings has each failure whole and findings numbers every rate. field_connect gives the steps to connect production. dispute records a check that reads this app wrong.`,
+  "Cortad tests the AI in this repository: simulated users written from the app's code talk to the app running on this machine, and every reply is checked. Cortad sends each AI endpoint a test request itself. status says whether the app is up, what Cortad's audit of the AI code found, and what a run would play and cost. A run starts when the person presses Run in the browser or asks you.",
+  `Tell the person what status found in three or four short, plain lines, leaving out file paths, endpoints, status codes and setting names unless they ask. Before you stop, start \`npx -y ${spec} wait\` as a background command: it returns when the next run or verify ends, with what it found. After a run, call findings and tell the person what their users ran into and what you would change, worst first, three problems at most; the person then says which fix to make, and nothing is edited before their go. On their go, one fix at a time: verify replays the failing conversations and says whether the failure is gone, and a further round plays only when verify is called again. findings has each failure whole and findings numbers every rate. connect gives the steps to connect the live app. intelligence says what is happening to it and incidents what went wrong and why; outcomes, subscribe and query are the layer's other tools. dispute records a check that reads this app wrong.`,
 ].join("\n\n");
 export const INSTRUCTIONS = instructions();
 
@@ -19,11 +19,11 @@ const str = (description, extra = {}) => ({ type: "string", description, ...extr
 const none = { type: "object", properties: {}, additionalProperties: false };
 const readOnly = { readOnlyHint: true };
 // What a note to the Cortad team may be about: a tool, the connect command, or the skill text.
-const ABOUT = ["status", "reach", "run", "run_status", "findings", "verify", "dispute", "field_connect", "field", "connect", "skill"];
+const ABOUT = ["status", "reach", "run", "run_status", "findings", "verify", "dispute", "field_connect", "field", "world", "world_status", "test", "connect", "intelligence", "incidents", "outcomes", "subscribe", "query", "skill"];
 
 export const TOOLS = [
   { name: "status", title: "Cortad status", annotations: readOnly,
-    description: "What Cortad found in this repository: whether the app is up and on which port, the reviews of its prompts and of the code around its model, each endpoint's answer to Cortad's test request or the file and line it failed at, the plan with runs left, and the latest run. Applies at the start of a session, right after a connect, and before a commit that changes prompts, tools, models or retrieval. With show, one section in full, in pages.",
+    description: "What Cortad found in this repository: whether the app is up and on which port, its audit of the prompts and of the code around the model, each endpoint's answer to Cortad's test request or the file and line it failed at, the plan with runs left, and the latest run. Applies at the start of a session, right after a connect, and before a commit that changes prompts, tools, models or retrieval. With show, one section in full, in pages.",
     inputSchema: { type: "object", properties: { show: { type: "string", enum: SHOW, description: "A section to list in full: rules, standards, journeys, endpoints, trials, records or reviews; or machine, what Cortad does on this machine." }, page: { type: "integer", minimum: 1, description: "The page of that list. Default 1." } }, additionalProperties: false } },
   { name: "reach", title: "Send Cortad's test requests again",
     description: "Sends Cortad's test request again to the endpoints status lists as failed or not yet answered, or to the paths named, from this machine to the app on its port. Each endpoint comes back with its HTTP status, its time and, when it is not 2xx, the start of what the app answered.",
@@ -58,6 +58,39 @@ export const TOOLS = [
   { name: "field", title: "Production numbers", annotations: readOnly,
     description: "Production in numbers: conversations read, checks passed, resolved, frustrated, asks for a human, and the rules broken most. Message text stays out of the answer.",
     inputSchema: { type: "object", properties: { days: { type: "integer", minimum: 1, maximum: 180, description: "Window in days. Default 30." } }, additionalProperties: false } },
+  { name: "world", title: "Test the AI in a world",
+    description: "For an AI in this app that is not a chat, such as a worker that reads data and writes a verdict: Cortad builds a copy of the product's data on this machine from the app's own seed, plants problems whose answers are known, runs the app's own detection on each, and scores what it raised against the answer key, repeated for a flip rate. Answers within a second with the world's id; world_status follows it. Say what was built or what to test, and the report keeps it.",
+    inputSchema: { type: "object", properties: { ask: str("What was built or what to test, in a sentence.", { maxLength: 2000 }) }, additionalProperties: false } },
+  { name: "world_status", title: "Where a world stands", annotations: readOnly,
+    description: "Where a world stands: planted problems found, missed, false alarms where nothing was planted, and flips between repeats, with what the app raised for each.",
+    inputSchema: { type: "object", properties: { jobId: str("The world's id, from world.") }, required: ["jobId"], additionalProperties: false } },
+  { name: "test", title: "Test what you built",
+    description: "The one call after a change: say what you built or want tested, in a sentence, and Cortad decides what kind of test that is. A world, where this app has one and the sentence names something it can plant; a run of the app's chat surfaces otherwise. Answers within a second with which kind started and the call that follows it.",
+    inputSchema: { type: "object", properties: { ask: str("What was built or what to test, in a sentence.", { maxLength: 2000 }) }, additionalProperties: false } },
+  { name: "connect", title: "Connect the live app", inputSchema: none,
+    description: "The steps to connect the live app, backend and page: a one-time code writes both keys into the env file, the SDK lines for the framework, the page tag, and where each conversation then appears. The same as field_connect." },
+  { name: "intelligence", title: "The live app in numbers", annotations: readOnly,
+    description: "What is happening to the live app: what is wrong now (since when, in how many of how many, the change before it), the window's conversations and checks, the visits and what people did after answers. No user's words.",
+    inputSchema: { type: "object", properties: { days: { type: "integer", minimum: 1, maximum: 90, description: "Window in days. Default 7." } }, additionalProperties: false } },
+  { name: "incidents", title: "What went wrong", annotations: readOnly, inputSchema: none,
+    description: "Each open incident: the check or reaction, since when, now against before, the cause the data points at (a release, a changed prompt or model, tool errors, page errors), and the conversations to open on the page. Fix the cause named first, then verify." },
+  { name: "outcomes", title: "What counts as a good ending",
+    description: "What the app counts as an outcome and how often it is reached; or, with proposals, new ones read from the code (a signup route, a checkout, a done button), which the person approves on the page before they count.",
+    inputSchema: { type: "object", properties: { proposals: { type: "array", maxItems: 10, items: { type: "object", properties: { name: str("A short name, as the person would say it.", { maxLength: 64 }), why: str("What in the code makes this an outcome.", { maxLength: 500 }), rules: { type: "array", minItems: 1, maxItems: 10, items: { type: "object", properties: { kind: { type: "string", enum: ["path", "click", "event", "backend"] }, match: { type: "string", enum: ["exact", "starts", "contains"] }, value: { type: "string" }, text: { type: "string" }, selector: { type: "string" }, name: { type: "string" } }, required: ["kind"], additionalProperties: false } } }, required: ["name", "rules", "why"], additionalProperties: false } } }, additionalProperties: false } },
+  { name: "subscribe", title: "Hear of incidents",
+    description: "Registers a public https address that receives each incident as signed JSON (x-cortad-event, x-cortad-signature: sha256=HMAC of the body). Answers with the secret once; keep it where the app keeps its secrets.",
+    inputSchema: { type: "object", properties: { url: str("A public https address that takes a POST.", { maxLength: 500 }) }, required: ["url"], additionalProperties: false } },
+  { name: "query", title: "Ask the warehouse", annotations: readOnly,
+    description: "A structured question over the live app's events, readings or reactions: a table, a time range of at most 90 days, filters, a grouping by columns or by hour or day, measures (count, count_distinct, sum, avg, min, max, share), a limit. Compiled by Cortad, pinned to this app; no SQL is taken. Rows come back as a table.",
+    inputSchema: { type: "object", properties: {
+      table: { type: "string", enum: ["events", "readings", "reactions"] },
+      from: str("Start, ISO 8601."), to: str("End, ISO 8601, at most 90 days after from."),
+      filters: { type: "array", maxItems: 20, items: { type: "object", properties: { column: { type: "string" }, op: { type: "string", enum: ["eq", "ne", "in", "gt", "gte", "lt", "lte", "null", "not_null"] }, value: {} }, required: ["column", "op"], additionalProperties: false } },
+      group: { type: "array", maxItems: 4, items: { type: "string" }, description: "Columns, or hour or day." },
+      measures: { type: "array", minItems: 1, maxItems: 8, items: { type: "object", properties: { fn: { type: "string", enum: ["count", "count_distinct", "sum", "avg", "min", "max", "share"] }, column: { type: "string" }, equals: {}, as: { type: "string" } }, required: ["fn"], additionalProperties: false } },
+      order: { type: "object", properties: { by: { type: "string" }, dir: { type: "string", enum: ["asc", "desc"] } }, required: ["by"], additionalProperties: false },
+      limit: { type: "integer", minimum: 1, maximum: 1000 },
+    }, required: ["table", "from", "to", "measures"], additionalProperties: false } },
 ];
 const NAMES = new Set(TOOLS.map((t) => t.name));
 

package/lib/mint.mjs

@@ -109,7 +109,7 @@ async function send(url, { method = "POST", headers = {}, body } = {}) {
   const res = await fetch(url, { method, headers: { "content-type": "application/json", ...headers }, ...(body === undefined ? {} : { body: JSON.stringify(body) }), signal: AbortSignal.timeout(20_000) });
   return { ok: res.ok, status: res.status, json: await res.json().catch(() => null) };
 }
-const saidBy = (r) => String(r.json?.errors?.[0]?.long_message ?? r.json?.msg ?? r.json?.error_description ?? r.json?.message ?? `status ${r.status}`).slice(0, 120);
+const saidBy = (r) => String(r.json?.errors?.[0]?.long_message ?? r.json?.msg ?? r.json?.error_description ?? r.json?.message ?? r.json?.error?.message ?? `status ${r.status}`).slice(0, 120);
 const refusedBy = (who, r) => ({ status: "refused", note: `${who} refused the test account: ${saidBy(r)}` });
 // An account the service already held may have been given a role since this machine made it.
 const ELEVATED_ACCOUNT = { status: "refused", note: "the test account carries an admin role; only an ordinary account is signed in" };
@@ -176,13 +176,31 @@ export function supabaseCookie(origin, session) {
   return value.match(/.{1,3180}/g).map((part, i) => `${name}.${i}=${part}`).join("; ");
 }
 
+// The Auth emulator their app verifies against while FIREBASE_AUTH_EMULATOR_HOST is set: it signs up any
+// address under any key. The account is this machine's own test account, made once and signed in after.
+export async function emulatorToken(host, account) {
+  // An emulator runs beside the app on this machine, and the test account's password goes to it in
+  // plain http: never to another host.
+  if (!/^(?:localhost|127\.0\.0\.1|\[::1\]):\d{2,5}$/.test(host)) return { status: "refused", note: "FIREBASE_AUTH_EMULATOR_HOST does not name an emulator on this machine" };
+  const at = (verb) => `http://${host}/identitytoolkit.googleapis.com/v1/accounts:${verb}?key=cortad-test`;
+  const body = { email: account.email, password: account.password, returnSecureToken: true };
+  let got = await send(at("signUp"), { body });
+  if (!got.ok && /EMAIL_EXISTS/.test(saidBy(got))) got = await send(at("signInWithPassword"), { body });
+  if (!got.ok || typeof got.json?.idToken !== "string") return refusedBy("your Firebase Auth emulator", got);
+  return { idToken: got.json.idToken, ttl: Number(got.json.expiresIn) || 3600 };
+}
+
 // Each hosted service's sign-in, as the value the role's header carries and how long it holds.
 const SIGN_IN = new Map([
-  ["firebase", async ({ env, all }) => {
-    const account = serviceAccountOf(env);
+  ["firebase", async ({ env, all, account }) => {
+    if (env.FIREBASE_AUTH_EMULATOR_HOST) {
+      const got = await emulatorToken(env.FIREBASE_AUTH_EMULATOR_HOST, account);
+      return got.idToken ? { value: `Bearer ${got.idToken}`, ttl: got.ttl, door: "your Firebase Auth emulator", said: "made a test account in your Firebase Auth emulator for the run to sign in with" } : got;
+    }
+    const admin = serviceAccountOf(env);
     const apiKey = webApiKeyOf(all);
-    if (!account || !apiKey) return { status: "absent", note: !account ? "no Firebase admin credential in your environment" : "no Firebase web API key in your environment" };
-    const got = await firebaseIdToken(account, apiKey);
+    if (!admin || !apiKey) return { status: "absent", note: !admin ? "no Firebase admin credential in your environment" : "no Firebase web API key in your environment" };
+    const got = await firebaseIdToken(admin, apiKey);
     if (!got.idToken) return { status: "refused", note: `your Firebase project refused the sign-in: ${got.error}` };
     return { value: `Bearer ${got.idToken}`, ttl: 3600, door: "your Firebase project", said: `signed in to your app as a test user it can tell apart (${TEST_UID}, in your own Firebase project)` };
   }],
@@ -251,13 +269,11 @@ export function makeIdentities({ root, work, envFiles, sourceFiles = () => [], s
     rmSync(out, { force: true });
     // ponytail: the program is Python, as it is in the sandbox. A machine without python3 mints
     // nothing and says so; port the program to this file if that turns out to be common.
-    // A caller a hosted service verifies is signed in at that service, below; a Firebase caller goes
-    // to the program only when an emulator stands in for their project. Handed to the program it
-    // waited its whole deadline on an emulator that was never there, and one app's sign-in arrived
-    // after the world had given up waiting for it.
+    // A caller a hosted service verifies is signed in at that service, below, a Firebase one at the
+    // Auth emulator when the app's settings name one: the program reads one env file and never saw an
+    // emulator named anywhere else, so a Python app verified by the emulator was knocked unsigned.
     const env = merged();
-    const emulated = Boolean(env.FIREBASE_AUTH_EMULATOR_HOST);
-    const signsHere = (r) => SIGN_IN.has(r?.kind) && !(r.kind === "firebase" && emulated);
+    const signsHere = (r) => SIGN_IN.has(r?.kind);
     const refused = new Map();
     // A pair the environment names for the app's own account is the one credential the raise is
     // allowed to reuse: the elevation and existing-account guards do not apply to it.