cortad 0.3.10 → 0.4.0

package/README.md

@@ -6,11 +6,16 @@ Runs Cortad's test conversations against the AI app on your machine, and gives y
 npx cortad <code>
 ```
 
-Run it in your app's folder with the code from cortad.com. It starts your app, connects it to Cortad, and adds Cortad to Claude Code, Codex, Cursor and Copilot on this machine. Cortad sends each AI endpoint it finds a test request, and the first run starts by itself once they have answered; later runs start when you press Run in the browser or ask your agent for one. Ctrl-C disconnects.
+Run it in your app's folder with the code from cortad.com and your own start command after `--`: Cortad runs that command as you typed it, with its hook inside and nothing else added, connects the app, and adds Cortad to Claude Code, Codex, Cursor and Copilot on this machine. Then send your AI one message the way a user would; that one request is what Cortad learns the endpoint from. Runs start when you press Run in the browser or ask your agent for one. Ctrl-C disconnects.
+
+```
+npx cortad <code> -- npm run dev           your command, as you start it, from the terminal that holds its settings
+npx cortad <code> --port 3000              an app already running: its replies are seen, its model calls are not
+```
 
 ## Your coding agent
 
-After that, your agent has ten tools: `status`, `reach`, `run`, `run_status`, `findings`, `verify`, `dispute`, `feedback`, `field_connect`, `field`. The same ten work as commands:
+After that, your agent has the tools `status`, `reach`, `run`, `run_status`, `findings`, `verify`, `dispute`, `feedback`, `field_connect`, `field`, `world`, `world_status`, `test`, `connect`, `intelligence`, `incidents`, `outcomes`, `subscribe` and `query`. The same work as commands:
 
 ```
 npx cortad status
@@ -22,7 +27,7 @@ npx cortad verify <findingId>
 
 `npx cortad wait` returns when the next run ends, with what it found; an agent starts it in the background so the run's end wakes it.
 
-A run needs your app up. If nothing on this machine is holding it, the command starts it with the key in `~/.cortad` and stops it ten minutes after the last run.
+A run needs your app up. If nothing on this machine is holding it, the command starts it with the key and the start command kept in `~/.cortad`, and stops it ten minutes after the last run.
 
 To make checking with Cortad part of the repository:
 
@@ -36,16 +41,18 @@ The hooks run after an edit and on your next message: the first names the prompt
 ## Flags
 
 ```
+-- <command>         how your app starts; everything after -- is run as typed (--start "cmd" says the same)
+--port 3000          use an app that is already running, as it is
+--port 3000 -- <command>   start a container and watch the port it publishes; the model base URL to set inside it is printed
 --explain            show what would be sent and started, then exit
---port 3000          use an app that is already running
---start "make dev"   how your app starts
 --verbose            print your app's output
 ```
 
+Nothing about your environment is guessed or changed. Your app gets this terminal's environment and its own request limits raised for the session, by name; its env files are read only to hide their values in what leaves this machine. Nothing is copied or started beside it: test conversations write where your app writes, after your yes in the browser.
+
 ## Files it creates
 
-- `~/.cortad/<project>/`     the key, the last tree digest, which process holds your app up, your app's output in `app.log`, the run it asked for last, in `news.txt` the line a finished run left for your agent, removed once the agent has it, and in `heard.txt` the ids of the runs your agent has read
-- `~/.cortad/identity.key`   the seed for the session's test accounts
+- `~/.cortad/<project>/`     the key, the start command, the last tree digest, which process holds your app up, your app's output in `app.log`, the sign-in your own request carried, the run it asked for last, in `news.txt` the line a finished run left for your agent, removed once the agent has it, and in `heard.txt` the ids of the runs your agent has read
 - `$TMPDIR/cortad-<pid>/`    removed on exit
 
 macOS and Linux, Node 20 or later. No dependencies. What is sent and what stays on your machine: `npx cortad --explain`, and cortad.com/privacy.

package/lib/auto-reach.mjs

