cortad 0.3.1-rc.11 → 0.3.1-rc.13

package/README.md

@@ -6,7 +6,7 @@ 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. The first run starts on its own. Ctrl-C disconnects.
+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. A run starts when you press Run in the browser or ask your agent for one. Ctrl-C disconnects.
 
 ## Your coding agent
 

package/lib/app-port.mjs

@@ -0,0 +1,9 @@
+// Which listening port is the app. A database that answers an HTTP probe on its own port is not the
+// app: MongoDB says so in words, and AI Answers' run followed its in-memory MongoDB after a restart
+// and sent every trial there. A database's own address in the log (mongodb://127.0.0.1:52011) names
+// the store, never the app.
+const NOT_AN_APP = /trying to access MongoDB over HTTP|^-ERR |^\$\d+\r?\n|^\+PONG/m;
+const STORE_URL = /\b(?:mongodb(?:\+srv)?|postgres(?:ql)?|redis|rediss|mysql|mariadb|amqp|nats):\/\/\S+/gi;
+
+export const notAnApp = (head) => NOT_AN_APP.test(head);
+export const withoutStores = (log) => log.replace(STORE_URL, "");

package/lib/backing.mjs

@@ -0,0 +1,230 @@
+// The services your app reaches on this machine, brought up when nothing answers there and the
+// repository says how: a store its compose file runs from an image, with Docker, or a second
+// service of its own, with that service's own start. Only a port the app is known to reach is
+// brought up: one its settings name when it could not start without it, or one the hook saw it
+// reach for. A compose file often lists a store the app is set up not to use, and starting it
+// would be a download of gigabytes nobody asked for. Each is stopped when this command ends, and
+// one that could not be brought up, or that nothing here brings up, is said before a run, with whose
+// side it is on.
+import { execFile } from "node:child_process";
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { connect } from "node:net";
+import { basename, dirname, join, relative } from "node:path";
+import { ledger } from "./ledger.mjs";
+import { servicePort } from "./service.mjs";
+import { startPlan, workspaces } from "./start.mjs";
+
+// Something accepts a connection on the port: a database answers no HTTP, so this is the test.
+export function tcpOpen(host, port, ms = 1500) {
+  return new Promise((done) => {
+    const s = connect({ host: host && !host.startsWith("/") && host !== "0.0.0.0" ? host.replace(/^\[|\]$/g, "") : "127.0.0.1", port });
+    const end = (ok) => { s.destroy(); done(ok); };
+    s.setTimeout(ms, () => end(false));
+    s.once("connect", () => end(true));
+    s.once("error", () => end(false));
+  });
+}
+async function waitTcp(port, ms, gone = () => false) {
+  for (const until = Date.now() + ms; Date.now() < until && !gone(); await new Promise((r) => setTimeout(r, 1000))) if (await tcpOpen("127.0.0.1", port)) return true;
+  return false;
+}
+
+const COMPOSE_FILE = /^(?:docker-)?compose(?:\.[\w-]+)?\.ya?ml$/;
+// The files compose reads by default come first: a second file beside them is a variant.
+const DEFAULT_FIRST = (a, b) => Number(/^(?:docker-)?compose\.ya?ml$/.test(basename(b))) - Number(/^(?:docker-)?compose\.ya?ml$/.test(basename(a))) || a.localeCompare(b);
+export function composeFiles(dirs) {
+  const out = new Set();
+  for (const dir of dirs) { try { for (const f of readdirSync(dir)) if (COMPOSE_FILE.test(f)) out.add(join(dir, f)); } catch { /* no folder */ } }
+  return [...out].sort(DEFAULT_FIRST);
+}
+
+const unquote = (v) => String(v ?? "").trim().replace(/^(['"])(.*)\1$/, "$2");
+// ${PG_PORT:-5432} and ${PG_PORT}, from the settings the app starts with.
+const interpolate = (v, values) => v.replace(/\$\{(\w+)(?::?-([^}]*))?\}/g, (_, name, dflt) => values[name] || dflt || "");
+// The host port of one port mapping: "5432:5432", "127.0.0.1:5432:5432/tcp". None for a container
+// port alone (compose picks the host's) or a range.
+function published(entry, values) {
+  const parts = interpolate(unquote(entry), values).replace(/\/(?:tcp|udp)$/, "").split(":");
+  const host = parts.length >= 2 ? parts[parts.length - 2] : "";
+  return /^\d+$/.test(host) ? Number(host) : null;
+}
+
+// The services a compose file declares: name, whether it runs an image or builds this repository's
+// code, and the host ports it publishes. A reader of the shape compose files are written in, not of
+// YAML at large.
+// ponytail: no anchors, extends, include or profiles; add them when a repository needs one to be read.
+export function composeServices(text, values = {}) {
+  const out = [];
+  let inServices = false, nameIndent = -1, keyIndent = -1, svc = null, portsIndent = -1;
+  for (const raw of String(text).split("\n")) {
+    const line = raw.replace(/\t/g, "  ").replace(/\s+#.*$/, "");
+    const t = line.trim();
+    if (!t || t.startsWith("#")) continue;
+    const indent = line.length - line.trimStart().length;
+    if (indent === 0) { inServices = /^services:\s*$/.test(t); svc = null; continue; }
+    if (!inServices) continue;
+    if (nameIndent < 0) nameIndent = indent;
+    if (indent <= nameIndent) {
+      const m = /^["']?([\w.-]+)["']?:\s*$/.exec(t);
+      svc = indent === nameIndent && m ? { name: m[1], image: null, build: false, ports: [] } : null;
+      if (svc) out.push(svc);
+      keyIndent = -1; portsIndent = -1;
+      continue;
+    }
+    if (!svc) continue;
+    if (portsIndent >= 0 && indent > portsIndent) {
+      const item = /^-\s*(.*)$/.exec(t);
+      const port = item && !/^[A-Za-z_]\w*:(?:\s|$)/.test(item[1]) ? published(item[1], values) : Number(unquote(/^(?:-\s*)?published:\s*(.+)$/.exec(t)?.[1] ?? "")) || null;
+      if (port) svc.ports.push(port);
+      continue;
+    }
+    portsIndent = -1;
+    if (keyIndent < 0) keyIndent = indent;
+    if (indent !== keyIndent) continue;
+    const kv = /^([\w-]+):\s*(.*)$/.exec(t);
+    if (!kv) continue;
+    if (kv[1] === "image") svc.image = unquote(kv[2]);
+    else if (kv[1] === "build") svc.build = true;
+    else if (kv[1] === "ports") {
+      if (kv[2].startsWith("[")) for (const e of kv[2].replace(/^\[|\]$/g, "").split(",")) { const p = published(e, values); if (p) svc.ports.push(p); }
+      else portsIndent = indent;
+    }
+  }
+  return out;
+}
+
+// A setting that is an address a page is opened from, not a service the app calls.
+// The app's own address and sign-in redirects are pages, not services: ai-appointment-setter's
+// NEXT_PUBLIC_APP_URL serves only its OAuth redirect, and a run was held on it.
+const PAGE = /(?:^|_)(?:ORIGINS?|FRONTEND|CLIENT|SITE|WEB|CALLBACK|REDIRECT|CORS|ALLOWED|HOMEPAGE|APP|BASE|NEXTAUTH)(?:_|$)/;
+// Addresses on this machine the app's settings point at: http://localhost:4000/api under API_URL.
+export function localAddresses(values) {
+  const byPort = new Map();
+  for (const [name, raw] of Object.entries(values)) {
+    if (PAGE.test(name)) continue;
+    let u;
+    try { u = new URL(String(raw ?? "").trim()); } catch { continue; }
+    if (!/^https?:$/.test(u.protocol) || !u.port || !/^(?:localhost|127(?:\.\d+){3}|\[::1\]|0\.0\.0\.0)$/i.test(u.hostname)) continue;
+    const port = Number(u.port);
+    byPort.set(port, [...(byPort.get(port) ?? []), name]);
+  }
+  return [...byPort].map(([port, names]) => ({ port, names }));
+}
+
+const run = (bin, args, opts = {}) => new Promise((done) => {
+  execFile(bin, args, { timeout: 180_000, maxBuffer: 4 * 1024 * 1024, ...opts }, (err, stdout, stderr) => done({ ok: !err, out: String(stdout ?? ""), err: String(stderr ?? err?.message ?? "") }));
+});
+// A service's own last words go into a sentence that leaves this machine: an address's password never does.
+const lastLine = (text) => String(text).replace(/\x1b\[[0-9;]*[A-Za-z]/g, "").replace(/:\/\/[^\s/@:]+:[^\s/@]+@/g, "://[masked]@").split("\n").map((l) => l.trim()).filter(Boolean).at(-1)?.slice(0, 160) ?? "";
+
+// How compose is run here: the docker plugin, the older standalone binary, or not at all and why.
+async function composeCommand(onPath) {
+  if (!onPath("docker") && !onPath("docker-compose")) return { why: "Docker is not installed on this machine" };
+  if (!(await run("docker", ["info"], { timeout: 15_000 })).ok) return { why: "Docker is not running on this machine" };
+  if ((await run("docker", ["compose", "version"], { timeout: 15_000 })).ok) return { bin: "docker", pre: ["compose"] };
+  return onPath("docker-compose") ? { bin: "docker-compose", pre: [] } : { why: "Docker here has no compose command" };
+}
+
+const upper = (s) => s.charAt(0).toUpperCase() + s.slice(1);
+// Why a port is wanted: a setting names it, or the app was seen reaching for it.
+const pointer = (w) => (!w.names?.length ? "Your app reached for"
+  : w.names.length === 1 ? `${w.names[0]} points at` : `${w.names[0]} and ${w.names.length - 1} more setting${w.names.length > 2 ? "s" : ""} point at`);
+const said = {
+  up: (what, how, w) => `Started ${what} ${how}: ${pointer(w)} port ${w.port} on this machine and nothing answered there. It is stopped when this command ends.`,
+  theirs: (what, why, w) => `${pointer(w)} port ${w.port} on this machine and nothing answers there. ${upper(what)} would start it, but ${why}: start it yourself before a run. This is on your side.`,
+  exited: (what, tail, w) => `${pointer(w)} port ${w.port} on this machine, which ${what} serves, and it stopped before it answered: ${tail}. This is on your side.`,
+  none: (w) => `${pointer(w)} port ${w.port} on this machine and nothing answers there, and nothing in this repository starts it: start it yourself before a run. This is on your side.`,
+  slow: (what, secs, w) => `${pointer(w)} port ${w.port} on this machine; ${what} was started for it, but nothing answered there within ${secs} seconds. This is on our side.`,
+};
+
+// One session's services. up(wants) brings up each wanted port it can, where nothing answers: a
+// compose store first, else a workspace of this repository that serves it. `launch` starts a
+// workspace the way the app is started and hands back its process. Answers what it said and the
+// ports that now answer.
+export function makeBacking({ root, appDir, values, onPath, ledgerFile, launch, adopt = true, storeWaitMs = 120_000, serviceWaitMs = 90_000 }) {
+  const book = ledger(ledgerFile);
+  const started = [];
+  const tried = new Set();
+  const lastSaid = new Map();
+  let compose = null;
+  const files = composeFiles([...new Set([appDir, root])]).map((file) => ({ file, services: (() => { try { return composeServices(readFileSync(file, "utf8"), values); } catch { return []; } })() }));
+  // Services a session that died left running are stopped by the next session that starts the app,
+  // never removed: the person may have used them since, and a removed container takes what they put
+  // in it. A session attached to an app already running leaves them to that app.
+  for (const row of adopt ? book.orphans("service") : []) {
+    const [file, service] = row.key.split("#");
+    if (!existsSync(file)) continue;
+    const kept = { ...row, made: "stop" };
+    book.remove(row);
+    book.add(kept);
+    started.push({ file, service, row: kept });
+  }
+
+  async function fromCompose(found, w) {
+    const where = `the ${found.service} service in ${relative(root, found.file) || basename(found.file)}`;
+    compose ??= await composeCommand(onPath);
+    if (compose.why) return said.theirs(where, compose.why, w);
+    const opts = { cwd: dirname(found.file), env: { ...process.env } };
+    const args = (...a) => [...compose.pre, "-f", found.file, ...a];
+    const existed = Boolean((await run(compose.bin, args("ps", "-a", "-q", found.service), opts)).out.trim());
+    const up = await run(compose.bin, args("up", "-d", found.service), opts);
+    if (!up.ok) return said.theirs(where, `Docker could not start it: ${lastLine(up.err)}`, w);
+    const row = { kind: "service", key: `${found.file}#${found.service}`, made: existed ? "stop" : "remove" };
+    book.add(row);
+    started.push({ file: found.file, service: found.service, row });
+    if (!(await waitTcp(w.port, storeWaitMs))) return said.slow(where, Math.round(storeWaitMs / 1000), w);
+    return said.up(where, "with Docker", w);
+  }
+
+  async function fromWorkspace(dir, w) {
+    const plan = startPlan({ root: dir, onPath });
+    if (!plan?.cmd) return null;
+    const what = relative(root, dir) || basename(dir);
+    const kid = launch(plan);
+    let exited = null;
+    let tail = "";
+    kid.on("exit", (code) => { exited = code ?? 1; });
+    const keep = (d) => { tail = (tail + d).slice(-2000); };
+    kid.stdout?.on("data", keep);
+    kid.stderr?.on("data", keep);
+    if (await waitTcp(w.port, serviceWaitMs, () => exited !== null)) return said.up(what, `with ${plan.cmd}`, w);
+    if (exited !== null) return said.exited(what, lastLine(tail) || `it exited ${exited}`, w);
+    return said.slow(what, Math.round(serviceWaitMs / 1000), w);
+  }
+
+  return {
+    // wants: [{ port, names, store }], each a port on this machine the app reaches or its settings
+    // name; `store` lets a compose image serve it. Answers what was said and the ports brought up.
+    // `down`: the ports a setting names that still answer nothing after this, each with what was
+    // said of it: a run without them is a run against an app missing a part, and holds.
+    async up(wants) {
+      const lines = [];
+      const ports = [];
+      const down = [];
+      const still = (w, why) => { if (w.names?.length && why) down.push({ port: w.port, names: w.names, why }); };
+      for (const w of wants) {
+        if (await tcpOpen("127.0.0.1", w.port)) continue;
+        if (tried.has(w.port)) { still(w, lastSaid.get(w.port)); continue; }
+        const image = w.store ? files.flatMap(({ file, services }) => services.filter((x) => x.image && !x.build && x.ports.includes(w.port)).map((x) => ({ file, service: x.name })))[0] : null;
+        const dir = image ? null : workspaces(root).find((d) => d !== appDir && servicePort(d) === w.port);
+        // A port only seen reached, and not a store's, may be a passing connection of the app's own.
+        if (!image && !dir && !w.names?.length && !w.store) continue;
+        tried.add(w.port);
+        const line = !image && !dir ? said.none(w) : image ? await fromCompose(image, w) : await fromWorkspace(dir, w);
+        if (line) { lines.push(line); lastSaid.set(w.port, line); }
+        if (await tcpOpen("127.0.0.1", w.port)) ports.push(w.port);
+        else still(w, line);
+      }
+      return { lines, ports, down };
+    },
+    // Compose services only: a workspace's process is the caller's, stopped with the app.
+    async stop() {
+      compose ??= started.length ? await composeCommand(onPath) : null;
+      if (!compose || compose.why) return;
+      for (const { file, service, row } of started.splice(0)) {
+        const how = row.made === "stop" ? ["stop", service] : ["rm", "-s", "-f", service];
+        if ((await run(compose.bin, [...compose.pre, "-f", file, ...how], { cwd: dirname(file), env: { ...process.env } })).ok) book.remove(row);
+      }
+    },
+  };
+}

package/lib/cli.mjs

@@ -3,10 +3,12 @@ import { spawn } from "node:child_process";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { makeCode } from "./fresh.mjs";
-import { homeOf, projectOf, readPending, readRunner, readToken, writePending, writeRunner } from "./home.mjs";
+import { homeOf, projectOf, readPending, readToken, writePending } from "./home.mjs";
+import { readRunner } from "./runner.mjs";
 import { markRun, putBack, writesDirOf } from "./writes.mjs";
 import { serveMcp } from "./mcp.mjs";
 import { SHOW } from "./read-text.mjs";
+import { answeringText, notStartedText } from "./text.mjs";
 import { cliSpec, VERSION } from "./spec.mjs";
 import { hookOutput, stick, unstick } from "./stick.mjs";
 import { makeVerbs, READY_MS } from "./verbs.mjs";
@@ -46,6 +48,7 @@ export async function main(argv, { root = process.cwd(), env = process.env, stdo
     root,
     writes,
     token: () => readToken(project),
+    runner: () => readRunner(project),
     pending,
     startApp: (args, kind) => startApp({ root, project, env, keep: mcp, children, args, kind }),
     code: makeCode({ project, root, waitMs: mcp ? RESTART_MS.mcp : RESTART_MS.shell }),
@@ -72,7 +75,8 @@ export async function main(argv, { root = process.cwd(), env = process.env, stdo
 }
 
 // Positional arguments for the shell face: `status rules 2`, `verify f1`, `run_status <jobId>`,
-// `findings 2`, `dispute f1 "why"`. A bare number is a page; in findings anything else is a run id.
+// `findings 2`, `findings numbers 3`, `dispute f1 "why"`. A bare number is a page; in findings the
+// word numbers is the whole table and anything else is a run id.
 function argsOf(command, rest) {
   const page = rest.find((w) => /^\d+$/.test(w));
   switch (command.replace(/-/g, "_")) {
@@ -82,8 +86,9 @@ function argsOf(command, rest) {
     }
     case "run_status": return rest[0] ? { jobId: rest[0] } : {};
     case "findings": {
-      const jobId = rest.find((w) => w !== "--page" && !/^\d+$/.test(w));
-      return { ...(jobId ? { jobId } : {}), ...(page ? { page: Number(page) } : {}) };
+      const show = rest.includes("numbers") ? { show: "numbers" } : {};
+      const jobId = rest.find((w) => w !== "--page" && w !== "numbers" && !/^\d+$/.test(w));
+      return { ...show, ...(jobId ? { jobId } : {}), ...(page ? { page: Number(page) } : {}) };
     }
     case "verify": return { findingId: rest[0], ...(rest[1] ? { jobId: rest[1] } : {}) };
     case "dispute": return { findingId: rest[0], why: rest.slice(1).join(" ") };
@@ -104,37 +109,45 @@ function requestOf(raw) {
 
 // Returns at once. The runner holds the app up: from the MCP it lives as long as the MCP does;
 // from a shell command it stays until the runs stop for a while (--until-idle). The waiter is
-// detached either way and ends once the run is posted or the app did not come up.
+// detached either way and ends once the run is posted or the app did not come up. The runner takes
+// the project's lock itself (lib/runner.mjs): one started beside a live one leaves at once.
 export function startApp({ root, project, env, keep, children, args, kind, spawnImpl = spawn }) {
   const log = openSync(join(homeOf(project), "runner.log"), "a");
   if (!readRunner(project)) {
     const child = spawnImpl(process.execPath, [LOCAL, "--token", ...(keep ? [] : ["--until-idle"])], { cwd: root, env, stdio: ["ignore", log, log], detached: !keep });
     if (keep) children.push(child); else child.unref();
-    writeRunner(project, { pid: child.pid, startedAt: new Date().toISOString(), by: keep ? "mcp" : "cli" });
   }
   spawnImpl(process.execPath, [LOCAL, WAITER, JSON.stringify({ kind, args })], { cwd: root, env, stdio: ["ignore", log, log], detached: true }).unref();
   closeSync(log);
   return { ok: true };
 }
 
-// The waiter: posts the run once the app answers and leaves the outcome in pending.json.
-export async function runWhenUp({ verbs, project, env, pending, request, poll = appOf, now = Date.now, sleep = (ms) => new Promise((r) => setTimeout(r, ms)), readyMs = READY_MS }) {
+// The waiter: posts the run once the runner says the app is up and Cortad can take it, and leaves
+// the outcome in pending.json. The app's state is the runner's; `poll` asks the server whether it can
+// play the app, and its latest reason why not is what a timeout says.
+export async function runWhenUp({ verbs, project, env, pending, request, poll = appOf, runner = () => readRunner(project), now = Date.now, sleep = (ms) => new Promise((r) => setTimeout(r, ms)), readyMs = READY_MS }) {
   const log = join(homeOf(project), "runner.log");
   const fail = (text) => pending.write({ ...pending.read(), error: text });
   const until = now() + readyMs;
-  let said = "";
+  const minutes = Math.round(readyMs / 60_000);
+  let here = null;
+  let app = null;
   while (now() < until) {
     await sleep(3000);
-    const app = await poll(env, project);
-    if (app?.state === "ready-to-test") {
-      const out = await verbs.post(request.args, request.kind);
-      if (!out.data?.jobId) fail(out.text);
-      return;
-    }
-    if (app?.said) said = ` ${app.said}`;
-    if (!readRunner(project)) return fail(`The process holding your app up ended before the app answered.${said} Its output is in ${log}.\nNothing ran.`);
+    here = runner();
+    if (!here) return fail(`The process holding your app up ended before the app answered. Its output is in ${log}.\nNothing ran.`);
+    if (here.state === "failed") return fail(notStartedText(here));
+    if (here.state !== "up") continue;
+    const seen = await poll(env, project);
+    app = seen ?? app;
+    if (seen?.state !== "ready-to-test") continue;
+    const out = await verbs.post(request.args, request.kind);
+    if (!out.data?.jobId) fail(out.text);
+    return;
   }
-  fail(`Your app did not answer within ${Math.round(readyMs / 60_000)} minutes.${said} Its output is in ${log}.\nNothing ran.`);
+  fail(here?.state === "up"
+    ? `${answeringText(here, app)}\nThe ${request.kind} did not start within ${minutes} minutes.\nNothing ran.`
+    : `Your app did not answer within ${minutes} minutes. Its output is in ${log}.\nNothing ran.`);
 }
 
 async function appOf(env, project) {

package/lib/contact-text.mjs

@@ -0,0 +1,119 @@
+import { at, clip, has, num, plural, SIDE } from "./words.mjs";
+
+// What `status` says between connect and a run: each endpoint a real request proved, with what the
+// hook saw inside those requests; each endpoint the read found that no request has reached; what a
+// run on the proven ones would be, and what it would write into. Every figure is one the agent can
+// check against its own request or a line of the code. A field the API leaves out prints nothing.
+
+const CARRIER = {
+  body: (k) => `the body field "${k}"`,
+  cookie: (k) => `the cookie "${k}"`,
+  header: (k) => `the header "${k}"`,
+  path: (k) => `the path segment {${k}}`,
+  history: (k) => `the earlier messages the client sends in "${k}"`,
+};
+const where = (x) => (x?.file || x?.path ? `${at(x.file ?? x.path, x.line)}: ` : "");
+const TIED = { sent: "the first request sent", got: "the first request got back" };
+
+// A door whose answer came on a second request: that request, what tied the two, and what the client
+// sent first in each turn, each as the agent's own requests showed it.
+function secondStepLine(s) {
+  if (!s?.request) return null;
+  const tie = s.tie?.key && TIED[s.tie.from] ? `, tied by the "${s.tie.key}" ${TIED[s.tie.from]}` : "";
+  const before = s.before?.length ? `; each turn first sent ${s.before.join(", ")}` : "";
+  return `The answer came on a second request, ${s.request}${tie}${before}.`;
+}
+
+function sessionLine(v) {
+  const s = v.session;
+  if (!s || !(v.requests > 1)) return null;
+  if (!s.held) return "No later request's prompt carried an earlier one.";
+  const by = CARRIER[s.carrier] && s.key ? CARRIER[s.carrier](s.key) : "nothing the request sent, so every caller shares what the app keeps";
+  return `A later request's prompt carried an earlier one, tied by ${by}.`;
+}
+
+function rulesLine(r) {
+  if (!r || !has(r.of) || r.of === 0) return null;
+  const head = r.carried ? `The prompts carried ${num(r.carried)} of the ${plural(r.of, "rule")} read from your code` : `The prompts carried none of the ${plural(r.of, "rule")} read from your code`;
+  const example = (r.examples ?? [])[0];
+  return `${head}${example ? `, for example ${at(example.path, example.line)} "${clip(example.text, 160)}"` : ""}.`;
+}
+
+const sideOf = (side) => (SIDE[side] ? `, ${SIDE[side]}` : "");
+// A door runs do not use yet, or one only Cortad's requests reached, and why.
+function standingLine(v) {
+  if (v.standing === "excluded") return `Runs will not use this endpoint yet${sideOf(v.side)}: ${v.why}`;
+  if (v.standing === "fallback") return `Proven by Cortad's requests alone: ${v.why}`;
+  return null;
+}
+
+// Who the conversations through a signed-in endpoint act as: the customers the agent's requests signed in as.
+const accountsLine = (n) => (!has(n) ? null : n > 1 ? `Conversations are split across ${num(n)} accounts, one for each customer your requests signed in as.` : "All conversations act as one account.");
+
+// Where a trial takes each value the app's own client sets for its model.
+const appFieldLine = (f) => (f.from === "app" ? `"${f.field}" is set by your app${f.path ? ` at ${f.path}` : ""}.` : `"${f.field}" is only in your agent's request.`);
+
+// The last exchange through the door; an ask the proof could not find in the request is left out.
+function sampleLine(s) {
+  if (!s?.reply) return null;
+  const cut = s.cut ? ", and the reply stopped before it finished" : "";
+  return s.ask ? `Last request: "${clip(s.ask, 160)}", answered "${clip(s.reply, 240)}"${cut}.` : `Last reply: "${clip(s.reply, 240)}"${cut}.`;
+}
+
+function doorLines(v) {
+  const reached = `${plural(v.requests, "request")} reached ${v.model ?? "the model"}`;
+  const calls = has(v.modelCallsPerRequest) ? `, ${plural(v.modelCallsPerRequest, "model call")} each` : "";
+  const seconds = has(v.replySeconds) ? `, ${v.replySeconds} seconds a reply` : "";
+  const lines = [`  ${v.door}: ${reached}${calls}${seconds}.`];
+  const inner = [
+    standingLine(v),
+    v.askField ? `The message goes in "${v.askField}".` : null,
+    ...(v.appFields ?? []).map(appFieldLine),
+    secondStepLine(v.secondStep),
+    v.later ? "Your app takes the message at once and its model answers afterwards; Cortad grades the model's last answer to each message." : null,
+    sessionLine(v),
+    accountsLine(v.accounts),
+    ...(v.checks ?? []).map((said) => `Cortad's own check on this endpoint: ${said}`),
+    rulesLine(v.rules),
+    v.tools?.length ? `Tools that ran: ${v.tools.join(", ")}.` : null,
+    v.passages ? `Passages handed to the model: ${num(v.passages)}.` : null,
+    ...(v.problems ?? []).map((p) => `Problem${where(p) ? ` at ${where(p)}` : ": "}${p.said}`),
+    sampleLine(v.sample),
+  ];
+  return [...lines, ...inner.filter(Boolean).map((l) => `    ${l}`)];
+}
+
+// The time is said at one request at a time, the pace every run starts at; a door the run widens
+// finishes sooner. While the read is still writing trials the counts are what it has so far.
+function readyLine(r) {
+  if (!r || !r.trials) return null;
+  const soFar = r.reading ? " so far" : "";
+  const fit = has(r.planned) && r.planned > r.trials ? `${num(r.trials)} of the ${plural(r.planned, "trial")} written${soFar}, the ones that fit in one run` : `${plural(r.trials, "trial")}${soFar}`;
+  // The time at the widest the run goes, and at one request at a time when that differs: the run
+  // ramps up only while replies keep pace, and a one-at-a-time app holds it to one.
+  const one = r.atOne;
+  const slower = one && has(one.minutes) && (one.minutes !== r.minutes || one.trials < r.trials);
+  const time = has(r.minutes) && (slower
+    ? `about ${plural(r.minutes, "minute")} if your app answers several requests at once, or up to about ${plural(one.minutes, "minute")}${one.trials < r.trials ? ` and ${plural(one.trials, "trial")}` : ""} if it answers one at a time`
+    : `about ${plural(r.minutes, "minute")}`);
+  const usd = (x) => `$${x.toFixed(2)}`;
+  const cost = has(r.usd) && `about ${usd(r.usd)}${has(r.usdHigh) ? ` to ${usd(r.usdHigh)}` : ""}${soFar} on your ${r.provider ? `${r.provider} ` : ""}key${r.model ? ` for ${r.model}` : ""}${r.estimated ? ", estimated from the length of the text since your provider sent no token counts" : ""}`;
+  const parts = [fit, has(r.replies) && `about ${plural(r.replies, "reply", "replies")}`, time, cost].filter(Boolean);
+  const rules = !has(r.rules) ? "" : r.rules === 0 ? " No rules of your own were read from the code, so the run checks replies against generic standards." : ` Replies are checked against the ${plural(r.rules, "rule")} read from your code.`;
+  return `A run on the proven endpoints: ${parts.join(", ")}.${r.reading ? " The read is still adding trials; the run waits for it and plays them all." : ""}${rules}`;
+}
+
+// `data`: what the command did with the app's stores and services, said right under the run it is
+// about, so what a run writes into for real is read before Run is pressed.
+export function contactLines(c, data = []) {
+  const said = data.map((s) => `Data: ${s}`);
+  if (!c) return said;
+  const proven = c.proven ?? [];
+  const lines = proven.length ? [`Endpoints your own requests proved (${num(proven.length)}):`, ...proven.flatMap(doorLines)] : ["No request has reached the app's model yet."];
+  const missing = c.notCalled ?? [];
+  if (missing.length) lines.push(`Endpoints the read found that no request has reached (${num(missing.length)}):`, ...missing.map((m) => `  ${m.method} ${m.path}${m.file ? `  ${at(m.file, m.line)}` : ""}${m.excluded ? `  ${m.excluded}` : ""}`));
+  const ready = readyLine(c.ready);
+  if (ready) lines.push(ready);
+  for (const b of c.ready?.blocked ?? []) lines.push(`Run waits${sideOf(b.side)}: ${b.door}: ${b.why}${b.question ? ` ${b.question}` : ""}`);
+  return [...lines, ...said];
+}

package/lib/data.mjs

@@ -2,24 +2,21 @@
 // records by the hundred; written into the file your app keeps its real data in, they stay there
 // after the run. So an app started here runs against a copy of its database file, made in this
 // command's own temp folder and pointed at through the same variable, and the original is never
-// opened. What cannot be copied (a database server, a file your code names with no variable in
-// front of it, an app that was already running) is said before the first run, in one sentence.
+// opened. What cannot be copied (a file your code names with no variable in front of it, an app that
+// was already running) is said before the first run, in one sentence. A database server is copied
+// on its own server (lib/stores.mjs).
 import { copyFileSync, cpSync, existsSync, mkdirSync, readdirSync, readFileSync, statSync } from "node:fs";
 import { basename, dirname, isAbsolute, join, relative, resolve } from "node:path";
+import { storesOf } from "./stores.mjs";
 
 const FILE_DB = /\.(?:db|sqlite3?|duckdb)$/i;
 // sqlite:///x.db (SQLAlchemy, relative), sqlite:////abs/x.db, sqlite+aiosqlite:///x.db, file:./dev.db (Prisma, libsql).
 const FILE_URL = /^(sqlite(?:\+\w+)?:\/\/\/|file:(?:\/\/(?=\/))?)([^?]*)(\?.*)?$/i;
-const SERVER_URL = /^(postgres(?:ql)?|mysql|mariadb|mongodb(?:\+srv)?|mssql|sqlserver|cockroachdb)(?:\+\w+)?:\/\//i;
-const ENGINE = { postgres: "Postgres", postgresql: "Postgres", cockroachdb: "CockroachDB", mysql: "MySQL", mariadb: "MariaDB", mongodb: "MongoDB", "mongodb+srv": "MongoDB", mssql: "SQL Server", sqlserver: "SQL Server" };
 
-// What one value names: a database file (with how to write the value again for another path), a
-// database server, or nothing.
+// What one value names: a database file, with how to write the value again for another path, or nothing.
 export function databaseOf(value) {
   const v = String(value ?? "").trim();
   if (!v) return null;
-  const server = SERVER_URL.exec(v);
-  if (server) return { server: ENGINE[server[1].toLowerCase()] ?? server[1] };
   const url = FILE_URL.exec(v);
   if (url) {
     const path = decodeURIComponent(url[2]);
@@ -56,7 +53,7 @@ const sizeOf = (dir, cap) => {
 const DEFAULTED = /(?:os\.(?:environ\.get|getenv)|\bgetenv)\(\s*['"]([A-Za-z_]\w*)['"]\s*,\s*['"]([^'"\n]+)['"]|process\.env(?:\.([A-Za-z_]\w*)|\[\s*['"]([A-Za-z_]\w*)['"]\s*\])\s*(?:\?\?|\|\|)\s*['"]([^'"\n]+)['"]/g;
 // A database file opened by a path written in the code, with no variable in front of it.
 const OPENED = /(?:sqlite3\.connect|aiosqlite\.connect|duckdb\.connect|new\s+(?:sqlite3\.)?Database|create_(?:async_)?engine)\(\s*['"]([^'"\n]+)['"]/g;
-const CODE = /\.(?:[cm]?[jt]sx?|py|rb|go|php)$/;
+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$/;
 // A folder bigger than this is not copied: said instead, so the person decides.
@@ -72,7 +69,7 @@ function scan(sources) {
     for (const m of text.matchAll(DEFAULTED)) {
       const name = m[1] ?? m[3] ?? m[4];
       const value = m[2] ?? m[5];
-      if (name && !(name in defaults) && databaseOf(value)) defaults[name] = value;
+      if (name && !(name in defaults) && (databaseOf(value) || storesOf({ [name]: value }).length)) defaults[name] = value;
     }
     for (const m of text.matchAll(OPENED)) { const db = databaseOf(m[1]); if (db?.path) opened.push({ file, path: db.path }); }
   }
@@ -90,7 +87,8 @@ function located(db, dirs, appDir) {
 }
 
 // values: the environment the app will start with, names to values. from: the env file each name
-// was read from, when there is one. Returns the variables to start the app with, and what to say.
+// was read from, when there is one. Returns the variables to start the app with, what to say, and
+// the settings with the code's own defaults beside them, which the stores are read from.
 export function keepData({ values, from = {}, appDir, root = appDir, work, sources = [], started = true }) {
   const { defaults, opened } = scan(sources);
   const all = { ...defaults, ...values };
@@ -114,10 +112,6 @@ export function keepData({ values, from = {}, appDir, root = appDir, work, sourc
       continue;
     }
     if (!db) continue;
-    if (db.server) {
-      said.push(`Trials write into the ${db.server} database ${name} names: a database server cannot be copied here, so what a run creates stays in it. Point ${name} at a scratch database before a run if that one holds real data.`);
-      continue;
-    }
     const original = located(db, from[name] ? [dirname(from[name])] : [], appDir);
     moved.add(original);
     if (!started) {
@@ -139,5 +133,5 @@ export function keepData({ values, from = {}, appDir, root = appDir, work, sourc
     moved.add(cwdPath);
     said.push(`Your app opens ${o.path} by a path written in ${rel(o.file)}, with no variable to point it at a copy: trials write into that file.`);
   }
-  return { env, copied, said };
+  return { env, copied, said, values: all };
 }