cortad 0.3.1-rc.9 → 0.3.2

package/lib/failed-text.mjs

@@ -0,0 +1,36 @@
+import { at, clip, plural } from "./words.mjs";
+
+// The replies that did not count and the doors that were not sent to, said before the score: one
+// sentence whose parts add up to the count, then the request behind each part that has one. A count
+// on its own ("17 of 33 replies failed") left resumeforge's agent asking what was attempted, whose it
+// was, and how to reproduce it.
+
+// A row the run held back names a door and why, or, when no door could take it, only the reason.
+export const heldBackLine = (h) => h.why === "not testable here"
+  ? `Set aside: ${plural(h.trials, "conversation")} cannot be played here: ${clip(h.surface, 200).replace(/\.$/, "")}.`
+  : `Set aside: ${plural(h.trials, "conversation")} on ${h.surface}${h.why ? `, ${clip(h.why, 200)}` : ""}.`;
+
+const HELD_SHOWN = 6;
+
+export function heldLines(held) {
+  const rows = (held ?? []).filter((h) => h.trials > 0);
+  const lines = rows.slice(0, HELD_SHOWN).map(heldBackLine);
+  if (rows.length > HELD_SHOWN) lines.push(`Set aside: ${plural(rows.slice(HELD_SHOWN).reduce((n, h) => n + h.trials, 0), "more conversation")} for ${plural(rows.length - HELD_SHOWN, "other reason")}.`);
+  return lines;
+}
+
+export function failedLines(f) {
+  if (!f) return [];
+  const lines = f.said ? [f.said] : [];
+  for (const row of f.rows ?? []) {
+    const sent = row.curl ?? row.request;
+    if (!sent && !row.verify) continue;
+    const [path, line] = (row.at ?? "").split(/:(?=\d+$)/);
+    const where = row.at ? `at ${at(path, Number(line))}` : `from ${row.door}`;
+    if (sent) lines.push(`  Request for the ${row.count} ${where}: ${clip(sent, 900)}`);
+    if (sent && row.response) lines.push(`    Answered: ${clip(row.response.replace(/\s+/g, " "), 300)}`);
+    if (row.printed) lines.push(`    Your app printed: "${clip(row.printed, 300)}"`);
+    if (row.verify) lines.push(sent ? `    verify ${row.verify} replays them.` : `  verify ${row.verify} replays the ${row.count} ${where}.`);
+  }
+  return [...lines, ...heldLines((f.held ?? []).map((h) => ({ surface: h.door, trials: h.trials, why: h.why })))];
+}

package/lib/fresh.mjs

@@ -8,7 +8,8 @@ import { createHash } from "node:crypto";
 import { readFileSync, statSync } from "node:fs";
 import { join } from "node:path";
 import { TEST } from "./data.mjs";
-import { homeOf, readApp, readRunner } from "./home.mjs";
+import { homeOf, readApp } from "./home.mjs";
+import { readRunner } from "./runner.mjs";
 import { writesDirOf, writtenPaths } from "./writes.mjs";
 
 // A command, or an app's own output, that says it picks a saved file up by itself. Not a compiler
@@ -38,13 +39,6 @@ export function commandText(cmd, dir) {
   return text;
 }
 
-// ps's etime, [[dd-]hh:]mm:ss, in milliseconds.
-export function elapsedMs(etime) {
-  const [days, clock] = String(etime).includes("-") ? String(etime).split("-") : [0, String(etime)];
-  const [s = 0, m = 0, h = 0] = clock.split(":").map(Number).reverse();
-  return (((Number(days) * 24 + h) * 60 + m) * 60 + s) * 1000;
-}
-
 // Not the app's code: this command's own line and hooks, the coding agents' folders, and tests.
 const NOT_APP = /^(?:AGENTS|CLAUDE)\.md$|^\.github\/copilot-instructions\.md$|^\.(?:claude|codex|cursor|agents)\//;
 const digestOf = (file) => { try { return createHash("sha1").update(readFileSync(file)).digest("hex"); } catch { return ""; } };
@@ -71,6 +65,26 @@ export function changesOf({ root, app, skip = new Set() }) {
   return { changed: changed.sort((a, b) => b.at - a.at), last };
 }
 
