cortad 0.1.0

package/lib/lock.mjs

@@ -0,0 +1,76 @@
+// The lock on the shell a world may run on your machine. Enforced by the operating system, not by
+// reading the command: on a Mac the same Seatbelt sandbox Codex and Claude Code use, on Linux
+// bubblewrap. Inside it a shell line can read your project and run your tests, and it can write
+// only where your own .gitignore already says files are disposable (caches, build output, coverage)
+// and in temp. It cannot write a tracked file, cannot read your keys or environment files, and on a
+// Mac cannot reach the network beyond this machine. With neither tool present there is no shell.
+import { execFile, execFileSync } from "node:child_process";
+import { existsSync, realpathSync } from "node:fs";
+import { homedir, tmpdir } from "node:os";
+import { join } from "node:path";
+import { promisify } from "node:util";
+
+const run = promisify(execFile);
+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"];
+
+async function disposableDirs(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 = [];
+  for (const line of out) {
+    if (!line.endsWith("/")) continue;
+    const rel = line.slice(0, -1);
+    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;
+  }
+  return dirs;
+}
+
+const SECRET_DIRS = [".ssh", ".aws", ".gnupg", ".config/gh", ".docker", ".kube"];
+const SECRET_FILES = [".netrc", ".npmrc", ".pypirc"];
+
+export async function makeLock({ root, work }) {
+  const home = homedir();
+  // Temp is writable, unless the project itself lives under it: a folder that contains your code is
+  // 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));
+  if (process.platform === "darwin" && existsSync("/usr/bin/sandbox-exec")) {
+    const profile = [
+      "(version 1)(allow default)",
+      "(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)$"))`,
+    ].join("");
+    return { name: "seatbelt", wrap: (cmd) => ({ file: "/usr/bin/sandbox-exec", args: ["-p", profile, "/bin/sh", "-c", cmd] }) };
+  }
+  const bwrap = process.platform === "linux" ? ["/usr/bin/bwrap", "/bin/bwrap"].find(existsSync) : null;
+  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.
+    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] }) };
+  }
+  return null;
+}
+
+// One line proving the lock holds here, before any world is allowed a shell.
+export function lockHolds(lock, root) {
+  const probe = join(root, `.bl-lock-probe-${process.pid}`);
+  const { file, args } = lock.wrap(`touch ${JSON.stringify(probe)}`);
+  try { execFileSync(file, args, { stdio: "ignore" }); } catch { /* refused, as it must be */ }
+  if (!existsSync(probe)) return true;
+  try { execFileSync("rm", ["-f", probe]); } catch { /* best effort */ }
+  return false;
+}

package/lib/mint.mjs

@@ -0,0 +1,133 @@
+// Signing in as the app's own callers, on the machine that holds its secrets. The cloud sends
+// recipes: names of env variables, routes and body fields, never a value and never code. They are
+// gated again here, the values are opened here, and what the app's own door issues is kept in a
+// folder only this user can read and wiped when the command exits. A request that should speak as
+// a role arrives carrying a marker; the real header is put in its place here, so neither a secret
+// nor a token ever leaves this machine.
+import { execFile } from "node:child_process";
+import { createSign } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
+import { promisify } from "node:util";
+import { identityScript, parseIdentityReport } from "./identities.mjs";
+
+const exec = promisify(execFile);
+export const AS_HEADER = "x-cortad-as";
+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";
+
+export function readEnv(file) {
+  const out = {};
+  let text = "";
+  try { text = readFileSync(file, "utf8"); } catch { return out; }
+  for (const line of text.split("\n")) {
+    const m = /^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)$/.exec(line);
+    if (m) out[m[1]] = m[2].trim().replace(/^(['"])([\s\S]*)\1$/, "$2");
+  }
+  return out;
+}
+
+// The admin credential the app itself runs with, under the names projects really use.
+function serviceAccountOf(env) {
+  const parse = (s) => { try { const j = JSON.parse(s); return j?.private_key && j?.client_email ? j : null; } catch { return null; } };
+  for (const [name, value] of Object.entries(env)) {
+    if (!/SERVICE_ACCOUNT|FIREBASE_ADMIN|GOOGLE_CREDENTIALS/.test(name) || !value) continue;
+    const found = parse(value) ?? parse(Buffer.from(value, "base64").toString("utf8"));
+    if (found) return found;
+  }
+  if (env.GOOGLE_APPLICATION_CREDENTIALS) { try { const found = parse(readFileSync(env.GOOGLE_APPLICATION_CREDENTIALS, "utf8")); if (found) return found; } catch { /* not a file here */ } }
+  return env.FIREBASE_PRIVATE_KEY && env.FIREBASE_CLIENT_EMAIL ? { private_key: env.FIREBASE_PRIVATE_KEY.replace(/\\n/g, "\n"), client_email: env.FIREBASE_CLIENT_EMAIL } : null;
+}
+const webApiKeyOf = (envs) => envs.flatMap((env) => Object.entries(env)).find(([name, value]) => /FIREBASE\w*API_KEY$/.test(name) && /^AIza[\w-]{20,}$/.test(value))?.[1] ?? null;
+
+// A custom token signed with their own admin credential, exchanged at their own project for the ID
+// token their app verifies. The first exchange creates the test user in that project, by that uid.
+async function firebaseIdToken(account, apiKey) {
+  const now = Math.floor(Date.now() / 1000);
+  const part = (o) => Buffer.from(JSON.stringify(o)).toString("base64url");
+  const unsigned = `${part({ alg: "RS256", typ: "JWT" })}.${part({ iss: account.client_email, sub: account.client_email, aud: "https://identitytoolkit.googleapis.com/google.identity.identitytoolkit.v1.IdentityToolkit", iat: now, exp: now + 3600, uid: TEST_UID })}`;
+  const token = `${unsigned}.${createSign("RSA-SHA256").update(unsigned).sign(account.private_key).toString("base64url")}`;
+  const res = await fetch(`https://identitytoolkit.googleapis.com/v1/accounts:signInWithCustomToken?key=${apiKey}`, {
+    method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ token, returnSecureToken: true }), signal: AbortSignal.timeout(20_000),
+  });
+  const out = await res.json().catch(() => null);
+  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 }) {
+  const dir = join(work, "identities");
+  const headerFile = (role) => join(dir, `bl-identity-${slug(role)}.header`);
+  const firebaseRoles = new Map();
+  const envs = () => {
+    // The app's own folder first: in a monorepo the root's env file is not the backend's.
+    const homes = [appDir(), root];
+    const own = homes.flatMap((h) => [envFiles.find((f) => dirname(f) === h && basename(f) === ".env"), envFiles.find((f) => dirname(f) === h)]).find(Boolean) ?? envFiles[0];
+    return { path: own ?? join(root, ".env"), all: [process.env, ...envFiles.map(readEnv)] };
+  };
+  const keep = (role, header, value) => { writeFileSync(headerFile(role), `${header}: ${value}\n`, { mode: 0o600 }); keepSecret(value.replace(/^Bearer\s+/i, "")); };
+
+  async function firebase(row) {
+    const { all } = envs();
+    const merged = Object.assign({}, ...[...all].reverse());
+    if (merged.FIREBASE_AUTH_EMULATOR_HOST) return row;
+    const account = serviceAccountOf(merged);
+    const apiKey = webApiKeyOf(all);
+    if (!account || !apiKey) return { ...row, status: "absent", note: !account ? "no Firebase admin credential in your environment" : "no Firebase web API key in your environment" };
+    const got = await firebaseIdToken(account, apiKey).catch((e) => ({ error: String(e?.message ?? e).slice(0, 120) }));
+    if (!got.idToken) return { ...row, status: "refused", note: `your Firebase project refused the sign-in: ${got.error}` };
+    keep(row.role, row.header, `Bearer ${got.idToken}`);
+    if (!firebaseRoles.has(row.role)) say(`signed in to your app as a test user it can tell apart (${TEST_UID}, in your own Firebase project)`);
+    firebaseRoles.set(row.role, { header: row.header, at: Date.now() });
+    return { ...row, status: "minted", door: "your Firebase project", expires: Math.floor(Date.now() / 1000) + 3600 };
+  }
+
+  async function mint(body, port) {
+    const recipes = Array.isArray(body?.recipes) ? body.recipes.slice(0, 12) : [];
+    if (!recipes.length || !port) return { identities: [] };
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const out = join(dir, "bl-identities.json");
+    rmSync(out, { force: true });
+    // ponytail: the program is Python, as it is in the sandbox. A machine without python3 mints
+    // nothing and says so; port the program to this file if that turns out to be common.
+    // A Firebase caller with no emulator on this machine is signed in at their real project, below.
+    // Handed to the program it waited its whole deadline on an emulator that was never there, and
+    // 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 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 });
+    const ran = forProgram.length ? await exec("python3", [file], { cwd: root, timeout: 115_000, maxBuffer: 1 << 20 }).then(() => true, (e) => e?.code !== "ENOENT") : true;
+    rmSync(file, { force: true });
+    const report = parseIdentityReport(existsSync(out) ? readFileSync(out, "utf8") : "");
+    const known = new Map((report?.identities ?? []).map((r) => [r.role, r]));
+    const rows = [];
+    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 };
+      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);
+    }
+    for (const row of rows) if (row.status === "minted" && existsSync(headerFile(row.role))) keepSecret(readFileSync(headerFile(row.role), "utf8").split(": ").slice(1).join(": ").trim().replace(/^Bearer\s+/i, ""));
+    return { identities: rows };
+  }
+
+  // The header a role speaks with, or nothing. A Firebase token lives an hour; it is renewed here
+  // when a run outlasts it.
+  async function headerFor(role) {
+    if (!ROLE.test(role)) return null;
+    const fb = firebaseRoles.get(role);
+    if (fb && Date.now() - fb.at > 50 * 60_000) await firebase({ role, header: fb.header, kind: "firebase" }).catch(() => null);
+    // A token the app's door issued, or a credential that is itself one of their secrets (an admin
+    // key). In the sandbox the second never leaves the box; here it never leaves this machine, which
+    // is the same promise, because this is where the request is sent from.
+    const file = [headerFile(role), headerFile(role).replace(/\.header$/, ".sealed")].find((f) => { try { return statSync(f).isFile(); } catch { return false; } });
+    if (!file) return null;
+    const line = readFileSync(file, "utf8").split("\n")[0] ?? "";
+    const at = line.indexOf(": ");
+    return at > 0 ? { name: line.slice(0, at).trim().toLowerCase(), value: line.slice(at + 2).trim() } : null;
+  }
+
+  return { mint, headerFor };
+}

