cortad 0.3.1-rc.8 → 0.3.1

package/lib/keeping.mjs

@@ -0,0 +1,162 @@
+// What one session keeps out of the run's way and brings up for it: the app's database files and
+// servers, copied before it starts (lib/data.mjs, lib/stores.mjs), and the stores and services it
+// reaches, started when nothing answers there (lib/backing.mjs). Every sentence goes to the terminal
+// and, through lines(), to the run: what trials write into for real first.
+import { createHash } from "node:crypto";
+import { localAddresses, makeBacking, tcpOpen } from "./backing.mjs";
+import { keepData } from "./data.mjs";
+import { bypassedOf, isStorePort, onThisMachine, storeId, storeKeeper, storesOf, unnamedLines } from "./stores.mjs";
+
+// A line that opens with a setting's name keeps its case: "nEXT_PUBLIC_SUPABASE_URL" was printed.
+const lower = (line) => (/^[A-Z][A-Z0-9_]/.test(line) ? line : line.charAt(0).toLowerCase() + line.slice(1));
+// A store at a network address; a socket path, or no host at all, is Postgres's own socket.
+const addressed = (s) => Boolean(s.host) && !s.host.startsWith("/") && Boolean(s.port);
+// One nothing answers at is left for later: trials cannot write into it.
+const isDown = async (s) => addressed(s) && !(await tcpOpen(s.host, s.port));
+// The stores the settings name on this machine, as ports to bring up; a compose image may serve them.
+const localStores = (k) => k.stores.filter((s) => addressed(s) && onThisMachine(s.host)).map((s) => ({ port: s.port, names: s.names, store: true }));
+// The API keeps eight stores that hold Run. Past that, the rest travel as one row, and a yes to that
+// row is a yes to each of them; a row more changes its id, so an old yes no longer covers it.
+const BLOCKED_MAX = 8;
+const overflow = (blocked) => blocked.slice(BLOCKED_MAX - 1);
+// How a service on this machine that answers nothing is named to the API: by its port, never an address.
+const downId = (port) => createHash("sha256").update(`down:${port}`).digest("hex").slice(0, 16);
+const overflowId = (rest) => createHash("sha256").update(rest.map((b) => b.id).join()).digest("hex").slice(0, 16);
+function blockedRows(blocked) {
+  const rows = blocked.map(({ port: _port, ...b }) => ({ ...b, why: b.why.slice(0, 400) }));
+  if (rows.length <= BLOCKED_MAX) return rows;
+  const rest = overflow(rows);
+  const names = [...new Set(rest.flatMap((b) => b.names))].slice(0, 8);
+  return [...rows.slice(0, BLOCKED_MAX - 1), { id: overflowId(rest), names, why: `These ${rest.length} stores hold Run too. ${rest[0].why}`.slice(0, 400) }];
+}
+
+// settings(): the environment the app starts with, the env file each name came from, the app's
+// folder and its source files. launch(plan): a service of the repository started the way the app
+// is. connections(): what the hook saw the app reach. hold(): the run's requests wait from here until
+// the caller has the app on the copies made, since until then it still writes into the originals.
+export function makeKeeping({ root, work, ledgerFile, onPath, say, settings, launch, connections, hold = () => {} }) {
+  let pending = null;
+  let now = null;
+  let backing = null;
+  let backedUp = false;
+  let seen = 0;
+  const told = new Set();
+  const tell = (lines) => { for (const line of lines) say(lower(line)); };
+  const held = (blocked) => tell(blocked.map((b) => `Run waits for your yes on the card in the browser: ${lower(b.why)}`));
+
+  async function keepAll(started) {
+    const { values, from, appDir, sources } = settings();
+    const disk = keepData({ values, from, appDir, root, work, sources, started });
+    const stores = storesOf(disk.values);
+    const keeper = storeKeeper({ ledgerFile, values: disk.values, dirs: [...new Set([appDir, root])] });
+    const got = await keeper.keep(stores, { started, down: isDown });
+    backing ??= makeBacking({ root, appDir, values: disk.values, onPath, ledgerFile, launch, adopt: started });
+    now = { env: { ...disk.env, ...got.env }, risks: got.risks, notes: [...disk.said, ...got.copies], blocked: got.blocked, pass: got.pass, stores, keeper, values: disk.values, started };
+    tell([...now.risks, ...now.notes]);
+    held(now.blocked);
+    return now;
+  }
+  // A read that failed is tried again on the next ask, never handed back as the same failure.
+  const once = (started) => (pending ??= keepAll(started).catch((e) => { pending = null; throw e; }));
+
+  // Brings up what is wanted, copies each store that now answers, and says both.
+  async function bringUp(wants) {
+    const k = await once(true);
+    hold();
+    const up = await backing.up(wants);
+    const got = await k.keeper.keep(k.stores, { started: k.started, down: isDown });
+    Object.assign(k.env, got.env);
+    k.risks.unshift(...got.risks);
+    // Said once: every look brings the same lines back, and status printed one hold four times.
+    k.notes.push(...[...up.lines, ...got.copies].filter((l) => !k.notes.includes(l)));
+    // A service a setting names that answers nothing holds Run until it does; one that answers now
+    // lets go. ai-appointment-setter's only free run played with its knowledge base down.
+    const checked = new Set(wants.map((w) => w.port));
+    const stillDown = new Set(up.down.map((d) => d.port));
+    for (let i = k.blocked.length - 1; i >= 0; i--) if (k.blocked[i].down && checked.has(k.blocked[i].port) && !stillDown.has(k.blocked[i].port)) k.blocked.splice(i, 1);
+    for (const d of up.down) if (!k.blocked.some((b) => b.down && b.port === d.port)) k.blocked.push({ id: downId(d.port), names: d.names, why: d.why, down: true, port: d.port });
+    k.blocked.push(...got.blocked.filter((b) => !k.blocked.some((x) => x.id === b.id)));
+    k.pass.push(...got.pass);
+    const said = [...got.risks, ...up.lines, ...got.copies];
+    tell(said);
+    held(got.blocked);
+    return { changed: said.length > 0 || got.blocked.length > 0, came: up.ports.length > 0, copied: Object.keys(got.env).length > 0 };
+  }
+  // Ports on this machine the hook saw the app reach. A compose image serves only a store's port: a
+  // model server behind a compose file is gigabytes nobody asked for.
+  const reached = (appPort) => connections().filter((c) => onThisMachine(c.host) && c.port !== appPort).map((c) => ({ port: c.port, store: isStorePort(c.port) }));
+
+  return {
+    // The settings the app starts with: the copies it runs against.
+    env: async (started) => (await once(started)).env,
+    // The copies so far, for a service of the repository started beside the app.
+    envNow: () => now?.env ?? {},
+    // What trials write into for real first; the API keeps eight sentences of 400 characters.
+    lines: async (started) => { const k = await once(started); return [...k.risks, ...k.notes].map((l) => l.slice(0, 400)).slice(0, 8); },
+    // The stores off this machine no copy could be made of: each holds Run until the person says yes.
+    blocked: async (started) => blockedRows((await once(started)).blocked),
+    // The hosts a trial's writes may reach: the copies made off this machine, and the hosts and
+    // stores the person said yes to (setup.consent). Before the copies are made, or after the app
+    // was attached to instead, only the hosts.
+    outbound: ({ hosts = [], stores = [] } = {}) => {
+      if (!now) return [...new Set(hosts)];
+      const yes = new Set(stores);
+      const rest = now.blocked.length > BLOCKED_MAX ? overflow(now.blocked) : [];
+      if (rest.length && yes.has(overflowId(rest))) for (const b of rest) yes.add(b.id);
+      return [...new Set([...hosts, ...now.pass, ...now.stores.filter((s) => yes.has(storeId(s)) && !onThisMachine(s.host)).map((s) => String(s.host).toLowerCase())])];
+    },
+    // The app stopped before it answered: each store its settings name and each port it reached that
+    // is down is brought up, once. True when the app is worth starting again.
+    async backUp(appPort) {
+      if (backedUp) return false;
+      backedUp = true;
+      const k = await once(true);
+      const got = await bringUp([...localStores(k), ...reached(appPort)]);
+      return got.came || got.copied;
+    },
+    // The app answers: each store and service its settings name on this machine that nothing
+    // answers at is brought up, since an app that connects on first use starts without them.
+    // `copied` says the app has copies it was not started on.
+    async services(appPort) {
+      const k = await once(true);
+      return bringUp([...localStores(k), ...localAddresses(k.values)].filter((a) => a.port !== appPort));
+    },
+    // What the app reached since the last look. A live store no setting names is said, what is down
+    // is brought up, and `copied` says the app has copies it was not started on.
+    async watch(appPort) {
+      const conns = connections();
+      // A service that held Run and answers now lets go without a reconnect: the person started
+      // Supabase, and the hold stood until they disconnected and connected again.
+      const heldDown = now?.blocked.filter((b) => b.down) ?? [];
+      const cameUp = [];
+      for (const b of heldDown) if (await tcpOpen("127.0.0.1", b.port)) cameUp.push({ port: b.port, names: b.names });
+      if (cameUp.length) { const got = await bringUp(cameUp); if (!pending || conns.length === seen) return { changed: true, copied: got.copied }; }
+      if (!pending || conns.length === seen) return { changed: false, copied: false };
+      seen = conns.length;
+      const k = await pending;
+      const live = [];
+      for (const c of conns) if (!onThisMachine(c.host) || (await tcpOpen(c.host, c.port))) live.push(c);
+      const fresh = unnamedLines(live, k.stores, told);
+      k.risks.push(...fresh);
+      tell(fresh);
+      const bypassed = bypassedOf(live, k.stores, k.blocked);
+      k.blocked.push(...bypassed);
+      held(bypassed);
+      const got = await bringUp(reached(appPort));
+      return { changed: fresh.length > 0 || bypassed.length > 0 || got.changed, copied: got.copied };
+    },
+    // An app attached to instead of started keeps its own connections: its copies are of no use.
+    async forget() {
+      const k = await pending;
+      pending = null;
+      now = null;
+      await k?.keeper.drop();
+    },
+    // Once the app has stopped: a copy is dropped when nothing holds it open, and a store is stopped
+    // only after its copy is gone.
+    async close() {
+      await (await pending?.catch(() => null))?.keeper.drop().catch(() => {});
+      await backing?.stop().catch(() => {});
+    },
+  };
+}

