cortad 0.1.0 → 0.1.2

package/README.md

@@ -1,45 +1,42 @@
 # cortad
 
-Runs Cortad test conversations against the app on your machine. Your env stays on your machine.
+Connects the AI app on your machine to Cortad, so Cortad can run test conversations against it.
 
 ```
 npx cortad <code>
 ```
 
-Run it in your app's folder. The code comes from the connect screen at cortad.com. Nothing is installed. Ctrl-C disconnects.
+Run it in your app's folder with the code from cortad.com. Nothing is installed. Ctrl-C disconnects.
 
-## Behavior
+## What it does
 
-- Starts your app with its dev script. If it is already running, uses it.
-- Finds the route your AI answers on. Sends requests to that port on `localhost`, nowhere else.
-- If it cannot find the route, the screen asks you to send one message in your app. It reads the route and body from that request.
-- Restarts your app when it stops and you save a fix.
-- The Cortad agent edits your files in place. Every edit can be undone from the screen. Git is never touched: no commit, stage, stash or push.
+- Starts your app with its dev script, or uses it if it is already running.
+- Sends Cortad's test conversations to your app on localhost and returns the replies.
+- Signs in as a test account when your app needs one: an account made for the session, never an existing user and never an admin.
+- Lets the Cortad agent edit files in your project. Every edit can be undone from the browser. Git is left alone.
 
-## Sent to cortad.com
+## What Cortad receives
 
-- Source files, once. Not `.env*`, key files, `node_modules` or `.git`.
-- Your app's replies to the test requests. Values from your env files are masked first.
+- The files git would commit, once. Nothing git ignores, and no env, key or data files.
+- Your app's replies to the test conversations, with values from your env files hidden and cookies removed.
 
-## Never sent
+## What stays on your machine
 
-- Env values.
-- Tokens, cookies, API keys. Signed-in requests get their token attached on your machine.
+- Your env files and their values.
+- Tokens and cookies. A signed-in test request gets its token added here.
 
-## Never done
+## The agent's shell
 
-- Writes to `.env*`, key files, `.git`, `node_modules`.
-- Requests to any port but your app's.
-- Agent shell access to the network or to files outside temp and git-ignored build folders.
+Commands the agent runs are confined by the operating system (Seatbelt on macOS, bubblewrap on Linux). They can read your project and your toolchains, write only to temp and build folders, and reach only localhost.
 
 ## Loaded into your app
 
-When cortad starts your app it preloads one file: `lib/trace.cjs` for Node (`NODE_OPTIONS=--require`), `lib/pyhook/sitecustomize.py` for Python (`PYTHONPATH`). It records the one request during which your app called a model, to a file in cortad's temp folder, mode 0600. It makes no network calls. Read it; it is short.
+When cortad starts your app it preloads one short file, `lib/trace.cjs` for Node or `lib/pyhook/sitecustomize.py` for Python. It notes which request called a model, so Cortad finds your chat route. It writes only to cortad's temp folder.
 
 ## Flags
 
 ```
---explain            print what would be sent and started, then exit; no network
+--explain            show what would be sent and started, then exit
 --port 3000          use an app that is already running
 --start "make dev"   how your app starts
 --verbose            print your app's output
@@ -50,4 +47,4 @@ When cortad starts your app it preloads one file: `lib/trace.cjs` for Node (`NOD
 - `~/.cortad/checkpoints/`  undo data for agent edits
 - `$TMPDIR/cortad-<pid>/`   removed on exit
 
-macOS, Linux. Node 20+.
+macOS and Linux, Node 20+. No dependencies, no install scripts.

package/lib/identities.mjs

@@ -68,6 +68,7 @@ PLAN = json.loads(base64.b64decode("__PLAN__").decode("utf-8"))
 OUT = "__OUT__"
 FILE = "__FILE__"
 TTL = 6 * 3600
+TEST = "cortad-test-user"
 # A dev server compiles its auth route on the first request: better-chatbot's sign-in timed out at 10s
 # and the caller was filed unreachable. The whole program stays inside the step's two minutes.
 DEADLINE = time.time() + 100
@@ -98,10 +99,10 @@ def slug(role):
 def gen(role):
     tag = secrets.token_hex(4)
     return {
-        "username": "bl-%s-%s" % (slug(role), tag),
-        "email": "bl-%s-%s@example.invalid" % (slug(role), tag),
+        "username": "cortad-%s-%s" % (slug(role), tag),
+        "email": "cortad-%s-%s@example.invalid" % (slug(role), tag),
         "password": secrets.token_urlsafe(18) + "A1!",
-        "name": "Brainsless %s" % role,
+        "name": "Cortad test %s" % role,
     }
 
 
