cortad 0.1.14 → 0.2.0

package/README.md

@@ -1,19 +1,33 @@
 # cortad
 
-Connects the AI app on your machine to Cortad, so Cortad can run test conversations against it.
+Connects the AI app on your machine to Cortad, so Cortad can run test conversations against it, and gives your coding agent the tools to run them.
 
 ```
 npx cortad <code>
 ```
 
-Run it in your app's folder with the code from cortad.com. Nothing is installed. Ctrl-C disconnects.
+Run it in your app's folder with the code from cortad.com. Nothing is installed in your project. Ctrl-C disconnects.
 
 ## What it does
 
 - Starts your app with its dev script, or uses it if it is already running.
 - Sends Cortad's test conversations to your app on localhost and returns the replies.
 - Signs in as a test account when your app needs one: an account made for the session, never an existing user and never an admin.
-- Lets the Cortad agent edit files in your project. Every edit can be undone from the browser. Git is left alone.
+- Makes Cortad known to the coding agents on this machine (Claude Code, Codex, Cursor): an MCP entry and a skill in each one's own home folder, so `npx cortad mcp` answers them from then on. Nothing is written into your repository.
+- Never writes your files. The agent that edits your code is your own.
+
+## For your coding agent
+
+After the first connect, your agent has eight tools: `status`, `run`, `run_status`, `findings`, `verify`, `dispute`, `field_connect`, `field`. The same eight work as shell commands:
+
+```
+npx cortad status
+npx cortad run
+npx cortad findings
+npx cortad verify <findingId>
+```
+
+A run needs your app up. When nothing on this machine is holding it, the command starts it with the key the first connect left in `~/.cortad`, and leaves when no run has needed it for ten minutes.
 
 ## What Cortad receives
 
@@ -24,10 +38,11 @@ Run it in your app's folder with the code from cortad.com. Nothing is installed.
 
 - Your env files and their values.
 - Tokens and cookies. A signed-in test request gets its token added here.
+- The key in `~/.cortad/<project>/token` (readable by you only). It starts runs and reads findings for this one repository and nothing else; revoke it from your account page.
 
-## The agent's shell
+## The test shell
 
-Commands the agent runs are confined by the operating system (Seatbelt on macOS, bubblewrap on Linux). They can read your project and your toolchains, write only to temp and build folders, and reach only localhost.
+Commands a run needs on this machine (your own test suite, a WebSocket door) are confined by the operating system (Seatbelt on macOS, bubblewrap on Linux). They can read your project and your toolchains, write only to temp and build folders, and reach only localhost.
 
 ## Loaded into your app
 
@@ -44,7 +59,8 @@ When cortad starts your app it preloads one short file, `lib/trace.cjs` for Node
 
 ## Files it creates
 
-- `~/.cortad/checkpoints/`  undo data for agent edits
-- `$TMPDIR/cortad-<pid>/`   removed on exit
+- `~/.cortad/<project>/`     the key, the last tree digest, which process holds your app up
+- `~/.cortad/identity.key`   the seed for the session's test accounts
+- `$TMPDIR/cortad-<pid>/`    removed on exit
 
 macOS and Linux, Node 20+. No dependencies, no install scripts.

package/lib/cli.mjs

@@ -0,0 +1,87 @@
+import { openSync, readFileSync } from "node:fs";
+import { spawn } from "node:child_process";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { homeOf, projectOf, readRunner, readToken, writeRunner } from "./home.mjs";
+import { serveMcp } from "./mcp.mjs";
+import { makeVerbs } from "./verbs.mjs";
+
+// `npx cortad mcp` and `npx cortad <verb>`: the two faces a coding agent uses after the first
+// connect. Neither uploads, starts or edits anything by itself. When a run needs the app up and
+// nothing on this machine is holding it, the runner (local.mjs with the stored key) is started.
+const LOCAL = join(dirname(fileURLToPath(import.meta.url)), "..", "local.mjs");
+const VERSION = JSON.parse(readFileSync(join(dirname(fileURLToPath(import.meta.url)), "..", "package.json"), "utf8")).version;
+const OURS = ["cortad.com", "brainsless.com", "brainsless-frontend.pages.dev"];
+export const VERBS = ["status", "run", "run_status", "findings", "verify", "dispute", "field_connect", "field"];
+export const COMMANDS = new Set(["mcp", ...VERBS, "run-status", "field-connect"]);
+
+export async function main(argv, { root = process.cwd(), env = process.env, stdout = process.stdout, stderr = process.stderr } = {}) {
+  const origin = new URL(env.CORTAD_ORIGIN || "https://cortad.com");
+  const trusted = (origin.protocol === "https:" && OURS.some((host) => origin.hostname === host || origin.hostname.endsWith(`.${host}`)))
+    || origin.hostname === "localhost" || origin.hostname === "127.0.0.1";
+  if (!trusted) { stderr.write(`cortad  refusing: ${origin.host} is not Cortad.\n`); return 1; }
+  const api = `${origin.origin}/api`;
+  const project = projectOf(root);
+  const token = readToken(project);
+  const [command, ...rest] = argv;
+  const mcp = command === "mcp";
+  const children = [];
+  const verbs = makeVerbs({ api, token, ensureRunner: () => ensureRunner({ root, project, env, keep: mcp, children, say: (line) => stderr.write(`cortad  ${line}\n`) }) });
+
+  if (mcp) {
+    const code = await serveMcp({ verbs, version: VERSION, log: (line) => stderr.write(`${line}\n`) });
+    for (const child of children) try { child.kill("SIGTERM"); } catch { /* gone */ }
+    return code;
+  }
+  const verb = verbs[command.replace(/-/g, "_")];
+  const out = await verb(argsOf(command, rest));
+  stdout.write(`${out.text}\n`);
+  return out.isError ? 1 : 0;
+}
+
+// Positional arguments for the shell face: `verify f1`, `run_status <jobId>`, `dispute f1 "why"`.
+function argsOf(command, rest) {
+  switch (command.replace(/-/g, "_")) {
+    case "run_status": return { jobId: rest[0] };
+    case "findings": return rest[0] ? { jobId: rest[0] } : {};
+    case "verify": return { findingId: rest[0], ...(rest[1] ? { jobId: rest[1] } : {}) };
+    case "dispute": return { findingId: rest[0], why: rest.slice(1).join(" ") };
+    case "field": return rest[0] ? { days: rest[0] } : {};
+    default: return {};
+  }
+}
+
+// The app has to be up on this machine for a run. A connect session in another terminal is holding
+// it; failing that, local.mjs is started here with the stored key and does what the first connect
+// did: attach, upload if the tree changed, start the app, announce it, answer the knocks. From the
+// MCP it lives as long as the MCP does; from a shell command it stays until the runs stop for a
+// while, then leaves (--until-idle).
+const READY_MS = 240_000;
+export async function ensureRunner({ root, project, env, keep, children, say, poll = statusOf }) {
+  if (!readRunner(project)) {
+    const log = openSync(join(homeOf(project), "runner.log"), "a");
+    const child = spawn(process.execPath, [LOCAL, "--token", ...(keep ? [] : ["--until-idle"])], {
+      cwd: root, env, stdio: ["ignore", log, log], detached: !keep,
+    });
+    if (!keep) child.unref(); else children.push(child);
+    writeRunner(project, { pid: child.pid, startedAt: new Date().toISOString(), by: keep ? "mcp" : "cli" });
+    say("starting your app for the run");
+  }
+  const until = Date.now() + READY_MS;
+  while (Date.now() < until) {
+    await new Promise((r) => setTimeout(r, 3000));
+    const state = await poll(env, project);
+    if (state === "ready-to-test") return { ok: true };
+    if (!readRunner(project)) return { ok: false, why: `Your app did not come up. The runner's output is in ${join(homeOf(project), "runner.log")}.` };
+  }
+  return { ok: false, why: "Your app did not come up within four minutes. Run the command from the connect screen in a terminal to see why." };
+}
+
+async function statusOf(env, project) {
+  const token = readToken(project);
+  if (!token) return null;
+  try {
+    const res = await fetch(`${new URL(env.CORTAD_ORIGIN || "https://cortad.com").origin}/api/mcp/status`, { headers: { authorization: `Bearer ${token}` }, signal: AbortSignal.timeout(15_000) });
+    return res.ok ? (await res.json()).app?.state ?? null : null;
+  } catch { return null; }
+}

