cortad 0.3.1-rc.9 → 0.3.2

package/lib/qdrant.mjs

@@ -0,0 +1,47 @@
+// A Qdrant collection copied for a session into a new collection of the same server, point by point
+// over Qdrant's own HTTP API with the vectors, payloads and payload indexes it holds, and deleted
+// after. The key, when the server has one, travels in its header.
+export const QDRANT_CAP = 200_000;
+const BATCH = 256;
+const at = (name) => `/collections/${encodeURIComponent(name)}`;
+
+async function call(conn, method, path, body) {
+  const res = await fetch(`${conn.base}${path}`, {
+    method,
+    headers: { "content-type": "application/json", ...(conn.apiKey ? { "api-key": conn.apiKey } : {}) },
+    body: body === undefined ? undefined : JSON.stringify(body),
+    signal: AbortSignal.timeout(30_000),
+  });
+  const data = await res.json().catch(() => null);
+  if (!res.ok) throw Object.assign(new Error(String(res.status)), { why: res.status === 401 || res.status === 403 ? "auth" : res.status === 404 ? "gone" : "other" });
+  return data?.result;
+}
+const whyOf = (e) => e?.why ?? (/ECONNREFUSED|fetch failed|timeout/i.test(String(e?.cause?.code ?? e?.message)) ? "down" : "other");
+
+// A collection the server does not hold yet is one the app makes on first use: pointed at the copy's
+// name, it makes that one instead, and it is deleted like any copy.
+export async function cloneQdrant(conn, source, clone) {
+  let info;
+  try { info = await call(conn, "GET", at(source)); } catch (e) { return e?.why === "gone" ? { how: "empty" } : { why: whyOf(e) }; }
+  if ((info.points_count ?? 0) > QDRANT_CAP) return { why: "big" };
+  let made = false;
+  try {
+    const { vectors, sparse_vectors, on_disk_payload } = info.config.params;
+    await call(conn, "PUT", at(clone), { vectors, ...(sparse_vectors ? { sparse_vectors } : {}), ...(on_disk_payload === undefined ? {} : { on_disk_payload }) });
+    made = true;
+    for (const [field_name, schema] of Object.entries(info.payload_schema ?? {})) await call(conn, "PUT", `${at(clone)}/index?wait=true`, { field_name, field_schema: schema.params ?? schema.data_type });
+    for (let offset; ;) {
+      const page = await call(conn, "POST", `${at(source)}/points/scroll`, { limit: BATCH, with_payload: true, with_vector: true, ...(offset === undefined ? {} : { offset }) });
+      if (page.points.length) await call(conn, "PUT", `${at(clone)}/points?wait=true`, { points: page.points.map(({ id, vector, payload }) => ({ id, vector, payload })) });
+      offset = page.next_page_offset;
+      if (offset === null || offset === undefined) return { how: "points" };
+    }
+  } catch (e) {
+    if (made) await dropQdrant(conn, clone);
+    return { why: whyOf(e) };
+  }
+}
+
+export async function dropQdrant(conn, clone) {
+  try { await call(conn, "DELETE", at(clone)); return true; } catch (e) { return e?.why === "gone"; }
+}

package/lib/reach.mjs