@@ -237,12 +238,13 @@ def jwt(recipe, env):
     if not secret:
         return {"status": "absent", "note": " or ".join(recipe["env"])}
     now = int(time.time())
-    # ponytail: subject 1, the first account of a restored copy; read a real id off the stand-in
-    # database when a customer's users table does not start there.
-    claims = {"sub": "1", "id": 1, "iat": now, "exp": now + TTL}
+    # On their own machine the database is theirs and live: the token names a test id that belongs
+    # to nobody, never account 1, which is usually the person who built the app. (The sandbox copy
+    # of this program signs account 1 of a restored copy; this one differs on purpose.)
+    claims = {"sub": TEST, "id": TEST, "iat": now, "exp": now + TTL}
     claim = recipe.get("claim") or "sub"
     if claim not in claims:
-        claims[claim] = 1
+        claims[claim] = TEST
     head = b64url(json.dumps({"alg": "HS256", "typ": "JWT"}, separators=(",", ":")).encode("utf-8"))
     body = b64url(json.dumps(claims, separators=(",", ":")).encode("utf-8"))
     sig = b64url(hmac.new(secret.encode("utf-8"), ("%s.%s" % (head, body)).encode("ascii"), hashlib.sha256).digest())

package/lib/lock.mjs

@@ -15,22 +15,31 @@ const real = (p) => { try { return realpathSync(p); } catch { return null; } };
 const q = (p) => `"${p.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
 // Dependencies are not disposable even though git ignores them; their caches are.
 const CACHES = [".cache", ".vite", ".vitest", ".bin/.cache"];
+// What git ignores splits in two: build output and dependency caches a test may rewrite, and
+// everything else, which is where a project keeps what it never commits (keys, exports, notes).
+const BUILT = /(^|\/)(dist|build|out|coverage|target|tmp|\.next|\.nuxt|\.turbo|\.cache|__pycache__|\.pytest_cache|\.mypy_cache|\.ruff_cache|\.venv|venv|\.parcel-cache|\.svelte-kit|\.output|\.wrangler|\.terraform|\.vite|\.vitest)$/;
 
-async function disposableDirs(root) {
+async function ignoredPaths(root) {
   const out = await run("git", ["-C", root, "ls-files", "--others", "--ignored", "--exclude-standard", "--directory"], { maxBuffer: 16 * 1024 * 1024 })
-    .then((r) => r.stdout.split("\n"), () => []);
-  const dirs = [];
+    .then((r) => r.stdout.split("\n").filter(Boolean), () => []);
+  const writable = [];
+  const hidden = [];
   for (const line of out) {
-    if (!line.endsWith("/")) continue;
-    const rel = line.slice(0, -1);
+    const dir = line.endsWith("/");
+    const rel = dir ? line.slice(0, -1) : line;
     if (/(^|\/)\.git($|\/)/.test(rel)) continue;
-    if (/(^|\/)node_modules$/.test(rel)) { for (const c of CACHES) dirs.push(join(root, rel, c)); continue; }
-    dirs.push(join(root, rel));
-    if (dirs.length >= 200) break;
+    if (/(^|\/)node_modules$/.test(rel)) { for (const c of CACHES) writable.push(join(root, rel, c)); continue; }
+    if (dir && BUILT.test(rel)) { if (writable.length < 200) writable.push(join(root, rel)); continue; }
+    if (/(^|\/)\.env(\..*)?$/.test(rel)) continue;
+    if (hidden.length < 400) hidden.push({ path: join(root, rel), dir });
   }
-  return dirs;
+  return { writable, hidden };
 }
 
+// Where a shell line looks for its tools inside your home folder. The rest of home is not read.
+const TOOLCHAINS = [".nvm", ".npm", ".node-gyp", ".pnpm-store", ".yarn", ".bun", ".deno", ".volta", ".asdf", ".cache", ".local",
+  ".pyenv", ".rbenv", ".gem", ".cargo", ".rustup", "go", ".gradle", ".m2", "Library/pnpm", "Library/Caches", ".gitconfig", ".config/git"];
+
 const SECRET_DIRS = [".ssh", ".aws", ".gnupg", ".config/gh", ".docker", ".kube"];
 const SECRET_FILES = [".netrc", ".npmrc", ".pypirc"];
 
@@ -40,17 +49,28 @@ export async function makeLock({ root, work }) {
   // never opened whole, whatever it is called.
   const home0 = real(root) ?? root;
   const holdsProject = (dir) => home0 === dir || home0.startsWith(`${dir}/`);
-  const writable = [work, tmpdir(), "/tmp", ...(await disposableDirs(root))].map((p) => real(p) ?? p).filter((dir) => !holdsProject(dir));
+  const ignored = await ignoredPaths(root);
+  const writable = [work, tmpdir(), "/tmp", ...ignored.writable].map((p) => real(p) ?? p).filter((dir) => !holdsProject(dir));
+  const project = real(root) ?? root;
+  const tools = TOOLCHAINS.map((t) => join(home, t)).filter(existsSync).map((p) => real(p) ?? p);
   if (process.platform === "darwin" && existsSync("/usr/bin/sandbox-exec")) {
+    // Later rules win: home is shut, the project and the toolchains are opened again inside it, and
+    // what the project ignores and your keys are shut last.
+    const hide = ignored.hidden.map(({ path, dir }) => `(${dir ? "subpath" : "literal"} ${q(real(path) ?? path)})`);
     const profile = [
       "(version 1)(allow default)",
+      `(deny file-read-data (subpath ${q(real(home) ?? home)}))`,
+      `(allow file-read-data (subpath ${q(project)}) ${[work, ...tools].map((p) => `(subpath ${q(p)})`).join(" ")})`,
+      ...(hide.length ? [`(deny file-read-data file-write* ${hide.join(" ")})`] : []),
       "(deny network*)",
       // This machine only. Unix sockets stay shut: through one, a request rides out to the internet
       // by name on a system network helper even with every direct connection refused.
       '(allow network-outbound (remote ip "localhost:*"))(allow network-inbound (local ip "localhost:*"))',
       "(deny file-write*)",
       `(allow file-write* ${writable.map((p) => `(subpath ${q(p)})`).join(" ")} (literal "/dev/null") (literal "/dev/stdout") (literal "/dev/stderr") (literal "/dev/tty") (subpath "/dev/fd"))`,
-      `(deny file-read* ${SECRET_DIRS.map((d) => `(subpath ${q(join(home, d))})`).join(" ")} ${SECRET_FILES.map((f) => `(literal ${q(join(home, f))})`).join(" ")} (regex #"/\\.env$") (regex #"/\\.env\\.(local|staging|stage|development|dev|test|production|prod)$"))`,
+      // The same operation the project is opened with: a rule naming file-read-data outranks one naming
+      // file-read*, so a wildcard deny here let every .env be read again.
+      `(deny file-read* file-read-data ${SECRET_DIRS.map((d) => `(subpath ${q(join(home, d))})`).join(" ")} ${SECRET_FILES.map((f) => `(literal ${q(join(home, f))})`).join(" ")} (regex #"\\.env$") (regex #"/\\.env\\.(local|staging|stage|development|dev|test|production|prod)$"))`,
     ].join("");
     return { name: "seatbelt", wrap: (cmd) => ({ file: "/usr/bin/sandbox-exec", args: ["-p", profile, "/bin/sh", "-c", cmd] }) };
   }