+// The app's source files saved after `since`, the start of the run the next one is compared with, or
+// gone since: what a run after a change is scoped by on Cortad's side. A file the app is writing now
+// is not a change, nor one holding the bytes it had when the app started before `since` (the app's
+// own writes, put back after a run). Null when `since` is not a time.
+// `since` is Cortad's clock and a file's time is this machine's: a minute of slack, so a clock running
+// behind still counts a save. A save just before the run that is counted again only widens the run.
+const SKEW_MS = 60_000;
+
+export function savedSince({ root, files, since, startedAt, skip = new Set() }) {
+  const t = Date.parse(since ?? "");
+  if (!Number.isFinite(t)) return null;
+  const hashedBefore = Date.parse(startedAt ?? "") <= t;
+  return Object.entries(files).filter(([rel, was]) => {
+    if (skip.has(rel)) return false;
+    let at;
+    try { at = statSync(join(root, rel)).mtimeMs; } catch { return true; }
+    return at > t - SKEW_MS && !(hashedBefore && was && digestOf(join(root, rel)) === was);
+  }).map(([rel]) => rel).sort();
+}
+
 // What the run's text says about the code it played (lib/text.mjs testedLine).
 export const testedOf = (app, { changed, last }) => ({
   startedAt: app.startedAt,
@@ -88,6 +102,11 @@ export function makeCode({ project, root, waitMs, base, signal = (pid) => proces
   };
   const changes = (app) => changesOf({ root, app, skip: writtenPaths(writesDirOf(homeOf(project, base))) });
   const tested = () => { const app = current(); return app ? testedOf(app, changes(app)) : null; };
+  // Every source file the app was started with, whoever holds it up now.
+  const saved = (since) => {
+    const app = readApp(project, base);
+    return Object.keys(app?.files ?? {}).length ? savedSince({ root, files: app.files, since, startedAt: app.startedAt, skip: writtenPaths(writesDirOf(homeOf(project, base))) }) : null;
+  };
 
   const fresh = async () => {
     const app = current();
@@ -97,12 +116,14 @@ export function makeCode({ project, root, waitMs, base, signal = (pid) => proces
     try { signal(app.runner); } catch { return { error: "The process holding your app up could not be asked to start it again for your change." }; }
     while (now() - asked < waitMs) {
       await sleep(500);
+      const held = readRunner(project, base);
+      if (!held) return { error: "The process holding your app up ended while starting it again for your change." };
+      if (held.state === "failed" && Date.parse(held.at) >= asked) return { error: `Your app was started again to play your change and did not come back. ${held.error ?? ""}`.trim() };
+      // Started after the ask, or by the command's own restart for the save, which the ask can land in.
       const next = readApp(project, base);
-      if (next?.failedAt && Date.parse(next.failedAt) >= asked) return { error: `Your app was started again to play your change and did not come back. ${next.error ?? ""}`.trim() };
-      if (next?.startedAt && Date.parse(next.startedAt) >= asked) return { restarted: changed.map((c) => c.path) };
-      if (!readRunner(project, base)) return { error: "The process holding your app up ended while starting it again for your change." };
+      if (next?.startedAt && (Date.parse(next.startedAt) >= asked || (next.startedAt !== app.startedAt && !changes(next).changed.length))) return { restarted: changed.map((c) => c.path) };
     }
     return { error: `Your app was started again to play your change and has not answered after ${Math.round(waitMs / 1000)} seconds.` };
   };
-  return { fresh, tested };
+  return { fresh, tested, saved };
 }

package/lib/health.mjs

@@ -0,0 +1,61 @@
+// Whether the app a run is using is alive, read the way a person would: is its process still there,
+// does anything still hold its port, and only then does it answer. An app slow to answer because it
+// is answering our own requests is working, not dead: resumeforge held sixteen of them on a database
+// pool of five, missed two probes of 2.5 seconds, and was restarted in the middle of the run.
+import { connect } from "node:net";
+
+const FLOOR_MS = 10_000;
+const CAP_MS = 120_000;
+const ASK_EVERY_MS = 60_000;
+const url = (host, port) => `http://${host === "::1" ? "[::1]" : host}:${port}/`;
+
+// Opens the socket and sends nothing. Only a refusal means nobody holds the port: a listener too
+// busy to accept still holds it.
+export const portHeld = (host, port, ms = 3000) => new Promise((done) => {
+  const socket = connect({ host, port });
+  const end = (held) => { socket.destroy(); done(held); };
+  socket.once("connect", () => end(true));
+  socket.once("error", (e) => end(e.code !== "ECONNREFUSED"));
+  socket.setTimeout(ms, () => end(true));
+});
+
+// `gone`: the process this command started has exited. `inFlight`: the run's requests the app has
+// not answered yet. Held port is checked every time by a bare connect, which an app does not log;
+// whether it answers is asked with HEAD / once a minute while it is up, and at every check once it
+// was not: a GET / every two seconds put 1,548 "GET / 404" lines in one app's own log. The probe
+// waits three times the app's last reply to it, never under ten seconds or over two minutes.
+export function makeHealth({ host, gone, inFlight, askEveryMs = ASK_EVERY_MS, now = Date.now }) {
+  let took = 0;
+  let askedAt = -Infinity;
+  let last = "up";
+  const timeout = () => Math.min(CAP_MS, Math.max(FLOOR_MS, took * 3));
+  const state = (s) => (last = s);
+  return {
+    timeout,
+    // "up", "busy" (slow while the run's requests are open: never restarted), or why it is down:
+    // "exited", "released" (nothing holds its port) or "quiet" (no answer with nothing of ours open).
+    async check(port) {
+      if (gone()) return state("exited");
+      if (!(await portHeld(host(), port))) return state("released");
+      if (last === "up" && now() - askedAt < askEveryMs) return "up";
+      const started = now();
+      askedAt = started;
+      try {
+        const res = await fetch(url(host(), port), { method: "HEAD", signal: AbortSignal.timeout(timeout()), redirect: "manual" });
+        await res.body?.cancel();
+        took = now() - started;
+        return state("up");
+      } catch {
+        return state(inFlight() > 0 ? "busy" : "quiet");
+      }
+    },
+  };
+}
+
+// The runner's own line for a restart, in the person's words.
+export function downLine(state, { port, downMs, crashed = false }) {
+  if (crashed) return "your app crashed, starting it again";
+  if (state === "exited") return "your app exited, starting it again";
+  if (state === "released") return `nothing is listening on port ${port} any more, starting your app again`;
+  return `your app has not answered for ${Math.round(downMs / 1000)} seconds while no test conversation was waiting on it, starting it again`;
+}

package/lib/held.mjs

@@ -0,0 +1,67 @@
+// The run's requests this command is holding open at your app, by the bus job that asked for each.
+// A request the run gives up on (its wait ran out, or the run ended) is let go here as well, so
+// your app is not left working for nobody. music-store-support (2026-09-29, job 1c7500f0) is a
+// Gradio app, whose queue serves one event at a time: the run's requests stayed open after it had
+// stopped waiting, and the agent's own test chat waited five minutes behind them.
+//
+// An app's own queue can keep a request after its caller leaves. The hook in the app sees it: a
+// model call that started after its request was let go, for a request the app was not already at
+// work on, in an app never seen working on two requests at once. That is said once, with how many
+// were let go with it and had not reached the model yet, the most that can still be ahead of
+// anything sent.
+const TOGETHER_MS = 10_000;
+
+export function makeHeld({ rows = () => [], say = () => {}, now = Date.now, everyMs = 2000 } = {}) {
+  const open = new Map();
+  const dropped = new Map();
+  let settled = false;
+  let timer = null;
+
+  const startOf = (r) => r.at - (r.ms ?? 0);
+  // Two requests' model calls under way at once: your app serves requests side by side, so what it
+  // goes on with after a cancel is its own work, never a queue ahead of the next request.
+  const sideBySide = (calls) => calls.some((a) => calls.some((b) => a.turn !== b.turn && startOf(a) <= startOf(b) && startOf(b) < a.at));
+  const settle = () => { settled = true; clearInterval(timer); };
+  const check = () => {
+    if (settled) return;
+    const tagged = rows().filter((r) => typeof r?.turn === "string");
+    if (sideBySide(tagged)) return settle();
+    const calls = tagged.filter((r) => dropped.has(r.turn));
+    // A request your app was already at work on goes on to its next model call with or without a queue.
+    const working = new Set(calls.filter((r) => startOf(r) < dropped.get(r.turn)).map((r) => r.turn));
+    const taken = calls.find((r) => !working.has(r.turn) && startOf(r) >= dropped.get(r.turn));
+    if (!taken) return;
+    settle();
+    // Let go together with the one taken up, and not already at work when they were.
+    const at = dropped.get(taken.turn);
+    const n = [...dropped].filter(([turn, t]) => Math.abs(t - at) <= TOGETHER_MS && !working.has(turn)).length;
+    say(n > 1
+      ? `your app took up a request after the run cancelled it: its own queue keeps requests after the caller leaves, so up to ${n} the run cancelled may be ahead of anything sent to your app until they are done or your app restarts`
+      : "your app took up a request after the run cancelled it: its own queue keeps requests after the caller leaves, so anything sent to your app waits behind it until it is done or your app restarts");
+  };
+
+  return {
+    // A request going out for bus job `id`, tagged with the run's `turn`: the signal that lets it go.
+    hold(id, turn) {
+      const stop = new AbortController();
+      open.set(id, { stop, turn });
+      return stop.signal;
+    },
+    done(id) { open.delete(id); },
+    // Lets go of the requests of these jobs that are still open; how many were.
+    letGo(ids) {
+      let n = 0;
+      for (const id of ids) {
+        const held = open.get(id);
+        if (!held) continue;
+        open.delete(id);
+        held.stop.abort(new Error("cancelled by the run"));
+        if (held.turn) dropped.set(held.turn, now());
+        n += 1;
+      }
+      if (n && !settled && !timer) { timer = setInterval(check, everyMs); timer.unref?.(); }
+      return n;
+    },
+    check,
+  };
+}

package/lib/home.mjs

@@ -1,12 +1,12 @@
 import { createHash } from "node:crypto";
-import { existsSync, mkdirSync, readFileSync, realpathSync, rmSync, writeFileSync } from "node:fs";
+import { closeSync, constants, existsSync, lstatSync, mkdirSync, openSync, readFileSync, realpathSync, renameSync, rmSync, writeFileSync, writeSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
 
 // What this machine keeps between sessions, per project, under ~/.cortad/<project>/: the key the
-// first connect left behind, the digest of the tree last uploaded, which process is holding the app
-// up, and the run this machine asked for last. The folder's path never leaves the machine; the
-// project is a hash of it.
+// first connect left behind, the digest of the tree last uploaded, the app as last started, and the
+// run this machine asked for last. The process holding the app up keeps its own file there
+// (lib/runner.mjs). The folder's path never leaves the machine; the project is a hash of it.
 export const projectOf = (root) => createHash("sha256").update(realpathSync(root)).digest("hex").slice(0, 16);
 export const homeOf = (project, base = join(homedir(), ".cortad")) => join(base, project);
 
@@ -20,19 +20,6 @@ export const writeToken = (project, token, base) => write(homeOf(project, base),
 export const readDigest = (project, base) => read(join(homeOf(project, base), "digest"));
 export const writeDigest = (project, digest, base) => write(homeOf(project, base), "digest", digest);
 
-// The process holding this project's app up for runs, if one is alive. A pid that no longer answers
-// is a stale file, not a runner.
-export function readRunner(project, base) {
-  const raw = read(join(homeOf(project, base), "runner.json"));
-  if (!raw) return null;
-  let runner;
-  try { runner = JSON.parse(raw); } catch { return null; }
-  if (!Number.isInteger(runner?.pid)) return null;
-  try { process.kill(runner.pid, 0); return runner; } catch { return null; }
-}
-export const writeRunner = (project, runner, base) => write(homeOf(project, base), "runner.json", JSON.stringify(runner));
-export const clearRunner = (project, base) => { try { rmSync(join(homeOf(project, base), "runner.json")); } catch { /* gone */ } };
-
 // The app that runner holds up, as it noted it last (lib/fresh.mjs): when it started, whether that
 // runner started it, and what its source files said then.
 export const readApp = (project, base) => readJson(join(homeOf(project, base), "app.json"));
@@ -42,3 +29,54 @@ export const readPending = (project, base) => readJson(join(homeOf(project, base
 export const writePending = (project, pending, base) => write(homeOf(project, base), "pending.json", JSON.stringify(pending));
 
 export const hasHome = (base = join(homedir(), ".cortad")) => existsSync(base);
+
+// What the server told this machine while no agent was listening (a run ending), kept until the
+// hook hands it to the agent on its next prompt or edit, or the agent reads that run itself. Each
+// line is said once. Where no hook ever takes it, only the latest lines stay.
+//
+// Three processes touch the file: the connector appends, a hook takes, a verb drops a run's line.
+// Nobody reads it in place. It is taken by rename first, so no two of them ever hold the same
+// lines, and what is kept goes back by append, after whatever landed in between.
+const NEWS_KEPT = 20;
+const HEARD_KEPT = 50;
+const newsFile = (project, base) => join(homeOf(project, base), "news.txt");
+const linesOf = (file) => (read(file) ?? "").split("\n").map((l) => l.trim()).filter(Boolean);
+// Appended through a handle that refuses a symbolic link: the lines are the server's, and a link
+// planted at this name must not point them at another file.
+function appendNews(project, base, lines) {
+  mkdirSync(homeOf(project, base), { recursive: true, mode: 0o700 });
+  const fd = openSync(newsFile(project, base), constants.O_WRONLY | constants.O_APPEND | constants.O_CREAT | constants.O_NOFOLLOW, 0o600);
+  try { writeSync(fd, `${lines.join("\n")}\n`); } finally { closeSync(fd); }
+}
+export function takeNews(project, base) {
+  const taken = `${newsFile(project, base)}.${process.pid}`;
+  try { renameSync(newsFile(project, base), taken); } catch { return []; }
+  // A link moved here is removed unread: its target is not news.
+  const lines = lstatSync(taken).isSymbolicLink() ? [] : linesOf(taken);
+  rmSync(taken, { force: true });
+  return lines;
+}
+const rewriteNews = (project, base, keep) => {
+  const kept = keep(takeNews(project, base));
+  if (kept.length) appendNews(project, base, kept);
+};
+// The runs the agent has read to their end, so a line that names one is not kept for it: the
+// server marks a run finished a moment before it says the line.
+const heardFile = (project, base) => join(homeOf(project, base), "heard.txt");
+export function addNews(project, line, base) {
+  if (linesOf(heardFile(project, base)).some((id) => line.includes(id))) return;
+  appendNews(project, base, [line]);
+  if (linesOf(newsFile(project, base)).length > NEWS_KEPT) rewriteNews(project, base, (lines) => lines.slice(-NEWS_KEPT));
+}
+/** Whether the agent has read this run to its end on this machine. */
+export const wasHeard = (project, runId, base) => linesOf(heardFile(project, base)).includes(runId);
+/** The agent has read this run itself: the line kept to tell it of that run is dropped, and one that arrives later is not kept. */
+export function dropNews(project, runId, base) {
+  if (typeof runId !== "string" || runId.length < 8) return;
+  rewriteNews(project, base, (lines) => lines.filter((l) => !l.includes(runId)));
+  const heard = [...linesOf(heardFile(project, base)).filter((id) => id !== runId), runId].slice(-HEARD_KEPT);
+  const next = `${heardFile(project, base)}.${process.pid}`;
+  mkdirSync(homeOf(project, base), { recursive: true, mode: 0o700 });
+  writeFileSync(next, `${heard.join("\n")}\n`, { mode: 0o600 });
+  renameSync(next, heardFile(project, base));
+}

package/lib/hosted.mjs

@@ -0,0 +1,201 @@
+// A store the app's settings name on a server off this machine. Trials write for real, so a run
+// never writes into one without the person's yes: the app is pointed at a copy made where the
+// store's maker makes one (a Neon branch, a local Supabase started from the repository's own
+// config), or at an empty database on this machine built by the app's own migrations. keep()
+// answers { env, pass, how } or { why } with every reason no copy could be made, most useful first.
+// Nothing here copies a row out of the hosted store.
+import { spawn } from "node:child_process";
+import { existsSync, readdirSync } from "node:fs";
+import { userInfo } from "node:os";
+import { join } from "node:path";
+import { applySql, dropPg, emptyPg } from "./pg.mjs";
+
+const NEON_API = "https://console.neon.tech/api/v2";
+const NEON_HOST = /\.neon\.tech$/i;
+// The endpoint a Neon host serves, pooled or not: ep-cool-darkness-123456(-pooler).region.aws.neon.tech.
+const ENDPOINT = /^(ep-[a-z0-9-]+?)(?:-pooler)?\./i;
+const SUPABASE_HOST = /\.supabase\.(?:co|in|com)$/i;
+const READY_MS = 90_000;
+const MIGRATE_MS = 180_000;
+const PROJECTS_MAX = 100;
+
+// A command of the repository's own, with the settings the app starts with. Never a shell.
+export function runCmd(bin, args, { cwd, env = process.env, timeout = 60_000 } = {}) {
+  return new Promise((done) => {
+    let out = "";
+    const child = spawn(bin, args, { cwd, env, stdio: ["ignore", "pipe", "pipe"] });
+    const timer = setTimeout(() => child.kill("SIGKILL"), timeout);
+    child.stdout.on("data", (d) => { out = (out + d).slice(-20_000); });
+    child.stderr.on("data", () => {});
+    child.on("error", () => { clearTimeout(timer); done({ ok: false, out }); });
+    child.on("close", (code) => { clearTimeout(timer); done({ ok: code === 0, out }); });
+  });
+}
+
+const URL_SETTING = /^[a-z][\w+.-]*:\/\//i;
+const settingWith = (values, text) => Object.keys(values).filter((k) => String(values[k] ?? "").includes(text));
+const swapped = (values, names, from, to) => Object.fromEntries(names.map((k) => [k, String(values[k]).split(from).join(to)]));
+
+function neonApi(key, fetchFn) {
+  return async (method, path, body) => {
+    const res = await fetchFn(`${NEON_API}${path}`, {
+      method,
+      headers: { authorization: `Bearer ${key}`, accept: "application/json", ...(body ? { "content-type": "application/json" } : {}) },
+      ...(body ? { body: JSON.stringify(body) } : {}),
+      signal: AbortSignal.timeout(20_000),
+    });
+    if (!res.ok) throw new Error(`neon answered ${res.status}`);
+    return res.status === 204 ? {} : res.json();
+  };
+}
+
+// The project and branch behind an endpoint: the API has no lookup by endpoint, so each project is asked.
+async function neonParent(api, endpoint) {
+  let cursor = "";
+  for (let seen = 0; seen < PROJECTS_MAX;) {
+    const page = await api("GET", `/projects?limit=100${cursor ? `&cursor=${encodeURIComponent(cursor)}` : ""}`);
+    const projects = page.projects ?? [];
+    for (const p of projects) {
+      const { endpoints = [] } = await api("GET", `/projects/${encodeURIComponent(p.id)}/endpoints`);
+      const at = endpoints.find((e) => e.id === endpoint);
+      if (at) return { project: p.id, branch: at.branch_id };
+    }
+    seen += projects.length;
+    cursor = page.pagination?.cursor ?? "";
+    if (!projects.length || !cursor) break;
+  }
+  return null;
+}
+
+async function settled(api, project, branch) {
+  for (const until = Date.now() + READY_MS; Date.now() < until; await new Promise((r) => setTimeout(r, 1000))) {
+    const got = await api("GET", `/projects/${project}/branches/${branch}`);
+    if (got.branch?.current_state === "ready") return true;
+  }
+  return false;
+}
+
+// How the app's schema is built where it has none yet, by the tool the repository already uses.
+const venvBin = (dir, bin) => ["venv", ".venv"].map((v) => join(dir, v, "bin", bin)).find(existsSync) ?? bin;
+const MIGRATORS = [
+  { tool: "Prisma", finds: (d) => existsSync(join(d, "prisma", "schema.prisma")),
+    cmd: (d) => ["npx", existsSync(join(d, "prisma", "migrations")) ? ["--no-install", "prisma", "migrate", "deploy"] : ["--no-install", "prisma", "db", "push", "--skip-generate"]] },
+  { tool: "Drizzle", finds: (d) => ["ts", "js", "mjs", "cjs", "json"].some((x) => existsSync(join(d, `drizzle.config.${x}`))), cmd: () => ["npx", ["--no-install", "drizzle-kit", "push"]] },
+  { tool: "Alembic", finds: (d) => existsSync(join(d, "alembic.ini")), cmd: (d) => [venvBin(d, "alembic"), ["upgrade", "head"]] },
+  { tool: "Django", finds: (d) => existsSync(join(d, "manage.py")), cmd: (d) => [venvBin(d, "python3"), ["manage.py", "migrate", "--noinput"]] },
+  { tool: "Supabase", finds: (d) => existsSync(join(d, "supabase", "migrations")), files: (d) => readdirSync(join(d, "supabase", "migrations")).filter((f) => f.endsWith(".sql")).sort().map((f) => join(d, "supabase", "migrations", f)) },
+];
+
+// `values`: every setting the app starts with. `dirs`: the app's folder, then the repository's.
+// `local`: the Postgres on this machine a stand-in is made on. `book`: the ledger, so what a session
+// that died made is undone by the next one.
+export function hostedKeeper({ values, dirs, book, fetchFn = globalThis.fetch, run = runCmd, local = null }) {
+  const made = [];
+  const neonKey = String(values.NEON_API_KEY ?? "").trim();
+  const api = neonKey ? neonApi(neonKey, fetchFn) : null;
+  const here = local ?? { host: "localhost", port: 5432, user: process.env.PGUSER || userInfo().username, password: process.env.PGPASSWORD ?? "" };
+  let supabase = null;
+  // Only a setting that is a whole address can be pointed at a copy: one naming a part of the store
+  // would keep pointing at the hosted one.
+  const inParts = (s) => !s.names.length || !s.names.every((n) => URL_SETTING.test(String(values[n] ?? "")));
+
+  const undo = {
+    branch: async (row) => { if (!api) return false; await api("DELETE", `/projects/${row.made}`); return true; },
+    shadow: (row) => dropPg(here, row.made),
+    // Their volumes are kept: a local Supabase they stopped themselves comes back with its data.
+    supabase: async (row) => (await run("supabase", ["stop"], { cwd: row.made, timeout: 120_000 })).ok,
+  };
+  const undone = async (row) => { if (await undo[row.kind](row).catch(() => false)) book.remove(row); };
+
+  async function neon(s) {
+    const endpoint = ENDPOINT.exec(s.host)?.[1];
+    const parent = endpoint && (await neonParent(api, endpoint));
+    if (!parent) return null;
+    const got = await api("POST", `/projects/${parent.project}/branches`, { branch: { parent_id: parent.branch, name: `cortad-${process.pid}-${Date.now()}` }, endpoints: [{ type: "read_write" }] });
+    const branch = got.branch?.id;
+    const host = got.endpoints?.[0]?.host ?? "";
+    const fresh = ENDPOINT.exec(host)?.[1];
+    if (!branch) return null;
+    const row = { kind: "branch", key: s.key, made: `${parent.project}/branches/${branch}` };
+    book.add(row);
+    made.push(row);
+    if (!fresh || !(await settled(api, parent.project, branch))) return null;
+    // Every setting naming the endpoint, pooled or direct, names the branch's: roles and passwords come with it.
+    return { how: "neon", env: swapped(values, settingWith(values, endpoint), endpoint, fresh), pass: [host, host.replace(fresh, `${fresh}-pooler`)] };
+  }
+
+  // One local Supabase per session, whichever store asks first; stopped at the end only when started here.
+  async function localSupabase() {
+    const dir = dirs.find((d) => existsSync(join(d, "supabase", "config.toml")));
+    if (!dir || !(await run("supabase", ["--version"], { timeout: 15_000 })).ok || !(await run("docker", ["info"], { timeout: 15_000 })).ok) return null;
+    let status = await run("supabase", ["status", "-o", "env"], { cwd: dir, timeout: 30_000 });
+    let started = false;
+    if (!status.ok) {
+      const row = { kind: "supabase", key: dir, made: dir };
+      book.add(row);
+      made.push(row);
+      started = true;
+      if (!(await run("supabase", ["start"], { cwd: dir, timeout: 600_000 })).ok) return null;
+      status = await run("supabase", ["status", "-o", "env"], { cwd: dir, timeout: 30_000 });
+      if (!status.ok) return null;
+    }
+    const vars = Object.fromEntries(status.out.split("\n").map((l) => /^([A-Z_]+)="?([^"]*)"?$/.exec(l.trim())).filter(Boolean).map((m) => [m[1], m[2]]));
+    return vars.API_URL ? { vars, started } : null;
+  }
+  async function supabaseCopy(s) {
+    const got = await (supabase ??= localSupabase().catch(() => null));
+    if (!got) return null;
+    const { vars } = got;
+    const env = {};
+    if (s.engine === "postgres") for (const n of s.names) env[n] = vars.DB_URL;
+    if (s.engine === "supabase") {
+      for (const n of s.names) env[n] = vars.API_URL;
+      for (const k of Object.keys(values).filter((k) => /SUPABASE/i.test(k))) {
+        const v = /ANON|PUBLISHABLE/i.test(k) ? vars.ANON_KEY ?? vars.PUBLISHABLE_KEY : /SERVICE_ROLE|SECRET_KEY/i.test(k) ? vars.SERVICE_ROLE_KEY ?? vars.SECRET_KEY : /JWT_SECRET/i.test(k) ? vars.JWT_SECRET : undefined;
+        if (v) env[k] = v;
+      }
+    }
+    return Object.values(env).every(Boolean) && Object.keys(env).length ? { how: "supabase", env, pass: [], started: got.started } : null;
+  }
+
+  // An empty database on this machine, built by the app's own migrations.
+  async function shadow(s) {
+    if (inParts(s)) return { why: "parts" };
+    const dir = dirs.find((d) => MIGRATORS.some((m) => m.finds(d)));
+    const migrator = dir && MIGRATORS.find((m) => m.finds(dir));
+    if (!migrator) return { why: "no-migrations" };
+    const name = `cortad_shadow_${process.pid}_${Date.now().toString(36)}`;
+    const row = { kind: "shadow", key: s.key, made: name };
+    book.add(row);
+    const got = await emptyPg(here, name);
+    if (got.why) { book.remove(row); return { why: got.why === "down" || got.why === "auth" || got.why === "missing" ? "no-local" : "other" }; }
+    made.push(row);
+    const address = `${encodeURIComponent(here.user)}${here.password ? `:${encodeURIComponent(here.password)}` : ""}@${here.host}:${here.port}/${name}`;
+    const env = Object.fromEntries(s.names.map((n) => [n, `${/^([a-z][\w+.-]*):\/\//i.exec(values[n])[1]}://${address}`]));
+    const ok = migrator.files
+      ? await (async () => { for (const f of migrator.files(dir)) if (!(await applySql(here, name, f))) return false; return true; })()
+      : (await run(...migrator.cmd(dir), { cwd: dir, env: { ...process.env, ...values, ...env }, timeout: MIGRATE_MS })).ok;
+    return ok ? { how: "shadow", tool: migrator.tool, env, pass: [] } : { why: "migrations", tool: migrator.tool };
+  }
+
+  return {
+    // Copies a session that died left behind.
+    orphans: async () => { for (const kind of Object.keys(undo)) for (const row of book.orphans(kind)) await undone(row); },
+    async keep(s) {
+      const why = [];
+      if (NEON_HOST.test(s.host)) {
+        if (!api) why.push("neon-key");
+        else { const got = await neon(s).catch(() => null); if (got) return got; why.push("neon"); }
+      }
+      if (SUPABASE_HOST.test(s.host) || s.engine === "supabase") {
+        const got = inParts(s) ? null : await supabaseCopy(s).catch(() => null);
+        if (got) return got;
+        why.push(inParts(s) ? "parts" : "supabase");
+      }
+      if (s.engine !== "postgres") return { why: [...why, "engine"] };
+      const got = await shadow(s).catch(() => ({ why: "other" }));
+      return got.env ? got : { why: [...why, got.why], tool: got.tool };
+    },
+    drop: async () => { for (const row of made.splice(0).reverse()) await undone(row); },
+  };
+}

package/lib/identities.mjs

@@ -26,7 +26,7 @@ const SOURCE = /^(?:env:[A-Z_][A-Z0-9_]*(?:\|[A-Z_][A-Z0-9_]*)*|gen:(?:username|
 // before the program saw it. Still no quote, angle bracket, `$`, backtick or semicolon.
 const WHERE = /^[\w./:@()[\] -]{1,300}$/;
 const BASE = /^http:\/\/(?:127\.0\.0\.1|\[::1\]|localhost):\d{2,5}$/;
-const KINDS = new Set(["header", "login", "jwt", "upstream", "firebase", "authjs", "supabase", "basic"]);
+const KINDS = new Set(["header", "login", "jwt", "upstream", "firebase", "authjs", "supabase", "basic", "clerk", "supabase-admin"]);
 const STATUSES = new Set(["minted", "sealed", "absent", "refused", "unreachable", "upstream"]);
 
 // A credential the app's own environment names for its own account: a user-side name and a