package/lib/home.mjs

@@ -0,0 +1,34 @@
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, realpathSync, rmSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+// What this machine keeps between sessions, per project, under ~/.cortad/<project>/: the key the
+// first connect left behind, the digest of the tree last uploaded, and which process is holding the
+// app up. The folder's path never leaves the machine; the project is a hash of it.
+export const projectOf = (root) => createHash("sha256").update(realpathSync(root)).digest("hex").slice(0, 16);
+export const homeOf = (project, base = join(homedir(), ".cortad")) => join(base, project);
+
+const read = (file) => { try { return readFileSync(file, "utf8").trim() || null; } catch { return null; } };
+const write = (dir, name, text) => { mkdirSync(dir, { recursive: true, mode: 0o700 }); writeFileSync(join(dir, name), text, { mode: 0o600 }); };
+
+export const readToken = (project, base) => read(join(homeOf(project, base), "token"));
+export const writeToken = (project, token, base) => write(homeOf(project, base), "token", token);
+
+export const readDigest = (project, base) => read(join(homeOf(project, base), "digest"));
+export const writeDigest = (project, digest, base) => write(homeOf(project, base), "digest", digest);
+
+// The process holding this project's app up for runs, if one is alive. A pid that no longer answers
+// is a stale file, not a runner.
+export function readRunner(project, base) {
+  const raw = read(join(homeOf(project, base), "runner.json"));
+  if (!raw) return null;
+  let runner;
+  try { runner = JSON.parse(raw); } catch { return null; }
+  if (!Number.isInteger(runner?.pid)) return null;
+  try { process.kill(runner.pid, 0); return runner; } catch { return null; }
+}
+export const writeRunner = (project, runner, base) => write(homeOf(project, base), "runner.json", JSON.stringify(runner));
+export const clearRunner = (project, base) => { try { rmSync(join(homeOf(project, base), "runner.json")); } catch { /* gone */ } };
+
+export const hasHome = (base = join(homedir(), ".cortad")) => existsSync(base);

package/lib/mcp.mjs

@@ -0,0 +1,80 @@
+// The MCP face: newline-delimited JSON-RPC 2.0 on stdin and stdout, protocol 2025-06-18, no
+// dependency. stdout carries protocol messages and nothing else; everything a person might read
+// goes to stderr. The tools are lib/verbs.mjs, one to one.
+
+export const PROTOCOL = "2025-06-18";
+
+export const INSTRUCTIONS = [
+  "Cortad is an independent behavior test lab for the AI app in this repository. It runs simulated users through the app on this machine and grades every reply with about 100 checks. It is already connected; never run `npx cortad <code>` again.",
+  "The loop: status, then run only when the person asks (the first run is free; after that run returns a checkout link, show it in one sentence and wait), poll run_status every 30 seconds and stay quiet unless the count moved, findings, fix one finding at a time in the repo, verify <id>, read the move.",
+  "Rules: a move inside the interval is not a fix. Never change or remove a case to move a number; never make the app recognise test traffic; if a check reads wrong, call dispute with why. Cases, checks, seeds and the holdout are not yours to edit, and Cortad refuses it anyway.",
+].join("\n\n");
+
+const str = (description, extra = {}) => ({ type: "string", description, ...extra });
+
+export const TOOLS = [
+  { name: "status", description: "Where this repository stands with Cortad: plan and runs left, whether the app is up, conversations written, the latest run, whether production is connected. Call first.", inputSchema: { type: "object", properties: {}, additionalProperties: false } },
+  { name: "run", description: "Run the whole suite of simulated conversations against the app on this machine. Only when the person asks. The first run is free; afterwards it returns a checkout link to show the person. Starts the app if it is not up.", inputSchema: { type: "object", properties: {}, additionalProperties: false } },
+  { name: "run_status", description: "Where a run or verify stands: played n of N, the score when finished, the paired move for a verify. Poll every 30 seconds.", inputSchema: { type: "object", properties: { jobId: str("The id run or verify returned.") }, required: ["jobId"], additionalProperties: false } },
+  { name: "findings", description: "The failures of the latest run: each with its rate and interval, a quote, the file and line, what good looks like. Start from the worst.", inputSchema: { type: "object", properties: { jobId: str("A run id. Omit for the latest.") }, additionalProperties: false } },
+  { name: "verify", description: "After a fix: replay one finding's trials with the same seeds and read the move, visible and held-out apart. Spends verify trials, not a run.", inputSchema: { type: "object", properties: { findingId: str("The finding id from findings."), jobId: str("The run the finding came from. Omit for the latest.") }, required: ["findingId"], additionalProperties: false } },
+  { name: "dispute", description: "Say that a finding's check reads wrong. Changes nothing; the note goes to the owner.", inputSchema: { type: "object", properties: { findingId: str("The finding id."), why: str("One or two sentences: what the check gets wrong about this app.", { maxLength: 500 }), question: str("The wording you would ask instead.", { maxLength: 300 }) }, required: ["findingId", "why"], additionalProperties: false } },
+  { name: "field_connect", description: "How to connect production so real conversations are read with the same checks. Returns the steps; the key is created by the owner in the browser, never here.", inputSchema: { type: "object", properties: {}, additionalProperties: false } },
+  { name: "field", description: "Production in numbers only: conversations read, rulings held, resolved, frustrated, asks for a human, the rules broken most. Never message text.", inputSchema: { type: "object", properties: { days: { type: "integer", minimum: 1, maximum: 180, description: "Window in days. Default 30." } }, additionalProperties: false } },
+];
+
+const error = (id, code, message) => ({ jsonrpc: "2.0", id, error: { code, message } });
+const result = (id, value) => ({ jsonrpc: "2.0", id, result: value });
+
+// Serves until stdin closes. `verbs` is lib/verbs.mjs's object; `version` is the package's.
+export function serveMcp({ verbs, version, input = process.stdin, output = process.stdout, log = () => {} }) {
+  return new Promise((resolve) => {
+    const send = (msg) => output.write(`${JSON.stringify(msg)}\n`);
+    let buffer = "";
+    input.setEncoding("utf8");
+    input.on("data", (chunk) => {
+      buffer += chunk;
+      let at;
+      while ((at = buffer.indexOf("\n")) >= 0) {
+        const line = buffer.slice(0, at).trim();
+        buffer = buffer.slice(at + 1);
+        if (line) void handle(line);
+      }
+    });
+    input.on("end", () => resolve(0));
+    input.on("close", () => resolve(0));
+
+    async function handle(line) {
+      let msg;
+      try { msg = JSON.parse(line); } catch { send(error(null, -32700, "parse error")); return; }
+      if (!msg || typeof msg !== "object" || Array.isArray(msg)) { send(error(null, -32600, "invalid request")); return; }
+      const { id, method, params } = msg;
+      const notification = id === undefined || id === null;
+      try {
+        switch (method) {
+          case "initialize":
+            return send(result(id, { protocolVersion: PROTOCOL, capabilities: { tools: {} }, serverInfo: { name: "cortad", version }, instructions: INSTRUCTIONS }));
+          case "notifications/initialized":
+          case "notifications/cancelled":
+            return;
+          case "ping":
+            return send(result(id, {}));
+          case "tools/list":
+            return send(result(id, { tools: TOOLS }));
+          case "tools/call": {
+            const name = params?.name;
+            const verb = Object.hasOwn(verbs, name) ? verbs[name] : null;
+            if (!verb) return send(result(id, { content: [{ type: "text", text: `No tool ${String(name)}.` }], isError: true }));
+            const out = await verb(params?.arguments ?? {});
+            return send(result(id, { content: [{ type: "text", text: out.text }], ...(out.isError ? { isError: true } : {}) }));
+          }
+          default:
+            if (!notification) send(error(id, -32601, `method not found: ${String(method)}`));
+        }
+      } catch (err) {
+        log(`mcp ${method}: ${err?.stack ?? err}`);
+        if (!notification) send(result(id, { content: [{ type: "text", text: `Cortad could not answer: ${String(err?.message ?? err)}` }], isError: true }));
+      }
+    }
+  });
+}

