cortad 0.3.0 → 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/read-text.mjs

@@ -12,10 +12,16 @@ 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 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`]);
@@ -41,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` : ""}.`);
@@ -70,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/text.mjs

@@ -22,10 +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}`);
@@ -57,7 +61,7 @@ function scoreLine(d) {
 }
 // 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)}.`
+  ? `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 = {
@@ -84,16 +88,33 @@ function runLines(d, prefix = "") {
   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")}.`);
-  for (const h of (d.heldBack ?? []).filter((h) => h.trials > 0).slice(0, 6)) lines.push(heldBackLine(h));
+  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;
@@ -180,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);
@@ -246,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
@@ -254,12 +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}`, 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
@@ -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
@@ -575,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`);
@@ -728,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: { ...envExports(envFiles), ...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); };
@@ -847,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`,
     ``,
@@ -963,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
@@ -1010,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",
+  "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/references/results.md

@@ -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.
 
 ```