package/lib/pyhook/sitecustomize.py

@@ -0,0 +1,301 @@
+# Loaded into your Python app by the command that started it (through PYTHONPATH), and only then.
+# The same job as trace.cjs does for Node: it watches for a request to your app during which your
+# app called a model. That request is your AI's door, with the exact body it takes and the sign-in
+# it carried. What it sees is written to a file only you can read, in the command's own folder on
+# this machine. Nothing here talks to a network, and nothing here may ever stop your app starting.
+# ponytail: shadows a sitecustomize of the project's own, which is rare; chain to it if one shows up.
+import os
+
+_FILE = os.environ.get("CORTAD_TRACE_FILE")
+
+
+def _install():
+    import contextvars
+    import importlib.abc
+    import importlib.util
+    import json
+    import re
+    import sys
+    import time
+    from urllib.parse import urlsplit
+
+    ctx = contextvars.ContextVar("cortad_request", default=None)
+    limit = 65536
+    said = set()
+    model_host = re.compile(r"(?:^|\.)(?:openai\.com|anthropic\.com|fireworks\.ai|openrouter\.ai|groq\.com|mistral\.ai|together\.xyz|together\.ai|deepseek\.com|cohere\.ai|cohere\.com|perplexity\.ai|x\.ai|openai\.azure\.com|cognitiveservices\.azure\.com|replicate\.com|huggingface\.co|cerebras\.ai|deepinfra\.com|novita\.ai|moonshot\.cn|dashscope\.aliyuncs\.com|bigmodel\.cn)$", re.I)
+    model_path = re.compile(r"/(?:chat/completions|completions|responses|messages|embeddings)$|:(?:generateContent|streamGenerateContent)|/invoke(?:-with-response-stream)?$|/api/(?:chat|generate)$", re.I)
+
+    def write(row):
+        try:
+            fd = os.open(_FILE, os.O_WRONLY | os.O_CREAT | os.O_APPEND, 0o600)
+            with os.fdopen(fd, "a", encoding="utf-8") as f:
+                f.write(json.dumps(row) + "\n")
+        except OSError:
+            pass
+
+    def is_model_call(url):
+        try:
+            parts = urlsplit(str(url))
+        except ValueError:
+            return False
+        host = (parts.hostname or "").lower()
+        path = parts.path or ""
+        if host.endswith("googleapis.com"):
+            return bool(re.search(r"generativelanguage|aiplatform", host)) and bool(model_path.search(path))
+        if host.endswith("amazonaws.com"):
+            return host.startswith("bedrock")
+        return bool(model_host.search(host)) or (bool(model_path.search(path)) and bool(re.search(r"/v\d|/api/", path)))
+
+    def text(body):
+        if body is None:
+            return ""
+        if isinstance(body, (bytes, bytearray)):
+            return bytes(body[:limit]).decode("utf-8", "replace")
+        if isinstance(body, str):
+            return body[:limit]
+        try:
+            return json.dumps(body)[:limit]
+        except (TypeError, ValueError):
+            return ""
+
+    def note(url, body):
+        req = ctx.get()
+        if not req or req["noted"] or not is_model_call(url):
+            return
+        req["noted"] = True
+        key = req["method"] + " " + req["path"].split("?")[0]
+        if key in said:
+            return
+        said.add(key)
+        write({"at": int(time.time() * 1000), "method": req["method"], "path": req["path"], "headers": req["headers"],
+               "body": b"".join(req["chunks"]).decode("utf-8", "replace")[:limit], "sent": text(body)})
+
+    def started(method, path, headers):
+        return {"method": method, "path": path, "headers": headers, "chunks": [], "size": 0, "noted": False}
+
+    def keep(req, chunk):
+        if chunk and req["size"] < limit:
+            req["chunks"].append(bytes(chunk))
+            req["size"] += len(chunk)
+
+    # Inbound, ASGI: FastAPI, Starlette, Django under uvicorn, Quart, Litestar.
+    class Asgi:
+        def __init__(self, app):
+            self.app = app
+
+        async def __call__(self, scope, receive, send):
+            if scope.get("type") != "http" or scope.get("method") in ("GET", "HEAD", "OPTIONS"):
+                return await self.app(scope, receive, send)
+            query = scope.get("query_string") or b""
+            req = started(scope["method"], scope.get("path", "/") + ("?" + query.decode("latin-1") if query else ""),
+                          {k.decode("latin-1").lower(): v.decode("latin-1") for k, v in scope.get("headers") or []})
+
+            async def seen():
+                message = await receive()
+                if message.get("type") == "http.request":
+                    keep(req, message.get("body") or b"")
+                return message
+
+            token = ctx.set(req)
+            try:
+                return await self.app(scope, seen, send)
+            finally:
+                ctx.reset(token)
+
+    # Inbound, WSGI: Flask, Django's runserver, anything under werkzeug.
+    class Tee:
+        def __init__(self, stream, req):
+            self.stream, self.req = stream, req
+
+        def read(self, *a):
+            chunk = self.stream.read(*a)
+            keep(self.req, chunk)
+            return chunk
+
+        def readline(self, *a):
+            chunk = self.stream.readline(*a)
+            keep(self.req, chunk)
+            return chunk
+
+        def __iter__(self):
+            for chunk in self.stream:
+                keep(self.req, chunk)
+                yield chunk
+
+        def __getattr__(self, name):
+            return getattr(self.stream, name)
+
+    def inside(req, iterable):
+        # A streamed reply is produced after the handler returns: the model call happens here.
+        it = iter(iterable)
+        try:
+            while True:
+                token = ctx.set(req)
+                try:
+                    item = next(it)
+                except StopIteration:
+                    return
+                finally:
+                    ctx.reset(token)
+                yield item
+        finally:
+            close = getattr(iterable, "close", None)
+            if close:
+                close()
+
+    def wsgi(app):
+        if getattr(app, "_brainsless", False):
+            return app
+
+        def wrapped(environ, start_response):
+            method = environ.get("REQUEST_METHOD", "GET")
+            if method in ("GET", "HEAD", "OPTIONS"):
+                return app(environ, start_response)
+            headers = {k[5:].replace("_", "-").lower(): v for k, v in environ.items() if k.startswith("HTTP_")}
+            if environ.get("CONTENT_TYPE"):
+                headers["content-type"] = environ["CONTENT_TYPE"]
+            query = environ.get("QUERY_STRING") or ""
+            req = started(method, (environ.get("SCRIPT_NAME", "") + environ.get("PATH_INFO", "/")) + ("?" + query if query else ""), headers)
+            if environ.get("wsgi.input") is not None:
+                environ["wsgi.input"] = Tee(environ["wsgi.input"], req)
+            token = ctx.set(req)
+            try:
+                return inside(req, app(environ, start_response))
+            finally:
+                ctx.reset(token)
+
+        wrapped._brainsless = True
+        return wrapped
+
+    # What is patched, once the module it lives in has been imported by the app itself.
+    def patch_uvicorn(module):
+        load = module.Config.load
+
+        def loaded(self, *a, **k):
+            out = load(self, *a, **k)
+            if not isinstance(self.loaded_app, Asgi):
+                self.loaded_app = Asgi(self.loaded_app)
+            return out
+
+        module.Config.load = loaded
+
+    def patch_werkzeug(module):
+        run_simple = module.run_simple
+
+        def run(hostname, port, application, *a, **k):
+            return run_simple(hostname, port, wsgi(application), *a, **k)
+
+        module.run_simple = run
+
+    def patch_django(module):
+        call = module.WSGIHandler.__call__
+
+        def called(self, environ, start_response):
+            return wsgi(lambda e, s: call(self, e, s))(environ, start_response)
+
+        module.WSGIHandler.__call__ = called
+
+    def patch_httpx(module):
+        for cls in (module.Client, module.AsyncClient):
+            send = cls.send
+            if cls is module.Client:
+                def sync_send(self, request, *a, _send=send, **k):
+                    try:
+                        note(request.url, request.content)
+                    except Exception:
+                        try:
+                            note(request.url, None)
+                        except Exception:
+                            pass
+                    return _send(self, request, *a, **k)
+                cls.send = sync_send
+            else:
+                async def async_send(self, request, *a, _send=send, **k):
+                    try:
+                        note(request.url, request.content)
+                    except Exception:
+                        try:
+                            note(request.url, None)
+                        except Exception:
+                            pass
+                    return await _send(self, request, *a, **k)
+                cls.send = async_send
+
+    def patch_requests(module):
+        send = module.Session.send
+
+        def sent(self, request, *a, **k):
+            try:
+                note(request.url, request.body)
+            except Exception:
+                pass
+            return send(self, request, *a, **k)
+
+        module.Session.send = sent
+
+    def patch_aiohttp(module):
+        request = module.ClientSession._request
+
+        async def requested(self, method, str_or_url, *a, **k):
+            try:
+                note(str_or_url, k.get("json") if k.get("json") is not None else k.get("data"))
+            except Exception:
+                pass
+            return await request(self, method, str_or_url, *a, **k)
+
+        module.ClientSession._request = requested
+
+    exact = {"uvicorn.config": patch_uvicorn, "werkzeug.serving": patch_werkzeug, "django.core.handlers.wsgi": patch_django,
+             "requests.sessions": patch_requests, "aiohttp.client": patch_aiohttp}
+    # By family, not by name: the OpenAI SDK moved to a renamed copy of httpx (httpx2), and a patch
+    # keyed on "httpx" alone saw none of its calls.
+    families = [(re.compile(r"httpx\d*$"), patch_httpx)]
+
+    def patch_for(name):
+        if name in exact:
+            return exact[name]
+        for pattern, patch in families:
+            if pattern.match(name):
+                return patch
+        return None
+
+    busy = set()
+
+    class Finder(importlib.abc.MetaPathFinder):
+        def find_spec(self, name, path=None, target=None):
+            patch = patch_for(name)
+            if patch is None or name in busy:
+                return None
+            busy.add(name)
+            try:
+                spec = importlib.util.find_spec(name)
+            except Exception:
+                spec = None
+            finally:
+                busy.discard(name)
+            if spec is None or spec.loader is None or not hasattr(spec.loader, "exec_module"):
+                return None
+            run = spec.loader.exec_module
+
+            def exec_module(module, _run=run, _patch=patch):
+                _run(module)
+                try:
+                    _patch(module)
+                except Exception:
+                    pass
+
+            try:
+                spec.loader.exec_module = exec_module
+            except Exception:
+                return None
+            return spec
+
+    sys.meta_path.insert(0, Finder())
+    write({"hello": "python", "pid": os.getpid()})
+
+
+if _FILE:
+    try:
+        _install()
+    except Exception:
+        pass

