cortad 0.3.0-rc.9 → 0.3.1-rc.1

package/lib/data.mjs

@@ -0,0 +1,143 @@
+// Your app's own database, kept out of the run's way. A run creates people, conversations and
+// records by the hundred; written into the file your app keeps its real data in, they stay there
+// after the run. So an app started here runs against a copy of its database file, made in this
+// command's own temp folder and pointed at through the same variable, and the original is never
+// opened. What cannot be copied (a database server, a file your code names with no variable in
+// front of it, an app that was already running) is said before the first run, in one sentence.
+import { copyFileSync, cpSync, existsSync, mkdirSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { basename, dirname, isAbsolute, join, relative, resolve } from "node:path";
+
+const FILE_DB = /\.(?:db|sqlite3?|duckdb)$/i;
+// sqlite:///x.db (SQLAlchemy, relative), sqlite:////abs/x.db, sqlite+aiosqlite:///x.db, file:./dev.db (Prisma, libsql).
+const FILE_URL = /^(sqlite(?:\+\w+)?:\/\/\/|file:(?:\/\/(?=\/))?)([^?]*)(\?.*)?$/i;
+const SERVER_URL = /^(postgres(?:ql)?|mysql|mariadb|mongodb(?:\+srv)?|mssql|sqlserver|cockroachdb)(?:\+\w+)?:\/\//i;
+const ENGINE = { postgres: "Postgres", postgresql: "Postgres", cockroachdb: "CockroachDB", mysql: "MySQL", mariadb: "MariaDB", mongodb: "MongoDB", "mongodb+srv": "MongoDB", mssql: "SQL Server", sqlserver: "SQL Server" };
+
+// What one value names: a database file (with how to write the value again for another path), a
+// database server, or nothing.
+export function databaseOf(value) {
+  const v = String(value ?? "").trim();
+  if (!v) return null;
+  const server = SERVER_URL.exec(v);
+  if (server) return { server: ENGINE[server[1].toLowerCase()] ?? server[1] };
+  const url = FILE_URL.exec(v);
+  if (url) {
+    const path = decodeURIComponent(url[2]);
+    if (!path || path === ":memory:" || path.startsWith(":memory")) return null;
+    return { path, write: (to) => `${url[1]}${to}${url[3] ?? ""}`, prisma: /^file:/i.test(url[1]) };
+  }
+  if (!v.includes("://") && FILE_DB.test(v)) return { path: v, write: (to) => to };
+  return null;
+}
+
+// A folder the app keeps its data in, named by a variable (DATA_DIR=./data): a database file sits
+// directly inside it. The whole folder is the database then, uploads and backups beside it.
+const FOLDER_NAME = /DATA|DB|DATABASE|STORAGE|STORE|PERSIST|SQLITE|DUCK/i;
+function dataFolder(name, value, dirs, appDir, root) {
+  const v = String(value ?? "").trim();
+  if (!FOLDER_NAME.test(name) || !v || v.includes("://") || FILE_DB.test(v) || !/^[.~/\w]/.test(v)) return null;
+  for (const place of [appDir, ...dirs].map((d) => resolve(d, v))) {
+    if (place === root || place === appDir || !place.startsWith(root + "/")) continue;
+    let names;
+    try { if (!statSync(place).isDirectory()) continue; names = readdirSync(place); } catch { continue; }
+    if (names.some((n) => FILE_DB.test(n))) return place;
+  }
+  return null;
+}
+const sizeOf = (dir, cap) => {
+  let total = 0;
+  const walk = (d) => { for (const e of readdirSync(d, { withFileTypes: true })) { if (total > cap) return; const p = join(d, e.name); if (e.isDirectory()) walk(p); else if (e.isFile()) total += statSync(p).size; } };
+  try { walk(dir); } catch { /* counted what it could */ }
+  return total;
+};
+
+// A name the code reads with a default written beside it: os.getenv("DATABASE_URL", "sqlite:///./app.db"),
+// process.env.DB_PATH ?? "./data.db". With nothing in the environment, the default is the database.
+const DEFAULTED = /(?:os\.(?:environ\.get|getenv)|\bgetenv)\(\s*['"]([A-Za-z_]\w*)['"]\s*,\s*['"]([^'"\n]+)['"]|process\.env(?:\.([A-Za-z_]\w*)|\[\s*['"]([A-Za-z_]\w*)['"]\s*\])\s*(?:\?\?|\|\|)\s*['"]([^'"\n]+)['"]/g;
+// A database file opened by a path written in the code, with no variable in front of it.
+const OPENED = /(?:sqlite3\.connect|aiosqlite\.connect|duckdb\.connect|new\s+(?:sqlite3\.)?Database|create_(?:async_)?engine)\(\s*['"]([^'"\n]+)['"]/g;
+const CODE = /\.(?:[cm]?[jt]sx?|py|rb|go|php)$/;
+// A test opens its own scratch file; that is not where the app keeps its data.
+const TEST = /(?:^|\/)(?:tests?|__tests__|spec|e2e|fixtures?)\/|[._-](?:test|spec)\.[^/]+$|(?:^|\/)(?:test_[^/]+|conftest)\.py$/;
+// A folder bigger than this is not copied: said instead, so the person decides.
+const FOLDER_CAP = 1024 ** 3;
+
+function scan(sources) {
+  const defaults = {};
+  const opened = [];
+  for (const file of sources) {
+    if (!CODE.test(file) || TEST.test(file)) continue;
+    let text = "";
+    try { if (statSync(file).size > 512_000) continue; text = readFileSync(file, "utf8"); } catch { continue; }
+    for (const m of text.matchAll(DEFAULTED)) {
+      const name = m[1] ?? m[3] ?? m[4];
+      const value = m[2] ?? m[5];
+      if (name && !(name in defaults) && databaseOf(value)) defaults[name] = value;
+    }
+    for (const m of text.matchAll(OPENED)) { const db = databaseOf(m[1]); if (db?.path) opened.push({ file, path: db.path }); }
+  }
+  return { defaults, opened };
+}
+
+// Where a relative path lands. The app's own folder first, which is where it runs; then the folder
+// of the env file that named it, which some settings loaders resolve against; for Prisma, the folder
+// its schema lives in. The first place the file exists is the one; none, and it is the app's folder.
+function located(db, dirs, appDir) {
+  if (isAbsolute(db.path)) return db.path;
+  const prisma = db.prisma ? [join(appDir, "prisma")] : [];
+  const places = [...prisma, appDir, ...dirs].map((d) => resolve(d, db.path));
+  return places.find((p) => existsSync(p)) ?? places[0];
+}
+
+// values: the environment the app will start with, names to values. from: the env file each name
+// was read from, when there is one. Returns the variables to start the app with, and what to say.
+export function keepData({ values, from = {}, appDir, root = appDir, work, sources = [], started = true }) {
+  const { defaults, opened } = scan(sources);
+  const all = { ...defaults, ...values };
+  const env = {};
+  const copied = [];
+  const said = [];
+  const moved = new Set();
+  const rel = (p) => relative(root, p) || basename(p);
+  for (const [name, value] of Object.entries(all)) {
+    const db = databaseOf(value);
+    const folder = db ? null : dataFolder(name, value, from[name] ? [dirname(from[name])] : [], appDir, root);
+    if (folder) {
+      moved.add(folder);
+      if (!started) { said.push(`Your app was already running when this command started, so it writes to its own data folder, ${rel(folder)}/: trials write into it. Stop your app and run the command again to run against a copy.`); continue; }
+      if (sizeOf(folder, FOLDER_CAP) > FOLDER_CAP) { said.push(`Your data folder ${rel(folder)}/ (${name}) is over 1 GB, so it is not copied: trials write into it.`); continue; }
+      const to = join(work, "data", String(copied.length), basename(folder));
+      cpSync(folder, to, { recursive: true });
+      env[name] = to;
+      copied.push({ name, from: folder, to });
+      said.push(`Your app runs against a copy of its data folder ${rel(folder)}/, through ${name}; the original is not touched.`);
+      continue;
+    }
+    if (!db) continue;
+    if (db.server) {
+      said.push(`Trials write into the ${db.server} database ${name} names: a database server cannot be copied here, so what a run creates stays in it. Point ${name} at a scratch database before a run if that one holds real data.`);
+      continue;
+    }
+    const original = located(db, from[name] ? [dirname(from[name])] : [], appDir);
+    moved.add(original);
+    if (!started) {
+      said.push(`Your app was already running when this command started, so it writes to its own database, ${rel(original)}: trials write into it. Stop your app and run the command again to run against a copy.`);
+      continue;
+    }
+    const to = join(work, "data", String(copied.length), basename(original));
+    mkdirSync(dirname(to), { recursive: true });
+    // The file and the journal beside it: SQLite keeps recent writes in -wal until a checkpoint.
+    if (existsSync(original)) for (const tail of ["", "-wal", "-shm", "-journal"]) if (existsSync(original + tail)) copyFileSync(original + tail, to + tail);
+    env[name] = db.write(to);
+    copied.push({ name, from: original, to });
+    said.push(`Your app runs against a copy of ${rel(original)}, through ${name}; the original is not touched.`);
+  }
+  for (const o of opened) {
+    const path = resolve(dirname(o.file), o.path);
+    const cwdPath = resolve(appDir, o.path);
+    if ([path, cwdPath].some((p) => moved.has(p) || [...moved].some((m) => p.startsWith(m + "/")))) continue;
+    moved.add(cwdPath);
+    said.push(`Your app opens ${o.path} by a path written in ${rel(o.file)}, with no variable to point it at a copy: trials write into that file.`);
+  }
+  return { env, copied, said };
+}

package/lib/identities.mjs

@@ -26,9 +26,18 @@ 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"]);
+const KINDS = new Set(["header", "login", "jwt", "upstream", "firebase", "authjs", "supabase", "basic"]);
 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
+// password-side name that share a prefix. The prefix is the name with its trailing token removed,
+// so USER_USERNAME pairs with USER_PASSWORD and TUDUDI_USER_EMAIL with TUDUDI_USER_PASSWORD.
+const USER_TOKEN = /_(?:USERNAME|USER|EMAIL|LOGIN)$/;
+const SECRET_TOKEN = /_(?:PASSWORD|PASS|SECRET)$/;
+const CRED_USER_FIELD = /^(?:e-?mail|user(?:_?name)?|login|account|identifier)$/i;
+const CRED_PASS_FIELD = /^(?:password|passcode|pass|pwd)$/i;
+const SIGN_IN_ROUTE = /(?:^|\/)(?:login|signin|sign-in|sign_in|session|token|authenticate)(?:\/|$)/i;
+
 const slug = (role) => role.replace(/[^a-z0-9-]/g, "-");
 export const identityHeaderFile = (role) => (ROLE.test(role) ? HEADER_FILE.replace("%s.%s", `${slug(role)}.header`) : null);
 // The curl argument a probe inside the box adds to speak as a role: the header line is read there,
@@ -450,6 +459,18 @@ def sealed(recipe, env):
     return {"status": "sealed", "header": recipe["header"], "line": "%s: %s" % (recipe["header"], bearer(recipe["header"], v)), "note": " or ".join(recipe["env"])}
 
 
+# HTTP Basic from the username and password the app's own environment names: env[0] is the user,
+# env[1] the password. The line carries the scheme verbatim, so it is not run through bearer().
+def basic(recipe, env):
+    names = recipe.get("env", [])
+    user = env.get(names[0]) if len(names) > 0 else None
+    pw = env.get(names[1]) if len(names) > 1 else None
+    if not user or not pw:
+        return {"status": "absent", "note": " and ".join(names)}
+    raw = base64.b64encode(("%s:%s" % (user, pw)).encode("utf-8")).decode("ascii")
+    return {"status": "minted", "header": recipe["header"], "line": "%s: Basic %s" % (recipe["header"], raw), "expires": int(time.time()) + TTL, "note": " and ".join(names)}
+
+
 def keep(path, line):
     fd = os.open(path, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
     with os.fdopen(fd, "w", encoding="utf-8") as f:
@@ -509,10 +530,15 @@ def main():
                     got = login(recipe, role, role_value, env)
                 elif recipe["kind"] == "firebase":
                     got = firebase(recipe, role, env)
+                elif recipe["kind"] == "basic":
+                    got = basic(recipe, env)
                 else:
                     got = {"status": "upstream", "note": " or ".join(recipe["env"]) or recipe["role"]}
             except Exception as err:
                 got = {"status": "unreachable", "note": type(err).__name__}
+            # A sign-in the environment named its own credential for records which names it used.
+            if recipe.get("envCred") and got.get("status") == "minted" and not got.get("note"):
+                got["note"] = " and ".join(recipe.get("env", []))
             line = got.pop("line", None)
             if line:
                 keep(FILE % (slug(role), "header" if got["status"] == "minted" else "sealed"), line)
@@ -551,12 +577,96 @@ export function parseIdentityReport(text) {
   return { identities };
 }
 
+// The credential pairs an environment names, by shared prefix. Names only, never values.
+export function credentialPairs(names) {
+  const list = (Array.isArray(names) ? names : []).filter((n) => typeof n === "string" && ENV_NAME.test(n));
+  const users = list.filter((n) => USER_TOKEN.test(n)).map((n) => ({ name: n, prefix: n.replace(USER_TOKEN, "") }));
+  const secrets = list.filter((n) => SECRET_TOKEN.test(n)).map((n) => ({ name: n, prefix: n.replace(SECRET_TOKEN, "") }));
+  const pairs = [];
+  const seen = new Set();
+  for (const u of users) {
+    const s = secrets.find((x) => x.prefix === u.prefix);
+    if (s && !seen.has(u.prefix)) { seen.add(u.prefix); pairs.push({ user: u.name, secret: s.name, prefix: u.prefix }); }
+  }
+  return pairs;
+}
+
+const routeRole = (route) => {
+  const seg = route.split("/").filter((s) => s && !/^(?:api|v\d+|auth)$/i.test(s)).pop() ?? "user";
+  const r = seg.toLowerCase().replace(/[^a-z0-9-]/g, "-").replace(/^-+|-+$/g, "").slice(0, 20);
+  return /^[a-z]/.test(r) ? r : "user";
+};
+const uniqueRole = (base, used) => {
+  const stem = /^[a-z]/.test(base) ? base : "account";
+  let role = stem;
+  for (let n = 2; used.has(role); n += 1) role = `${stem}-${n}`;
+  used.add(role);
+  return role;
+};
+
+// When the app's own environment names a credential pair, the box can sign in with it. Each login
+// recipe whose sign-in form takes a username or email and a password is filled from the pair
+// instead of a generated account; each discovered sign-in route with no recipe becomes one; and an
+// HTTP Basic identity is minted for a door that answers 401 with a Basic challenge. Values are
+// opened by the mint program on the machine, never here: this only rewrites which env name a field
+// reads. A register step (one of several, not a sign-in) keeps its fresh account.
+export function envCredentialRecipes(recipes, names, loginRoutes = []) {
+  const list = Array.isArray(recipes) ? recipes : [];
+  const pairs = credentialPairs(names);
+  if (!pairs.length) return list;
+  const pair = pairs[0];
+  const userSrc = `env:${pair.user}`;
+  const passSrc = `env:${pair.secret}`;
+  const used = new Set(list.map((r) => r?.role).filter(Boolean));
+  const covered = new Set();
+  const out = list.map((r) => {
+    if (r?.kind !== "login" || !Array.isArray(r.steps)) return r;
+    let touched = false;
+    const steps = r.steps.map((s) => {
+      if (r.steps.length !== 1 && !SIGN_IN_ROUTE.test(s.route)) return s;
+      const body = { ...(s.body ?? {}) };
+      let hit = false;
+      for (const [f, v] of Object.entries(body)) {
+        if (typeof v !== "string" || !v.startsWith("gen:")) continue;
+        if (CRED_USER_FIELD.test(f)) { body[f] = userSrc; hit = true; }
+        else if (CRED_PASS_FIELD.test(f)) { body[f] = passSrc; hit = true; }
+      }
+      if (!hit) return s;
+      covered.add(s.route);
+      touched = true;
+      return { ...s, body };
+    });
+    return touched ? { ...r, steps, env: [...new Set([...(r.env ?? []), pair.user, pair.secret])], envCred: true } : r;
+  });
+  const known = new Set(out.flatMap((r) => (r?.steps ?? []).map((s) => s.route)));
+  const userField = /_EMAIL$/.test(pair.user) ? "email" : "username";
+  for (const route of (Array.isArray(loginRoutes) ? loginRoutes : []).slice(0, 6)) {
+    if (typeof route !== "string" || !route.startsWith("/") || known.has(route) || covered.has(route)) continue;
+    out.push({
+      kind: "login", role: uniqueRole(routeRole(route), used), header: "authorization", env: [pair.user, pair.secret],
+      steps: [{ route, body: { [userField]: userSrc, password: passSrc } }], opens: [], envCred: true,
+      where: `your environment (${pair.user} and ${pair.secret})`,
+    });
+  }
+  // A Basic identity for each pair as well: a door that wants a sign-in form ignores it, and a door
+  // behind HTTP Basic (which declares no route to fill) is reached by nothing else.
+  for (const p of pairs) {
+    out.push({
+      kind: "basic", role: uniqueRole(slug(p.prefix.toLowerCase()) || "account", used), header: "authorization",
+      env: [p.user, p.secret], opens: [], envCred: true, where: `your environment (${p.user} and ${p.secret})`,
+    });
+  }
+  return out;
+}
+
 // What each row means to the person whose app this is.
 export function identitySentence(row) {
   switch (row.status) {
     case "minted": return row.kind === "firebase"
       ? `signed in as ${row.role} through the Firebase emulator standing in for your project; the token stays inside the sandbox`
-      : `signed in as ${row.role} through your own door ${row.door}; the token stays inside the sandbox`;
+      : row.kind === "basic"
+        ? `signed in as ${row.role} with the username and password your environment sets (${row.note ?? "two variables"}); the header stays inside the sandbox`
+        : `signed in as ${row.role} through your own door ${row.door}; the token stays inside the sandbox`;
     case "sealed": return `${row.role} is the sealed ${row.note} value itself; it never leaves the sandbox, so only the compile's own probe can speak as it`;
     case "absent": return `could not sign in as ${row.role}: ${row.note} is not in the environment you sealed`;
     case "refused": return `your door refused the ${row.role} sign-in (${row.note}), so cases behind it are counted and not driven`;

package/lib/mint.mjs

@@ -10,7 +10,7 @@ import { existsSync, mkdirSync, readFileSync, rmSync, statSync, writeFileSync }
 import { homedir } from "node:os";
 import { basename, dirname, join } from "node:path";
 import { promisify } from "node:util";
-import { identityScript, parseIdentityReport } from "./identities.mjs";
+import { envCredentialRecipes, identityScript, parseIdentityReport } from "./identities.mjs";
 
 const exec = promisify(execFile);
 export const AS_HEADER = "x-cortad-as";
@@ -128,7 +128,13 @@ export function makeIdentities({ root, work, envFiles, sourceFiles = () => [], s
   }
 
   async function mint(body, port) {
-    const recipes = Array.isArray(body?.recipes) ? body.recipes.slice(0, 12) : [];
+    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 (!recipes.length || !port) return { identities: [] };
     mkdirSync(dir, { recursive: true, mode: 0o700 });
     const out = join(dir, "bl-identities.json");
@@ -141,7 +147,9 @@ export function makeIdentities({ root, work, envFiles, sourceFiles = () => [], s
     const merged = Object.assign({}, ...[...envs().all].reverse());
     const emulated = Boolean(merged.FIREBASE_AUTH_EMULATOR_HOST);
     const refused = new Map();
-    for (const r of recipes) { const why = refusal(r, merged, (value) => inSource(root, sourceFiles(), value)); if (why && typeof r?.role === "string") refused.set(r.role, why); }
+    // 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));
     // 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.

package/lib/read-text.mjs

@@ -12,11 +12,19 @@ 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")}` : ""}.`;
 };
-const ruleLine = (e) => `  ${at(e.path, e.line)}  "${clip(e.text, 300)}"`;
+// 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 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`]);
-const standardLine = (x) => `  ${x.path ? `${at(x.path, x.line)}  ` : ""}${x.standard}${x.detail ? `: ${clip(x.detail, 240)}` : ""}${x.decidedBy ? ` (decided by ${x.decidedBy === "code" ? "code" : "a model"})` : ""}`;
-const trialsHead = (t) => headOf("Trials", [has(t.written) && `${num(t.written)} written`, has(t.playable) && `${num(t.playable)} playable`]);
+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")}` : ""}`]);
+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.
+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)}  ` : ""}${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 heldWhy = (h) => `${SIDE[h.side] ? `, ${SIDE[h.side]}` : ""}${h.why ? `: ${clip(h.why, 300)}` : ""}`;
 const named = (label, group, max = 12) => {
   if (!group) return null;
@@ -39,8 +47,10 @@ export function readLines(r) {
   const m = r.machine;
   if (m) {
     const misses = m.misses ?? [];
-    lines.push(standardsHead(m), ...misses.slice(0, 12).map(standardLine));
-    if (misses.length > 12) lines.push(`  and ${misses.length - 12} more.`);
+    // "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` : ""}.`);
@@ -68,7 +78,7 @@ function sectionOf(r, show) {
       const mets = m.mets ?? [];
       return {
         head: standardsHead(m),
-        lines: [misses.length && counted("Missed", m.missed, misses.length), ...misses.map(standardLine), mets.length && counted("Met", m.met, mets.length), ...mets.map(standardLine)].filter(Boolean),
+        lines: [misses.length && (has(m.problems) ? counted("Problems", m.problems, misses.length) : counted("Missed", m.missed, misses.length)), ...misses.map(standardLine), mets.length && counted("Met", m.met, mets.length), ...mets.map(standardLine)].filter(Boolean),
         continued: "Engineering standards, continued.",
       };
     }

package/lib/start.mjs

@@ -38,22 +38,61 @@ export function lockRoot(dir, root) {
 // The manager this repository was installed with, named by its lockfile.
 const manager = (dir) => (existsSync(join(dir, "pnpm-lock.yaml")) ? "pnpm" : existsSync(join(dir, "yarn.lock")) ? "yarn" : existsSync(join(dir, "bun.lockb")) || existsSync(join(dir, "bun.lock")) ? "bun" : "npm");
 
+// A script that only bundles or serves a browser build: the AI is never behind it.
+const BUNDLER = /\b(?:vite|next|nuxt|astro|svelte-kit|vinxi|webpack(?:-dev-server)?|react-scripts|parcel|rsbuild|storybook)\b/;
+// A script that runs a server file, or runs everything at once.
+const RUNS_SERVER = /\b(?:node|nodemon|tsx|ts-node(?:-dev)?|bun run|deno run|concurrently|npm-run-all|run-p|turbo run)\b|\.(?:sh|mjs|cjs|js|ts)\b/;
+const SERVER_SCRIPT = /^(?:dev:(?:full|all|server|api|backend)|server|start:server|backend(?::dev)?|api(?::dev)?|start:api|serve:api|start)$/;
+// The script that starts the AI, not the page: flowviz's dev runs vite and its server runs node
+// server.js with openai behind express; tududi's dev is the frontend and backend:dev the API.
+function serverScript(scripts, deps) {
+  const first = ["dev", "develop", "start:dev", "serve", "start"].find((s) => scripts?.[s]);
+  if (!first) return null;
+  const command = String(scripts[first]);
+  const frontendOnly = BUNDLER.test(command) && !RUNS_SERVER.test(command.replace(BUNDLER, ""));
+  if (!frontendOnly || !deps.some((d) => SERVER.test(d) || MODEL_SDK.test(d))) return first;
+  const better = Object.keys(scripts).filter((s) => SERVER_SCRIPT.test(s) && s !== first && RUNS_SERVER.test(String(scripts[s])) && !(BUNDLER.test(String(scripts[s])) && !/concurrently|npm-run-all|run-p|\.sh\b/.test(String(scripts[s]))));
+  const rank = (s) => (/full|all/.test(s) ? 0 : /server|backend|api/.test(s) ? 1 : 2);
+  return better.sort((a, b) => rank(a) - rank(b))[0] ?? first;
+}
+
 function nodeStart(dir, onPath) {
   const pkg = json(join(dir, "package.json"));
   if (!pkg) return null;
-  const script = ["dev", "develop", "start:dev", "serve", "start"].find((s) => pkg.scripts?.[s]);
+  const deps = Object.keys({ ...(pkg.dependencies ?? {}), ...(pkg.devDependencies ?? {}) });
+  const script = serverScript(pkg.scripts, deps);
   if (!script) return null;
   const locked = manager(dir);
-  const deps = Object.keys({ ...(pkg.dependencies ?? {}), ...(pkg.devDependencies ?? {}) });
   // A lockfile names the manager the repository was installed with, not one this machine has.
   return { cmd: `${onPath(locked) ? locked : "npm"} run ${script}`, serves: deps.some((d) => SERVER.test(d)) || SERVES_JS.test(pkg.scripts[script]) };
 }
 
+// A package that serves through its own console script: pyproject [project.scripts] names it, and
+// its command module defines a serve or run command (typer, click, argparse). RepoWiki starts with
+// `repowiki serve --port N`; no module-level app object exists to hand uvicorn.
+function consoleServe(dir, venv) {
+  if (!venv) return null;
+  const toml = read(join(dir, "pyproject.toml"));
+  const block = /\[project\.scripts\]([^[]*)/.exec(toml)?.[1] ?? "";
+  for (const m of block.matchAll(/^\s*"?([\w.-]+)"?\s*=\s*"([\w.]+):(\w+)"/gm)) {
+    const [, name, module] = m;
+    const file = ["src/", ""].map((base) => join(dir, base, `${module.split(".").join("/")}.py`)).find(existsSync);
+    const text = file ? read(file) : "";
+    const sub = /(?:def serve\(|@\w+\.command\(\s*(?:name\s*=\s*)?["']serve["']|add_parser\(\s*["']serve["']|["']serve["']\s*:)/.test(text) ? "serve"
+      : /(?:def run\(|add_parser\(\s*["']run["']|@\w+\.command\(\s*(?:name\s*=\s*)?["']run["'])/.test(text) ? "run" : null;
+    const bin = join(dirname(venv), name);
+    if (sub && existsSync(bin)) return { cmd: `${JSON.stringify(bin)} ${sub}${/--port/.test(text) ? " --port 8000" : ""}`, serves: true };
+  }
+  return null;
+}
+
 function pythonStart(dir, onPath) {
   if (!["requirements.txt", "pyproject.toml", "manage.py", "Pipfile", "uv.lock"].some((f) => existsSync(join(dir, f)))) return null;
   const venv = [".venv/bin/python", "venv/bin/python", "env/bin/python"].map((p) => join(dir, p)).find(existsSync);
   const py = venv ? JSON.stringify(venv) : existsSync(join(dir, "uv.lock")) && onPath("uv") ? "uv run python" : existsSync(join(dir, "poetry.lock")) && onPath("poetry") ? "poetry run python" : "python3";
   if (existsSync(join(dir, "manage.py"))) return { cmd: `${py} manage.py runserver`, serves: true };
+  const served = consoleServe(dir, venv);
+  if (served) return served;
   const named = [...new Set([...ENTRIES, ...entriesIn(dir)])].map((entry) => [entry, read(join(dir, entry))]).filter(([, text]) => text);
   const manifest = `${read(join(dir, "requirements.txt"))}\n${read(join(dir, "pyproject.toml"))}\n${read(join(dir, "Pipfile"))}`;
   // The file that serves before the file that merely runs: src/run_agent.py runs a conversation in
@@ -115,7 +154,11 @@ export function startPlan({ root, typed, onPath }) {
   if (typed) return { cmd: typed, cwd: root };
   const pkg = json(join(root, "package.json"));
   const mono = Boolean(pkg?.workspaces) || existsSync(join(root, "pnpm-workspace.yaml")) || existsSync(join(root, "turbo.json")) || existsSync(join(root, "lerna.json"));
-  const own = mono ? null : startOf(root, onPath);
+  // A root with both manifests: the side that names a model SDK is the app; the other is its page.
+  const rootPkg = json(join(root, "package.json"));
+  const rootPy = `${read(join(root, "requirements.txt"))}\n${read(join(root, "pyproject.toml"))}`;
+  const pythonFirst = Boolean(rootPkg) && PY_MODEL.test(rootPy) && !Object.keys({ ...(rootPkg.dependencies ?? {}), ...(rootPkg.devDependencies ?? {}) }).some((d) => MODEL_SDK.test(d));
+  const own = mono ? null : pythonFirst ? (pythonStart(root, onPath) ?? nodeStart(root, onPath)) : startOf(root, onPath);
   if (own) return { cmd: own.cmd, cwd: root };
   const ranked = workspaces(root).map((dir) => ({ dir, start: startOf(dir, onPath), weight: weight(dir, relative(root, dir)) })).filter((w) => w.start).sort((a, b) => b.weight - a.weight);
   const best = ranked[0];

package/lib/text.mjs

@@ -22,9 +22,14 @@ export function statusText(d) {
   const plan = planLine(d.plan);
   if (plan) lines.push(plan);
   if (d.app?.said) lines.push(`App: ${d.app.said}`);
+  for (const s of d.app?.data ?? []) lines.push(`Data: ${s}`);
+  if (d.read?.complete === false) lines.push("The read of your repository is still running; the lists below fill in as it finishes.");
   if (d.read) lines.push(...readLines(d.read));
   if (d.run === null) lines.push("No run yet.");
   else if (d.run) lines.push(...runLines(d.run, "latest "));
+  // Trials the read wrote after this run chose its own: the one count that is not the run's.
+  const since = (d.read?.trials?.written ?? 0) - (d.run?.trials?.written ?? Infinity);
+  if (since > 0 && d.run?.kind !== "verify") lines.push(`${plural(since, "more trial")} written since this run; the next run chooses from them too.`);
   if (d.field) lines.push(`Production: ${d.field.connected ? "connected" : "not connected"}.`);
   if (d.links?.lab && (d.read || d.run)) lines.push(`For the person: ${d.links.lab} shows this in the browser.`);
   if (d.run && !finished(d.run)) lines.push(`next: run_status ${d.run.jobId}`);
@@ -41,10 +46,23 @@ function planLine(p) {
 
 // The number with what it stands on: a 100 beside an app that stopped, or from five readings, read
 // as a verdict to two agents. Under the 22-reading floor it is provisional and says so.
+function coverageLine(d) {
+  const never = d.questionsOf - d.questionsAsked;
+  const share = Math.round((100 * d.questionsAsked) / d.questionsOf);
+  return `Measured ${num(d.questionsAsked)} of ${plural(d.questionsOf, "check")} (${share}%)${never > 0 ? `; ${num(never)} never came up in the situations played, so nothing below speaks for them` : ""}.`;
+}
+
 function scoreLine(d) {
   const floor = has(d.decided) && d.decided < 22;
-  return `${floor ? "Provisional score" : "Score"} ${num(d.score)} of 100${interval(d.ci)}${floor ? `, from ${plural(d.decided, "decided reading")}: under the 22-reading floor, so not a verdict yet` : ""}.`;
+  // The number never stands without its denominator: "93 of 100" read as broad assurance to four
+  // agents whose runs had measured a quarter of the checks.
+  const on = has(d.questionsAsked) && has(d.questionsOf) && d.questionsOf > 0 ? ` on the ${num(d.questionsAsked)} of ${plural(d.questionsOf, "check")} measured` : "";
+  return `${floor ? "Provisional score" : "Score"} ${num(d.score)} of 100${on}${interval(d.ci)}${floor ? `, from ${plural(d.decided, "decided reading")}: under the 22-reading floor, so not a verdict yet` : ""}.`;
 }
+// A row the run held back names a door and why, or, when no door could take it, only the reason.
+const heldBackLine = (h) => h.why === "not testable here"
+  ? `Held back: ${plural(h.trials, "trial")} cannot be played here: ${clip(h.surface, 200).replace(/\.$/, "")}.`
+  : `Held back: ${plural(h.trials, "trial")} on ${h.surface}${h.why ? `, ${clip(h.why, 200)}` : ""}.`;
 const haltLine = (h) => `${h.side === "ours" ? "We lost your app" : "Your app stopped answering"} after ${plural(h.after, "turn")}${h.why ? `: ${clip(h.why, 200)}` : ""}. The score covers the turns before that.`;
 const LAYER_WORDS = {
   retrieval: "what the store returned behind the reply, not how the reply was written",
@@ -59,18 +77,44 @@ function runLines(d, prefix = "") {
   const done = finished(d);
   const played = d.of ? `${num(d.played ?? 0)} of ${plural(d.of, "trial")} played` : "no trial played yet";
   const lines = [`${upper(`${prefix}${d.kind === "verify" ? "verify" : "run"}`)} ${d.jobId}: ${d.status === "succeeded" || !d.status ? (done ? "finished" : "running") : d.status}, ${played}.`];
-  if (done && typeof d.score === "number") lines.push(scoreLine(d));
+  // Coverage before the number: a 97 beside 59 of 80 checks that never fired read as production-ready
+  // to every agent that got it. What was measured leads, then the rate on what was measured.
+  if (done && has(d.questionsAsked) && has(d.questionsOf) && d.questionsOf > 0) lines.push(coverageLine(d));
+  if (done && d.blocked) lines.push(d.blocked);
+  if (done && d.notCounted) lines.push(d.notCounted);
+  // A verify is a move, not a score: "100 of 100" on a replay whose run before decided nothing read
+  // as a clean bill to bloom's agent, beside "zero verified fixes".
+  if (done && typeof d.score === "number" && d.kind !== "verify") lines.push(scoreLine(d));
   if (done && d.halted) lines.push(haltLine(d.halted));
+  if (done && has(d.readingsHeld) && has(d.readings) && d.readings > 0) lines.push(`The question readings held in ${num(d.readingsHeld)} of ${num(d.readings)}, ${Math.round((100 * d.readingsHeld) / d.readings)}%; the score is the case checks' pass rate on the checks measured.`);
   if (done && has(d.findings)) lines.push(`${plural(d.findings, "finding")}.`);
+  const trials = trialsLine(d);
+  if (trials) lines.push(trials);
+  // Every row, or six and the rest in one line, so the rows always sum to the held-back count.
+  const heldRows = (d.heldBack ?? []).filter((h) => h.trials > 0);
+  for (const h of heldRows.slice(0, 6)) lines.push(heldBackLine(h));
+  if (heldRows.length > 6) lines.push(`Held back: ${plural(heldRows.slice(6).reduce((n, h) => n + h.trials, 0), "more trial")} for ${plural(heldRows.length - 6, "other reason")}.`);
   const reads = readingsLine(d);
   if (reads) lines.push(reads);
   if (d.stopped) lines.push(stoppedLine(d));
   for (const f of d.faults ?? []) lines.push(`Fault${SIDE[f.side] ? ` ${SIDE[f.side]}` : ""}: ${f.what}${f.fix ? ` ${f.fix}` : ""}`);
+  for (const s of d.data ?? []) lines.push(`Data: ${s}`);
   if (d.error) lines.push(`Error: ${d.error}`);
   if (d.verify) lines.push(...verifyLines(d.verify));
   return lines;
 }
 
+// The run's trials in one sentence that adds up: written = chosen + held back + not planned, and
+// chosen = played + not played. Three counts from three places never met before.
+function trialsLine(d) {
+  const t = d.trials;
+  // A verify replays the trials it names, so it has no written count of its own to add up.
+  if (!t || !has(t.written) || d.kind === "verify") return null;
+  const parts = [`${num(t.chosen)} chosen for this run`, t.heldBack && `${num(t.heldBack)} held back`, t.notPlanned && `${num(t.notPlanned)} not planned`].filter(Boolean);
+  const rest = t.notPlayed ? `; ${num(t.played)} played, ${num(t.notPlayed)} ${finished(d) ? "not played" : "still to play"}` : "";
+  return `Trials: ${num(t.written)} written: ${parts.join(", ")}${rest}.`;
+}
+
 // A reading is one question checked against one reply.
 function readingsLine(d) {
   if (!has(d.readings) && !has(d.questionsAsked)) return null;
@@ -116,7 +160,7 @@ export function runText(d) {
 export function startedText(d, kind, findingId) {
   const verify = (d.kind ?? kind) === "verify";
   const what = verify ? `Verify${findingId && !d.joined ? ` of ${findingId}` : ""}` : "Run";
-  return `${what} ${d.joined ? "already playing" : "started"}: ${d.jobId}.\nnext: run_status ${d.jobId}`;
+  return `${what} ${d.joined ? "already playing" : "started"}: ${d.jobId}.${d.note ? `\n${d.note}` : ""}\nnext: run_status ${d.jobId}`;
 }
 
 export const waitingText = (p, now, limitMs) =>
@@ -157,7 +201,7 @@ function ledgerLines(l) {
 // Findings grouped by the line they live at: the server's byLine, or the findings' own file and
 // line when it sends none. The same line from two server pages is one group.
 export function linesOf(d) {
-  const rows = d.byLine ?? (d.findings ?? []).filter((f) => f.file).map((f) => ({ path: f.file, line: f.line, findingIds: [f.id] }));
+  const rows = (d.byLine ?? (d.findings ?? []).map((f) => ({ path: f.file, line: f.line, findingIds: [f.id] }))).filter((r) => r.path);
   const merged = new Map();
   for (const r of rows) {
     const key = at(r.path, r.line);
@@ -170,7 +214,9 @@ export function linesOf(d) {
 export const findingsText = (d, page = 1) => pageOf(findingsPages(d), page, (n) => `findings with page ${n}`);
 
 function findingsHead(d) {
+  if (!d.runId) return ["No run has finished on this repository yet."];
   const lines = [`Run ${d.runId}: ${plural(d.findings?.length ?? 0, "finding")}.`];
+  if (d.blocked) lines.push(d.blocked);
   if (typeof d.score === "number") lines.push(scoreLine(d));
   if (d.halted) lines.push(haltLine(d.halted));
   const reads = readingsLine(d);
@@ -221,6 +267,13 @@ function findingBlock(f, placed) {
   if (f.door) lines.push(`  Endpoint: ${f.door}`);
   else if (f.doors?.length) lines.push(`  Endpoints: ${f.doors.join(", ")}`);
   if (f.where) lines.push(`  Situation: ${f.where}`);
+  if (f.fix) lines.push(`  Fix: ${f.fix}`);
+  // One cause, one finding: the same sentence broke these too, and they are not findings of their own.
+  if (f.alsoIn?.length) {
+    lines.push(`  Same cause in ${plural(f.alsoIn.length, "more place")}, the same reply sentence in each:`);
+    for (const a of f.alsoIn.slice(0, 8)) lines.push(`    ${a.where}: ${clip(a.asks, 160)}, broke in ${num(a.rate.n - a.rate.k)} of ${plural(a.rate.n, "reply", "replies")}`);
+    if (f.alsoIn.length > 8) lines.push(`    and ${num(f.alsoIn.length - 8)} more.`);
+  }
   if (f.layer && LAYER_WORDS[f.layer]) lines.push(`  Layer: ${f.layer}, ${LAYER_WORDS[f.layer]}.`);
   const r = f.rate;
   // The break count, whichever way the question is phrased: "held in 21 of 33" under a question
@@ -229,9 +282,24 @@ function findingBlock(f, placed) {
   if (f.unsettled) lines.push("  Unsettled: under the 22-reading floor.");
   const by = [f.decidedBy?.code && `code in ${plural(f.decidedBy.code, "reading")}`, f.decidedBy?.model && `a model in ${plural(f.decidedBy.model, "reading")}`].filter(Boolean);
   if (by.length) lines.push(`  Decided by ${by.join(", by ")}.`);
+  const logsShown = new Set();
+  let logRoom = 30;
   for (const q of (f.quotes ?? []).slice(0, 3)) {
-    const about = [typeof q.p === "number" && `confidence ${q.p.toFixed(2)}`, q.trialId && `trial ${q.trialId}`].filter(Boolean).join(", ");
+    const about = [typeof q.p === "number" && `confidence ${q.p.toFixed(2)}`, q.trialId && `trial ${q.trialId}`, q.door && `at ${q.door}`].filter(Boolean).join(", ");
+    // The request beside the reply: an agent handed "HTTP 502 happened" did the rest of the
+    // investigation itself.
+    if (q.asked) lines.push(`  Asked: "${clip(q.asked, 300)}"`);
     lines.push(`  Reply ${q.reply}: "${clip(q.quote, 400)}"${about ? ` (${about})` : ""}`);
+    // What a developer reproduces it from: the request as sent, the body back, the app's own log.
+    if (q.request) lines.push(`    Request: ${q.request.method} ${q.request.path}${q.request.body ? ` ${clip(q.request.body, 600)}` : ""}`);
+    if (has(q.response)) lines.push(`    Response: ${q.response ? clip(q.response, 600) : "(empty body)"}`);
+    // A page stays under what a client keeps: the same log twice is said once, and a finding
+    // prints thirty log lines at most.
+    const log = (q.log ?? []).join("\n");
+    if (log && logsShown.has(log)) lines.push("    Log: the same lines as the reply above.");
+    else for (const line of (q.log ?? []).slice(0, logRoom)) { lines.push(`    Log: ${clip(line, 240)}`); logRoom -= 1; }
+    if (log) logsShown.add(log);
+    if (q.at && q.at !== at(f.file, f.line)) lines.push(`    At ${q.at}`);
   }
   for (const line of (f.log ?? []).slice(0, 8)) lines.push(`  Log: ${clip(line, 300)}`);
   if (f.replay) lines.push(`  Replay: ${plural(f.replay.trials, "trial")}, verify ${f.id}`);

package/lib/words.mjs

@@ -1,3 +1,6 @@
+import { readFileSync } from "node:fs";
+import { resolve, sep } from "node:path";
+
 // The small pieces every rendering shares: numbers with their units, file and line, whose side a
 // stop is on, and the pages a long answer is cut into.
 
@@ -9,7 +12,21 @@ export const has = (v) => v !== undefined && v !== null;
 export const num = (x) => (typeof x === "number" ? Math.round(x).toLocaleString("en-US") : String(x));
 export const plural = (n, one, many = `${one}s`) => `${num(n)} ${n === 1 ? one : many}`;
 export const upper = (s) => `${s.charAt(0).toUpperCase()}${s.slice(1)}`;
-export const at = (path, line) => `${path}${has(line) ? `:${line}` : ""}`;
+// A line past the end of the file as it stands on this machine is not an address: the file moved
+// on since it was read, and an agent was sent to line 204 of a 172-line file. The file stays.
+// Read each time, never kept: the agent edits these files while this server runs. Only a path
+// inside the project is opened, and only its length is used.
+const linesIn = (path) => {
+  const root = process.cwd();
+  const file = resolve(root, path);
+  if (file !== root && !file.startsWith(`${root}${sep}`)) return null;
+  try { return readFileSync(file, "utf8").split("\n").length; } catch { return null; }
+};
+export const at = (path, line) => {
+  const n = has(line) && line > 0 && path ? linesIn(path) : null;
+  // A line of 0 is no line: "finding at :0" read to an agent as an address that pointed nowhere.
+  return `${path}${has(line) && line > 0 && !(n !== null && line > n) ? `:${line}` : ""}`;
+};
 export const clip = (s, max) => (String(s).length > max ? `${String(s).slice(0, max - 3)}...` : String(s));
 
 // One page of many, with the call that reads the next one: `next(2)` gives "findings with page 2".

package/local.mjs

@@ -32,6 +32,7 @@ import { mintAcross, originFor, waitForPort } from "./lib/service.mjs";
 import { listingUrl } from "./lib/listing.mjs";
 import { installPlan, missingDependency, startPlan, workspaces } from "./lib/start.mjs";
 import { openSwitches } from "./lib/switches.mjs";
+import { keepData } from "./lib/data.mjs";
 
 const argv = process.argv.slice(2);
 // The two faces a coding agent uses after the first connect (lib/cli.mjs): the MCP server the
@@ -370,8 +371,8 @@ async function verb(job) {
       // method", which is what your chat looked like from the outside. So the chain is walked the
       // way a browser walks it, one GET with redirects followed, and the request is sent again with
       // the session your app just handed out. The cookie is kept here and never leaves this machine.
-      const url = `http://127.0.0.1:${port}${path}`;
-      const yours = (to) => { try { const u = new URL(to, url); return u.hostname === "127.0.0.1" && u.port === String(port) ? u.href : null; } catch { return null; } };
+      const url = hostUrl(port, path);
+      const yours = (to) => { try { const u = new URL(to, url); return ["127.0.0.1", "::1", "[::1]", "localhost"].includes(u.hostname) && u.port === String(port) ? u.href : null; } catch { return null; } };
       let jar = "";
       const sent = (at, over = {}) => fetch(at, {
         ...init, ...over,
@@ -427,6 +428,18 @@ async function verb(job) {
       mint: (recipes, port, origin) => identities.mint({ ...b, recipes, headers: { ...(b.headers ?? {}), ...(origin ? { origin, referer: `${origin}/` } : {}) } }, port),
       originFor: (port) => originFor(port, envOrigins(envFiles)),
     })))) : { identities: [] };
+    // The last of what your app printed, for a reply it failed: the traceback a developer reads.
+    // Masked like everything else, and the folder named so its paths can be read as your files.
+    case "log": {
+      const want = Math.min(Math.max(Number(b.bytes) || 16_000, 1), 200_000);
+      try {
+        const all = readFileSync(bootLog);
+        const text = mask(all.subarray(Math.max(0, all.length - want)).toString("utf8").replace(/\x1b\[[0-9;]*[A-Za-z]/g, ""));
+        // A JVM stack names a class, not a path: the source files it could be are sent with it.
+        const jvm = /\bat\s+[\w$.]+\([\w$]+\.(?:java|kt|scala|groovy):\d+\)/.test(text);
+        return { text, root, size: all.length, ...(jvm ? { files: files.filter((f) => /\.(?:java|kt|scala|groovy)$/.test(f)).slice(0, 20_000) } : {}) };
+      } catch { return { text: "", root, size: 0 }; }
+    }
     case "restart": return restartApp();
     case "inventory": return inventoryOf(b.probe && typeof b.probe === "object" ? b.probe : {});
     // Your own pages, read here rather than in a world's shell: that shell is sealed away from
@@ -448,10 +461,26 @@ async function verb(job) {
 const exec = promisify(execFile);
 
 // ---- start or attach to the app
+// The address the app answers on: 127.0.0.1, or [::1] when it bound IPv6 localhost alone, which a
+// Vite dev server does and which a probe of 127.0.0.1 waited three minutes on.
+let appHost = "127.0.0.1";
+const hostUrl = (port, path = "/") => `http://${appHost === "::1" ? "[::1]" : appHost}:${port}${path}`;
 const answers = async (port) => {
-  try { await fetch(`http://127.0.0.1:${port}/`, { method: "GET", signal: AbortSignal.timeout(2500), redirect: "manual" }); return true; }
-  catch { return false; }
+  for (const host of [appHost, appHost === "::1" ? "127.0.0.1" : "::1"]) {
+    try {
+      await fetch(`http://${host === "::1" ? "[::1]" : host}:${port}/`, { method: "GET", signal: AbortSignal.timeout(2500), redirect: "manual" });
+      appHost = host;
+      return true;
+    } catch { /* the other family next */ }
+  }
+  return false;
 };
+// The values an env file beside the app declares, exported into its process the way `source .env`
+// would: an app with no dotenv loader of its own crashed every route without them. Example files
+// hold placeholders and are left out; the shell's own environment and the lifted limits win.
+function envExports(envFiles) {
+  return envValues(envFiles.filter((f) => !/\.(example|sample)$/.test(f)));
+}
 const onPath = (bin) => (process.env.PATH ?? "").split(":").some((dir) => dir && existsSync(join(dir, bin)));
 // Where their app lives inside this repository, and how it starts. Worked out in lib/start.mjs.
 let appDir = root;
@@ -516,7 +545,9 @@ async function ask(question) {
 let child = null;
 async function startApp() {
   const wanted = Number(flag("--port"));
-  if (wanted) {
+  // "--port 8106 --start ..." is "start it, it will answer on 8106", not "it is already on 8106":
+  // read as the latter it said nothing was answering and never ran the command it was given.
+  if (wanted && !flag("--start")) {
     if (!(await answers(wanted))) return { port: null, said: "", why: `nothing is answering on port ${wanted}, so there is nothing to ask.`, noStart: true };
     const took = await takeOver(wanted);
     if (took) return took;
@@ -557,7 +588,7 @@ async function startApp() {
     const ports = [...up.tail.matchAll(/(?::|port\s*[:=]?\s*)(\d{4,5})\b/gi)].map((m) => Number(m[1]));
     for (const port of new Set(ports)) {
       if (await answers(port)) {
-        launched = null; child = null;
+        launched = null; child = null; data = null;
         const took = await takeOver(port);
         if (took) return took;
         say(`your app is already running on port ${port}, so that one is used; its request limits stay as they are`);
@@ -694,9 +725,14 @@ async function freePortAbove(port) {
   for (let next = port + 1; next < port + 30; next++) if (!lost.has(next) && !(await listenerOn(next))) return next;
   return null;
 }
+// The port a bind failure names, in the app's own words: uvicorn's "('127.0.0.1', 8105): address
+// already in use", Node's "EADDRINUSE: address already in use :::3000".
+const portInError = (said) => Number(/(\d{4,5})\)?:?\s*address already in use/i.exec(said)?.[1] ?? /(?:EADDRINUSE|address already in use)\D{0,40}?(\d{4,5})\b/i.exec(said)?.[1] ?? 0);
 async function freed(cmd, lifted) {
   const m = /(--port[= ]|-p |\bPORT=)(\d{4,5})\b/.exec(cmd);
-  const named = m ? Number(m[2]) : Number(lifted.PORT) || 0;
+  // The app's own env file names its port too: yunqiao's PORT=8105 sat in .env, and a stale copy
+  // on that port was reported as "your app stopped" instead of moved past.
+  const named = m ? Number(m[2]) : Number(lifted.PORT) || Number(envExports(envFiles).PORT) || 0;
   if (!named || (!lost.has(named) && !(await listenerOn(named)))) return { cmd, lifted };
   const port = await freePortAbove(named);
   if (!port) return { cmd, lifted };
@@ -705,9 +741,27 @@ async function freed(cmd, lifted) {
   return m ? { cmd: cmd.replace(m[0], `${m[1]}${port}`), lifted } : { cmd, lifted: { ...lifted, PORT: String(port) } };
 }
 
+// Your app's database, read once per session: a copy made before the first start, and every
+// restart after it runs against the same copy, so a crash mid-run does not lose what the run made.
+// Told in the terminal here and to the run with the app (announce), so status and the report say it.
+let data = null;
+function dataOnce(started) {
+  if (data) return data;
+  const values = { ...envExports(envFiles), ...process.env };
+  const from = {};
+  for (const file of envFiles.filter((f) => !/\.(example|sample)$/.test(f))) {
+    let text = "";
+    try { text = readFileSync(file, "utf8"); } catch { continue; }
+    for (const line of text.split("\n")) { const m = /^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=/.exec(line); if (m && !(m[1] in process.env)) from[m[1]] = file; }
+  }
+  data = keepData({ values, from, appDir, root, work, sources: files.map((f) => join(root, f)), started });
+  for (const line of data.said) say(line.charAt(0).toLowerCase() + line.slice(1));
+  return data;
+}
+
 async function start(waitMs) {
   const { cmd, lifted } = await freed(launched.cmd, launched.lifted ?? {});
-  child = spawn("/bin/sh", ["-c", cmd], { cwd: appDir, env: { ...process.env, ...lifted, ...(capture ? capture.env(process.env) : {}), FORCE_COLOR: "0", ...(pinned.bin ? { PATH: `${pinned.bin}:${process.env.PATH ?? ""}` } : {}) }, stdio: ["ignore", "pipe", "pipe"], detached: true });
+  child = spawn("/bin/sh", ["-c", cmd], { cwd: appDir, env: { ...envExports(envFiles), ...process.env, ...lifted, ...dataOnce(true).env, ...(capture ? capture.env(process.env) : {}), FORCE_COLOR: "0", ...(pinned.bin ? { PATH: `${pinned.bin}:${process.env.PATH ?? ""}` } : {}) }, stdio: ["ignore", "pipe", "pipe"], detached: true });
   const mine = child;
   let seen = "";
   const onData = (d) => { const s = d.toString(); appendFileSync(bootLog, s); seen = (seen + s).slice(-20_000); lastSaid = seen; lastOutputAt = Date.now(); if (verbose) process.stdout.write(s); };
@@ -719,7 +773,10 @@ async function start(waitMs) {
   const started = Date.now();
   while (Date.now() - started < waitMs) {
     const tail = () => seen.replace(/\x1b\[[0-9;]*m/g, "").split("\n").filter(Boolean).slice(-25).join("\n");
-    if (exited !== null) return { port: null, exited, tail: tail() };
+    // The port was taken: the app says so and exits at once, so this is read before the exit code,
+    // or a bed whose .env named a port another round still held printed "your app stopped" three times.
+    const taken = /EADDRINUSE|address already in use/i.test(seen);
+    if (exited !== null && !taken) return { port: null, exited, tail: tail() };
     // nodemon and its kind outlive the app they watch: the app is gone, the process is not, and
     // the wait ran its whole three minutes on one app with the reason sitting in the output.
     // Also: the port is taken, under a watcher that does not exit when its app cannot listen. The app
@@ -728,7 +785,7 @@ async function start(waitMs) {
       await stopApp(mine.pid);
       // The port this start named was taken between the check and the bind: the next free one, at
       // most three times, before the failure is theirs to read.
-      const named = /(?:--port[= ]|-p |\bPORT=)(\d{4,5})\b/.exec(cmd)?.[1] ?? lifted.PORT;
+      const named = /(?:--port[= ]|-p |\bPORT=)(\d{4,5})\b/.exec(cmd)?.[1] ?? lifted.PORT ?? envExports(envFiles).PORT ?? (portInError(seen) || undefined);
       if (/EADDRINUSE|address already in use/i.test(seen) && named && lost.size < 3) { lost.add(Number(named)); return start(waitMs); }
       return { port: null, exited: 1, tail: tail() };
     }
@@ -821,6 +878,7 @@ if (explain) {
     `would raise     ${flag("--port") ? "nothing: your app's own request limits stay as they are" : `${Object.keys(liftedLimits(envFiles, files.map((f) => join(root, f)))).join(", ") || "no request limits found"}   (for this session only)`}`,
     `loads into app  lib/trace.cjs (Node, Bun) or lib/pyhook/sitecustomize.py (Python): records the one request during which your app calls a model`,
     `your files      never written by this program; your own coding agent edits them`,
+    `your database   a database file your env or code names is copied to this program's temp folder and your app is started on the copy; a database server is named, not copied`,
     `test shell      confined by the OS: your project and toolchains only, writes to temp and build folders, localhost only`,
     `for your agent  an MCP entry and a skill in each coding agent's own home folder (Claude Code, Codex, Cursor), and a key in ~/.cortad for later runs`,
     ``,
@@ -888,6 +946,7 @@ await exec("tar", ["-czf", archive, "-C", root, "-T", list]);
 const bytes = readFileSync(archive);
 const PART = 1_500_000;
 let resumed = false;
+let moved = false;
 const parts = Math.max(1, Math.ceil(bytes.length / PART));
 for (let off = 0; off < bytes.length; off += PART) {
   const last = off + PART >= bytes.length;
@@ -899,12 +958,13 @@ for (let off = 0; off < bytes.length; off += PART) {
   if (!put.ok) fail(put.data?.error ?? `upload failed (${put.status})`);
   if (last) {
     resumed = put.data?.resumed === true;
+    moved = put.data?.moved === true;
     if (typeof put.data?.machineKey === "string" && put.data.machineKey) writeToken(project, put.data.machineKey);
     writeDigest(project, treeDigest);
   }
 }
 // Unchanged code has already been read: coming back says so instead of claiming a second read.
-stepDone(resumed ? "connected · nothing changed since last time" : "connected");
+stepDone(moved ? "connected · your change is in; the read from before stands" : resumed ? "connected · nothing changed since last time" : "connected");
 // The coding agents on this machine learn about Cortad now, once: an MCP entry and a skill in each
 // one's own home folder. A run started by an agent later comes back through lib/cli.mjs.
 if (!viaToken) {
@@ -935,7 +995,7 @@ function sourceChanged() {
 }
 // `watching` says whether a message sent to this app can be seen arriving: only an app this command
 // started carries the hook, and only a runtime the hook exists for.
-const announce = () => call("POST", `/local/${box}/app`, { port: app.port, cmd: app.cmd, origins: envOrigins(envFiles), lifted: app.lifted ?? [], watching: Boolean(launched && capture?.watching(app.port)), metered: Boolean(launched && capture?.watching(app.port)) });
+const announce = () => call("POST", `/local/${box}/app`, { port: app.port, cmd: app.cmd, origins: envOrigins(envFiles), lifted: app.lifted ?? [], data: dataOnce(Boolean(launched)).said.slice(0, 8), watching: Boolean(launched && capture?.watching(app.port)), metered: Boolean(launched && capture?.watching(app.port)) });
 
 // Your app's life beside this connection. It is started; if it stops, or never comes up, this stays
 // and starts it again the moment you save a fix, and the browser is told each time it answers, so a
@@ -982,7 +1042,10 @@ async function appLife() {
     const busy = launched && !appGone && !crashed && Date.now() - lastOutputAt < 15_000;
     if (busy || downFor < (crashed ? 4_000 : 10_000)) continue;
     // Down for real. The screen is told, so it never shows an app that is not there.
-    if (!toldDown) toldDown = Boolean((await call("POST", `/local/${box}/stopped`, { said: mask(lastSaid || "your app stopped answering").slice(-2000) }).catch(() => null))?.ok);
+    // `exited`: the process this command started is gone or its watcher said it crashed, not a process
+    // running and not answering. The run tells the two apart: one is their crash, the other may be our
+    // load. An app it only attached to is not its to watch, so nothing is said either way.
+    if (!toldDown) toldDown = Boolean((await call("POST", `/local/${box}/stopped`, { said: mask(lastSaid || "your app stopped answering").slice(-2000), ...(launched ? { exited: Boolean(appGone || crashed) } : {}) }).catch(() => null))?.ok);
     // An app that went quiet or exited did not stop because of a save (it was killed, it ran out
     // of memory, it crashed on a request), so waiting for a save would wait forever. It is started
     // here, whoever started it first: an app this command only attached to (yours, from another

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cortad",
-  "version": "0.3.0-rc.9",
+  "version": "0.3.1-rc.1",
   "description": "Connects the AI app on your machine to Cortad for test conversations, and gives your coding agent the MCP and skill to run them. No dependencies.",
   "bin": {
     "cortad": "local.mjs"
@@ -9,6 +9,7 @@
   "files": [
     "README.md",
     "lib/cli.mjs",
+    "lib/data.mjs",
     "lib/home.mjs",
     "lib/identities.mjs",
     "lib/keys.mjs",

package/skill/SKILL.md

@@ -53,7 +53,9 @@ Take the person through them worst first, each with its file and line. A long li
 2. `verify <findingId>`. It answers within a second, and `run_status` follows it. Cortad starts the app again itself before the replay, so the saved edit is what plays.
 3. Read the move on the `Visible trials:` and `Held-out trials:` lines:
    - `improved` without `inside the noise`, with the held-out line improved too or `no pair`: the behavior moved. The change stays.
-   - `inside the noise`, `no change` or `unsettled`: the trials cannot tell the change from chance. The file goes back to how it was.
+   - `no change` or `regressed`: the file goes back to how it was.
+   - `inside the noise` or `unsettled`: the trials cannot tell yet, which is not a verdict against the change. `verify` again to add readings; a change the app's own tests support may stay, said as not yet verified by Cortad.
+   - A verify that played no trial says so and compares nothing; the file stays as it was left.
    - An `Overfit:` line: the visible trials moved and the held-out trials stayed where they were, so the change fits the trials it could see. The file goes back, and the next change aims at the behavior the question asks about.
    - `regressed`: the file goes back.
 4. Then the next finding.

package/skill/references/results.md

@@ -35,7 +35,7 @@ Engineering standards: 38 decided, 35 met, 3 missed.
   apps/api/src/agent/system.ts:30  User text stays out of the system prompt: the student's name is written into the system prompt (decided by a model)
   apps/api/src/tools/search.ts:51  Tool errors reach the model as errors: search returns an empty list when the index is down (decided by a model)
 Questions: 112; 40 asked in every conversation, 72 placed in the situations they fit.
-Trials: 58 written, 51 playable.
+Trials: 58 written.
   POST /api/homework/upload: 7 trials held back, on the app's side: the route needs a signed file URL, and no test account can make one
 Latest run 8f2a1c4e-5b6d-4e7f-9a0b-1c2d3e4f5a6b: running, 14 of 51 trials played.
 410 readings of 112 questions.
@@ -129,6 +129,8 @@ For the person: the report is at https://cortad.com/lab
 next: findings
 ```
 
+Your app stopped during the run and was started again: that is a finding of its own, `crash:1`, with the error your app printed and the turn it happened at. Fix the error it quotes. It has no trials to replay, so `verify` refuses it; the next run that finishes without it is the proof. A `Data:` line says whether the run wrote to a copy of your app's database or into the real one.
+
 A verify that holds: both intervals are above zero and the held-out trials moved with the visible ones.
 
 ```