@@ -0,0 +1,223 @@
+import { isIPv4 } from "node:net";
+import { unreached } from "./contact-text.mjs";
+import { plural, upper } from "./words.mjs";
+
+// One request to each endpoint status lists as not reached, from this machine to the app on its port.
+// Each body is the one Cortad read that endpoint's client sending (the server's `request`).
+// The connect command sends these by itself, one at a time, each tagged x-cortad-turn: reach:auto:<n>
+// (sendOurs), signed in only as a test account this machine made. Headers are never the agent's: they
+// go from here to the app on this machine and nowhere else, and only their names are printed. These
+// are real requests with real effects.
+
+// Under the 60 seconds Codex, Cursor CLI and Copilot CLI give an MCP call, with the status read first.
+export const REACH_MS = 55_000;
+const SAID_CHARS = 200;
+const NAME = /^[!#$%&'*+.^_`|~0-9A-Za-z-]{1,100}$/;
+const RUN_TURN = "x-cortad-turn";
+const loopback = (host) => host === "::1" || (isIPv4(host) && host.startsWith("127."));
+const keyOf = (m) => `${m.method} ${m.path}`;
+const appUrl = (runner) => new URL(`http://${runner.host === "::1" ? "[::1]" : runner.host ?? "127.0.0.1"}:${runner.port}`);
+
+// Why nothing can be sent to the app this record names, or null.
+export function notUp(runner) {
+  if (runner?.state !== "up") {
+    return !runner ? "No connect command is running for this repository, so no app is up on this machine."
+      : runner.state === "failed" ? upper(runner.error) : "Your app is still starting.";
+  }
+  const host = runner.host ?? "127.0.0.1";
+  return loopback(host) ? null : `${host} is not this machine; reach sends only to your app on this machine.`;
+}
+
+// The rows a call sends and the ones it leaves: the named paths, else every row with a ready request
+// that is not marked by hand.
+export function picked(contact, receipts, paths = []) {
+  const rows = unreached(contact, receipts);
+  const named = new Set(Array.isArray(paths) ? paths : []);
+  const chosen = named.size ? rows.filter((m) => named.has(m.path) || named.has(keyOf(m))) : rows.filter((m) => !m.unsure);
+  const sent = chosen.filter((m) => m.request);
+  return {
+    rows, sent,
+    left: (named.size ? chosen : rows).filter((m) => !m.excluded && !sent.includes(m)),
+    unknown: [...named].filter((p) => !rows.some((m) => p === m.path || p === keyOf(m))),
+  };
+}
+
+// `runner`: this machine's record of the app (lib/runner.mjs); `contact`: status's section of the same name.
+export async function reach({ runner, contact, headers = {}, paths = [], fetchImpl = fetch }) {
+  const down = notUp(runner);
+  if (down) return refused(down);
+  const sign = headersOf(headers);
+  if (sign.error) return refused(sign.error);
+  const pick = picked(contact, runner.receipts, paths);
+  const app = appUrl(runner);
+  const secrets = secretsIn(sign.headers);
+  const names = Object.keys(sign.headers);
+  // Without a test sign-in the request is Cortad's own, and tagged so.
+  let n = 0;
+  const headersFor = () => (names.length ? sign.headers : { [RUN_TURN]: `reach:agent:${++n}` });
+  const answers = await Promise.all(pick.sent.map((m) => sendOne(m, app, headersFor(), fetchImpl, secrets)));
+  return { text: reachText(pick, answers, `${runner.port} at once${names.length ? `, with the headers ${names.join(", ")}` : ""}`) };
+}
+
+// What a reach did, for the agent: each endpoint's status and time, and what was not sent.
+export function reachText({ rows, sent, left, unknown }, answers, how) {
+  return [
+    sent.length ? `Sent ${plural(sent.length, "request")} to your app on port ${how}:`
+      : rows.length ? "Nothing was sent." : "Nothing was sent: status lists no endpoint that no request has reached.",
+    ...answers.map((a) => `  ${a.line}`),
+    ...(left.length ? ["Not sent:", ...left.map((m) => `  ${m.method} ${m.path}: ${whyNot(m)}`)] : []),
+    unknown.length ? `Not among the endpoints no request has reached: ${unknown.join(", ")}.` : "",
+    sent.length ? "status shows which of them reached your model." : "",
+    "next: status",
+  ].filter(Boolean).join("\n");
+}
+
+// Cortad's own test requests, sent by the connect command: one at a time, so what the app prints
+// belongs to one of them, each with the app's own origin where one is known. An endpoint that answers
+// 401 or 403 is asked once more as the test account this machine signed in, when there is one
+// (`signIn(row)` gives { name, value } or null); the token never leaves this machine.
+// `stop()`: true when the rest should wait, for the agent's ask; the answers so far come back.
+// Four at a time: one each in turn left a 22-endpoint app waiting nearly two minutes behind its two
+// slowest replies (ulaim, 2026-10-06). Answers keep the rows' order; a row is not sent once stop() says so.
+const AT_ONCE = 4;
+export async function sendOurs(rows, { runner, origin, signIn = async () => null, next, stop = () => false, fetchImpl = fetch, atOnce = AT_ONCE }) {
+  const app = appUrl(runner);
+  const base = () => ({ ...(origin ? { origin, referer: `${origin}/` } : {}), [RUN_TURN]: `reach:auto:${next()}` });
+  const answers = [];
+  let at = 0, stopped = false;
+  const one = async (m) => {
+    let got = await sendOne(m, app, base(), fetchImpl);
+    if (refusedVisitor(got)) {
+      const as = await signIn(m).catch(() => null);
+      if (as?.name && as.value) {
+        const again = await sendOne(m, app, { ...base(), [as.name]: as.value }, fetchImpl, secretsIn({ [as.name]: as.value }));
+        got = { ...again, signedIn: true, line: `${again.line} Sent as a test account.` };
+      }
+    }
+    return got;
+  };
+  const lane = async () => {
+    while (at < rows.length) {
+      if (stopped || stop()) { stopped = true; return; }
+      const i = at++;
+      answers[i] = await one(rows[i]);
+    }
+  };
+  await Promise.all(Array.from({ length: Math.min(atOnce, rows.length) }, lane));
+  // Rows never sent leave no hole: the answers stop where the first unsent row was.
+  const end = answers.findIndex((a) => a === undefined);
+  return end === -1 ? answers : answers.slice(0, end);
+}
+const refusedVisitor = (a) => a.status === 401 || a.status === 403;
+
+// One line for the terminal per batch: "tested 6 endpoints: 5 answered, 1 needs a signed-in user",
+// or null when none reached the app. A row never sent, or cut by a restart and sent again later, is
+// no test; one refused as a test account too failed.
+export function testedLine(answers) {
+  const tested = answers.filter((a) => !a.unsent && !a.down);
+  if (!tested.length) return null;
+  const answered = tested.filter((a) => a.ok).length;
+  const signIn = tested.filter((a) => refusedVisitor(a) && !a.signedIn).length;
+  const failed = tested.length - answered - signIn;
+  return `tested ${plural(tested.length, "endpoint")}: ${[
+    `${answered} answered`,
+    failed && `${failed} failed`,
+    signIn && `${signIn} ${signIn === 1 ? "needs" : "need"} a signed-in user`,
+  ].filter(Boolean).join(", ")}`;
+}
+
+const refused = (why) => ({ text: `${why} Nothing was sent.\nnext: status`, isError: true });
+
+const whyNot = (m) => m.byHand ?? (m.request ? "Cortad is not sure it reaches your model; name its path to reach to send it." : "Cortad has no request ready for it.");
+
+// The headers as the caller passed them, checked at this edge: never echoed back, a bad one named only
+// when its name is a header name, and the run's own header dropped.
+export function headersOf(given) {
+  if (!given || typeof given !== "object" || Array.isArray(given)) return { error: "Headers are passed as names with their values." };
+  const headers = {};
+  for (const [name, value] of Object.entries(given)) {
+    if (!NAME.test(name) || typeof value !== "string") return { error: "Each header is passed as a name and a value." };
+    if (/[\r\n\0]/.test(value)) return { error: `The value of the header ${name} holds a line break.` };
+    if (name.toLowerCase() !== RUN_TURN) headers[name] = value;
+  }
+  return { headers };
+}
+
+// What the sign-in is made of, long enough to be a secret, so it is never printed even where the app
+// writes it into its answer.
+// ponytail: a value the app re-encodes before writing it back (URL or JSON escaping) is not matched.
+const secretsIn = (headers) => [...new Set(Object.values(headers).flatMap((v) => [v, ...v.split(/[\s;,=]+/)]))]
+  .filter((s) => s.length >= 8).sort((a, b) => b.length - a.length);
+const masked = (text, secrets) => secrets.reduce((t, s) => t.split(s).join("[sign-in]"), text);
+
+// Sent only where the address, parsed, is still the app's own, and the listed endpoint's own: a path
+// the server sent is never trusted to keep the host, nor to be the endpoint the line names. A request
+// listed as POST /api/chat went to another address of the app with the person's sign-in while the
+// line printed said /api/chat (the release review of 2026-10-05).
+const sameRoute = (listed, sent) => {
+  const [a, b] = [String(listed).split("?")[0].split("/"), sent.split("/")];
+  return a.length === b.length && a.every((part, i) => (/^(?::|\{|\[|\*)/.test(part) ? b[i] !== "" : part === b[i]));
+};
+// What a message to a control route does is not a reply. The server never prepares one
+// (src/local/unreached.ts sendFor, the same two patterns); the command does not take its word for it.
+const ADMIN_CONTROL = /(?:^|\/)(?:admin|setup|settings?|configs?|configuration|billing|keys?|tokens?|users?|logout|import|export|uploads?|files?)(?:[-_/]|$|\?)/i;
+const SETTINGS_WRITE = /(?:^|[/_-])(?:admin|setup|settings?|configs?|configuration|billing)(?:[-_/]|$|\?)/i;
+export async function sendOne(m, app, headers, fetchImpl, secrets = []) {
+  const { method, path } = m.request;
+  const body = withImages(m.request.body);
+  const label = `${m.method} ${m.path}`;
+  const url = /^\/(?!\/)/.test(String(path)) ? new URL(`${app.origin}${path}`) : null;
+  if (url?.origin !== app.origin || !/^(?:GET|POST)$/.test(method)) return { line: `${label}: not sent, its request is not one to this app.`, ok: false, status: 0, unsent: true };
+  if (method !== m.method || !sameRoute(m.path, url.pathname)) return { line: `${label}: not sent, the request prepared for it goes to another address.`, ok: false, status: 0, unsent: true };
+  if (ADMIN_CONTROL.test(url.pathname) || (method !== "GET" && SETTINGS_WRITE.test(url.pathname))) return { line: `${label}: not sent, its address says it administers your app.`, ok: false, status: 0, unsent: true };
+  const json = body !== undefined && method === "POST";
+  const typed = Object.keys(headers).some((k) => k.toLowerCase() === "content-type");
+  const started = performance.now();
+  const seconds = () => `${((performance.now() - started) / 1000).toFixed(1)} seconds`;
+  let res;
+  try {
+    res = await fetchImpl(url, { method, headers: json && !typed ? { "content-type": "application/json", ...headers } : headers,
+      ...(json ? { body: JSON.stringify(body) } : {}), redirect: "manual", signal: AbortSignal.timeout(REACH_MS) });
+  } catch (err) {
+    return { line: `${label}: ${failedSaid(err, app.port || 80)}`, ok: false, status: 0, down: /^(?:ECONNREFUSED|ECONNRESET)$/.test(err?.cause?.code ?? err?.code ?? "") };
+  }
+  let text;
+  try { text = await res.text(); } catch { return { line: `${label}: ${res.status}, and the answer had not finished after ${REACH_MS / 1000} seconds.`, ok: false, status: res.status }; }
+  const ok = res.status >= 200 && res.status < 300;
+  const said = ok ? "" : masked(text || res.headers.get("location") || "", secrets).replace(/\s+/g, " ").trim().slice(0, SAID_CHARS);
+  return { line: `${label}: ${res.status} in ${seconds()}.${said ? ` Your app answered: "${said}"` : ""}`, ok, status: res.status };
+}
+
+// A real 64x64 PNG where the request carries an image and the server sent none: a made-up string in
+// an image field is refused by the app before its model sees it. The same rule as the server's
+// (src/local/unreached.ts withImages); a link, or an image already, stays.
+const PNG_64 = "iVBORw0KGgoAAAANSUhEUgAAAEAAAABACAIAAAAlC+aJAAAAS0lEQVR42u3PMQ0AAAwDoPo33UrYvQQckD4XAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAYHLAMpT0sIcNbcEAAAAAElFTkSuQmCC";
+const IMAGE_FIELD = /(?:image|img|photo|picture|screenshot)s?(?:[_-]?(?:base64|b64|data|url|uri|src|file|content))?$/i;
+const MIME_FIELD = /^(?:mime|mime_?type|content_?type|media_?type|image_?type)$/i;
+const IMAGE_BYTES = [[0x89, 0x50, 0x4e, 0x47], [0xff, 0xd8, 0xff], [0x47, 0x49, 0x46], [0x52, 0x49, 0x46, 0x46]];
+const isImage = (v) => {
+  const bytes = Buffer.from(v.replace(/^data:image\/[\w.+-]+;base64,/, ""), "base64");
+  return IMAGE_BYTES.some((sig) => sig.every((b, i) => bytes[i] === b));
+};
+export function withImages(value) {
+  if (Array.isArray(value)) return value.map(withImages);
+  if (!value || typeof value !== "object") return value;
+  const out = {};
+  let placed = false;
+  for (const [k, v] of Object.entries(value)) {
+    if (typeof v === "string" && IMAGE_FIELD.test(k) && !/^https?:\/\//i.test(v.trim()) && !isImage(v)) {
+      out[k] = /url|uri|src/i.test(k) || v.startsWith("data:") ? `data:image/png;base64,${PNG_64}` : PNG_64;
+      placed = true;
+    } else out[k] = withImages(v);
+  }
+  if (placed) for (const k of Object.keys(out)) if (MIME_FIELD.test(k) && typeof out[k] === "string") out[k] = "image/png";
+  return out;
+}
+
+// Why a request got no answer, from the error's name and code alone: its message can quote a header.
+function failedSaid(err, port) {
+  if (err?.name === "TimeoutError" || err?.name === "AbortError") return `no answer within ${REACH_MS / 1000} seconds.`;
+  const code = err?.cause?.code ?? err?.code;
+  if (code === "ECONNREFUSED") return `nothing answers on port ${port}.`;
+  return `the connection failed${/^[A-Z_]{2,40}$/.test(code ?? "") ? ` (${code})` : ""}.`;
+}

package/lib/read-text.mjs

@@ -5,72 +5,119 @@ import { at, clip, has, num, pack, pageOf, plural, SIDE } from "./words.mjs";
 //
 // The full list comes back from GET /mcp/status?show=<name>: read.rules.all, read.machine.misses
 // complete with read.machine.mets, read.journeys.all, read.doors.all, read.trials.all. Where the API
-// has not sent it, what it did send is listed with "n of N listed".
-export const SHOW = ["rules", "standards", "journeys", "endpoints", "trials"];
+// has not sent it, what it did send is listed with "n of N listed". Where Cortad's team reviewed the
+// code by hand, read.machine is only `reviewed` and the lines that review cites: no standard is graded.
+// `records` lists the plain status's own `read.records`: the server sends them with every status.
+// `reviews` are the two reviews the read leaves, of the prompts and of the code around the model:
+// status hands them over once as news, and this lists them again.
+// `machine` is what the connect command does on this machine, from the runner's record alone.
+export const SHOW = ["rules", "standards", "journeys", "endpoints", "trials", "records", "reviews", "machine"];
 
 const rulesHead = (rules) => {
   const files = Array.isArray(rules.files) ? rules.files.length : rules.files;
   return `Rules in the code: ${num(rules.count)}${has(files) ? `, in ${plural(files, "file")}` : ""}.`;
 };
 // What the last run found about the rule beside it; a rule it never asked is not a rule that held.
-const measuredOf = (m) => (m === null ? "; not measured yet" : m ? `; asked of ${plural(m.asked, "reply", "replies")}, held in ${num(m.held)}${m.asked > m.held ? `, broke in ${num(m.asked - m.held)}` : ""}` : "");
+const measuredOf = (m) => (m === null ? "; asked of no reply yet" : m ? `; asked of ${plural(m.asked, "reply", "replies")}, passed in ${num(m.held)}${m.asked > m.held ? `, broke in ${num(m.asked - m.held)}` : ""}` : "");
 const ruleLine = (e) => `  ${e.path ? `${at(e.path, e.line)}  ` : ""}"${clip(e.text, 300)}"${"measured" in e ? measuredOf(e.measured) : ""}`;
 const headOf = (label, parts) => (parts.some(Boolean) ? `${label}: ${parts.filter(Boolean).join(", ")}.` : `${label}:`);
-const standardsHead = (m) => headOf("Engineering standards", [has(m.decided) && `${num(m.decided)} decided`, has(m.met) && `${num(m.met)} met`, has(m.missed) && `${num(m.missed)} missed${has(m.problems) ? `, from ${plural(m.problems, "problem")}` : ""}`]);
+// "28 decided, 28 met, 0 missed, from 0 problems" was four counts for one fact.
+// A review that decided nothing (it failed, or no standard applied) makes no claim: "meets all 0".
+const standardsHead = (m) => (!has(m.met) || !(m.met + (m.missed ?? 0)) ? "Engineering standards:"
+  : m.missed ? `Engineering standards: your code misses ${num(m.missed)} of the ${num(m.decided ?? m.met + m.missed)} Cortad checks${has(m.problems) ? `, through ${plural(m.problems, "problem")}` : ""}.`
+    : `Engineering standards: your code meets all ${num(m.met)} that Cortad checks.`);
+const REVIEWED_CODE = "The Cortad team reviewed the code around your model by hand instead of grading it against these standards, and status with show reviews lists what it found.";
 const decided = (x) => (x.decidedBy ? ` (decided by ${x.decidedBy === "code" ? "code" : "a model"})` : "");
 // A miss is one problem with the standards it fails beneath it; an older API sent one standard a row.
+// A problem their own documents waive says so, with the line; the server lists it last.
+const designed = (x) => (x.byDesign ? `\n    By design here, per ${x.byDesign.at}: "${clip(x.byDesign.said, 200)}"` : "");
 const standardLine = (x) => Array.isArray(x.standards)
-  ? `  ${x.path ? `${at(x.path, x.line)}  ` : ""}${clip(x.problem, 240)}${decided(x)}\n    ${x.standards.length === 1 ? "Fails" : `Fails ${num(x.standards.length)}`}: ${x.standards.join("; ")}`
+  ? `  ${x.path ? `${at(x.path, x.line)}  ` : ""}${clip(x.problem, 240)}${decided(x)}${x.fix ? `\n    ${clip(x.fix, 300)}` : ""}\n    ${x.standards.length === 1 ? "Fails" : `Fails ${num(x.standards.length)}`}: ${x.standards.join("; ")}${designed(x)}`
   : `  ${x.path ? `${at(x.path, x.line)}  ` : ""}${x.standard}${x.detail ? `: ${clip(x.detail, 240)}` : ""}${decided(x)}`;
 // Which trials can be played is decided when a run knocks: a read that said "21 playable, none held
 // back" was followed by a run that held 28 back, and three agents called the counts contradictory.
-const trialsHead = (t) => headOf("Trials", [has(t.written) && `${num(t.written)} written`]);
+const trialsHead = (t) => headOf("Conversations", [has(t.written) && `${num(t.written)} written`]);
 const heldWhy = (h) => `${SIDE[h.side] ? `, ${SIDE[h.side]}` : ""}${h.why ? `: ${clip(h.why, 300)}` : ""}`;
 const named = (label, group, max = 12) => {
   if (!group) return null;
   const names = group.names ?? [];
   const more = (group.count ?? names.length) - Math.min(names.length, max);
-  const list = names.slice(0, max).join(", ");
-  return `${label} (${num(group.count ?? names.length)})${list ? `: ${list}${more > 0 ? `, and ${more} more` : ""}` : ""}.`;
+  // A name may hold commas ("A student, Grade 10 Sem 2 (Jordan), English"): one name ends at a semicolon.
+  const list = names.slice(0, max).join("; ");
+  return `${label} (${num(group.count ?? names.length)})${list ? `: ${list}${more > 0 ? `; and ${more} more` : ""}` : ""}.`;
 };
 // "Journeys (6):" when every one is here, "Journeys (6), 4 listed:" when not.
 const counted = (label, count, n) => `${label} (${num(count ?? n)})${has(count) && n < count ? `, ${num(n)} listed` : ""}:`;
 
 // The records the app already holds, read from its own data files, that a trial may name: an agent
 // that sees a trial ask about SO20260810001 can tell it is a real order, not an invented one.
-const recordsLine = (records) => {
-  const collections = (records?.collections ?? []).filter((c) => c?.name && c.examples?.length);
-  if (!collections.length) return null;
-  return `Records the trials can name: ${collections.map((c) => `${c.name} (${c.examples.slice(0, 3).map((e) => clip(e, 40)).join(", ")})`).join(", ")}.`;
-};
+// Listed with show records, never in the walkthrough: ulaim's was 45 ids in one line.
+const recordLines = (records) => (records?.collections ?? []).filter((c) => c?.name && c.examples?.length)
+  .map((c) => `  ${c.name}: ${c.examples.slice(0, 3).map((e) => clip(e, 40)).join(", ")}`);
 
 // The walkthrough, in the order the person is walked through it.
+// The endpoints are listed above it, proven or not reached, and the questions are the rules and
+// standards counted again: neither is said here, and status with show lists every section in full.
 export function readLines(r) {
   const lines = ["What Cortad read:"];
   if (r.rules) {
     const examples = (r.rules.examples ?? []).slice(0, 3);
-    lines.push(`${rulesHead(r.rules)}${examples.length ? ` ${examples.length} of them:` : ""}`, ...examples.map(ruleLine));
+    // "Asked of no reply yet" on each rule before any run is a fact about no run.
+    const ran = has(r.rules.measured);
+    lines.push(`${rulesHead(r.rules)}${examples.length ? ` ${examples.length} of them:` : ""}`, ...examples.map((e) => ruleLine(ran ? e : { text: e.text, path: e.path, line: e.line })));
   }
-  for (const line of [named("Journeys", r.journeys), named("Simulated users", r.profiles), named("Endpoints", r.doors), recordsLine(r.records)]) if (line) lines.push(line);
+  for (const line of [named("Journeys", r.journeys), named("Simulated users", r.profiles)]) if (line) lines.push(line);
   const m = r.machine;
-  if (m) {
+  if (m && (m.met || m.missed || (m.misses ?? []).length)) {
     const misses = m.misses ?? [];
     // "3 missed" was read off a list of three under a head that said thirteen: the list says it is a part.
     lines.push(standardsHead(m), ...(misses.length > 3 && has(m.missed) && m.missed > 3 ? [`  3 of the ${num(m.missed)} missed:`] : []), ...misses.slice(0, 3).map(standardLine));
     const more = (m.problems ?? misses.length) - Math.min(misses.length, 3);
     if (more > 0) lines.push(`  and ${plural(more, "more problem")}; status with show standards lists them all.`);
   }
-  const q = r.questions;
-  if (q) lines.push(`Questions: ${num(q.total)}${has(q.everywhere) ? `; ${num(q.everywhere)} asked in every conversation` : ""}${has(q.placed) ? `, ${num(q.placed)} placed in the situations they fit` : ""}.`);
-  const t = r.trials;
-  if (t) lines.push(trialsHead(t), ...(t.held ?? []).map((h) => `  ${h.surface}: ${plural(h.n, "trial")} held back${heldWhy(h)}`));
+  if (r.reviews?.lines.length) lines.push("The reviews of your prompts and of the code around your model are listed whole by status with show reviews.");
+  // What a run plays is the quote's to say; here only conversations set aside, and why.
+  const held = r.trials?.held ?? [];
+  if (held.length) lines.push("Conversations set aside:", ...held.map((h) => `  ${h.surface}: ${plural(h.n, "conversation")}${heldWhy(h)}`));
+  return lines.length > 1 ? lines : [];
+}
+
+// Where each coding agent keeps the entry the connect command writes for Cortad, in the home folder.
+const listed = (names) => (names.length > 1 ? `${names.slice(0, -1).join(", ")} and ${names.at(-1)}` : names[0]);
+
+// What the connect command does on this machine, from the facts it keeps in the runner's record:
+// what it started and stops, the database copies, the settings its app runs with, what it loads,
+// what a run holds and puts back, and what it keeps and writes outside this repository. At most
+// eight lines, the two for the person first.
+export function machineText(f) {
+  if (!f) return ["No connect command is running for this repository now, so nothing Cortad started is running here."];
+  const lines = [
+    f.started
+      ? `For the person: Cortad started your app in ${f.dir === "." ? "this folder" : f.dir} and stops it, with everything it started for it, when you press Ctrl-C in its terminal; your code and settings files are never edited.`
+      : `For the person: Cortad uses your app already running on port ${f.port} and leaves it running when you press Ctrl-C in its terminal; your code and settings files are never edited.`,
+    f.copies === "made"
+      ? "For the person: Where Cortad could copy a database, your app runs on the copy, made from your own at every connect and deleted when this command ends, so records created in a copy are gone at the next connect; keep records every run needs in your own database. Each Data line in status says what happens to one store."
+      : "For the person: No copy of a database was made for this session, so what test conversations create stays where your app keeps its data; each Data line in status names one store.",
+  ];
+  // Env values reach only a process the command started itself.
+  if (f.started) lines.push(f.changed?.length ? `Your env file values go into your app's process alone, with ${listed(f.changed)} set for this session only; no value is sent to Cortad.` : "Your env file values go into your app's process alone, unchanged; no value is sent to Cortad.");
+  lines.push(f.hooked ? "A hook loaded into your app records each request that reaches a model and the model calls it makes; request headers stay on this machine and are deleted when the command stops."
+    : f.proxy ? `A local proxy on port ${f.proxy} sees each request sent to it and the model calls your app makes through it; request headers stay on this machine and are deleted when the command stops.`
+      : "Nothing is loaded into your app, since Cortad did not start it, so its model calls are not seen.");
+  // Only the hook holds a write or records a file: through the proxy, or with nothing loaded, both go as the app does them.
+  lines.push(f.hooked ? "During a run, a write your app sends to a service off this machine, such as a payment or an email, is answered inside your app and never sent, unless it carries a test key, goes to a provider's sandbox, or goes to a host you said yes to on the card; a call named as a read where every call is a POST, such as customers.get, goes out."
+    : "During a run, a write your app sends to a service off this machine, such as a payment or an email, is sent for real.");
+  lines.push(f.hooked ? "Files your app writes in its own folder during a run are put back when run_status reads the run's end; its log files are left as they are." : "Files your app writes in its own folder stay as it writes them.");
+  lines.push("Kept between connects in ~/.cortad on this machine: this repository's key for later runs, the key the test accounts' passwords are made from, the files to put back, a list of what to undo, and your app's output from the last session with the values from your env files masked, which the next connect starts over.");
   return lines;
 }
 
 export function showText(d, show, page = 1) {
-  if (!d.read) return "Cortad is still reading this repository.";
+  if (!d.read || (d.read.complete === false && show !== "reviews")) return "Cortad is still reading this repository.";
   const { head, lines, continued } = sectionOf(d.read, show);
-  return pageOf(pack(head, lines, continued), page, (n) => `status with show ${show} and page ${n}`);
+  // A heading with nothing under it ("Endpoints (0):") reads as a list that failed to print.
+  const said = lines.length || !head.endsWith(":") ? head : `${head.replace(/ \(0\):$|:$/, "")}: none yet.`;
+  return pageOf(pack(said, lines, continued), page, (n) => `status with show ${show} and page ${n}`);
 }
 
 function sectionOf(r, show) {
@@ -82,6 +129,7 @@ function sectionOf(r, show) {
     }
     case "standards": {
       const m = r.machine ?? {};
+      if (m.reviewed) return { head: REVIEWED_CODE, lines: [], continued: "" };
       const misses = m.misses ?? [];
       const mets = m.mets ?? [];
       return {
@@ -98,12 +146,18 @@ function sectionOf(r, show) {
       const all = r.doors?.all ?? (r.doors?.names ?? []).map((name) => ({ name }));
       return { head: counted("Endpoints", r.doors?.count, all.length), lines: all.map((e) => `  ${e.name}${e.path ? `: ${[e.method, e.path].filter(Boolean).join(" ")}` : ""}`), continued: "Endpoints, continued." };
     }
+    case "records":
+      return recordLines(r.records).length
+        ? { head: "Records a conversation can name, three of each:", lines: recordLines(r.records), continued: "Records, continued." }
+        : { head: "Reading your code found no records a conversation can name.", lines: [], continued: "" };
+    case "reviews":
+      return { head: "The reviews of your prompts and of the code around your model:", lines: r.reviews?.lines.length ? r.reviews.lines : [r.complete === false ? "Your code is still being read; the reviews come when that is done." : r.reviews ? "Reading your code left no review of this app's prompts or code." : "This status carries no reviews."], continued: "The reviews, continued." };
     case "trials":
     default: {
       const t = r.trials ?? {};
       const all = t.all ?? (t.held ?? []).map((h) => ({ surface: h.surface, held: h.n, why: h.why, side: h.side }));
-      const line = (x) => `  ${x.surface}: ${[has(x.written) && `${num(x.written)} written`, has(x.playable) && `${num(x.playable)} playable`, x.held && `${num(x.held)} held back`].filter(Boolean).join(", ")}${x.held ? heldWhy(x) : ""}`;
-      return { head: trialsHead(t), lines: all.map(line), continued: "Trials, continued." };
+      const line = (x) => `  ${x.surface}: ${[has(x.written) && `${num(x.written)} written`, has(x.playable) && `${num(x.playable)} playable`, x.held && `${num(x.held)} set aside`].filter(Boolean).join(", ")}${x.held ? heldWhy(x) : ""}`;
+      return { head: trialsHead(t), lines: all.map(line), continued: "Conversations, continued." };
     }
   }
 }

package/lib/redis.mjs

@@ -0,0 +1,130 @@
+// A Redis database copied for a session into an empty logical database of the same server, and
+// emptied after. Spoken over the wire here (RESP), so nothing needs redis-cli on this machine and
+// the password never sits on a command line.
+import { connect as tcp } from "node:net";
+import { connect as tls } from "node:tls";
+
+// A database with more keys than this is not copied: said instead.
+export const REDIS_CAP = 200_000;
+// Written into the copy, so an emptying after a crash only ever empties a database this command
+// filled: a database index can be taken by something else between two sessions.
+export const MARKER = "__cortad_copy__";
+const BATCH = 500;
+
+// One connection, commands sent in batches and answered in order.
+async function open({ host, port, tlsOn, user, password }) {
+  const socket = await new Promise((ok, no) => {
+    const s = (tlsOn ? tls : tcp)({ host: host || "127.0.0.1", port, ...(tlsOn ? { servername: host } : {}) });
+    s.setTimeout(10_000, () => s.destroy(new Error("timeout")));
+    s.once(tlsOn ? "secureConnect" : "connect", () => ok(s));
+    s.once("error", no);
+  });
+  let buf = Buffer.alloc(0);
+  const waiting = [];
+  const replies = [];
+  socket.on("data", (chunk) => {
+    buf = Buffer.concat([buf, chunk]);
+    for (let r; (r = parse(buf, 0)); ) { buf = buf.subarray(r.end); replies.push(r.value); }
+    while (waiting.length && replies.length >= waiting[0].n) { const w = waiting.shift(); w.ok(replies.splice(0, w.n)); }
+  });
+  socket.on("error", (e) => { for (const w of waiting.splice(0)) w.no(e); });
+  const send = (cmds) => new Promise((ok, no) => {
+    waiting.push({ n: cmds.length, ok, no });
+    socket.write(Buffer.concat(cmds.map(encode)));
+  });
+  const client = { send, one: async (...cmd) => (await send([cmd]))[0], close: () => socket.end() };
+  if (password) {
+    const said = await client.one(...(user ? ["AUTH", user, password] : ["AUTH", password]));
+    // A development server with no password set refuses AUTH itself; the app connects the same way.
+    if (said instanceof Error && !/without any password configured|no password is set/i.test(said.message)) { client.close(); throw Object.assign(new Error("auth"), { why: "auth" }); }
+  }
+  return client;
+}
+
+// Arguments go as bytes: a key is whatever bytes the app named it with, and it is copied as such.
+const encode = (cmd) => Buffer.concat([Buffer.from(`*${cmd.length}\r\n`), ...cmd.flatMap((a) => {
+  const b = Buffer.isBuffer(a) ? a : Buffer.from(String(a));
+  return [Buffer.from(`$${b.length}\r\n`), b, Buffer.from("\r\n")];
+})]);
+
+// One reply from buf at i, or null until the whole of it has arrived.
+function parse(buf, i) {
+  const eol = buf.indexOf("\r\n", i);
+  if (eol < 0) return null;
+  const type = String.fromCharCode(buf[i]);
+  const line = buf.subarray(i + 1, eol).toString();
+  if (type === "+") return { value: line, end: eol + 2 };
+  if (type === "-") return { value: new Error(line), end: eol + 2 };
+  if (type === ":") return { value: Number(line), end: eol + 2 };
+  if (type === "$") {
+    const n = Number(line);
+    if (n < 0) return { value: null, end: eol + 2 };
+    if (buf.length < eol + 2 + n + 2) return null;
+    return { value: Buffer.from(buf.subarray(eol + 2, eol + 2 + n)), end: eol + 2 + n + 2 };
+  }
+  if (type === "*") {
+    const n = Number(line);
+    const items = [];
+    let at = eol + 2;
+    for (let k = 0; k < n; k++) { const r = parse(buf, at); if (!r) return null; items.push(r.value); at = r.end; }
+    return { value: n < 0 ? null : items, end: at };
+  }
+  return { value: new Error(`unreadable reply ${type}`), end: eol + 2 };
+}
+
+const why = (e) => e?.why ?? (/NOAUTH|WRONGPASS|invalid password/i.test(String(e?.message)) ? "auth" : /ECONNREFUSED|ENOTFOUND|timeout|EHOSTUNREACH/i.test(String(e?.code ?? e?.message)) ? "down" : "other");
+
+// COPY came in Redis 6.2. A server that hides INFO is let try: a refused COPY is said then.
+export function tooOld(info) {
+  const m = /redis_version:(\d+)\.(\d+)/.exec(Buffer.isBuffer(info) ? info.toString() : "");
+  return Boolean(m) && (Number(m[1]) < 6 || (Number(m[1]) === 6 && Number(m[2]) < 2));
+}
+
+// The copy: the first empty database from the top of the server's range, claimed with the marker,
+// then every key of the source copied into it with COPY. Answers { index } or { why }.
+export async function cloneRedis(conn, source, marker) {
+  let c;
+  try { c = await open(conn); } catch (e) { return { why: why(e) }; }
+  try {
+    const [picked, size, info] = await c.send([["SELECT", source], ["DBSIZE"], ["INFO", "server"]]);
+    if (picked instanceof Error) return { why: /cluster/i.test(picked.message) ? "cluster" : why(picked) };
+    if (tooOld(info)) return { why: "oldServer" };
+    if (size > REDIS_CAP) return { why: "big" };
+    let index = null;
+    for (let n = 15; n >= 1 && index === null; n--) {
+      if (n === source) continue;
+      const [sel, count] = await c.send([["SELECT", n], ["DBSIZE"]]);
+      if (sel instanceof Error) continue;
+      if (count === 0) index = n;
+    }
+    if (index === null) return { why: "full" };
+    await c.send([["SELECT", index], ["SET", MARKER, marker], ["SELECT", source]]);
+    let cursor = "0";
+    do {
+      const [next, keys] = await c.one("SCAN", cursor, "COUNT", BATCH);
+      cursor = String(next);
+      const copied = keys.length ? await c.send(keys.map((k) => ["COPY", k, k, "DB", index])) : [];
+      const refused = copied.find((r) => r instanceof Error);
+      if (refused) { await c.send([["SELECT", index], ["FLUSHDB"]]); return { why: "other" }; }
+    } while (cursor !== "0");
+    return { index };
+  } catch (e) {
+    return { why: why(e) };
+  } finally {
+    c.close();
+  }
+}
+
+// Emptied only when the marker in it is this session's. With no index, the database is found by its
+// marker: a session killed mid-copy recorded the copy before it knew which database it claimed.
+export async function dropRedis(conn, index, marker) {
+  let c;
+  try { c = await open(conn); } catch { return false; }
+  try {
+    for (const n of index == null ? Array.from({ length: 15 }, (_, i) => 15 - i) : [index]) {
+      const [sel, held] = await c.send([["SELECT", n], ["GET", MARKER]]);
+      if (!(sel instanceof Error) && String(held) === marker) return (await c.one("FLUSHDB")) === "OK";
+    }
+    return index == null;
+  } catch { return false; } finally { c.close(); }
+}