@@ -1,8 +1,9 @@
-// The connect command tests the endpoints the read lists by itself, as soon as status lists them:
-// no agent, no headers from anyone. Each endpoint is sent once per connection, and again only when
-// the file it is written in changes or the agent asks with `reach`. The agent's ask reaches this
-// process through two files beside the runner record, since the identities this machine signed in
-// live here and nowhere else.
+// The agent's `reach`, sent by the connect command: one request to each endpoint the ask names, or to
+// every endpoint status lists as not reached, from this machine to the app on its port. The ask
+// reaches this process through two files beside the runner record, since the sign-in the person's own
+// request carried lives here and nowhere else. A round with no ask sends each due endpoint once and
+// again only when its file changes; the connect command runs none, so nothing reaches the app on
+// Cortad's own account.
 import { existsSync, readdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { notUp, picked, reachText, REACH_MS, sendOurs, testedLine } from "./reach.mjs";

package/lib/cli.mjs

@@ -25,7 +25,7 @@ const WAITER = "run-when-up";
 // How long `run` and `verify` wait for an app started again for a change. An MCP call is cut at
 // about 60 seconds by Codex, Cursor CLI and Copilot CLI; a shell command is not.
 const RESTART_MS = { mcp: 45_000, shell: 150_000 };
-export const VERBS = ["status", "reach", "run", "run_status", "findings", "verify", "dispute", "feedback", "field_connect", "field"];
+export const VERBS = ["status", "reach", "run", "run_status", "findings", "verify", "dispute", "feedback", "field_connect", "field", "world", "world_status", "test"];
 export const COMMANDS = new Set(["mcp", ...VERBS, "wait", "news", "run-status", "field-connect", "stick", "unstick", WAITER]);
 // A lowercase word this version has no command for, so it is never read as a connect code.
 export const unknownVerb = (word) => /^[a-z][a-z_]*$/.test(word ?? "") && !COMMANDS.has(word);
@@ -161,6 +161,9 @@ export function argsOf(command, rest) {
       return { about: words[0], kind: words[1], needed: words.slice(2).join(" "), ...(got ? { got } : {}), ...(tried ? { tried } : {}) };
     }
     case "field": return rest[0] ? { days: rest[0] } : {};
+    case "world": return rest.length ? { ask: rest.join(" ") } : {};
+    case "test": return rest.length ? { ask: rest.join(" ") } : {};
+    case "world_status": return rest[0] ? { jobId: rest[0] } : {};
     case "reach": {
       const paths = rest.filter((w) => w.startsWith("/"));
       return paths.length ? { paths } : {};

package/lib/commits.mjs

@@ -0,0 +1,202 @@
+import { execFileSync } from "node:child_process";
+
+// Their commit history, read here and sent after the code: every commit since the newest one Cortad
+// holds, the whole history the first time, oldest first, each with its message, author, dates, the
+// paths it moved and a diff cut to the files this program would upload anyway, with any line that
+// carries a key replaced before it leaves. One connect sends up to a budget; a longer history goes
+// on at the next connect from where this one stopped. Git never reaches the network for this: lazy
+// fetching is off and every call has a time limit, so a blobless clone sends messages alone.
+
+export const LIMITS = {
+  // Bytes of history one connect sends; the newer commits past it follow at the next connect.
+  budget: 64_000_000,
+  // Commits whose diffs one git call reads.
+  window: 200,
+  // A diff larger than this, after filtering, is reported by size and not sent.
+  diffBytes: 256_000,
+  // One request to the server, under its limits.
+  partBytes: 1_500_000,
+  partCommits: 500,
+  messageChars: 4000,
+  paths: 2000,
+};
+
+const SHA = /^[0-9a-f]{40}$/;
+const HEADER = /[0-9a-f]{40}\x1f/;
+const FORMAT = "--format=%H%x1f%P%x1f%an%x1f%ae%x1f%aI%x1f%cI%x1f%B%x1e";
+// GIT_NO_LAZY_FETCH is read by git 2.44 and later; the time limit covers the rest.
+const ENV = { ...process.env, GIT_NO_LAZY_FETCH: "1", GIT_OPTIONAL_LOCKS: "0", GIT_TERMINAL_PROMPT: "0" };
+
+const git = (root, args, timeout = 30_000) =>
+  execFileSync("git", ["-C", root, ...args], { env: ENV, stdio: ["ignore", "pipe", "ignore"], maxBuffer: 256 * 1024 * 1024, timeout }).toString("utf8");
+
+export function headOf(root) {
+  try { const sha = git(root, ["rev-parse", "HEAD"]).trim(); return SHA.test(sha) ? sha : null; } catch { return null; }
+}
+
+// Everything after `since` while it is still behind HEAD; the whole history when nothing is held or
+// history was rewritten under it.
+export function rangeOf(root, since) {
+  if (since && SHA.test(since)) {
+    try { git(root, ["merge-base", "--is-ancestor", since, "HEAD"]); return `${since}..HEAD`; } catch { /* unknown here, or rewritten */ }
+  }
+  return "HEAD";
+}
+
+// A rename as numstat writes it, read as the path it ended at: "{a => b}/x", "a => b".
+export const renamedTo = (path) => path.replace(/\{([^{}]*) => ([^{}]*)\}/g, "$2").replace(/^[^{]* => /, "").replace(/\/{2,}/g, "/");
+
+function statsOf(text) {
+  const changed = [];
+  for (const line of text.split("\n")) {
+    const m = /^(\d+|-)\t(\d+|-)\t(.+)$/.exec(line);
+    if (m) changed.push({ path: renamedTo(m[3]), added: m[1] === "-" ? null : Number(m[1]), deleted: m[2] === "-" ? null : Number(m[2]) });
+  }
+  return changed;
+}
+
+// The commits of a range, oldest first, each with the paths it moved that `keep` allows; the rest
+// are counted as hidden. One git call for everything; when the stats cannot be read without the
+// network, the commits are sent without them.
+export function listCommits(root, range, { keep }) {
+  let out;
+  let withStats = true;
+  try { out = git(root, ["log", FORMAT, "--numstat", "-M", range], 120_000); } catch {
+    withStats = false;
+    try { out = git(root, ["log", FORMAT, range], 120_000); } catch { return { commits: [], withStats: false }; }
+  }
+  const segments = out.split("\x1e");
+  const commits = [];
+  let header = segments[0] ?? "";
+  for (let i = 1; i <= segments.length; i += 1) {
+    const rest = segments[i] ?? "";
+    const at = rest.search(HEADER);
+    const stats = at < 0 ? rest : rest.slice(0, at);
+    const [sha, parents = "", name = "", email = "", authoredAt = "", committedAt = "", ...body] = header.replace(/^\n+/, "").split("\x1f");
+    if (SHA.test(sha ?? "")) {
+      const all = statsOf(stats);
+      const shown = all.filter((c) => keep(c.path));
+      commits.push({
+        sha,
+        parents: parents.split(" ").filter((p) => SHA.test(p)),
+        author: { name: name.slice(0, 200), email: email.slice(0, 320) },
+        authoredAt, committedAt,
+        message: body.join("\x1f").trimEnd().slice(0, LIMITS.messageChars),
+        stats: { files: all.length, insertions: all.reduce((n, c) => n + (c.added ?? 0), 0), deletions: all.reduce((n, c) => n + (c.deleted ?? 0), 0) },
+        changed: shown.slice(0, LIMITS.paths),
+        hidden: all.length - shown.length,
+        stripped: 0,
+      });
+    }
+    if (at < 0) break;
+    header = rest.slice(at);
+  }
+  commits.reverse();
+  return { commits, withStats };
+}
+
+// git writes a path with unusual characters C-quoted; a plain one as it is.
+const unquote = (path) => (path.startsWith('"') && path.endsWith('"') ? JSON.parse(path) : path);
+
+// The two paths of one file's diff: before and after. A rename with no edit has only the rename lines.
+function pathsOf(file) {
+  const line = (re) => { const m = re.exec(file); return m ? unquote(m[1]) : null; };
+  const head = /^diff --git a\/(.*) b\/(.*)$/m.exec(file);
+  const a = line(/^--- a\/(.*)$/m) ?? line(/^rename from (.*)$/m) ?? line(/^copy from (.*)$/m) ?? (head ? unquote(head[1]) : null);
+  const b = line(/^\+\+\+ b\/(.*)$/m) ?? line(/^rename to (.*)$/m) ?? line(/^copy to (.*)$/m) ?? (head ? unquote(head[2]) : null);
+  return { a, b };
+}
+
+const HELD = "[line held back on this machine: it carries a key]";
+
+// A patch cut to the files `keep` allows, every added or removed line that carries a key replaced.
+// A patch that grows past the limit is given up at that point: `over` says so, and no line of it
+// is read for keys, since the key detector works line by line and a generated file's one long
+// line would cost minutes.
+export function filterDiff(patch, keep, holdsKey, limit = LIMITS.diffBytes) {
+  let stripped = 0;
+  let bytes = 0;
+  const kept = [];
+  for (const file of patch.split(/^(?=diff --git )/m)) {
+    if (!file.startsWith("diff --git ")) continue;
+    const { a, b } = pathsOf(file);
+    if (!a || !b || !keep(a) || !keep(b)) continue;
+    bytes += Buffer.byteLength(file);
+    if (bytes > limit) return { diff: "", stripped: 0, over: true, bytes: Buffer.byteLength(patch) };
+    kept.push(file.split("\n").map((line) => {
+      const sign = line[0];
+      if ((sign === "+" || sign === "-") && !/^(\+\+\+|---) /.test(line) && holdsKey(line.slice(1))) { stripped += 1; return sign + HELD; }
+      return line;
+    }).join("\n"));
+  }
+  const diff = kept.join("");
+  return { diff, stripped, over: false, bytes: Buffer.byteLength(diff) };
+}
+
+// These commits' diffs in one git call, by sha. A diff over the limit is reported by size and not
+// carried. A merge carries none, as in git log.
+export function diffsOf(root, shas, { keep, holdsKey }) {
+  const diffs = new Map();
+  if (!shas.length) return diffs;
+  let out;
+  try { out = git(root, ["log", "--no-walk=unsorted", "-p", "--no-color", "--no-ext-diff", "-M", "--format=%x1eCOMMIT %H", ...shas]); } catch { return diffs; }
+  for (const chunk of out.split("\x1eCOMMIT ")) {
+    const sha = chunk.slice(0, 40);
+    if (!SHA.test(sha)) continue;
+    const { diff, stripped, over, bytes } = filterDiff(chunk.slice(41), keep, holdsKey);
+    diffs.set(sha, over || !diff ? { bytes, stripped } : { bytes, stripped, diff });
+  }
+  return diffs;
+}
+
+// A remote address with any credential removed; an scp-like address carries none.
+export function safeRemote(url) {
+  if (!url) return null;
+  try { const u = new URL(url); return `${u.protocol}//${u.host}${u.pathname}`.slice(0, 300); } catch { return /^[\w.-]+@[\w.-]+:/.test(url) ? url.slice(0, 300) : null; }
+}
+
+// What the repository is: where it pushes, which branch, how many have written to it, when it began.
+export function repoFacts(root) {
+  const read = (args, f = (s) => s.trim()) => { try { return f(git(root, args)); } catch { return null; } };
+  const facts = {
+    remote: safeRemote(read(["config", "--get", "remote.origin.url"])),
+    branch: read(["rev-parse", "--abbrev-ref", "HEAD"], (s) => s.trim().slice(0, 200)),
+    contributors: read(["log", "-5000", "--format=%ae"], (s) => new Set(s.split("\n").filter(Boolean)).size),
+    firstCommitAt: read(["log", "--format=%cI"], (s) => s.trim().split("\n").at(-1) || null),
+  };
+  return Object.fromEntries(Object.entries(facts).filter(([, v]) => v !== null && v !== undefined));
+}
+
+// The commits to send, oldest first, each with its diff, up to this connect's budget, cut into
+// parts under the server's limits.
+export function historyParts(root, since, { keep, holdsKey }) {
+  const { commits } = listCommits(root, rangeOf(root, since), { keep });
+  const sent = [];
+  let spent = 0;
+  for (let i = 0; i < commits.length && spent < LIMITS.budget; i += LIMITS.window) {
+    const window = commits.slice(i, i + LIMITS.window);
+    const diffs = diffsOf(root, window.map((c) => c.sha), { keep, holdsKey });
+    for (const c of window) {
+      const held = diffs.get(c.sha);
+      if (held) {
+        c.stripped = held.stripped;
+        c.diffBytes = held.bytes;
+        if (held.diff) c.diff = held.diff;
+      }
+      spent += JSON.stringify(c).length;
+      if (spent > LIMITS.budget) break;
+      sent.push(c);
+    }
+  }
+  const parts = [];
+  let part = [];
+  let bytes = 0;
+  for (const c of sent) {
+    const size = JSON.stringify(c).length;
+    if (part.length && (bytes + size > LIMITS.partBytes || part.length === LIMITS.partCommits)) { parts.push(part); part = []; bytes = 0; }
+    part.push(c);
+    bytes += size;
+  }
+  if (part.length) parts.push(part);
+  return parts;
+}

package/lib/contact-text.mjs

@@ -125,11 +125,10 @@ function unreachedLine(m) {
   return `  ${m.method} ${m.path}${m.file ? `  ${at(m.file, m.line)}` : ""}${said ? `  ${said}` : ""}`;
 }
 
-// Cortad sends the rest itself, said only where the server has a request ready for one of them.
+// The agent sends each one message, or asks Cortad to send the request it read where there is one.
 function reachLine(missing) {
-  if (!missing.some((m) => m.request && !m.unsure)) return null;
-  const except = [missing.some((m) => m.unsure || m.byHand) && "marked by hand", missing.some((m) => m.excluded) && "left out of runs"].filter(Boolean);
-  return `Cortad sends each of them a test request${except.length ? `, except any ${except.join(" or ")}` : ""}.`;
+  const ready = missing.filter((m) => m.request && !m.unsure && !m.excluded);
+  return `Send each one message as a user would, signed in where your app needs it${ready.length ? `, or call reach to send the request Cortad read for ${ready.length === missing.length ? "them" : `${num(ready.length)} of them`}` : ""}.`;
 }
 
 // `data`: what the command did with the app's stores and services, said right under the run it is

package/lib/env-files.mjs

@@ -0,0 +1,39 @@
+// 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;
+}

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/files.mjs

@@ -0,0 +1,5 @@
+// Which of the repository's files are code, and which are tests: where a problem is placed at its
+// line (lib/replay.mjs), and which files count as the app a run plays (lib/fresh.mjs).
+export const CODE = /\.(?:[cm]?[jt]sx?|py|rb|go|php)$/;
+// A test opens its own scratch file; that is not where the app keeps its data.
+export const TEST = /(?:^|\/)(?:tests?|__tests__|spec|e2e|fixtures?)\/|[._-](?:test|spec)\.[^/]+$|(?:^|\/)(?:test_[^/]+|conftest)\.py$/;

package/lib/fresh.mjs

@@ -7,7 +7,7 @@
 import { createHash } from "node:crypto";
 import { readFileSync, statSync } from "node:fs";
 import { join } from "node:path";
-import { TEST } from "./data.mjs";
+import { TEST } from "./files.mjs";
 import { homeOf, readApp } from "./home.mjs";
 import { readRunner } from "./runner.mjs";
 import { writesDirOf, writtenPaths } from "./writes.mjs";

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/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 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. 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. You connect the app with its own start command after `--`, then send each AI endpoint one message as a user would; Cortad learns the endpoint from that request. 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,14 +19,14 @@ 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, 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.",
+  { name: "reach", title: "Send a request Cortad read to an endpoint",
+    description: "Sends the request Cortad read for an endpoint, to the ones status lists as failed or not yet answered, or to the paths named, from this machine to the app on its port, signed in as your own request was where one was seen. Each endpoint comes back with its HTTP status, its time and, when it is not 2xx, the start of what the app answered. A message you send the app yourself does the same.",
     inputSchema: { type: "object", properties: {
       paths: { type: "array", items: { type: "string" }, description: "Only these endpoints, by path. Default: every endpoint status lists as failed or not yet answered." },
     }, additionalProperties: false } },
@@ -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));