@@ -58,9 +78,12 @@ export async function makeLock({ root, work }) {
   if (bwrap) {
     // ponytail: writes and secrets are locked on Linux, the network is not; add a network
     // namespace with a loopback bridge when a customer's threat model asks for it.
+    // Home is an empty tmpfs; the project and the toolchains are bound back into it, then the
+    // project's ignored files are covered and the writable folders opened.
+    const back = [project, ...tools].filter(existsSync).flatMap((p) => ["--ro-bind", p, p]);
     const binds = writable.filter(existsSync).flatMap((p) => ["--bind", p, p]);
-    const hidden = [...SECRET_DIRS.map((d) => join(home, d)).filter(existsSync).flatMap((p) => ["--tmpfs", p])];
-    return { name: "bubblewrap", wrap: (cmd) => ({ file: bwrap, args: ["--ro-bind", "/", "/", "--dev", "/dev", "--proc", "/proc", ...binds, ...hidden, "/bin/sh", "-c", cmd] }) };
+    const covered = ignored.hidden.filter(({ path }) => existsSync(path)).flatMap(({ path, dir }) => (dir ? ["--tmpfs", path] : ["--ro-bind", "/dev/null", path]));
+    return { name: "bubblewrap", wrap: (cmd) => ({ file: bwrap, args: ["--ro-bind", "/", "/", "--dev", "/dev", "--proc", "/proc", "--tmpfs", home, ...back, ...covered, ...binds, "/bin/sh", "-c", cmd] }) };
   }
   return null;
 }

package/lib/mint.mjs