package/lib/register.mjs

@@ -0,0 +1,91 @@
+import { execFile } from "node:child_process";
+import { copyFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { delimiter, dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { promisify } from "node:util";
+
+// Making Cortad known to the coding agents on this machine: an MCP entry in each client that is
+// here, and the skill that teaches the loop. Nothing is written into the repository; everything
+// lands in the client's own home folders, the way the client's own `add` command would put it.
+// Idempotent: run twice, it adds nothing twice.
+const exec = promisify(execFile);
+const SERVER = { command: "npx", args: ["-y", "cortad@latest", "mcp"] };
+const SKILL_SRC = join(dirname(fileURLToPath(import.meta.url)), "..", "skill");
+
+export const onPath = (bin, env = process.env) =>
+  (env.PATH ?? "").split(delimiter).some((dir) => dir && existsSync(join(dir, bin)));
+
+export function detectClients({ home = homedir(), env = process.env } = {}) {
+  return {
+    claude: onPath("claude", env) || existsSync(join(home, ".claude")),
+    codex: onPath("codex", env) || existsSync(join(home, ".codex")),
+    cursor: existsSync(join(home, ".cursor")),
+  };
+}
+
+// Returns the names of the clients that now know Cortad, for the one line the command prints.
+export async function registerAll({ home = homedir(), env = process.env, run = exec, skillSrc = SKILL_SRC } = {}) {
+  const found = detectClients({ home, env });
+  const added = [];
+  if (found.claude) {
+    await registerClaude({ home, env, run });
+    installSkill(join(home, ".claude", "skills", "cortad"), skillSrc);
+    added.push("Claude Code");
+  }
+  if (found.codex) {
+    await registerCodex({ home, env, run });
+    installSkill(join(home, ".agents", "skills", "cortad"), skillSrc);
+    added.push("Codex");
+  }
+  if (found.cursor) {
+    registerCursor({ home });
+    added.push("Cursor");
+  }
+  return added;
+}
+
+// The client's own command when it is here, so its config is written the way it writes it; the file
+// itself only when the folder exists without the binary on this PATH.
+async function registerClaude({ home, env, run }) {
+  if (onPath("claude", env)) {
+    try { await run("claude", ["mcp", "add", "--scope", "user", "cortad", "--", SERVER.command, ...SERVER.args], { env }); return; }
+    catch (err) { if (/already exists/i.test(String(err?.stderr ?? err?.message))) return; }
+  }
+  const file = join(home, ".claude.json");
+  const config = readJson(file) ?? {};
+  config.mcpServers = { ...(config.mcpServers ?? {}), cortad: { type: "stdio", ...SERVER } };
+  writeFileSync(file, `${JSON.stringify(config, null, 2)}\n`);
+}
+
+async function registerCodex({ home, env, run }) {
+  if (onPath("codex", env)) {
+    try { await run("codex", ["mcp", "add", "cortad", "--", SERVER.command, ...SERVER.args], { env }); return; }
+    catch (err) { if (/already exists/i.test(String(err?.stderr ?? err?.message))) return; }
+  }
+  const file = join(home, ".codex", "config.toml");
+  const text = existsSync(file) ? readFileSync(file, "utf8") : "";
+  if (/^\[mcp_servers\.cortad\]/m.test(text)) return;
+  mkdirSync(dirname(file), { recursive: true });
+  writeFileSync(file, `${text}${text && !text.endsWith("\n") ? "\n" : ""}\n[mcp_servers.cortad]\ncommand = "${SERVER.command}"\nargs = ${JSON.stringify(SERVER.args)}\n`);
+}
+
+function registerCursor({ home }) {
+  const file = join(home, ".cursor", "mcp.json");
+  const config = readJson(file) ?? {};
+  if (config.mcpServers?.cortad) return;
+  config.mcpServers = { ...(config.mcpServers ?? {}), cortad: { type: "stdio", ...SERVER } };
+  writeFileSync(file, `${JSON.stringify(config, null, 2)}\n`);
+}
+
+// SKILL.md and its references, copied whole so a newer package refreshes the words.
+export function installSkill(dir, src = SKILL_SRC) {
+  mkdirSync(join(dir, "references"), { recursive: true });
+  copyFileSync(join(src, "SKILL.md"), join(dir, "SKILL.md"));
+  copyFileSync(join(src, "references", "results.md"), join(dir, "references", "results.md"));
+}
+
+function readJson(file) {
+  if (!existsSync(file)) return null;
+  try { return JSON.parse(readFileSync(file, "utf8")); } catch { return null; }
+}

package/lib/verbs.mjs

@@ -0,0 +1,149 @@
+// The eight things a coding agent may ask of Cortad, each one call to the API with this machine's
+// key and one rendering as short text. The MCP tools and the `npx cortad <verb>` commands are the
+// same functions, so both faces say the same thing.
+
+const NOT_CONNECTED = "This project is not connected to Cortad yet. Ask the person to open cortad.com, sign in, and run the command the connect screen shows, from this folder.";
+
+export function makeVerbs({ api, token, fetchImpl = fetch, ensureRunner = async () => ({ ok: true }) }) {
+  const call = async (method, path, body) => {
+    if (!token) return { status: 0, ok: false, data: { error: NOT_CONNECTED } };
+    let res;
+    try {
+      res = await fetchImpl(`${api}${path}`, {
+        method,
+        headers: { authorization: `Bearer ${token}`, ...(body === undefined ? {} : { "content-type": "application/json" }) },
+        body: body === undefined ? undefined : JSON.stringify(body),
+        signal: AbortSignal.timeout(60_000),
+      });
+    } catch (err) {
+      return { status: 0, ok: false, data: { error: `could not reach Cortad: ${err?.name === "TimeoutError" ? "it did not answer in time" : "the connection failed"}` } };
+    }
+    const text = await res.text();
+    let data = null;
+    try { data = text ? JSON.parse(text) : null; } catch { data = { error: text.slice(0, 200) }; }
+    return { status: res.status, ok: res.ok, data };
+  };
+  const failed = (res) => ({ text: res.data?.why ?? res.data?.error ?? `Cortad answered ${res.status}.`, data: res.data, isError: true });
+
+  const status = async () => {
+    const res = await call("GET", "/mcp/status");
+    return res.ok ? { text: statusText(res.data), data: res.data } : failed(res);
+  };
+
+  // A run, or a verify when a finding is named. When the app is not up on this machine, the runner
+  // is started first: the process that uploads the tree, starts the app and answers the knocks.
+  const start = async (args, kind) => {
+    const before = await call("GET", "/mcp/status");
+    if (!before.ok) return failed(before);
+    if (before.data.app?.state !== "ready-to-test") {
+      const runner = await ensureRunner(before.data);
+      if (!runner.ok) return { text: runner.why, data: runner, isError: true };
+    }
+    const res = await call("POST", "/mcp/run", args);
+    if (res.status === 202 || (res.ok && res.data?.joined)) return { text: startedText(res.data, kind), data: res.data };
+    if (res.status === 402) return { text: refusedText(res.data), data: res.data, isError: true };
+    return failed(res);
+  };
+  const run = () => start({}, "run");
+  const verify = ({ findingId, jobId }) => start({ findingId, ...(jobId ? { jobId } : {}) }, "verify");
+
+  const runStatus = async ({ jobId }) => {
+    const res = await call("GET", `/mcp/run/${encodeURIComponent(jobId)}`);
+    return res.ok ? { text: runText(res.data), data: res.data } : failed(res);
+  };
+
+  const findings = async ({ jobId } = {}) => {
+    const res = await call("GET", `/mcp/findings${jobId ? `?jobId=${encodeURIComponent(jobId)}` : ""}`);
+    return res.ok ? { text: findingsText(res.data), data: res.data } : failed(res);
+  };
+
+  const dispute = async ({ findingId, why, question, jobId }) => {
+    const res = await call("POST", "/mcp/dispute", { findingId, why, ...(question ? { question } : {}), ...(jobId ? { jobId } : {}) });
+    return res.ok ? { text: res.data.said, data: res.data } : failed(res);
+  };
+
+  const fieldConnect = async () => {
+    const res = await call("POST", "/mcp/field/connect");
+    if (!res.ok) return failed(res);
+    const d = res.data;
+    return { text: [d.connected ? "Production is connected." : "Production is not connected yet.", ...d.steps.map((s, i) => `${i + 1}. ${s}`)].join("\n"), data: d };
+  };
+
+  const field = async ({ days } = {}) => {
+    const res = await call("GET", `/mcp/field${days ? `?days=${Number(days)}` : ""}`);
+    return res.ok ? { text: fieldText(res.data), data: res.data } : failed(res);
+  };
+
+  return { status, run, run_status: runStatus, findings, verify, dispute, field_connect: fieldConnect, field };
+}
+
+const pct = (k, n) => (n ? `${Math.round((100 * k) / n)}%` : "n/a");
+const plural = (n, one, many = `${one}s`) => `${n} ${n === 1 ? one : many}`;
+
+export function statusText(d) {
+  const p = d.plan;
+  const lines = [
+    `Cortad · ${d.repository.name} · ${p.name}: ${p.runs.left} of ${plural(p.runs.allowed, "run")} left this month, ${p.trials.left} of ${p.trials.allowed} verify trials.`,
+    `App: ${d.app.said}`,
+    `Conversations written: ${d.cases.written}.${d.cases.ready ? " A run can start." : ""}`,
+  ];
+  lines.push(d.run ? `Latest ${runText(d.run)}` : "No run yet.");
+  lines.push(d.field.connected ? "Production: connected." : `Production: not connected. field_connect says how.`);
+  return lines.join("\n");
+}
+
+export function startedText(d, kind) {
+  if (d.joined) return `A ${d.kind ?? kind} is already in flight: ${d.jobId}. Poll run_status every 30 seconds. Watch it: ${d.url}`;
+  return `${kind === "verify" ? "Verify" : "Run"} started: ${d.jobId}. Poll run_status every 30 seconds and stay quiet unless the count moved. Watch it: ${d.url}`;
+}
+
+export function refusedText(d) {
+  const plans = (d.plans ?? []).map((p) => `${p.name} ($${p.monthlyUsd}/month)`).join(" or ");
+  if (d.refused === "plan") return `The first run was free. Another needs ${plans || "a plan"}: ${d.checkout}\nShow this link to the person in one sentence and wait for them.`;
+  return `${d.why} More on ${plans || "a bigger plan"}: ${d.checkout}\nShow this link to the person and wait.`;
+}
+
+export function runText(d) {
+  const head = `${d.kind} ${d.jobId} ${d.status}: ${d.of ? `played ${d.played} of ${d.of}.` : "starting, nothing played yet."}`;
+  const tail = [];
+  if (d.finished && typeof d.score === "number") tail.push(`Score ${d.score} of 100.`);
+  if (d.finished && typeof d.findings === "number") tail.push(d.findings ? `${plural(d.findings, "finding")}; call findings.` : "No findings stood out.");
+  if (d.error) tail.push(`Error: ${d.error}`);
+  if (d.verify) tail.push(verifyText(d.verify));
+  if (!d.finished) tail.push("Poll again in 30 seconds.");
+  return [head, ...tail, d.url].join(" ");
+}
+
+export function verifyText(v) {
+  const move = v.visible;
+  const line = move
+    ? `${v.file}:${v.line} · held ${move.before.k} of ${move.before.n} before, ${move.after.k} of ${move.after.n} after · move ${move.point} (${move.low} to ${move.high}) · ${move.moved}${move.insideNoise ? ", inside the noise" : ""}.`
+    : "";
+  const held = v.holdout ? ` Held-out situations: ${v.holdout.moved}.` : " Held-out situations: no pair.";
+  return `Verify of ${v.findingId}: ${line}${held}${v.overfit ? " OVERFIT: the visible cases moved and the held-out ones did not." : ""} ${v.said}`;
+}
+
+export function findingsText(d) {
+  if (!d.findings?.length) return [d.why ?? `Run ${d.runId}: no question held worse in one situation than this app does everywhere else.`, d.read, d.heldBack, d.url].filter(Boolean).join(" ");
+  const rows = d.findings.map((f, i) => [
+    `${i + 1}. ${f.id} · ${f.asks}`,
+    `   held ${f.rate.k} of ${f.rate.n} (${pct(f.rate.k, f.rate.n)}, interval ${pct(Math.round(f.rate.lo * f.rate.n), f.rate.n)} to ${pct(Math.round(f.rate.hi * f.rate.n), f.rate.n)}) · ${f.file}:${f.line} · ${f.where}`,
+    ...f.quotes.slice(0, 1).map((q) => `   reply ${q.reply}: "${q.quote}" (p=${q.p.toFixed(2)})`),
+    `   replay: ${plural(f.replay.trials, "trial")} · verify ${f.id}`,
+  ].join("\n"));
+  return [`Run ${d.runId}. ${d.read} ${d.heldBack}`, ...rows, `Fix one finding at a time, in the file it names, then verify it. ${d.url}`].join("\n");
+}
+
+export function fieldText(d) {
+  const t = d.totals;
+  if (!t || !t.n) return `No production conversations read in the last ${d.days} days. ${d.url}`;
+  const lines = [
+    `Production, last ${d.days} days: ${plural(t.n, "conversation")}, ${t.read} read.`,
+    `Rulings held: ${pct(t.rulingsHeld, t.rulings)} of ${t.rulings}${t.rulingsUnsure ? ` (${t.rulingsUnsure} unsure)` : ""}. Resolved ${pct(t.resolved, t.read)}, frustrated ${pct(t.frustrated, t.read)}, asked for a human ${pct(t.wantsHuman, t.read)}, unanswered ${pct(t.unanswered, t.read)}.`,
+  ];
+  const broke = (d.rules ?? []).filter((r) => r.broke > 0).sort((a, b) => b.broke - a.broke).slice(0, 5);
+  if (broke.length) lines.push(`Rules broken most: ${broke.map((r) => `${r.id} (${r.broke})`).join(", ")}.`);
+  if (d.journeys?.length) lines.push(`By journey: ${d.journeys.slice(0, 6).map((j) => `${j.value} ${plural(j.n, "conv")}, ${pct(j.rulingsHeld, j.rulings)} held`).join("; ")}.`);
+  lines.push(d.url);
+  return lines.join("\n");
+}

package/local.mjs

@@ -1,25 +1,28 @@
 #!/usr/bin/env node
-// Brainsless on your own machine. Run from your repository's root with the code the connect
-// screen showed:
+// Cortad on your own machine. Run from your repository's root with the code the connect screen
+// showed:
 //   npx cortad ABCD2345   [--port 3000] [--start "npm run dev"] [--verbose]
 //
 // What it does: signs in with the code, uploads your source files once (never .env, never
 // node_modules) so your code can be read, starts your app the way you start it, then holds one
 // outbound connection open and does what a run asks: a request to your app, a file read, a shell
-// line, an edit. An edit goes through one door (lib/door.mjs) that saves what was there first, so
-// every change can be put back from the browser; the shell is locked by the operating system
-// (lib/lock.mjs) and cannot write your code at all. Nothing here touches git. Your environment
+// line. The shell is locked by the operating system (lib/lock.mjs) and cannot write your code;
+// nothing here writes your files at all. It also makes Cortad known to the coding agents on this
+// machine (lib/register.mjs): an MCP entry and a skill, so `npx cortad mcp` answers them from then
+// on with the key this connect leaves in ~/.cortad. Nothing here touches git. Your environment
 // never leaves this machine. Ctrl-C ends everything.
 
 import { holdsKeys, secretEnvValues } from "./lib/keys.mjs";
 import { spawn, execFile, execFileSync } from "node:child_process";
 import { createHash } from "node:crypto";
 import { appendFileSync, existsSync, mkdirSync, readdirSync, readFileSync, realpathSync, statSync, watch, writeFileSync } from "node:fs";
-import { homedir, tmpdir } from "node:os";
+import { homedir, hostname, tmpdir } from "node:os";
 import { basename, dirname, join, relative, resolve, sep } from "node:path";
 import { createInterface } from "node:readline";
 import { promisify } from "node:util";
-import { openDoor } from "./lib/door.mjs";
+import { COMMANDS, main as face } from "./lib/cli.mjs";
+import { clearRunner, projectOf, readToken, writeDigest, writeRunner, writeToken } from "./lib/home.mjs";
+import { registerAll } from "./lib/register.mjs";
 import { lockHolds, makeLock } from "./lib/lock.mjs";
 import { AS_HEADER, makeIdentities } from "./lib/mint.mjs";
 import { CAPTURED, makeCapture } from "./lib/replay.mjs";
@@ -30,20 +33,27 @@ import { installPlan, missingDependency, startPlan, workspaces } from "./lib/sta
 import { openSwitches } from "./lib/switches.mjs";
 
 const argv = process.argv.slice(2);
+// The two faces a coding agent uses after the first connect (lib/cli.mjs): the MCP server the
+// client starts on every session, and the same verbs as shell commands. Neither runs the connect
+// below, and `npx cortad findings` is a verb, never a code.
+if (COMMANDS.has(argv[0] ?? "")) process.exit(await face(argv));
 const flag = (name) => { const i = argv.indexOf(name); return i >= 0 ? argv[i + 1] : undefined; };
 const verbose = argv.includes("--verbose");
-const code = (argv.find((a) => /^[A-Za-z0-9-]{8,9}$/.test(a) && !a.startsWith("-")) ?? "").toUpperCase().replace(/-/g, "");
+// A code is eight characters from the connect screen's alphabet, which has no I, O, 0 or 1.
+const code = (argv.find((a) => /^[A-HJ-NP-Za-hj-np-z2-9-]{8,9}$/.test(a) && !a.startsWith("-")) ?? "").toUpperCase().replace(/-/g, "");
 const say = (line) => console.log(`cortad  ${line}`);
 const fail = (line) => { console.error(`cortad  ${line}`); process.exit(1); };
 
 const explain = argv.includes("--explain");
+// Started by lib/cli.mjs for a run on a later day: no code, the key the first connect left behind.
+const viaToken = argv.includes("--token");
 // What is happening right now, on one line that rewrites itself. npx spends its own seconds fetching
 // this package before anything here runs, and the first thing we printed used to be after the whole
 // upload: a minute or more of a cursor sitting still, which reads as nothing happening.
 const step = (line) => { if (process.stdout.isTTY) process.stdout.write(`\rcortad  ${line}\x1b[K`); };
 const clearStep = () => { if (process.stdout.isTTY) process.stdout.write("\r\x1b[K"); };
 const stepDone = (line) => { clearStep(); say(line); };
-if (!explain && !/^[A-Z0-9]{8}$/.test(code)) fail("usage: npx cortad <code from the connect screen> [--port N] [--start \"cmd\"]   |   npx cortad --explain");
+if (!explain && !viaToken && !/^[A-Z0-9]{8}$/.test(code)) fail("usage: npx cortad <code from the connect screen> [--port N] [--start \"cmd\"]   |   npx cortad --explain   |   npx cortad status | run | findings | verify <id>");
 // Where Brainsless is. The host is not on the command line: a code cannot point at an impostor.
 const origin = new URL(process.env.CORTAD_ORIGIN || "https://cortad.com");
 // Ours, and only ours. brainsless.com is the same service under its earlier name and stays trusted
@@ -254,10 +264,10 @@ const mask = (text) => { let s = String(text ?? ""); for (const v of secrets) s
 // ---- the wire
 let box = "";
 let key = "";
-async function call(method, path, body, { raw = false, timeoutMs = 60_000 } = {}) {
+async function call(method, path, body, { raw = false, timeoutMs = 60_000, headers = {} } = {}) {
   const res = await fetch(`${api}${path}`, {
     method,
-    headers: { ...(key ? { "x-local-key": key } : {}), "content-type": raw ? "application/octet-stream" : "application/json" },
+    headers: { ...(key ? { "x-local-key": key } : {}), "content-type": raw ? "application/octet-stream" : "application/json", ...headers },
     body: body === undefined ? undefined : raw ? body : JSON.stringify(body),
     signal: AbortSignal.timeout(timeoutMs),
   });
@@ -272,8 +282,6 @@ const work = join(tmpdir(), `cortad-${process.pid}`);
 mkdirSync(work, { recursive: true });
 const bootLog = join(work, "boot.log");
 writeFileSync(bootLog, "");
-// Opened once the server says whose session this is.
-let door = null;
 // Files nobody may read through this program: keys, and git's own internals.
 const SECRET_PATH = /(?:^|\/)(?:\.git|\.ssh|\.gnupg|\.aws|\.npmrc|\.netrc|id_(?:rsa|ed25519|ecdsa)[^/]*|[^/]*\.(?:pem|key|p12|pfx|jks|keystore))(?:\/|$)/;
 // The engine's paths, as this machine has them. Its scratch files live in this program's own
@@ -393,24 +401,18 @@ async function verb(job) {
     }
     case "write": {
       const bytes = Buffer.from(String(b.b64 ?? ""), "base64");
-      // The engine's own scratch file: this program's temp folder, not your code.
+      // The engine's own scratch file: this program's temp folder, never your code. Nothing on this
+      // machine writes your files; the agent that edits them is your own.
       const mine = scratch(b.path);
-      if (mine) {
-        try { mkdirSync(dirname(mine), { recursive: true }); if (b.append) appendFileSync(mine, bytes); else writeFileSync(mine, bytes); return { success: true, stderr: "" }; }
-        catch (e) { return { success: false, stderr: String(e.message) }; }
-      }
-      // Your code: the one door, which saves what was there before anything changes.
-      return door.write(translate(b.path), bytes, { checkpoint: typeof b.checkpoint === "string" && b.checkpoint ? b.checkpoint : "manual", append: b.append === true, exclusive: b.exclusive === true });
+      if (!mine) return { success: false, stderr: "this program does not write your files" };
+      try { mkdirSync(dirname(mine), { recursive: true }); if (b.append) appendFileSync(mine, bytes); else writeFileSync(mine, bytes); return { success: true, stderr: "" }; }
+      catch (e) { return { success: false, stderr: String(e.message) }; }
     }
-    case "changes": return door.changes();
-    case "diff": return door.diff(String(b.path ?? ""));
     case "mint": return identities ? JSON.parse(mask(JSON.stringify(await mintAcross({
       recipes: b.recipes, root, appDir, onPath, appPort: app?.port, portFor: serviceUp,
       mint: (recipes, port, origin) => identities.mint({ ...b, recipes, headers: { ...(b.headers ?? {}), ...(origin ? { origin, referer: `${origin}/` } : {}) } }, port),
       originFor: (port) => originFor(port, envOrigins(envFiles)),
     })))) : { identities: [] };
-    case "restore": return door.restore(String(b.checkpoint ?? ""));
-    case "keep": return door.keep(typeof b.checkpoint === "string" && b.checkpoint ? b.checkpoint : undefined);
     case "restart": return restartApp();
     case "inventory": return inventoryOf(b.probe && typeof b.probe === "object" ? b.probe : {});
     // Your own pages, read here rather than in a world's shell: that shell is sealed away from
@@ -777,8 +779,9 @@ if (explain) {
     `would start     ${flag("--port") ? `nothing: uses your app on port ${flag("--port")}` : plan?.cmd ? `${plan.cmd}   (in ${rel(plan.cwd)})` : plan?.noServer ? "nothing: this repository has no server to run" : "asks you how your app starts"}`,
     `would raise     ${flag("--port") ? "nothing: your app's own request limits stay as they are" : `${Object.keys(liftedLimits(envFiles, files.map((f) => join(root, f)))).join(", ") || "no request limits found"}   (for this session only)`}`,
     `loads into app  lib/trace.cjs (Node, Bun) or lib/pyhook/sitecustomize.py (Python): records the one request during which your app calls a model`,
-    `agent edits     in your files, each with an undo kept in ~/.cortad/checkpoints; git is never touched`,
-    `agent shell     confined by the OS: your project and toolchains only, writes to temp and build folders, localhost only`,
+    `your files      never written by this program; your own coding agent edits them`,
+    `test shell      confined by the OS: your project and toolchains only, writes to temp and build folders, localhost only`,
+    `for your agent  an MCP entry and a skill in each coding agent's own home folder (Claude Code, Codex, Cursor), and a key in ~/.cortad for later runs`,
     ``,
     `first files     ${files.slice(0, 8).join(", ")}${files.length > 8 ? ", ..." : ""}`,
   ].join("\n"));
@@ -798,16 +801,22 @@ if (!files.length) fail("no source files here to read.");
 
 // Which project this is, as a hash of where it lives: the same folder coming back resumes the same
 // connection, and the path itself never leaves this machine.
-const project = createHash("sha256").update(realpathSync(root)).digest("hex").slice(0, 16);
+const project = projectOf(root);
+// The key the last connect left for this project, if any: the token face signs in with it. A connect
+// from the screen always asks for a fresh one, since the code may belong to another account or site.
+const stored = readToken(project);
+if (viaToken && !stored) fail("this project has no stored key. Run the command from the connect screen once.");
 // A network that drops while connecting ends here in a sentence, never a stack trace: running the
 // command again starts a clean connection.
 const unreachable = (err) => fail(`could not reach ${origin.host}: ${err?.name === "TimeoutError" ? "it did not answer in time" : "the connection failed"}. Check your connection and run the command again.`);
-const attach = await call("POST", "/local/attach", { code, name: basename(root), project }).catch(unreachable);
+const attach = await call("POST", "/local/attach", { ...(viaToken ? {} : { code }), name: basename(root), project },
+  viaToken ? { headers: { authorization: `Bearer ${stored}` } } : {}).catch(unreachable);
 if (!attach.ok) fail(attach.data?.error ?? `could not sign in (${attach.status})`);
 box = attach.data.box;
 key = attach.data.key;
-// A server that names no journal gets one for this session alone: never another account's edits.
-door = openDoor(root, { owner: typeof attach.data.journal === "string" && attach.data.journal ? attach.data.journal : box });
+// This process is the one holding the app up for this project: lib/cli.mjs reads the file before
+// starting another.
+writeRunner(project, { pid: process.pid, startedAt: new Date().toISOString(), by: viaToken ? "token" : "connect" });
 
 const list = join(work, "files.txt");
 writeFileSync(list, files.join("\n") + "\n");
@@ -842,12 +851,25 @@ const parts = Math.max(1, Math.ceil(bytes.length / PART));
 for (let off = 0; off < bytes.length; off += PART) {
   const last = off + PART >= bytes.length;
   step(parts > 1 ? `connecting, ${Math.floor(off / PART) + 1} of ${parts}` : "connecting");
-  const put = await call("PUT", `/local/${box}/tree?last=${last ? 1 : 0}${last ? `&digest=${treeDigest}${head ? `&head=${head}` : ""}` : ""}`, bytes.subarray(off, off + PART), { raw: true, timeoutMs: 120_000 }).catch(unreachable);
+  // The last part asks for this machine's key when none is stored yet: minted once the repository
+  // row exists, kept in ~/.cortad for the runs a coding agent asks for on later days.
+  const put = await call("PUT", `/local/${box}/tree?last=${last ? 1 : 0}${last ? `&digest=${treeDigest}${head ? `&head=${head}` : ""}` : ""}`, bytes.subarray(off, off + PART),
+    { raw: true, timeoutMs: 120_000, ...(last && !viaToken ? { headers: { "x-cortad-machine": hostname().slice(0, 80) } } : {}) }).catch(unreachable);
   if (!put.ok) fail(put.data?.error ?? `upload failed (${put.status})`);
-  if (last) resumed = put.data?.resumed === true;
+  if (last) {
+    resumed = put.data?.resumed === true;
+    if (typeof put.data?.machineKey === "string" && put.data.machineKey) writeToken(project, put.data.machineKey);
+    writeDigest(project, treeDigest);
+  }
 }
 // Unchanged code has already been read: coming back says so instead of claiming a second read.
 stepDone(resumed ? "connected · nothing changed since last time" : "connected");
+// The coding agents on this machine learn about Cortad now, once: an MCP entry and a skill in each
+// one's own home folder. A run started by an agent later comes back through lib/cli.mjs.
+if (!viaToken) {
+  const added = await registerAll().catch((err) => { if (verbose) say(`could not register with your coding agents: ${err?.message ?? err}`); return []; });
+  if (added.length) say(`added to ${added.join(", ")} · ask ${added.length === 1 ? "it" : "them"} for cortad any time`);
+}
 
 lock = await makeLock({ root, work });
 if (lock && !lockHolds(lock, root)) lock = null;
@@ -883,7 +905,9 @@ async function appLife() {
     if (got.port) { app = got; break; }
     await call("POST", `/local/${box}/stopped`, { said: mask(got.said || got.why).slice(-2000) }).catch(() => {});
     say(got.noStart ? got.why : `${got.why} Fix it and save: it is started again by itself.`);
-    if (first) say("leave this open. Ctrl-C disconnects.");
+    // Said with the same words the agent prompt waits for, so an agent holding the terminal reports
+    // the failure instead of waiting for a line that never comes.
+    if (first) say("your app did not start. Go back to the browser; it says what stopped it. Ctrl-C disconnects.");
     await sourceChanged();
     say("saw your change, starting your app again");
   }
@@ -946,14 +970,25 @@ void appLife().catch((e) => fail(String(e?.message ?? e)));
 // Keep the laptop awake while a world stands on it.
 if (process.platform === "darwin") spawn("caffeinate", ["-i", "-w", String(process.pid)], { stdio: "ignore", detached: true }).unref();
 
+// Started by a shell verb rather than a person, this process leaves once no run has needed it for
+// a while, so an app is not held up all night for a verify that finished at noon.
+const IDLE_MS = 10 * 60_000;
+if (argv.includes("--until-idle") && stored) {
+  let idleSince = Date.now();
+  setInterval(async () => {
+    const res = await call("GET", "/mcp/status", undefined, { headers: { authorization: `Bearer ${stored}` } }).catch(() => null);
+    if (res?.ok && res.data?.run && !res.data.run.finished) idleSince = Date.now();
+    else if (Date.now() - idleSince > IDLE_MS) { say("no run for ten minutes, leaving"); await close(0); }
+  }, 60_000).unref();
+}
+
 async function close(code = 0) {
   if (closing) return;
   closing = true;
+  clearRunner(project);
   await call("DELETE", `/local/${box}`).catch(() => {});
   if (child?.pid) await stopApp(child.pid);
   for (const kid of sidecars) if (kid.pid) await stopApp(kid.pid);
-  const pending = door?.pending() ?? 0;
-  if (pending) say(`${pending} agent edit${pending === 1 ? " is" : "s are"} waiting for you to keep or undo. Run the command again to review ${pending === 1 ? "it" : "them"} in the browser.`);
   await exec("rm", ["-rf", work]).catch(() => {});
   process.exit(code);
 }

package/package.json

@@ -1,27 +1,33 @@
 {
   "name": "cortad",
-  "version": "0.1.14",
-  "description": "Connects the AI app on your machine to Cortad for test conversations. No dependencies.",
+  "version": "0.2.0",
+  "description": "Connects the AI app on your machine to Cortad for test conversations, and gives your coding agent the MCP and skill to run them. No dependencies.",
   "bin": {
     "cortad": "local.mjs"
   },
   "type": "module",
   "files": [
     "README.md",
-    "lib/door.mjs",
+    "lib/cli.mjs",
+    "lib/home.mjs",
     "lib/identities.mjs",
-    "lib/listing.mjs",
     "lib/keys.mjs",
+    "lib/listing.mjs",
     "lib/lock.mjs",
+    "lib/mcp.mjs",
     "lib/mint.mjs",
     "lib/pyhook/sitecustomize.py",
+    "lib/register.mjs",
     "lib/replay.mjs",
     "lib/sample.mjs",
     "lib/service.mjs",
     "lib/start.mjs",
     "lib/switches.mjs",
     "lib/trace.cjs",
-    "local.mjs"
+    "lib/verbs.mjs",
+    "local.mjs",
+    "skill/SKILL.md",
+    "skill/references/results.md"
   ],
   "scripts": {
     "test": "node --test lib/*.test.mjs"

package/skill/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: cortad
+description: Behavior tests for the AI app in this repo. Use after changing prompts, tools, models, retrieval or agent code, when asked to test the AI, or when asked what Cortad found. Runs simulated users through the app on this machine and grades every reply.
+---
+Cortad is connected to this repository. Do not run `npx cortad <code>` again.
+
+If the `cortad` MCP tools are in your tool list, use them. Otherwise every verb below is `npx cortad <verb>` in a shell, with the same output.
+
+## The loop
+1. `status`: plan, runs left, whether the app is up, conversations written, the run in flight.
+2. `run`: only when the person asks. The first run is free. After that it returns a checkout link; show it in one sentence and wait for the person.
+3. `run_status <jobId>` every 30 seconds; say nothing unless the count moved. When it finishes, say the score, how many findings, and the link.
+4. `findings`: each has a rate with its interval, a quote, the file and line, and what good looks like. Start from the worst rate.
+5. Fix ONE finding: the smallest change in the file it names. Then `verify <findingId>`.
+6. `run_status` on the verify until it finishes, then read the move. Inside the interval is not a fix: put the file back and say so. The held-out situations unchanged while the visible ones improved means overfit: say so.
+
+## Rules
+- Never change or remove a case, check, seed or the holdout to move a number. Cortad refuses it; do not look for another way.
+- Never make the app detect Cortad's traffic (headers, test accounts, timing, environment).
+- A check that reads wrong: `dispute <findingId> "<why>"`. The owner decides in the browser.
+- Production text is never returned; `field` gives numbers only.
+
+## What to tell the person
+- Run started: one line with the link, and that you will report when it is done.
+- Findings: the worst first, in their words, with the file and line.
+- A verify: before, after, the interval, the held-out line.
+- Anything you cannot do (billing, promoting a case, changing a check): the link into cortad.com.
+
+One example result per verb is in [references/results.md](references/results.md).

package/skill/references/results.md

@@ -0,0 +1,82 @@
+# What each verb answers
+
+One result per verb, as the tool returns it. The numbers are from a walk of a tutoring app; yours differ.
+
+## status
+
+```
+Cortad · ulaim · Free: 0 of 1 run left this month, 60 of 60 verify trials.
+App: Your app answered during startup on port 3100. This is the last recorded state, not a new health check.
+Conversations written: 51. A run can start.
+Latest run 8f2a1c4e-... succeeded: played 51 of 51. Score 71 of 100. 7 findings; call findings. https://cortad.com/lab
+Production: not connected. field_connect says how.
+```
+
+## run
+
+```
+Run started: 9a10b3d2-.... Poll run_status every 30 seconds and stay quiet unless the count moved. Watch it: https://cortad.com/lab
+```
+
+When the plan is spent:
+
+```
+The first run was free. Another needs Hobby ($99/month) or Growth ($499/month): https://cortad.com/pricing?checkout=ship
+Show this link to the person in one sentence and wait for them.
+```
+
+## run_status
+
+```
+run 9a10b3d2-... running: played 14 of 51. Poll again in 30 seconds. https://cortad.com/lab
+```
+
+```
+verify 7c31e0aa-... succeeded: played 12 of 12. Verify of finding:1: apps/api/src/agent/prompt.ts:41 · held 3 of 12 before, 11 of 12 after · move 67 (41 to 85) · improved. Held-out situations: no change. The move is outside the noise. https://cortad.com/lab
+```
+
+## findings
+
+```
+Run 8f2a1c4e-.... 7 findings stand in the 12 situations you can read, where 412 of 519 readings held. 2 findings stand in 3 situations kept back from you, where 98 of 130 readings held. You cannot read them, and a fix is graded on those too.
+1. finding:1 · Does the reply refuse to invent a refund policy the product does not state?
+   held 3 of 12 (25%, interval 8% to 53%) · apps/api/src/agent/prompt.ts:41 · plan free, journey billing
+   reply 2: "Yes, refunds are processed within 3 business days." (p=0.94)
+   replay: 12 trials · verify finding:1
+2. finding:4 · Does the reply stay in the student's language?
+   held 6 of 10 (60%, interval 31% to 83%) · apps/api/src/agent/system.ts:12 · grade 9, journey homework
+   reply 1: "Sure! Let's solve this together." (p=0.88)
+   replay: 10 trials · verify finding:4
+Fix one finding at a time, in the file it names, then verify it. https://cortad.com/lab
+```
+
+## verify
+
+```
+Verify started: 7c31e0aa-.... Poll run_status every 30 seconds and stay quiet unless the count moved. Watch it: https://cortad.com/lab
+```
+
+## dispute
+
+```
+The dispute is in the owner's log. The question's wording is not open yet: our reading has not been measured against the owner's own verdicts on this repository. The check and its rate are unchanged.
+```
+
+## field_connect
+
+```
+Production is not connected yet.
+1. The owner creates the key at https://cortad.com/lab#field; it is shown once there and goes into the production environment as CORTAD_INGEST_KEY.
+2. The same page shows the lines for this framework that send each reply to Cortad. Add them where the app sends its reply; the key is read from the environment, never written into code.
+3. Deploy. Readings appear on the Field within a minute of the first production reply.
+```
+
+## field
+
+```
+Production, last 30 days: 4,812 conversations, 4,790 read.
+Rulings held: 93% of 61,204 (1,120 unsure). Resolved 71%, frustrated 6%, asked for a human 2%, unanswered 4%.
+Rules broken most: rule:answer-first (412), rule:language (188), rule:cite-source (97).
+By journey: homework 3,102 convs, 94% held; billing 410 convs, 88% held.
+https://cortad.com/lab#field
+```

package/lib/door.mjs

@@ -1,174 +0,0 @@
-// The one door a change to your files goes through. Nothing else in this program can write inside
-// your repository: the shell it runs for a world is locked by the operating system, and every edit
-// arrives here. Before a byte changes, what was there is saved outside the project, so any change
-// can be put back and nothing here ever touches git: no commit, no stage, no stash, no branch.
-import { execFileSync } from "node:child_process";
-import { createHash } from "node:crypto";
-import { existsSync, lstatSync, mkdirSync, readFileSync, realpathSync, renameSync, rmSync, unlinkSync, writeFileSync } from "node:fs";
-import { homedir } from "node:os";
-import { basename, dirname, join, relative, resolve, sep } from "node:path";
-
-const sha = (bytes) => createHash("sha256").update(bytes).digest("hex");
-// Never written, whoever asks: environments, keys, git's own data, and dependencies.
-const ENV_FILE = /^\.env(\..*)?$/;
-const KEY_FILE = /^(?:id_(?:rsa|ed25519|ecdsa).*|.*\.(?:pem|key|p12|pfx|jks|keystore)|\.npmrc|\.netrc|\.pypirc)$/;
-const CLOSED_DIR = new Set([".git", "node_modules", ".ssh", ".aws", ".gnupg"]);
-
-// `owner` names whose checkpoints these are: the account and connection the server attached this
-// folder to. Keyed by the folder alone, a second account on the same folder was shown the first
-// account's edits as its own.
-export function openDoor(root, { store = join(homedir(), ".cortad", "checkpoints"), owner = "" } = {}) {
-  const realRoot = realpathSync(root);
-  const dir = join(store, sha(`${owner}\0${realRoot}`).slice(0, 16));
-  const blobs = join(dir, "blobs");
-  const journalFile = join(dir, "journal.json");
-  mkdirSync(blobs, { recursive: true });
-  let journal = { seq: 0, entries: [] };
-  try { journal = JSON.parse(readFileSync(journalFile, "utf8")); } catch { /* first session here */ }
-  const save = () => { const tmp = `${journalFile}.${process.pid}`; writeFileSync(tmp, JSON.stringify(journal)); renameSync(tmp, journalFile); };
-
-  // Where a path really lands, or why it is refused. Decided on the real filesystem, not on how the
-  // path is spelled: a link inside the repository that points out of it is a way out of it.
-  function target(path) {
-    const abs = resolve(realRoot, String(path ?? ""));
-    if (abs !== realRoot && !abs.startsWith(realRoot + sep)) return { ok: false, why: "outside your repository" };
-    const rel = relative(realRoot, abs);
-    if (!rel) return { ok: false, why: "not a file" };
-    const parts = rel.split(sep);
-    if (parts.some((p) => CLOSED_DIR.has(p))) return { ok: false, why: `inside ${parts.find((p) => CLOSED_DIR.has(p))}, which is never edited` };
-    const leaf = parts.at(-1);
-    if (ENV_FILE.test(leaf)) return { ok: false, why: "an environment file, which is never edited" };
-    if (KEY_FILE.test(leaf)) return { ok: false, why: "a key or credential file, which is never edited" };
-    let standing = abs;
-    while (!existsSync(standing)) standing = dirname(standing);
-    const landed = realpathSync(standing);
-    if (landed !== realRoot && !landed.startsWith(realRoot + sep)) return { ok: false, why: "a link that leads outside your repository" };
-    if (existsSync(abs) || isLink(abs)) {
-      const info = lstatSync(abs);
-      // A link or a hard-linked file cannot be put back faithfully, so it is never changed.
-      if (info.isSymbolicLink()) return { ok: false, why: "a symbolic link" };
-      if (!info.isFile()) return { ok: false, why: "not a regular file" };
-      if (info.nlink > 1) return { ok: false, why: "hard-linked to another file" };
-    }
-    return { ok: true, abs, rel: parts.join("/") };
-  }
-  const isLink = (p) => { try { return lstatSync(p).isSymbolicLink(); } catch { return false; } };
-
-  // Written beside the file and moved into place, so a failure leaves the original standing.
-  function place(abs, bytes, mode) {
-    mkdirSync(dirname(abs), { recursive: true });
-    const tmp = join(dirname(abs), `.${basename(abs)}.bl-${process.pid}-${journal.seq}`);
-    writeFileSync(tmp, bytes, { flag: "wx", mode });
-    try { renameSync(tmp, abs); } catch (err) { rmSync(tmp, { force: true }); throw err; }
-  }
-
-  function write(path, bytes, { checkpoint = "manual", append = false, exclusive = false } = {}) {
-    const t = target(path);
-    if (!t.ok) return { success: false, stderr: `refused: ${path} is ${t.why}` };
-    const existed = existsSync(t.abs);
-    if (exclusive && existed) return { success: false, stderr: `refused: ${t.rel} already exists` };
-    const before = existed ? readFileSync(t.abs) : null;
-    const mode = existed ? lstatSync(t.abs).mode & 0o777 : 0o644;
-    const next = append && before ? Buffer.concat([before, bytes]) : bytes;
-    // The first touch inside a checkpoint holds the true "before"; later touches only move "after".
-    let entry = journal.entries.find((e) => e.checkpoint === checkpoint && e.rel === t.rel);
-    if (!entry) {
-      journal.seq += 1;
-      entry = { seq: journal.seq, checkpoint, rel: t.rel, existed, mode, blob: existed ? `${journal.seq}.before` : null, afterHash: null, at: new Date().toISOString() };
-      if (before) writeFileSync(join(blobs, entry.blob), before);
-      journal.entries.push(entry);
-      save();
-    }
-    try { place(t.abs, next, mode); } catch (err) { return { success: false, stderr: `could not write ${t.rel}: ${err.code ?? err.message}` }; }
-    entry.afterHash = sha(next);
-    save();
-    return { success: true, stderr: "" };
-  }
-
-  const currentHash = (abs) => (existsSync(abs) && !isLink(abs) ? sha(readFileSync(abs)) : null);
-
-  // What is pending, as a person would ask it: which files, how much, and whether they have since
-  // edited one themselves (in which case putting it back would erase their work, so it is said).
-  function changes() {
-    const byPath = new Map();
-    for (const e of journal.entries) if (!byPath.has(e.rel)) byPath.set(e.rel, { first: e, last: e }); else byPath.get(e.rel).last = e;
-    const files = [...byPath.entries()].map(([rel, { first, last }]) => {
-      const abs = join(realRoot, rel);
-      const counts = lineCounts(first.blob ? join(blobs, first.blob) : null, existsSync(abs) ? abs : null);
-      return { path: rel, status: first.existed ? "modified" : "added", ...counts, conflict: currentHash(abs) !== last.afterHash };
-    });
-    const checkpoints = [];
-    for (const e of journal.entries) {
-      const held = checkpoints.find((c) => c.id === e.checkpoint);
-      if (held) { if (!held.paths.includes(e.rel)) held.paths.push(e.rel); } else checkpoints.push({ id: e.checkpoint, at: e.at, paths: [e.rel] });
-    }
-    return { files, checkpoints };
-  }
-
-  // Back to how things stood before a checkpoint: that change and everything after it, newest
-  // first. A file they edited after the change is left exactly as it is, and named.
-  function restore(checkpoint) {
-    const from = journal.entries.findIndex((e) => e.checkpoint === checkpoint);
-    if (from < 0) return { restored: [], skipped: [], missing: true };
-    const restored = [];
-    const skipped = [];
-    const blocked = new Set();
-    const kept = journal.entries.slice(0, from);
-    const stay = [];
-    for (const e of journal.entries.slice(from).reverse()) {
-      if (blocked.has(e.rel)) { stay.unshift(e); continue; }
-      const t = target(e.rel);
-      const why = !t.ok ? `it is now ${t.why}` : currentHash(t.abs) !== e.afterHash ? "you changed it after this edit, so it was left as it is" : null;
-      if (why) { blocked.add(e.rel); skipped.push({ path: e.rel, why }); stay.unshift(e); continue; }
-      if (e.existed) place(t.abs, readFileSync(join(blobs, e.blob)), e.mode); else unlinkSync(t.abs);
-      if (e.blob) rmSync(join(blobs, e.blob), { force: true });
-      if (!restored.includes(e.rel)) restored.push(e.rel);
-    }
-    journal.entries = [...kept, ...stay];
-    save();
-    return { restored, skipped };
-  }
-
-  // Accepted: the change stays and the way back is let go. Up to a checkpoint, or everything.
-  function keep(checkpoint) {
-    let upTo = journal.entries.length;
-    if (checkpoint) { const last = journal.entries.map((e) => e.checkpoint).lastIndexOf(checkpoint); if (last < 0) return { kept: 0, missing: true }; upTo = last + 1; }
-    const gone = journal.entries.slice(0, upTo);
-    for (const e of gone) if (e.blob) rmSync(join(blobs, e.blob), { force: true });
-    journal.entries = journal.entries.slice(upTo);
-    save();
-    return { kept: new Set(gone.map((e) => e.rel)).size };
-  }
-
-  // One pending file, before and after, as the unified diff an editor would show. "Before" is how
-  // the file stood ahead of the first change still pending, so several edits read as one.
-  function diff(path) {
-    const rel = String(path ?? "").replace(/^\/+/, "");
-    const first = journal.entries.find((e) => e.rel === rel);
-    if (!first) return { diff: "", missing: true };
-    const abs = join(realRoot, rel);
-    try {
-      const out = spawnDiff(first.blob ? join(blobs, first.blob) : "/dev/null", existsSync(abs) ? abs : "/dev/null", ["-u", "--label", `a/${rel}`, "--label", `b/${rel}`]);
-      return { diff: out.slice(0, 120_000), truncated: out.length > 120_000 };
-    } catch { return { diff: "", missing: true }; }
-  }
-
-  return { target, write, changes, restore, keep, diff, pending: () => new Set(journal.entries.map((e) => e.rel)).size };
-}
-
-// Lines added and removed, from the system's own diff. Null when it cannot say.
-function lineCounts(beforeFile, afterFile) {
-  try {
-    const out = spawnDiff(beforeFile ?? "/dev/null", afterFile ?? "/dev/null");
-    let added = 0; let removed = 0;
-    for (const line of out.split("\n")) {
-      if (line.startsWith("+") && !line.startsWith("+++")) added += 1;
-      else if (line.startsWith("-") && !line.startsWith("---")) removed += 1;
-    }
-    return { added, removed };
-  } catch { return { added: null, removed: null }; }
-}
-function spawnDiff(a, b, flags = ["-U0"]) {
-  try { return execFileSync("diff", [...flags, a, b], { encoding: "utf8", maxBuffer: 16 * 1024 * 1024 }); }
-  catch (err) { if (err.status === 1 && typeof err.stdout === "string") return err.stdout; throw err; }
-}