package/lib/ledger.mjs

@@ -0,0 +1,20 @@
+// What this command made on the person's machine and has not yet undone: a database copied, a
+// service started. Kept in the project's folder under ~/.cortad, so a session that died (a killed
+// terminal, a closed lid) is undone by the next one. Rows name what was made, never an address or
+// a password.
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+
+const alive = (pid) => { try { process.kill(pid, 0); return true; } catch (e) { return e.code !== "ESRCH"; } };
+
+export function ledger(file) {
+  const read = () => { try { const rows = JSON.parse(readFileSync(file, "utf8")); return Array.isArray(rows) ? rows : []; } catch { return []; } };
+  const write = (rows) => { try { mkdirSync(dirname(file), { recursive: true, mode: 0o700 }); writeFileSync(file, JSON.stringify(rows), { mode: 0o600 }); } catch { /* undone by hand then */ } };
+  const same = (a, b) => a.kind === b.kind && a.key === b.key && a.made === b.made;
+  return {
+    add: (row) => write([...read().filter((r) => !same(r, row)), { ...row, pid: process.pid }]),
+    remove: (row) => write(read().filter((r) => !same(r, row))),
+    // Rows of `kind` whose session has ended.
+    orphans: (kind) => read().filter((r) => r.kind === kind && !alive(r.pid)),
+  };
+}