@@ -17,6 +17,38 @@ const ROLE = /^[a-z][a-z0-9_-]{0,30}(?::[a-z][a-z0-9_-]{0,30})?$/;
 const slug = (role) => role.replace(/[^a-z0-9-]/g, "-");
 const TEST_UID = "brainsless-test-user";
 
+// Who this machine signs in as, whatever a recipe asks: an account made for the session, or a test
+// id that belongs to nobody. Never a person who already has an account, never an admin, and never a
+// key the app does not already hand to every browser. The recipes come from the cloud; these rules
+// are here, beside the secrets, so a recipe cannot talk its way past them.
+const ELEVATED = /admin|owner|super|root/i;
+const PUBLIC_NAME = /^(NEXT_PUBLIC_|VITE_|REACT_APP_|EXPO_PUBLIC_|NUXT_PUBLIC_|PUBLIC_|GATSBY_)/;
+const ACCOUNT_FIELD = /^(e-?mail|user(_?name)?|login|phone|account|identifier)$/i;
+const ID_CLAIM = /^(sub|id|uid|user_?id|userid)$/i;
+
+// Whether a value is already in the code the app ships: then every browser holds it, and sending it
+// as the caller's key tells the app nothing a visitor could not.
+function inSource(root, files, value) {
+  for (const rel of files) {
+    try { if (readFileSync(join(root, rel), "utf8").includes(value)) return true; } catch { /* gone */ }
+  }
+  return false;
+}
+
+export function refusal(recipe, env, shipped) {
+  if ([recipe?.role, ...(recipe?.roles ?? [])].some((r) => ELEVATED.test(String(r ?? "")))) return "an admin role; only an ordinary test account is signed in";
+  if (recipe?.kind === "jwt" && recipe.claim && !ID_CLAIM.test(recipe.claim)) return `a token field (${recipe.claim}) other than the user's id`;
+  if (recipe?.kind === "header") {
+    const names = recipe.env ?? [];
+    const value = names.map((n) => env[n]).find(Boolean);
+    if (value && !names.some((n) => PUBLIC_NAME.test(n)) && !shipped(value)) return `${names.join(" or ")} is a private key, never sent as a caller's own`;
+  }
+  for (const step of [...(recipe?.steps ?? []), ...(recipe?.alt ?? [])])
+    for (const [field, spec] of Object.entries(step?.body ?? {}))
+      if (ACCOUNT_FIELD.test(field) && String(spec).startsWith("env:")) return "an existing account from your environment; only a new test account is signed in";
+  return null;
+}
+
 export function readEnv(file) {
   const out = {};
   let text = "";
@@ -55,7 +87,7 @@ async function firebaseIdToken(account, apiKey) {
   return res.ok && out?.idToken ? { idToken: out.idToken } : { error: String(out?.error?.message ?? `status ${res.status}`).slice(0, 120) };
 }
 
-export function makeIdentities({ root, work, envFiles, say, keepSecret, appDir = () => root }) {
+export function makeIdentities({ root, work, envFiles, sourceFiles = () => [], say, keepSecret, appDir = () => root }) {
   const dir = join(work, "identities");
   const headerFile = (role) => join(dir, `bl-identity-${slug(role)}.header`);
   const firebaseRoles = new Map();
@@ -93,8 +125,11 @@ export function makeIdentities({ root, work, envFiles, say, keepSecret, appDir =
     // A Firebase caller with no emulator on this machine is signed in at their real project, below.
     // Handed to the program it waited its whole deadline on an emulator that was never there, and
     // planless's sign-in arrived after the world had given up waiting for it.
-    const emulated = Boolean(Object.assign({}, ...[...envs().all].reverse()).FIREBASE_AUTH_EMULATOR_HOST);
-    const forProgram = recipes.filter((r) => r?.kind !== "firebase" || emulated);
+    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); }
+    const forProgram = recipes.filter((r) => !refused.has(r?.role) && (r?.kind !== "firebase" || emulated));
     const script = identityScript(forProgram, { envPath: envs().path, base: `http://127.0.0.1:${port}`, headers: body?.headers ?? {} }).split("/tmp/bl-identit").join(join(dir, "bl-identit"));
     const file = join(dir, "mint.py");
     writeFileSync(file, script, { mode: 0o600 });
@@ -106,6 +141,7 @@ export function makeIdentities({ root, work, envFiles, say, keepSecret, appDir =
     for (const recipe of recipes) {
       if (typeof recipe?.role !== "string" || !ROLE.test(recipe.role)) continue;
       const blank = { role: recipe.role, kind: recipe.kind, header: recipe.header, opens: [], door: recipe.header, where: recipe.where };
+      if (refused.has(recipe.role)) { rows.push({ ...blank, status: "refused", note: refused.get(recipe.role) }); continue; }
       const row = known.get(recipe.role) ?? (recipe.kind === "firebase" && !emulated ? { ...blank, status: "upstream" } : { ...blank, status: ran ? "unreachable" : "absent", ...(ran ? {} : { note: "python3 is not installed on this machine" }) });
       rows.push(recipe.kind === "firebase" && row.status !== "minted" ? await firebase(row) : row);
     }

package/local.mjs

@@ -11,7 +11,7 @@
 // (lib/lock.mjs) and cannot write your code at all. Nothing here touches git. Your environment
 // never leaves this machine. Ctrl-C ends everything.
 
-import { spawn, execFile } from "node:child_process";
+import { spawn, execFile, execFileSync } from "node:child_process";
 import { createHash } from "node:crypto";
 import { appendFileSync, existsSync, mkdirSync, readdirSync, readFileSync, realpathSync, statSync, watch, writeFileSync } from "node:fs";
 import { homedir, tmpdir } from "node:os";
@@ -32,12 +32,19 @@ const say = (line) => console.log(`cortad  ${line}`);
 const fail = (line) => { console.error(`cortad  ${line}`); process.exit(1); };
 
 const explain = argv.includes("--explain");
+// What is happening right now, on one line that rewrites itself. npx spends its own seconds fetching
+// this package before anything here runs, and the first thing we printed used to be after the whole
+// upload: a minute or more of a cursor sitting still, which reads as nothing happening.
+const step = (line) => { if (process.stdout.isTTY) process.stdout.write(`\rcortad  ${line}\x1b[K`); };
+const clearStep = () => { if (process.stdout.isTTY) process.stdout.write("\r\x1b[K"); };
+const stepDone = (line) => { clearStep(); say(line); };
 if (!explain && !/^[A-Z0-9]{8}$/.test(code)) fail("usage: npx cortad <code from the connect screen> [--port N] [--start \"cmd\"]   |   npx cortad --explain");
 // Where Brainsless is. The host is not on the command line: a code cannot point at an impostor.
 const origin = new URL(process.env.CORTAD_ORIGIN || "https://cortad.com");
 // Ours, and only ours. brainsless.com is the same service under its earlier name and stays trusted
 // while people still hold links to it.
-const OURS = ["cortad.com", "brainsless.com"];
+// The last is our own Pages project: its subdomains are our branch deploys, staging among them.
+const OURS = ["cortad.com", "brainsless.com", "brainsless-frontend.pages.dev"];
 const trusted = (origin.protocol === "https:" && OURS.some((host) => origin.hostname === host || origin.hostname.endsWith(`.${host}`)))
   || origin.hostname === "localhost" || origin.hostname === "127.0.0.1";
 if (!trusted) fail(`refusing: ${origin.host} is not Cortad.`);
@@ -47,9 +54,10 @@ const root = process.cwd();
 const MANIFEST = ["package.json", "pyproject.toml", "requirements.txt", "go.mod", "Cargo.toml", "docker-compose.yml", "docker-compose.yaml", "Gemfile", "mix.exs"];
 if (!MANIFEST.some((f) => existsSync(join(root, f)))) fail(`this folder has no package.json or pyproject.toml. Run it from your repository's root: ${root}`);
 
-// ---- what leaves the machine: source files only
-const SKIP_DIR = /^(node_modules|\.git|dist|build|out|coverage|vendor|venv|\.venv|env|target|tmp|\.next|\.nuxt|\.turbo|\.cache|__pycache__|\.terraform|\.wrangler|\.svelte-kit|\.output|\.parcel-cache|\.idea|\.vscode)$/;
-const SKIP_FILE = /^\.env(\..*)?$|\.(pem|key|p12|pfx|jks|keystore|sqlite|sqlite3|db|log|lock|map|zip|tar|gz|tgz|7z|rar|png|jpe?g|gif|webp|ico|svg|mp3|mp4|wav|mov|pdf|woff2?|ttf|otf|eot|bin|exe|dll|so|dylib|wasm|onnx|pt|pth|safetensors|parquet|csv|xlsx?|numbers|DS_Store)$/i;
+// ---- what leaves the machine: the source git would commit, and nothing git is told to ignore
+const SKIP_DIR = /^(node_modules|\.git|dist|build|out|coverage|vendor|venv|\.venv|env|target|tmp|\.next|\.nuxt|\.turbo|\.cache|__pycache__|\.terraform|\.wrangler|\.svelte-kit|\.output|\.parcel-cache|\.idea|\.vscode|secrets?|\.secrets?)$/i;
+// Env files by any name (scripts/books.env is one), keys, and data rather than code.
+const SKIP_FILE = /^\.env(\..*)?$|^\.envrc$|\.env$|\.(pem|key|p12|pfx|jks|keystore|sqlite|sqlite3|db|log|lock|map|zip|tar|gz|tgz|7z|rar|png|jpe?g|gif|webp|ico|svg|mp3|mp4|wav|mov|pdf|woff2?|ttf|otf|eot|bin|exe|dll|so|dylib|wasm|onnx|pt|pth|safetensors|parquet|csv|tsv|jsonl|ndjson|xlsx?|numbers|DS_Store)$/i;
 const MAX_FILE = 1_000_000;
 const MAX_TOTAL = 80_000_000;
 const ENV_FILE = /^\.env(\.(local|staging|stage|development|dev|test|example|sample))?$/;
@@ -66,12 +74,37 @@ function walk(dir, depth, out, envs, total) {
     let size;
     try { size = statSync(full).size; } catch { continue; }
     if (size > MAX_FILE || total + size > MAX_TOTAL) continue;
+    if (!shareable(relative(root, full))) continue;
     out.push(relative(root, full));
     total += size;
   }
   return total;
 }
 
+// What git lists here: tracked files and new ones it would pick up, never an ignored one. A folder
+// that is not a git repository has no such list and is read by the rules above alone.
+function gitListed() {
+  if (!existsSync(join(root, ".git")) && !onPath("git")) return null;
+  let inside = false;
+  try { inside = execFileSync("git", ["-C", root, "rev-parse", "--is-inside-work-tree"], { stdio: ["ignore", "pipe", "ignore"] }).toString().trim() === "true"; } catch { /* not a repository */ }
+  if (!inside) return null;
+  // A repository whose list cannot be read is not read by guesswork: it stops here.
+  try {
+    const out = execFileSync("git", ["-C", root, "ls-files", "-z", "--cached", "--others", "--exclude-standard"], { maxBuffer: 256 * 1024 * 1024, stdio: ["ignore", "pipe", "ignore"] });
+    return new Set(out.toString().split("\0").filter(Boolean));
+  } catch (e) { fail(`could not list this repository's files with git: ${e.message}`); }
+}
+// One rule for every file that could leave: the upload, and a read the engine asks for later.
+function shareable(rel) {
+  const parts = rel.split(sep);
+  if (parts.slice(0, -1).some((d) => SKIP_DIR.test(d)) || SKIP_FILE.test(parts.at(-1))) return false;
+  if (listed === null) return true;
+  if (listed.has(rel)) return true;
+  // A file made after the list was taken (an agent edit) is asked of git directly.
+  try { execFileSync("git", ["-C", root, "check-ignore", "-q", rel], { stdio: "ignore" }); return false; } catch (e) { return e.status === 1; }
+}
+let listed = null;
+
 // Values from your env files, read here and only here, so nothing a command prints can carry one.
 function secretValues(envFiles) {
   const values = new Set();
@@ -170,7 +203,8 @@ const readable = (p) => {
   if (r.startsWith(work + sep)) return r;
   let landed; try { landed = realpathSync(r); } catch { return null; }
   const home = realpathSync(root);
-  return (landed === home || landed.startsWith(home + sep)) && !ENV_FILE.test(basename(landed)) && !SECRET_PATH.test(landed) ? landed : null;
+  if (!landed.startsWith(home + sep) || ENV_FILE.test(basename(landed)) || SECRET_PATH.test(landed)) return null;
+  return shareable(relative(home, landed)) ? landed : null;
 };
 // A shell line runs with a plain environment: the app's own process reads its .env itself, and
 // nothing a world sends inherits this terminal's keys.
@@ -230,7 +264,9 @@ async function verb(job) {
         const res = await fetch(`http://127.0.0.1:${port}${path}`, { ...init, signal: AbortSignal.timeout(170_000) });
         const buf = Buffer.from(await res.arrayBuffer());
         const LIMIT = 262_144;
-        return { status: res.status, headers: Object.fromEntries(res.headers), body: mask(buf.subarray(0, LIMIT).toString("utf8")), truncated: buf.length > LIMIT };
+        // A session cookie your app sets is its business: it is dropped here, and every other header masked.
+        const headers = Object.fromEntries([...res.headers].filter(([k]) => !/^set-cookie2?$/i.test(k)).map(([k, v]) => [k, mask(v)]));
+        return { status: res.status, headers, body: mask(buf.subarray(0, LIMIT).toString("utf8")), truncated: buf.length > LIMIT };
       };
       try { return await ask(); }
       catch (e) {
@@ -259,7 +295,7 @@ async function verb(job) {
     }
     case "changes": return door.changes();
     case "diff": return door.diff(String(b.path ?? ""));
-    case "mint": return identities ? identities.mint(b, app?.port) : { identities: [] };
+    case "mint": return identities ? JSON.parse(mask(JSON.stringify(await identities.mint(b, app?.port)))) : { identities: [] };
     case "restore": return door.restore(String(b.checkpoint ?? ""));
     case "keep": return door.keep(typeof b.checkpoint === "string" && b.checkpoint ? b.checkpoint : undefined);
     case "restart": return restartApp();
@@ -302,8 +338,9 @@ async function startApp() {
   pinned = pinnedNode();
   if (plan?.within) say(`your app is in ${plan.within}, started there with: ${cmd}`);
   const lifted = liftedLimits(envFiles);
-  if (Object.keys(lifted).length) say(`your own request limits are raised for this session: ${Object.keys(lifted).join(", ")}`);
+  if (Object.keys(lifted).length) say(`higher request limits for this session: ${Object.keys(lifted).join(", ")}`);
   launched = { cmd, lifted };
+  step(`starting your app: ${cmd}`);
   const up = await launch(180_000);
   if (up.port) return { port: up.port, cmd, lifted: Object.keys(lifted) };
   // Already running: a second start dies on the port the first one holds. The one that is running
@@ -417,8 +454,11 @@ async function stopApp(pid) {
 }
 
 // ---- go
+say("getting ready");
+step("looking at this folder");
 const envFiles = [];
 const files = [];
+listed = gitListed();
 walk(root, 0, files, envFiles, 0);
 // --explain: what this would send and start, from this folder, and nothing else. No network, no
 // app started, nothing written. For the person (or the agent) who reads before running.
@@ -430,13 +470,13 @@ if (explain) {
     `cortad --explain  (nothing is sent or started by this)`,
     ``,
     `talks to        ${origin.origin}  and  localhost (your app's port only)`,
-    `would send      ${files.length} source files, ${Math.round(bytes / 1024)} KB, once`,
-    `never sent      .env* (${envFiles.length} found: ${envFiles.slice(0, 6).map(rel).join(", ") || "none"}), key files, node_modules, .git`,
-    `env files       read on this machine only: to mask their values in your app's replies, and to sign test requests in`,
+    `would send      ${files.length} source files, ${Math.round(bytes / 1024)} KB, once${listed ? " (what git would commit)" : ""}`,
+    `not sent        anything git ignores, env files (${envFiles.length} here: ${envFiles.slice(0, 6).map(rel).join(", ") || "none"}), key files, data files, node_modules, .git`,
+    `env files       read here only: to hide their values in replies, and to sign in a test account`,
     `would start     ${flag("--port") ? `nothing: uses your app on port ${flag("--port")}` : plan ? `${plan.cmd}   (in ${rel(plan.cwd)})` : "asks you how your app starts"}`,
     `loads into app  lib/trace.cjs (Node) or lib/pyhook/sitecustomize.py (Python): records the one request during which your app calls a model`,
     `agent edits     in your files, each with an undo kept in ~/.cortad/checkpoints; git is never touched`,
-    `agent shell     sandboxed by the OS: no network but localhost, no writes outside temp and ignored build folders, no .env reads`,
+    `agent shell     confined by the OS: your project and toolchains only, writes to temp and build folders, localhost only`,
     ``,
     `first files     ${files.slice(0, 8).join(", ")}${files.length > 8 ? ", ..." : ""}`,
   ].join("\n"));
@@ -444,7 +484,7 @@ if (explain) {
 }
 secrets = secretValues(envFiles);
 const keepSecret = (v) => { if (v && v.length >= 12 && !secrets.includes(v)) secrets.push(v); };
-identities = makeIdentities({ root, work, envFiles, say, keepSecret, appDir: () => appDir });
+identities = makeIdentities({ root, work, envFiles, sourceFiles: () => files, say, keepSecret, appDir: () => appDir });
 // One message sent in their own app tells us the door for certain. The route and the body go up,
 // masked like everything else; the sign-in that message carried stays here.
 capture = makeCapture({ work, keepSecret, onDoor: (door) => {
@@ -464,23 +504,38 @@ key = attach.data.key;
 
 const list = join(work, "files.txt");
 writeFileSync(list, files.join("\n") + "\n");
+// Which code this is, from what the files say rather than from the archive: gzip stamps the time into
+// every archive, so the same folder packed twice never matched and every reconnect bought a whole new
+// read of code that had not changed, emptying the page's counts and its price while it ran.
+const treeDigest = (() => {
+  const h = createHash("sha256");
+  for (const rel of [...files].sort()) {
+    let body = Buffer.alloc(0);
+    try { body = readFileSync(join(root, rel)); } catch { continue; }
+    h.update(rel).update("\0").update(createHash("sha256").update(body).digest("hex")).update("\n");
+  }
+  return h.digest("hex");
+})();
 const archive = join(work, "tree.tgz");
+step("connecting");
 await exec("tar", ["-czf", archive, "-C", root, "-T", list]);
 const bytes = readFileSync(archive);
 const PART = 1_500_000;
 let resumed = 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;
-  const put = await call("PUT", `/local/${box}/tree?last=${last ? 1 : 0}`, bytes.subarray(off, off + PART), { raw: true, timeoutMs: 120_000 });
+  step(parts > 1 ? `connecting, ${Math.floor(off / PART) + 1} of ${parts}` : "connecting");
+  const put = await call("PUT", `/local/${box}/tree?last=${last ? 1 : 0}${last ? `&digest=${treeDigest}` : ""}`, bytes.subarray(off, off + PART), { raw: true, timeoutMs: 120_000 });
   if (!put.ok) fail(put.data?.error ?? `upload failed (${put.status})`);
   if (last) resumed = put.data?.resumed === true;
 }
 // Unchanged code has already been read: coming back says so instead of claiming a second read.
-say(resumed ? "connected · your code is unchanged, picking up where you left off" : `connected · reading your code (${files.length} files, ${Math.round(bytes.length / 1024)} KB)`);
+stepDone(resumed ? "connected · nothing changed since last time" : "connected");
 
 lock = await makeLock({ root, work });
 if (lock && !lockHolds(lock, root)) lock = null;
-if (!lock) say("no sandbox tool on this machine (sandbox-exec or bubblewrap), so no shell line will be run here. Runs and edits still work.");
+if (!lock) say("shell commands are off on this machine (no sandbox-exec or bubblewrap). Everything else works.");
 
 // A change to their own files, settled: what "I fixed it" looks like from here. Folders an app
 // writes to by itself are not a fix.
@@ -517,6 +572,7 @@ async function appLife() {
     say("saw your change, starting your app again");
   }
   const told = await announce();
+  clearStep();
   if (!told.ok) fail(told.data?.error ?? `could not register your app (${told.status})`);
   say(`your app is answering on port ${app.port}${app.cmd ? ` · ${app.cmd}` : ""}`);
   say("leave this open. Go back to the browser; Ctrl-C disconnects.");
@@ -580,7 +636,7 @@ async function close(code = 0) {
   await call("DELETE", `/local/${box}`).catch(() => {});
   if (child?.pid) await stopApp(child.pid);
   const pending = door.pending();
-  if (pending) say(`${pending} file${pending === 1 ? "" : "s"} changed by the agent ${pending === 1 ? "is" : "are"} still in your folder, not yet kept or undone. Run this command again to decide from the browser.`);
+  if (pending) say(`${pending} agent edit${pending === 1 ? " is" : "s are"} waiting for you to keep or undo. Run the command again to review ${pending === 1 ? "it" : "them"} in the browser.`);
   await exec("rm", ["-rf", work]).catch(() => {});
   process.exit(code);
 }

package/package.json

@@ -1,22 +1,22 @@
 {
   "name": "cortad",
-  "version": "0.1.0",
-  "description": "Runs Cortad test conversations against the app on your machine. Env values never leave it. Zero dependencies, no install scripts.",
+  "version": "0.1.2",
+  "description": "Connects the AI app on your machine to Cortad for test conversations. No dependencies.",
   "bin": {
     "cortad": "local.mjs"
   },
   "type": "module",
   "files": [
-    "local.mjs",
-    "lib/door.mjs",
-    "lib/lock.mjs",
     "README.md",
+    "lib/door.mjs",
     "lib/identities.mjs",
+    "lib/lock.mjs",
     "lib/mint.mjs",
-    "lib/trace.cjs",
+    "lib/pyhook/sitecustomize.py",
     "lib/replay.mjs",
     "lib/start.mjs",
-    "lib/pyhook/sitecustomize.py"
+    "lib/trace.cjs",
+    "local.mjs"
   ],
   "engines": {
     "node": ">=20"
@@ -25,5 +25,12 @@
   "homepage": "https://cortad.com",
   "publishConfig": {
     "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/brainsless/cortad.git"
+  },
+  "bugs": {
+    "url": "https://github.com/brainsless/cortad/issues"
   }
 }