package/lib/replay.mjs

@@ -0,0 +1,49 @@
+// The other half of lib/trace.cjs: the command's side. It hands the hook to the app it starts,
+// reads what the hook wrote, keeps the sign-in that request carried on this machine, and tells the
+// cloud only what it needs to ask again: the route, the method and the body.
+import { readFileSync, statSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const HOOK = join(HERE, "trace.cjs");
+const PYHOOK = join(HERE, "pyhook");
+export const CAPTURED = "captured";
+// Never replayed: they describe one connection, not the caller.
+const HOP = /^(?:host|content-length|connection|keep-alive|transfer-encoding|upgrade|expect|te|trailer|accept-encoding|x-cortad-as)$/i;
+
+export function makeCapture({ work, keepSecret, onDoor }) {
+  const file = join(work, "trace.jsonl");
+  let read = 0;
+  let held = null;
+  let alive = false;
+  // Both hooks are handed to whatever is started: a Node app loads the first, a Python app the
+  // second, and each ignores the other's variable.
+  // ponytail: Node and Python. Go, Ruby, Java and PHP apps are asked for their route on the screen.
+  const env = (base) => ({
+    CORTAD_TRACE_FILE: file,
+    NODE_OPTIONS: `${base.NODE_OPTIONS ?? ""} --require ${JSON.stringify(HOOK)}`.trim(),
+    PYTHONPATH: [PYHOOK, base.PYTHONPATH].filter(Boolean).join(":"),
+  });
+
+  function poll() {
+    let size = 0;
+    try { size = statSync(file).size; } catch { return; }
+    if (size <= read) return;
+    const fresh = readFileSync(file, "utf8").slice(read);
+    read = size;
+    for (const line of fresh.split("\n").filter(Boolean)) {
+      let row; try { row = JSON.parse(line); } catch { continue; }
+      if (row.hello) { alive = true; continue; }
+      let body; try { body = JSON.parse(row.body); } catch { continue; }
+      if (!body || typeof body !== "object" || typeof row.path !== "string" || !row.path.startsWith("/")) continue;
+      const headers = Object.fromEntries(Object.entries(row.headers ?? {}).filter(([k, v]) => !HOP.test(k) && typeof v === "string"));
+      for (const [k, v] of Object.entries(headers)) if (/authorization|cookie|token|secret|session|csrf|api-?key/i.test(k)) keepSecret(String(v).replace(/^Bearer\s+/i, ""));
+      held = { headers, at: Date.now() };
+      onDoor({ method: String(row.method || "POST").toUpperCase(), path: row.path, body, headerNames: Object.keys(headers).sort() });
+    }
+  }
+  const timer = setInterval(poll, 700);
+  timer.unref();
+  return { env, headers: () => held?.headers ?? null, alive: () => { poll(); return alive; } };
+}

package/lib/start.mjs

@@ -0,0 +1,85 @@
+// How their app is started, and from which folder, worked out from the repository itself so nobody
+// is asked. A monorepo root has no app of its own: the app is the workspace that serves the AI.
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { join, relative } from "node:path";
+
+const read = (file) => { try { return readFileSync(file, "utf8"); } catch { return ""; } };
+const json = (file) => { try { return JSON.parse(read(file)); } catch { return null; } };
+const MODEL_SDK = /^(?:openai|ai|@ai-sdk\/.+|@anthropic-ai\/sdk|langchain|@langchain\/.+|llamaindex|@google\/generative-ai|@google\/genai|groq-sdk|@mistralai\/.+|cohere-ai|ollama|replicate|together-ai)$/;
+const SERVER = /^(?:express|fastify|hono|koa|@nestjs\/core|@strapi\/strapi|next|nuxt|@remix-run\/.+|@sveltejs\/kit|@hapi\/hapi|restify|elysia)$/;
+const PY_MODEL = /^\s*["']?(?:openai|anthropic|langchain|langgraph|litellm|llama[-_]index|google-generativeai|google-genai|groq|cohere|mistralai|ollama|fireworks-ai|together)\b/im;
+const PY_SERVER = /^\s*["']?(?:fastapi|flask|django|starlette|quart|litestar|sanic|aiohttp|uvicorn|gunicorn)\b/im;
+const ENTRIES = ["main.py", "app.py", "server.py", "run.py", "api.py", "wsgi.py", "asgi.py", "src/main.py", "app/main.py", "src/app.py", "backend/main.py", "api/main.py"];
+
+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]);
+  if (!script) return null;
+  const locked = 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 lockfile names the manager the repository was installed with, not one this machine has.
+  return `${onPath(locked) ? locked : "npm"} run ${script}`;
+}
+
+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 `${py} manage.py runserver`;
+  for (const entry of ENTRIES) {
+    const text = read(join(dir, entry));
+    if (!text) continue;
+    // Their own way of starting it carries their own port and settings.
+    if (/if\s+__name__\s*==\s*["']__main__["']/.test(text)) return `${py} ${entry}`;
+    const module = entry.replace(/\.py$/, "").split("/").join(".");
+    const fast = /^(\w+)\s*=\s*(?:FastAPI|Starlette|Litestar|Quart)\(/m.exec(text);
+    if (fast) return `${py} -m uvicorn ${module}:${fast[1]} --host 127.0.0.1 --port 8000`;
+    const flask = /^(\w+)\s*=\s*Flask\(/m.exec(text);
+    if (flask) return `${py} -m flask --app ${module} run --port 5000`;
+  }
+  return null;
+}
+
+const startOf = (dir, onPath) => nodeStart(dir, onPath) ?? pythonStart(dir, onPath);
+
+// How much a folder looks like the thing that serves the AI.
+function weight(dir, name) {
+  const pkg = json(join(dir, "package.json"));
+  const deps = Object.keys({ ...(pkg?.dependencies ?? {}), ...(pkg?.devDependencies ?? {}) });
+  const py = `${read(join(dir, "requirements.txt"))}\n${read(join(dir, "pyproject.toml"))}`;
+  const model = deps.some((d) => MODEL_SDK.test(d)) || PY_MODEL.test(py);
+  const server = deps.some((d) => SERVER.test(d)) || PY_SERVER.test(py);
+  return (model ? 4 : 0) + (server ? 2 : 0) + (/back|api|server|service/i.test(name) ? 1 : 0) - (!model && /front|web|client|ui|mobile|docs|site|landing|admin/i.test(name) ? 3 : 0);
+}
+
+const SKIP = /^(?:node_modules|\.git|dist|build|\.next|coverage|\.venv|venv|__pycache__|\.turbo|\.cache)$/;
+function workspaces(root) {
+  const found = [];
+  const visit = (dir, depth) => {
+    let names = [];
+    try { names = readdirSync(dir); } catch { return; }
+    for (const name of names) {
+      if (SKIP.test(name) || name.startsWith(".")) continue;
+      const at = join(dir, name);
+      try { if (!statSync(at).isDirectory()) continue; } catch { continue; }
+      if (["package.json", "requirements.txt", "pyproject.toml", "manage.py"].some((f) => existsSync(join(at, f)))) found.push(at);
+      else if (depth < 2) visit(at, depth + 1);
+    }
+  };
+  visit(root, 1);
+  return found;
+}
+
+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);
+  if (own) return { cmd: own, cwd: root };
+  const ranked = workspaces(root).map((dir) => ({ dir, cmd: startOf(dir, onPath), weight: weight(dir, relative(root, dir)) })).filter((w) => w.cmd).sort((a, b) => b.weight - a.weight);
+  const best = ranked[0];
+  if (best && best.weight > 0 && (ranked.length === 1 || best.weight > ranked[1].weight)) return { cmd: best.cmd, cwd: best.dir, within: relative(root, best.dir) };
+  // A root that does have a start of its own after all (a monorepo whose root script runs everything).
+  const rootStart = startOf(root, onPath);
+  return rootStart ? { cmd: rootStart, cwd: root } : best ? { cmd: best.cmd, cwd: best.dir, within: relative(root, best.dir), unsure: true } : null;
+}