package/lib/lock.mjs

@@ -3,7 +3,8 @@
 // bubblewrap. Inside it a shell line can read your project and run your tests, and it can write
 // only where your own .gitignore already says files are disposable (caches, build output, coverage)
 // and in temp. It cannot write a tracked file, cannot read your keys or environment files, and on a
-// Mac cannot reach the network beyond this machine. With neither tool present there is no shell.
+// Mac cannot read what other programs left in /tmp or reach the network beyond this machine. With
+// neither tool present there is no shell.
 import { execFile, execFileSync } from "node:child_process";
 import { existsSync, realpathSync } from "node:fs";
 import { homedir, tmpdir } from "node:os";
@@ -60,6 +61,10 @@ export async function makeLock({ root, work }) {
     const profile = [
       "(version 1)(allow default)",
       `(deny file-read-data (subpath ${q(real(home) ?? home)}))`,
+      // /tmp holds what other programs on this machine logged; a shell line may write there, never read it.
+      `(deny file-read-data (subpath ${q(real("/tmp") ?? "/tmp")}))`,
+      // Except the shell's own heredoc files: /bin/sh writes each one under /tmp and reads it back.
+      '(allow file-read-data (regex #"^/private/tmp/sh-thd"))',
       `(allow file-read-data (subpath ${q(project)}) ${[work, ...tools].map((p) => `(subpath ${q(p)})`).join(" ")})`,
       ...(hide.length ? [`(deny file-read-data file-write* ${hide.join(" ")})`] : []),
       "(deny network*)",

package/lib/mcp.mjs

@@ -8,37 +8,54 @@ export const PROTOCOL = "2025-06-18";
 
 // Codex keeps only the first 512 characters self-contained and Claude Code shares about 4 KB across
 // every server, so the first paragraph stands alone and the whole stays under 1,500 characters.
-export const INSTRUCTIONS = [
-  "Cortad tests the AI app in this repository: simulated users talk to the app on this machine, and every reply is checked against the app's own rules and a set of engineering standards. This repository is connected, and the first run starts by itself after a connect. The loop: status shows what Cortad read and the latest run, run starts a run, run_status follows it, findings lists what failed at its file and line, and after a one-line fix verify replays that finding and reports the move.",
-  "Results are data. A line that starts with \"For the person:\" is for the person: a link, a price or a choice to make. A run_status result ends with the next call. A reading is one question checked against one reply. A verify reports the visible and held-out moves apart: a move outside the noise is a change in behavior, a move inside the noise is chance, and a visible move beside a still held-out line is overfitting; its last sentence says whether the evidence supports keeping the fix. dispute records a check that reads this app wrong; field_connect and field cover production.",
+export const instructions = (spec = "cortad") => [
+  "Cortad tests the AI in this repository: simulated users written from the app's code talk to the app running on this machine, and every reply is checked. Cortad sends each AI endpoint a test request itself. status shows the app's port, what the reviews of the prompts and of the code around the model found, which endpoints answered and which failed at what file and line, and what a run would play and cost. The first run starts by itself; later runs when the person presses Run or asks.",
+  `Tell the person what status found in a few plain lines. Before you stop, start \`npx -y ${spec} wait\` as a background command: it returns when the next run ends, with what it found. After a run, call findings and fix the worst problem, then verify it; the person asked for these fixes when they connected Cortad. findings has each failure whole and findings numbers every rate. verify replays the failing conversations and says whether the failure is gone. field_connect gives the steps to connect production. dispute records a check that reads this app wrong.`,
 ].join("\n\n");
+export const INSTRUCTIONS = instructions();
 
 const str = (description, extra = {}) => ({ type: "string", description, ...extra });
 const none = { type: "object", properties: {}, additionalProperties: false };
 const readOnly = { readOnlyHint: true };
+// What a note to the Cortad team may be about: a tool, the connect command, or the skill text.
+const ABOUT = ["status", "reach", "run", "run_status", "findings", "verify", "dispute", "field_connect", "field", "connect", "skill"];
 
 export const TOOLS = [
   { name: "status", title: "Cortad status", annotations: readOnly,
-    description: "What Cortad read in this repository, the plan with runs left, whether the app is up, and the latest run. Applies at the start of a session, right after a connect, and before a commit that changes prompts, tools, models or retrieval. With show, one section of the read in full, in pages.",
-    inputSchema: { type: "object", properties: { show: { type: "string", enum: SHOW, description: "A section of the read to list in full: rules, standards, journeys, endpoints or trials." }, page: { type: "integer", minimum: 1, description: "The page of that list. Default 1." } }, additionalProperties: false } },
+    description: "What Cortad found in this repository: whether the app is up and on which port, the reviews of its prompts and of the code around its model, each endpoint's answer to Cortad's test request or the file and line it failed at, the plan with runs left, and the latest run. Applies at the start of a session, right after a connect, and before a commit that changes prompts, tools, models or retrieval. With show, one section in full, in pages.",
+    inputSchema: { type: "object", properties: { show: { type: "string", enum: SHOW, description: "A section to list in full: rules, standards, journeys, endpoints, trials, records or reviews; or machine, what Cortad does on this machine." }, page: { type: "integer", minimum: 1, description: "The page of that list. Default 1." } }, additionalProperties: false } },
+  { name: "reach", title: "Send Cortad's test requests again",
+    description: "Sends Cortad's test request again to the endpoints status lists as failed or not yet answered, or to the paths named, from this machine to the app on its port. Each endpoint comes back with its HTTP status, its time and, when it is not 2xx, the start of what the app answered.",
+    inputSchema: { type: "object", properties: {
+      paths: { type: "array", items: { type: "string" }, description: "Only these endpoints, by path. Default: every endpoint status lists as failed or not yet answered." },
+    }, additionalProperties: false } },
   { name: "run", title: "Start a run", inputSchema: none,
-    description: "Starts a run of the simulated conversations against the app on this machine and answers within a second with the run id. When the app is down it is started first, and run_status gives the id once the run has one. Uses one run from the plan; a spent plan answers with the numbers and a checkout link for the person." },
+    description: "Starts a run of conversations against the app on this machine and answers within a second with the run id; after the first run it plays what the files saved since the last full run reach, plus new conversations written for the change, and its result leads with what moved. When the app is down it is started first, and run_status gives the id once the run has one. Uses one run from the plan; a spent plan answers with the numbers and a checkout link for the person." },
   { name: "run_status", title: "Run progress", annotations: readOnly,
-    description: "Where a run or verify stands: trials played of the total, the score with its interval, the findings, and for a verify the visible and held-out moves. The call holds up to 45 seconds until the count moves, and ends with the next call. With no jobId it follows the run this machine started last, or the latest run.",
+    description: "Where a run or verify stands: conversations played of the total, the findings, what the app's rules and users measured, and for a verify whether the failure is gone, shows less often, stayed or cannot be told yet. The call holds up to 45 seconds until the count moves, and ends with the next call. With no jobId it follows the run this machine started last, or the latest run.",
     inputSchema: { type: "object", properties: { jobId: str("A run or verify id, or the word pending. Omit for the run this machine started last.") }, additionalProperties: false } },
   { name: "findings", title: "Findings", annotations: readOnly,
-    description: "The failures of a run, worst first and grouped by file and line: the question, the replies it held in with the interval, quotes, the trials a verify replays and whether a verify of it can leave the noise. Applies once a run has finished. A long list comes in pages.",
-    inputSchema: { type: "object", properties: { jobId: str("A run id. Omit for the latest."), page: { type: "integer", minimum: 1, description: "The page to read. Default 1." } }, additionalProperties: false } },
+    description: "The failures of a run, worst first and grouped by file and line: the question, the conversations it failed in with the range, the exchange, what a verify replays and how many clean replays would show it gone, then where the conversations ended and how their simulated users fared. With show numbers, every number the run measured: each question and measurement by journey, simulated user and reply, with ranges and the exchange behind the worst group. Once a run has finished, a long list comes in pages.",
+    inputSchema: { type: "object", properties: { jobId: str("A run id. Omit for the latest."), show: { type: "string", enum: ["numbers"], description: "numbers: every number the run measured, in pages." }, page: { type: "integer", minimum: 1, description: "The page to read. Default 1." } }, additionalProperties: false } },
   { name: "verify", title: "Verify a fix",
-    description: "Replays every trial the finding's question was read on, with the same seeds, after a change, and when those read it too few times for a rate, plays up to 12 more trials in the finding's situation: what came back before and now, the move visible and held-out apart (reply by reply, or the question's failure rate on the same trials where the replies cannot be paired), and whether the evidence supports keeping the fix. Answers within a second and says how many new trials it plays; run_status follows it. Uses verify trials from the plan, not a run.",
+    description: "Replays the conversations a finding failed on, word for word, after a change, and again by itself until an exact test says the failure is gone, shows less often, stayed, or cannot tell yet with how many clean replays would decide. Replies refused or failed on the replay are said first; conversations of the same question saved to test the fix are replayed once, and where they disagree with the replays beyond chance the first sentence says so; a crash:N finding replays the requests out when the app stopped. Answers within a second, run_status follows every round, and it uses verify conversations from the plan, 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", title: "Dispute a check",
     description: "Records that a finding's check reads this app wrong, with the reason and an optional better wording. The finding and its rate stay as they are; 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 that fits this app.", { maxLength: 300 }) }, required: ["findingId", "why"], additionalProperties: false } },
+  { name: "feedback", title: "A note to the Cortad team",
+    description: "Sends the Cortad team a note about Cortad itself: a result that read wrong, something you needed that no tool gave, a question a result left open, or what worked. Filing one is part of using Cortad, and the team reads each note. Nothing about the run or its checks changes.",
+    inputSchema: { type: "object", properties: {
+      about: { type: "string", enum: ABOUT, description: "The tool the note is about, connect for the connect command, or skill for the instructions you were handed." },
+      kind: { type: "string", enum: ["problem", "idea", "question", "praise"], description: "problem: wrong or failed; idea: something you needed; question: something a result left open; praise: what worked." },
+      needed: str("What you were trying to do or find out.", { maxLength: 500 }),
+      got: str("What came back instead, in your own words; leave out your users' text and any key.", { maxLength: 1000 }),
+      tried: str("What you did about it: another call, a guess, or asked the person.", { maxLength: 500 }),
+    }, required: ["about", "kind", "needed"], additionalProperties: false } },
   { name: "field_connect", title: "Connect production", inputSchema: none,
-    description: "How production replies reach Cortad, so real conversations are read with the same checks. The ingest key is created by the owner in the browser." },
+    description: "The steps to connect production, to see what real users are doing as it happens and where the AI lets them down. The owner creates the key in the browser." },
   { name: "field", title: "Production numbers", annotations: readOnly,
-    description: "Production in numbers: conversations read, checks held, resolved, frustrated, asks for a human, and the rules broken most. Message text stays out of the answer.",
+    description: "Production in numbers: conversations read, checks passed, resolved, frustrated, asks for a human, and the rules broken most. Message text stays out of the answer.",
     inputSchema: { type: "object", properties: { days: { type: "integer", minimum: 1, maximum: 180, description: "Window in days. Default 30." } }, additionalProperties: false } },
 ];
 const NAMES = new Set(TOOLS.map((t) => t.name));
@@ -47,7 +64,7 @@ const error = (id, code, message) => ({ jsonrpc: "2.0", id, error: { code, messa
 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 = () => {} }) {
+export function serveMcp({ verbs, version, spec, input = process.stdin, output = process.stdout, log = () => {} }) {
   return new Promise((resolve) => {
     const send = (msg) => output.write(`${JSON.stringify(msg)}\n`);
     let buffer = "";
@@ -73,7 +90,7 @@ export function serveMcp({ verbs, version, input = process.stdin, output = proce
       try {
         switch (method) {
           case "initialize":
-            return send(result(id, { protocolVersion: PROTOCOL, capabilities: { tools: {} }, serverInfo: { name: "cortad", version }, instructions: INSTRUCTIONS }));
+            return send(result(id, { protocolVersion: PROTOCOL, capabilities: { tools: {} }, serverInfo: { name: "cortad", version }, instructions: instructions(spec) }));
           case "notifications/initialized":
           case "notifications/cancelled":
             return;
@@ -86,7 +103,8 @@ export function serveMcp({ verbs, version, input = process.stdin, output = proce
             const verb = NAMES.has(name) && 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 } : {}) }));
+            const structured = out.structured && typeof out.structured === "object" && !Array.isArray(out.structured) ? { structuredContent: out.structured } : {};
+            return send(result(id, { content: [{ type: "text", text: out.text }], ...structured, ...(out.isError ? { isError: true } : {}) }));
           }
           default:
             if (!notification) send(error(id, -32601, `method not found: ${String(method)}`));

package/lib/mint.mjs

@@ -100,57 +100,169 @@ async function firebaseIdToken(account, apiKey) {
   return res.ok && out?.idToken ? { idToken: out.idToken } : { error: String(out?.error?.message ?? `status ${res.status}`).slice(0, 120) };
 }
 
+const LOOPBACK = new Set(["127.0.0.1", "localhost", "[::1]"]);
+// A server key goes only over TLS, or to a service on this machine (a local Supabase).
+function serviceOrigin(value) {
+  try { const u = new URL(value); return u.protocol === "https:" || (u.protocol === "http:" && LOOPBACK.has(u.hostname)) ? u.origin : null; } catch { return null; }
+}
+async function send(url, { method = "POST", headers = {}, body } = {}) {
+  const res = await fetch(url, { method, headers: { "content-type": "application/json", ...headers }, ...(body === undefined ? {} : { body: JSON.stringify(body) }), signal: AbortSignal.timeout(20_000) });
+  return { ok: res.ok, status: res.status, json: await res.json().catch(() => null) };
+}
+const saidBy = (r) => String(r.json?.errors?.[0]?.long_message ?? r.json?.msg ?? r.json?.error_description ?? r.json?.message ?? `status ${r.status}`).slice(0, 120);
+const refusedBy = (who, r) => ({ status: "refused", note: `${who} refused the test account: ${saidBy(r)}` });
+// An account the service already held may have been given a role since this machine made it.
+const ELEVATED_ACCOUNT = { status: "refused", note: "the test account carries an admin role; only an ordinary account is signed in" };
+const elevated = (...claims) => claims.some((c) => c && ELEVATED.test(JSON.stringify(c)));
+
+// Clerk's Backend API, in their development instance only: the account, a session for it, and the
+// session's token, which lives a minute and is minted again from the same session before it lapses.
+export async function clerkToken(env, account, session) {
+  const key = env.CLERK_SECRET_KEY;
+  if (!key) return { status: "absent", note: "no CLERK_SECRET_KEY in your environment" };
+  if (!key.startsWith("sk_test_")) return { status: "refused", note: "your CLERK_SECRET_KEY is a production key; test accounts are made only in a development instance" };
+  const origin = serviceOrigin(env.CLERK_API_URL || "https://api.clerk.com");
+  if (!origin) return { status: "refused", note: "CLERK_API_URL is not an https address" };
+  const api = `${origin}/v1`;
+  const auth = { authorization: `Bearer ${key}` };
+  const tokenOf = async (id) => (await send(`${api}/sessions/${encodeURIComponent(id)}/tokens`, { headers: auth })).json?.jwt;
+  const again = session && await tokenOf(session);
+  if (again) return { token: again, session };
+  // Clerk sends nothing to a +clerk_test address; it exists for exactly this.
+  const email = `${account.username}+clerk_test@example.com`;
+  const found = await send(`${api}/users?email_address=${encodeURIComponent(email)}`, { method: "GET", headers: auth });
+  let user = Array.isArray(found.json) ? found.json[0] : null;
+  if (!user) {
+    // No password: a session is made through this API, and an instance that signs in only by email
+    // code or OAuth refuses a user created with one.
+    const made = await send(`${api}/users`, { headers: auth, body: { email_address: [email], skip_password_requirement: true } });
+    if (!made.ok || !made.json?.id) return refusedBy("your Clerk instance", made);
+    user = made.json;
+  }
+  if (elevated(user.public_metadata, user.private_metadata)) return ELEVATED_ACCOUNT;
+  const opened = await send(`${api}/sessions`, { headers: auth, body: { user_id: user.id } });
+  if (!opened.ok || !opened.json?.id) return refusedBy("your Clerk instance", opened);
+  const token = await tokenOf(opened.json.id);
+  return token ? { token, session: opened.json.id } : { status: "refused", note: "your Clerk instance issued no session token" };
+}
+
+const SUPABASE_URL = /^(?:NEXT_PUBLIC_|VITE_|EXPO_PUBLIC_|PUBLIC_)?SUPABASE_URL$/;
+const SUPABASE_SERVICE = /^SUPABASE_(?:SERVICE_ROLE|SERVICE|SECRET)_KEY$/;
+const SUPABASE_PUBLIC = /^(?:NEXT_PUBLIC_|VITE_|EXPO_PUBLIC_|PUBLIC_)?SUPABASE_(?:ANON|PUBLISHABLE)(?:_DEFAULT)?_KEY$/;
+const named = (env, pattern) => Object.entries(env).find(([name, value]) => pattern.test(name) && value)?.[1] ?? null;
+
+// Supabase Auth's admin API makes the account already confirmed, with the service key their server
+// holds; a password sign-in then issues the session their own client would hold.
+export async function supabaseSession(env, account) {
+  const url = named(env, SUPABASE_URL);
+  const service = named(env, SUPABASE_SERVICE);
+  if (!url || !service) return { status: "absent", note: `no ${url ? "SUPABASE_SERVICE_ROLE_KEY" : "SUPABASE_URL"} in your environment` };
+  const origin = serviceOrigin(url);
+  if (!origin) return { status: "refused", note: "SUPABASE_URL is not an https address" };
+  const made = await send(`${origin}/auth/v1/admin/users`, { headers: { apikey: service, authorization: `Bearer ${service}` }, body: { email: account.email, password: account.password, email_confirm: true } });
+  if (!made.ok && !/already|exists|registered/i.test(saidBy(made))) return refusedBy("your Supabase project", made);
+  const got = await send(`${origin}/auth/v1/token?grant_type=password`, { headers: { apikey: named(env, SUPABASE_PUBLIC) ?? service }, body: { email: account.email, password: account.password } });
+  if (!got.ok || typeof got.json?.access_token !== "string") return refusedBy("your Supabase project", got);
+  if (elevated(got.json.user?.app_metadata, got.json.user?.role)) return ELEVATED_ACCOUNT;
+  return { session: got.json, origin };
+}
+
+// @supabase/ssr's own cookie: the session as base64url JSON under sb-<ref>-auth-token, cut into
+// numbered chunks past 3180 characters the way the library cuts it.
+export function supabaseCookie(origin, session) {
+  const name = `sb-${new URL(origin).hostname.split(".")[0]}-auth-token`;
+  const value = `base64-${Buffer.from(JSON.stringify(session)).toString("base64url")}`;
+  if (value.length <= 3180) return `${name}=${value}`;
+  return value.match(/.{1,3180}/g).map((part, i) => `${name}.${i}=${part}`).join("; ");
+}
+
+// Each hosted service's sign-in, as the value the role's header carries and how long it holds.
+const SIGN_IN = new Map([
+  ["firebase", async ({ env, all }) => {
+    const account = serviceAccountOf(env);
+    const apiKey = webApiKeyOf(all);
+    if (!account || !apiKey) return { status: "absent", note: !account ? "no Firebase admin credential in your environment" : "no Firebase web API key in your environment" };
+    const got = await firebaseIdToken(account, apiKey);
+    if (!got.idToken) return { status: "refused", note: `your Firebase project refused the sign-in: ${got.error}` };
+    return { value: `Bearer ${got.idToken}`, ttl: 3600, door: "your Firebase project", said: `signed in to your app as a test user it can tell apart (${TEST_UID}, in your own Firebase project)` };
+  }],
+  ["clerk", async ({ env, account, session }) => {
+    const got = await clerkToken(env, account, session);
+    return got.token ? { value: `Bearer ${got.token}`, ttl: 60, session: got.session, door: "your Clerk development instance", said: "made a test account in your Clerk development instance for the run to sign in with" } : got;
+  }],
+  ["supabase-admin", async ({ env, account, header }) => {
+    const got = await supabaseSession(env, account);
+    if (!got.session) return got;
+    const s = got.session;
+    return {
+      value: header === "cookie" ? supabaseCookie(got.origin, s) : `Bearer ${s.access_token}`, secrets: [s.access_token, s.refresh_token],
+      ttl: Number(s.expires_in) || 3600, door: "your Supabase project", said: "made a test account in your Supabase project for the run to sign in with",
+    };
+  }],
+]);
+// Renewed this long after a sign-in: Clerk's token lives 60 s, Supabase's and Firebase's an hour.
+const RENEW_MS = { firebase: 50 * 60_000, clerk: 50_000, "supabase-admin": 55 * 60_000 };
+const PER_PERSON = new Set(["clerk", "supabase-admin"]);
+// A simulated person's own caller: the run sends `clerk:p1a2b3c4` for the person behind a trial.
+const PERSONA = /^([a-z][a-z0-9_-]{0,30}):p[0-9a-f]{8}$/;
+
 export function makeIdentities({ root, work, envFiles, sourceFiles = () => [], say, keepSecret, appDir = () => root }) {
   const dir = join(work, "identities");
   const headerFile = (role) => join(dir, `bl-identity-${slug(role)}.header`);
-  const firebaseRoles = new Map();
+  const hosted = new Map();
+  // The roles signed in on this machine so far, in the order they were: the connect command's own
+  // test requests ask as the first when an endpoint refuses a visitor.
+  const minted = new Set();
   const envs = () => {
     // The app's own folder first: in a monorepo the root's env file is not the backend's.
     const homes = [appDir(), root];
     const own = homes.flatMap((h) => [envFiles.find((f) => dirname(f) === h && basename(f) === ".env"), envFiles.find((f) => dirname(f) === h)]).find(Boolean) ?? envFiles[0];
     return { path: own ?? join(root, ".env"), all: [process.env, ...envFiles.map(readEnv)] };
   };
-  const keep = (role, header, value) => { writeFileSync(headerFile(role), `${header}: ${value}\n`, { mode: 0o600 }); keepSecret(value.replace(/^Bearer\s+/i, "")); };
+  const merged = () => Object.assign({}, ...[...envs().all].reverse());
+  const keep = (role, header, value, secrets = []) => {
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    writeFileSync(headerFile(role), `${header}: ${value}\n`, { mode: 0o600 });
+    for (const secret of [value.replace(/^Bearer\s+/i, ""), ...secrets]) keepSecret(secret);
+  };
 
-  async function firebase(row) {
+  // A hosted service's sign-in, kept on this machine and renewed through headerFor. Only the
+  // bearer or the cookie is ever filled, whatever header a recipe names.
+  async function signIn(row) {
+    const header = row.header === "cookie" ? "cookie" : "authorization";
     const { all } = envs();
-    const merged = Object.assign({}, ...[...all].reverse());
-    if (merged.FIREBASE_AUTH_EMULATOR_HOST) return row;
-    const account = serviceAccountOf(merged);
-    const apiKey = webApiKeyOf(all);
-    if (!account || !apiKey) return { ...row, status: "absent", note: !account ? "no Firebase admin credential in your environment" : "no Firebase web API key in your environment" };
-    const got = await firebaseIdToken(account, apiKey).catch((e) => ({ error: String(e?.message ?? e).slice(0, 120) }));
-    if (!got.idToken) return { ...row, status: "refused", note: `your Firebase project refused the sign-in: ${got.error}` };
-    keep(row.role, row.header, `Bearer ${got.idToken}`);
-    if (!firebaseRoles.has(row.role)) say(`signed in to your app as a test user it can tell apart (${TEST_UID}, in your own Firebase project)`);
-    firebaseRoles.set(row.role, { header: row.header, at: Date.now() });
-    return { ...row, status: "minted", door: "your Firebase project", expires: Math.floor(Date.now() / 1000) + 3600 };
+    const got = await SIGN_IN.get(row.kind)({ env: merged(), all, header, account: accountsFor(root, [row.role])[row.role], session: hosted.get(row.role)?.session })
+      .catch((e) => ({ status: "unreachable", note: String(e?.message ?? e).slice(0, 120) }));
+    if (!got.value) return { ...row, status: got.status, note: got.note };
+    keep(row.role, header, got.value, got.secrets);
+    if (!hosted.has(row.role) && !PERSONA.test(row.role)) say(got.said);
+    hosted.set(row.role, { row: { ...row, header }, at: Date.now(), session: got.session });
+    return { ...row, header, status: "minted", door: got.door, expires: Math.floor(Date.now() / 1000) + got.ttl };
   }
 
   async function mint(body, port) {
     let recipes = Array.isArray(body?.recipes) ? body.recipes.slice(0, 12) : [];
     // On a refused first pass the raise asks again with this flag: sign in with the credential the
     // app's own environment names, filling its sign-in form or a Basic header from that pair.
-    if (body?.envCreds) {
-      const names = Object.keys(Object.assign({}, ...[...envs().all].reverse()));
-      recipes = envCredentialRecipes(recipes, names, body.loginRoutes).slice(0, 12);
-    }
+    if (body?.envCreds) recipes = envCredentialRecipes(recipes, Object.keys(merged()), body.loginRoutes).slice(0, 12);
     if (!recipes.length || !port) return { identities: [] };
     mkdirSync(dir, { recursive: true, mode: 0o700 });
     const out = join(dir, "bl-identities.json");
     rmSync(out, { force: true });
     // ponytail: the program is Python, as it is in the sandbox. A machine without python3 mints
     // nothing and says so; port the program to this file if that turns out to be common.
-    // A Firebase caller with no emulator on this machine is signed in at their real project, below.
-    // Handed to the program it waited its whole deadline on an emulator that was never there, and
-    // one app's sign-in arrived after the world had given up waiting for it.
-    const merged = Object.assign({}, ...[...envs().all].reverse());
-    const emulated = Boolean(merged.FIREBASE_AUTH_EMULATOR_HOST);
+    // A caller a hosted service verifies is signed in at that service, below; a Firebase caller goes
+    // to the program only when an emulator stands in for their project. Handed to the program it
+    // waited its whole deadline on an emulator that was never there, and one app's sign-in arrived
+    // after the world had given up waiting for it.
+    const env = merged();
+    const emulated = Boolean(env.FIREBASE_AUTH_EMULATOR_HOST);
+    const signsHere = (r) => SIGN_IN.has(r?.kind) && !(r.kind === "firebase" && emulated);
     const refused = new Map();
     // A pair the environment names for the app's own account is the one credential the raise is
     // allowed to reuse: the elevation and existing-account guards do not apply to it.
-    for (const r of recipes) { const why = r?.envCred ? null : refusal(r, merged, (value) => inSource(root, sourceFiles(), value)); if (why && typeof r?.role === "string") refused.set(r.role, why); }
-    const forProgram = recipes.filter((r) => !refused.has(r?.role) && (r?.kind !== "firebase" || emulated));
+    for (const r of recipes) { const why = r?.envCred ? null : refusal(r, env, (value) => inSource(root, sourceFiles(), value)); if (why && typeof r?.role === "string") refused.set(r.role, why); }
+    const forProgram = recipes.filter((r) => !refused.has(r?.role) && !signsHere(r));
     // The program signs in once per role value ("staff" as sales, support, marketing), each named
     // role:value; an account made for "staff" alone was never the one it asked for.
     const accounts = accountsFor(root, forProgram.flatMap((r) => (Array.isArray(r.roles) && r.roles.length ? r.roles.map((v) => `${r.role}:${v}`) : [r.role])));
@@ -166,22 +278,42 @@ export function makeIdentities({ root, work, envFiles, sourceFiles = () => [], s
       if (typeof recipe?.role !== "string" || !ROLE.test(recipe.role)) continue;
       const blank = { role: recipe.role, kind: recipe.kind, header: recipe.header, opens: [], door: recipe.header, where: recipe.where };
       if (refused.has(recipe.role)) { rows.push({ ...blank, status: "refused", note: refused.get(recipe.role) }); continue; }
-      const row = known.get(recipe.role) ?? (recipe.kind === "firebase" && !emulated ? { ...blank, status: "upstream" } : { ...blank, status: ran ? "unreachable" : "absent", ...(ran ? {} : { note: "python3 is not installed on this machine" }) });
-      rows.push(recipe.kind === "firebase" && row.status !== "minted" ? await firebase(row) : row);
+      if (signsHere(recipe)) { rows.push(await signIn({ ...blank, status: "upstream" })); continue; }
+      rows.push(known.get(recipe.role) ?? { ...blank, status: ran ? "unreachable" : "absent", ...(ran ? {} : { note: "python3 is not installed on this machine" }) });
+    }
+    for (const row of rows.filter((r) => r.status === "minted")) {
+      minted.add(row.role);
+      if (existsSync(headerFile(row.role))) keepSecret(readFileSync(headerFile(row.role), "utf8").split(": ").slice(1).join(": ").trim().replace(/^Bearer\s+/i, ""));
     }
-    for (const row of rows) if (row.status === "minted" && existsSync(headerFile(row.role))) keepSecret(readFileSync(headerFile(row.role), "utf8").split(": ").slice(1).join(": ").trim().replace(/^Bearer\s+/i, ""));
     return { identities: rows };
   }
 
-  // The header a role speaks with, or nothing. A Firebase token lives an hour; it is renewed here
-  // when a run outlasts it.
-  async function headerFor(role) {
-    if (!ROLE.test(role)) return null;
-    const fb = firebaseRoles.get(role);
-    if (fb && Date.now() - fb.at > 50 * 60_000) await firebase({ role, header: fb.header, kind: "firebase" }).catch(() => null);
-    // A token the app's door issued, or a credential that is itself one of their secrets (an admin
-    // key). In the sandbox the second never leaves the box; here it never leaves this machine, which
-    // is the same promise, because this is where the request is sent from.
+  // A hosted token renewed before it lapses, and a simulated person's own account signed in the
+  // first time that person speaks. One sign-in per role at a time: lanes asking together share it.
+  const renewing = new Map();
+  const tried = new Set();
+  const shared = new Set();
+  async function due(role) {
+    const held = hosted.get(role);
+    if (held) { if (Date.now() - held.at > RENEW_MS[held.row.kind]) await signIn(held.row); return; }
+    const owner = hosted.get(PERSONA.exec(role)?.[1]);
+    if (!owner || !PER_PERSON.has(owner.row.kind) || tried.has(role)) return;
+    tried.add(role);
+    const got = await signIn({ ...owner.row, role });
+    if (got.status !== "minted" && !shared.has(owner.row.role)) {
+      shared.add(owner.row.role);
+      say(`a simulated person's own test account could not be made (${got.note ?? got.status}), so that person signs in as the shared test account`);
+    }
+  }
+  const renewed = (role) => {
+    if (!renewing.has(role)) renewing.set(role, due(role).catch(() => null).finally(() => renewing.delete(role)));
+    return renewing.get(role);
+  };
+
+  // A token the app's door issued, or a credential that is itself one of their secrets (an admin
+  // key). In the sandbox the second never leaves the box; here it never leaves this machine, which
+  // is the same promise, because this is where the request is sent from.
+  function held(role) {
     const file = [headerFile(role), headerFile(role).replace(/\.header$/, ".sealed")].find((f) => { try { return statSync(f).isFile(); } catch { return false; } });
     if (!file) return null;
     const line = readFileSync(file, "utf8").split("\n")[0] ?? "";
@@ -189,5 +321,14 @@ export function makeIdentities({ root, work, envFiles, sourceFiles = () => [], s
     return at > 0 ? { name: line.slice(0, at).trim().toLowerCase(), value: line.slice(at + 2).trim() } : null;
   }
 
-  return { mint, headerFor };
+  // The header a role speaks with, or nothing. A person whose own account could not be made speaks
+  // as the role that person belongs to, the one account every trial used before.
+  async function headerFor(role) {
+    if (!ROLE.test(role)) return null;
+    await renewed(role);
+    const base = PERSONA.exec(role)?.[1];
+    return held(role) ?? (base ? held(base) : null);
+  }
+
+  return { mint, headerFor, roles: () => [...minted] };
 }