@zanii/blackbox 0.0.0-stage → 0.2.0

package/dist/cli.js

@@ -0,0 +1,1057 @@
+#!/usr/bin/env node
+// The `blackbox` command. Mirrors the Python SDK's `python -m zanii_blackbox.<command>` entry points.
+import { createHash } from "node:crypto";
+import { appendFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { parseCommand } from "./attest/index.js";
+import { serveMcp } from "./mcp-server/index.js";
+import { mcpWrap } from "./mcp-wrap/index.js";
+import { RecordNotVerified, reconcile } from "./reconcile/index.js";
+import { session } from "./session/index.js";
+import { verifyBundle } from "./verify/index.js";
+import { VERSION } from "./version.js";
+import { postReceipt, receiptFor, workspaceTree } from "./workspace-receipt/index.js";
+const USAGE = `usage (spec/cli.md):
+  blackbox verify <bundle.json> [--proofs] [--bodies <dir>]
+  blackbox export <session_id> --out <bundle.json> [--bodies <dir>]
+  blackbox export-all --from <date> --to <date> --out <file.ndjson>
+  blackbox sessions [--limit N] [--label L] [--open | --closed] [--before <session_id>] [--from <date>] [--to <date>] [--json]
+  blackbox sessions <session_id> [--json]
+  blackbox summary <session_id>
+  blackbox incident <session_id> [--lang en|ar]
+  blackbox fleet
+  blackbox logbook [--limit N]
+  blackbox occurrence <session_id> --framework <id> [--lang en|ar] [--json]
+  blackbox occurrence-pack <session_id> --framework <id>
+  blackbox file <session_id> --framework <id> --reference <ref> [--channel <c>] [--filed-at <iso>]
+  blackbox replay <session_id> [--fork] [--fork-after N] [--label L] [--drill <drill.json>]
+  blackbox tail <session_id> [--after-seq N]
+  blackbox close <session_id> [--outcome success|failure|abandoned] [--note <text>]
+  blackbox resume <session_id> [--token <resume token>] [--note <text>] [--force]   (a paused session needs no token)
+  blackbox emergency <session_id> [--note <text>]
+  blackbox pause <session_id> [--note <text>]   (stops at the next call; resume needs no token)
+  blackbox erase <session_id>
+  blackbox approvals <session_id>
+  blackbox decide <session_id> <approval_id> approve|reject [--note <text>]
+  blackbox drain [--spool-dir <dir>]   (ships what a stopped agent left in its spool)
+  blackbox analyze <bundle.json> [--bodies <dir>] [--prices <file>]
+  blackbox verify-certificate <certificate.json> [--did <did:key:…>]
+  blackbox investigate <bundle.json> [--bodies <dir>] [--directives <file>] [--identity <file>] [--proofs] [--out <prefix>]
+  blackbox statement --provider anthropic|openai --from <YYYY-MM-DD> --to <YYYY-MM-DD> [--out <file>]
+  blackbox statement --provider csv --file <f> --model-column <name> --amount-column <name> --unit usd|cents|micro_usd|aed [--delimiter <c>] --from <d> --to <d> [--out <file>]
+  blackbox statement --provider custom --connector <file> --from <d> --to <d> [--out <file>]
+  blackbox preflight --require <items> [--optional <items>]
+  blackbox --version
+  blackbox mcp   (an MCP server on stdio: spec/mcp-server.md)
+  blackbox mcp-wrap --server <name> -- <command> [args...]
+  blackbox reconcile --harness claude-code|codex --bundle <bundle.json> --bodies <dir> [--agent-session <id>]... [--require-receipts] <path>
+  blackbox reconcile-system --connector <connector.json> --log <export.csv|jsonl> [--pack <pack.json>] <session_id>
+  blackbox workspace-receipt   (a Claude Code PreToolUse / PostToolUse hook; reads the hook JSON on stdin)
+  blackbox attest   (a Claude Code PostToolUse hook: spec/attestation.md §4)`;
+async function main(argv) {
+    const [command, ...rest] = argv;
+    if (command === "mcp")
+        return mcpCommand(rest);
+    if (command === "mcp-wrap")
+        return wrap(rest);
+    if (command === "reconcile")
+        return reconcileCommand(rest);
+    if (command === "reconcile-system")
+        return reconcileSystemCommand(rest);
+    if (command === "workspace-receipt")
+        return receiptCommand();
+    if (command === "attest")
+        return attestCommand();
+    if (command === "verify")
+        return verifyCommand(rest);
+    if (command === "export")
+        return exportCommand(rest);
+    if (command === "sessions")
+        return sessionsCommand(rest);
+    if (command === "summary")
+        return oneRead(rest, (id) => `/v1/sessions/${id}/summary`);
+    if (command === "incident")
+        return incidentCommand(rest);
+    if (command === "fleet")
+        return rest.length ? usage() : printJson("/v1/fleet");
+    if (command === "logbook")
+        return logbookCommand(rest);
+    if (command === "occurrence")
+        return occurrenceCommand(rest);
+    if (command === "replay")
+        return replayCommand(rest);
+    if (command === "analyze")
+        return analyzeCommand(rest);
+    if (command === "verify-certificate")
+        return certificateCommand(rest);
+    if (command === "preflight")
+        return preflightCommand(rest);
+    if (command === "investigate")
+        return investigateCommand(rest);
+    if (command === "statement")
+        return statementCommand(rest);
+    if (command === "export-all")
+        return exportAllCommand(rest);
+    if (command === "occurrence-pack")
+        return occurrencePackCommand(rest);
+    if (command === "file")
+        return fileCommand(rest);
+    if (command === "tail")
+        return tailCommand(rest);
+    if (command === "drain")
+        return drainCommand(rest);
+    if (command === "approvals")
+        return oneRead(rest, (id) => `/v1/sessions/${id}/approvals`);
+    if (command === "close" ||
+        command === "resume" ||
+        command === "emergency" ||
+        command === "pause" ||
+        command === "erase" ||
+        command === "decide")
+        return controlCommand(command, rest);
+    if (command === "--version" || command === "version") {
+        process.stdout.write(`blackbox ${VERSION} (typescript)\n`);
+        return 0;
+    }
+    process.stderr.write(`${USAGE}\n`);
+    return 2;
+}
+function wrap(rest) {
+    const split = rest.indexOf("--");
+    const flags = split < 0 ? rest : rest.slice(0, split);
+    const server = flags[0] === "--server" ? flags[1] : undefined;
+    const url = process.env.BLACKBOX_URL;
+    const token = process.env.BLACKBOX_TOKEN;
+    if (!server || flags.length !== 2 || split < 0 || !url || !token) {
+        process.stderr.write(`${USAGE}\n(mcp-wrap: BLACKBOX_URL and BLACKBOX_TOKEN must be set)\n`);
+        return 2;
+    }
+    return mcpWrap({ server, command: rest.slice(split + 1), gatewayUrl: url, token });
+}
+async function reconcileCommand(rest) {
+    const agentSessions = [];
+    const flags = {};
+    const paths = [];
+    for (let i = 0; i < rest.length; i++) {
+        const a = rest[i];
+        if (a === "--agent-session")
+            agentSessions.push(rest[++i] ?? "");
+        else if (a === "--require-receipts")
+            flags["require-receipts"] = "1";
+        else if (a.startsWith("--"))
+            flags[a.slice(2)] = rest[++i] ?? "";
+        else
+            paths.push(a);
+    }
+    const harness = flags.harness;
+    if ((harness !== "claude-code" && harness !== "codex") ||
+        !flags.bundle ||
+        !flags.bodies ||
+        paths.length !== 1) {
+        process.stderr.write(`${USAGE}\n`);
+        return 2;
+    }
+    const bundle = JSON.parse(readFileSync(flags.bundle, "utf8"));
+    const bodies = bodiesIn(flags.bodies);
+    try {
+        const report = await reconcile({
+            harness,
+            bundle,
+            bodies,
+            local: paths[0],
+            agentSessions,
+            requireReceipts: flags["require-receipts"] === "1",
+        });
+        process.stdout.write(`${JSON.stringify(report)}\n`);
+        return report.ok ? 0 : 1;
+    }
+    catch (error) {
+        if (!(error instanceof RecordNotVerified))
+            throw error;
+        process.stdout.write(`${JSON.stringify({ v: 1, ok: false, error: error.message })}\n`);
+        return 2;
+    }
+}
+/** Never blocks the agent: every failure is reported on stderr and the hook still exits 0. */
+/** spec/attestation.md §4. Never blocks the agent: always exits 0, prints nothing on stdout. */
+async function attestCommand() {
+    const url = process.env.BLACKBOX_URL;
+    const token = process.env.BLACKBOX_TOKEN;
+    const sessionId = process.env.BLACKBOX_SESSION_ID;
+    if (!url || !token || !sessionId)
+        return 0;
+    try {
+        const parts = [];
+        for await (const chunk of process.stdin)
+            parts.push(chunk);
+        const hook = JSON.parse(Buffer.concat(parts).toString("utf8"));
+        const argv = hook.tool_name === "Bash" && typeof hook.tool_input?.command === "string"
+            ? parseCommand(hook.tool_input.command)
+            : null;
+        const stdout = hook.tool_response?.stdout;
+        if (!argv || typeof stdout !== "string")
+            return 0;
+        const s = await session({ url, token, sessionId });
+        const cwd = typeof hook.cwd === "string" && hook.cwd !== "" ? hook.cwd : undefined;
+        // L7.3.6: the exit code too, when the tool result reports one.
+        const rc = hook.tool_response?.exit_code ?? hook.tool_response?.returnCode;
+        const exit = Number.isSafeInteger(rc) ? rc : undefined;
+        if (s.attest(argv, stdout, cwd, exit))
+            await s.flush();
+    }
+    catch (error) {
+        process.stderr.write(`blackbox attest: ${error instanceof Error ? error.message : error}\n`);
+    }
+    return 0;
+}
+async function receiptCommand() {
+    const url = process.env.BLACKBOX_URL;
+    const token = process.env.BLACKBOX_TOKEN;
+    if (!url || !token) {
+        process.stderr.write("blackbox workspace-receipt: BLACKBOX_URL and BLACKBOX_TOKEN must be set; no receipt\n");
+        return 0;
+    }
+    let hook;
+    try {
+        const parts = [];
+        for await (const chunk of process.stdin)
+            parts.push(chunk);
+        hook = JSON.parse(Buffer.concat(parts).toString("utf8"));
+    }
+    catch {
+        process.stderr.write("blackbox workspace-receipt: the hook input is not JSON; no receipt\n");
+        return 0;
+    }
+    const cwd = typeof hook.cwd === "string" && hook.cwd !== "" ? hook.cwd : process.cwd();
+    const receipt = receiptFor(hook, workspaceTree(cwd));
+    if (!receipt)
+        return 0;
+    const failure = await postReceipt(url, token, receipt);
+    if (failure)
+        process.stderr.write(`blackbox workspace-receipt: not recorded: ${failure}\n`);
+    return 0;
+}
+// ---------------------------------------------------------------- verify / export / sessions (spec/cli.md)
+/** `--flag value` pairs and positionals; `booleans` are flags without a value. */
+function parse(rest, booleans) {
+    const flags = {};
+    const positional = [];
+    for (let i = 0; i < rest.length; i++) {
+        const a = rest[i];
+        if (booleans.includes(a))
+            flags[a.slice(2)] = "1";
+        else if (a.startsWith("--"))
+            flags[a.slice(2)] = rest[++i] ?? "";
+        else
+            positional.push(a);
+    }
+    return { flags, positional };
+}
+const SESSION_ID = /^ses_[A-Za-z0-9]{16,64}$/;
+async function verifyCommand(rest) {
+    const { flags, positional } = parse(rest, ["--proofs"]);
+    if (positional.length !== 1)
+        return usage();
+    let bundle;
+    try {
+        bundle = JSON.parse(readFileSync(positional[0], "utf8"));
+    }
+    catch (error) {
+        process.stdout.write(`${JSON.stringify({ ok: false, error: String(error) })}\n`);
+        return 2;
+    }
+    const report = await verifyBundle(bundle, {
+        proofs: flags.proofs === "1",
+        ...(flags.bodies ? { body: bodiesIn(flags.bodies) } : {}),
+    });
+    const identity = { ok: report.identity.ok, message: report.identity.message ?? null };
+    process.stdout.write(`${JSON.stringify({ ...report, identity })}\n`);
+    return report.ok ? 0 : 1;
+}
+function mcpCommand(rest) {
+    const url = process.env.BLACKBOX_URL?.replace(/\/+$/, "");
+    // audit, also found: a tenant's key (read-only works) instead of the operator's
+    const key = process.env.BLACKBOX_API_KEY || process.env.BLACKBOX_ADMIN_KEY;
+    if (rest.length > 0 || !url || !key) {
+        process.stderr.write(`${USAGE}\n(mcp: BLACKBOX_URL and BLACKBOX_API_KEY or BLACKBOX_ADMIN_KEY must be set)\n`);
+        return 2;
+    }
+    return serveMcp(async (path) => {
+        const res = await fetch(`${url}${path}`, {
+            headers: { authorization: `Bearer ${key}` },
+            signal: AbortSignal.timeout(30_000),
+        });
+        return { status: res.status, text: await res.text() };
+    });
+}
+class ServerError extends Error {
+}
+/** GET from the gateway's admin API (BLACKBOX_URL + BLACKBOX_ADMIN_KEY). */
+async function admin(path, body, allow = []) {
+    const url = process.env.BLACKBOX_URL;
+    const key = process.env.BLACKBOX_ADMIN_KEY;
+    if (!url || !key)
+        throw new ServerError("BLACKBOX_URL and BLACKBOX_ADMIN_KEY must be set");
+    let res;
+    try {
+        res = await fetch(`${url.replace(/\/+$/, "")}${path}`, {
+            ...(body === undefined ? {} : { method: "POST", body: JSON.stringify(body) }),
+            headers: {
+                authorization: `Bearer ${key}`,
+                ...(body === undefined ? {} : { "content-type": "application/json" }),
+            },
+            signal: AbortSignal.timeout(30_000),
+        });
+    }
+    catch (error) {
+        throw new ServerError(`can't reach ${url}: ${error instanceof Error ? error.message : error}`);
+    }
+    if (!res.ok && !allow.includes(res.status))
+        throw new ServerError(`${path}: HTTP ${res.status} ${(await res.text()).slice(0, 200)}`);
+    return res;
+}
+/** Audit K3: a bodies folder, read by hash. Only a real sha256 names a file; the bytes are
+ *  checked against the chain wherever the record is verified (verifyBundle's `body`). */
+function bodiesIn(dir) {
+    return (hash) => {
+        if (!dir || !/^sha256:[0-9a-f]{64}$/.test(hash))
+            return undefined;
+        const file = join(dir, hash.slice("sha256:".length));
+        return existsSync(file) ? readFileSync(file) : undefined;
+    };
+}
+const adminJson = async (path) => (await (await admin(path)).json());
+async function exportCommand(rest) {
+    const { flags, positional } = parse(rest, []);
+    const id = positional[0] ?? "";
+    if (positional.length !== 1 || !SESSION_ID.test(id) || !flags.out)
+        return usage();
+    const bundle = (await adminJson(`/v1/sessions/${id}/bundle`));
+    writeFileSync(flags.out, `${JSON.stringify(bundle)}\n`);
+    let bodies = 0;
+    let erased = 0;
+    if (flags.bodies) {
+        mkdirSync(flags.bodies, { recursive: true });
+        const hashes = new Set(bundle.lines.map((l) => JSON.parse(l).body_hash));
+        for (const hash of hashes) {
+            // The hash names a file: only a real sha256 may, and the bytes must be what it names.
+            if (!/^sha256:[0-9a-f]{64}$/.test(hash))
+                throw new ServerError(`bad body hash in the bundle`);
+            const file = join(flags.bodies, hash.slice("sha256:".length));
+            if (existsSync(file))
+                continue;
+            // Audit K16: after a PDPL / GDPR erasure, the rest of the evidence still exports.
+            const res = await admin(`/v1/bodies/${hash}`, undefined, [410]);
+            if (res.status === 410) {
+                erased++;
+                continue;
+            }
+            const data = Buffer.from(await res.arrayBuffer());
+            if (`sha256:${createHash("sha256").update(data).digest("hex")}` !== hash)
+                throw new ServerError(`the server sent a body that doesn't match ${hash}`);
+            writeFileSync(file, data);
+            bodies++;
+        }
+    }
+    process.stdout.write(`${JSON.stringify({ ok: true, events: bundle.lines.length, bodies, ...(erased ? { erased } : {}) })}\n`);
+    return 0;
+}
+async function sessionsCommand(rest) {
+    const { flags, positional } = parse(rest, ["--json", "--open", "--closed"]);
+    const f = flags;
+    const asJson = flags.json === "1";
+    if (positional.length === 1)
+        return oneSession(positional[0], asJson);
+    const limit = Number(flags.limit ?? 20);
+    if (positional.length > 1 || !Number.isSafeInteger(limit) || limit < 1)
+        return usage();
+    if (f.open === "1" && f.closed === "1")
+        return usage();
+    // Audit S16: the server's filters (spec/api.md).
+    const q = new URLSearchParams({ limit: String(limit) });
+    if (f.label !== undefined)
+        q.set("label", f.label);
+    if (f.before !== undefined)
+        q.set("before", f.before);
+    if (f.from !== undefined)
+        q.set("from", f.from);
+    if (f.to !== undefined)
+        q.set("to", f.to);
+    if (f.open === "1")
+        q.set("status", "open");
+    if (f.closed === "1")
+        q.set("status", "closed");
+    const { sessions } = await adminJson(`/v1/sessions?${q}`);
+    const rows = [];
+    for (const s of sessions) {
+        const info = await adminJson(`/v1/sessions/${s.session_id}`);
+        rows.push({
+            session_id: s.session_id,
+            label: s.label,
+            created_at: s.created_at,
+            closed_at: s.closed_at,
+            verified: info.verification.ok === true,
+        });
+    }
+    if (asJson)
+        process.stdout.write(`${JSON.stringify({ sessions: rows })}\n`);
+    else
+        table(["SESSION", "LABEL", "OPENED", "CLOSED", "VERIFIED"], rows.map((r) => [
+            r.session_id,
+            r.label ?? "",
+            r.created_at,
+            r.closed_at ?? "open",
+            r.verified ? "yes" : "NO",
+        ]));
+    return 0;
+}
+async function oneSession(id, asJson) {
+    if (!SESSION_ID.test(id))
+        return usage();
+    const info = await adminJson(`/v1/sessions/${id}`);
+    const cost = await adminJson(`/v1/sessions/${id}/cost`);
+    const landing = await adminJson(`/v1/sessions/${id}/landing`);
+    const waste = await adminJson(`/v1/sessions/${id}/waste`);
+    const text = await (await admin(`/v1/sessions/${id}/events`)).text();
+    const findings = text
+        .split("\n")
+        .filter(Boolean)
+        .map((l) => JSON.parse(l))
+        .filter((e) => e.kind === "finding")
+        .map((e) => ({
+        seq: e.seq,
+        code: e.meta.code,
+        fault: e.meta.fault ?? null,
+        severity: e.meta.severity,
+    }));
+    const { verification, anchors: _anchors, ...session } = info;
+    const out = {
+        session,
+        verification,
+        cost: { total_micro_usd: cost.total_micro_usd, total_aed: cost.total_aed },
+        findings,
+        landing,
+        waste,
+    };
+    const code = verification.ok ? 0 : 1;
+    if (asJson) {
+        process.stdout.write(`${JSON.stringify(out)}\n`);
+        return code;
+    }
+    const say = (s) => process.stdout.write(`${s}\n`);
+    say(`${id}${session.label ? `  ${session.label}` : ""}`);
+    say(`  events     ${session.events}   opened ${session.created_at}   ${session.closed_at ? `closed ${session.closed_at}` : "open"}`);
+    say(`  verified   ${verification.ok ? "yes" : `NO: ${verification.code} at ${verification.index}`}   anchors ${session.anchor_status}`);
+    say(`  cost       ${cost.total_micro_usd} µUSD (${cost.total_aed})   wasted ${waste.wasted_micro_usd} µUSD   outcome ${waste.outcome ?? "none"}`);
+    if (session.control?.state === "blocked")
+        say(`  BLOCKED    by ${session.control.blocked_by}`);
+    for (const c of landing.claims)
+        say(`  claim      seq ${c.seq}: ${c.verdict}`);
+    if (findings.length === 0)
+        say("  findings   none");
+    else {
+        say("  findings");
+        table(["SEQ", "FAULT", "LEVEL", "CODE"], findings.map((f) => [String(f.seq), f.fault ?? "", f.severity, f.code]), "    ");
+    }
+    return code;
+}
+// ---------------------------------------------------------------- reads, replay, offline analysis (audit S11–S15, S22)
+async function printJson(path) {
+    process.stdout.write(`${JSON.stringify(await adminJson(path))}\n`);
+    return 0;
+}
+function oneRead(rest, path) {
+    const { positional } = parse(rest, []);
+    const id = positional[0] ?? "";
+    if (positional.length !== 1 || !SESSION_ID.test(id))
+        return usage();
+    return printJson(path(id));
+}
+async function incidentCommand(rest) {
+    const { flags, positional } = parse(rest, []);
+    const id = positional[0] ?? "";
+    const lang = flags.lang ?? "en";
+    if (positional.length !== 1 || !SESSION_ID.test(id) || (lang !== "en" && lang !== "ar"))
+        return usage();
+    process.stdout.write(await (await admin(`/v1/sessions/${id}/incident?lang=${lang}`)).text());
+    return 0;
+}
+function logbookCommand(rest) {
+    const { flags, positional } = parse(rest, []);
+    const limit = Number(flags.limit ?? 1000);
+    if (positional.length || !Number.isSafeInteger(limit) || limit < 1)
+        return usage();
+    return printJson(`/v1/logbook?limit=${limit}`);
+}
+async function occurrenceCommand(rest) {
+    const { flags, positional } = parse(rest, ["--json"]);
+    const id = positional[0] ?? "";
+    if (positional.length !== 1 || !SESSION_ID.test(id) || !flags.framework)
+        return usage();
+    if (flags.lang !== undefined && flags.lang !== "en" && flags.lang !== "ar")
+        return usage();
+    const q = new URLSearchParams({
+        framework: flags.framework,
+        format: flags.json === "1" ? "json" : "md",
+        ...(flags.lang ? { lang: flags.lang } : {}),
+    });
+    const res = await admin(`/v1/sessions/${id}/occurrence?${q}`);
+    if (flags.json === "1")
+        process.stdout.write(`${JSON.stringify(await res.json())}\n`);
+    else
+        process.stdout.write(await res.text());
+    return 0;
+}
+/** spec/replay.md: opens a replay (or a fork) of a recorded session. Prints the new session. */
+async function replayCommand(rest) {
+    const { flags, positional } = parse(rest, ["--fork"]);
+    const id = positional[0] ?? "";
+    const after = flags["fork-after"] === undefined ? undefined : Number(flags["fork-after"]);
+    if (positional.length !== 1 || !SESSION_ID.test(id))
+        return usage();
+    if (after !== undefined && (!Number.isSafeInteger(after) || after < 0 || flags.fork !== "1"))
+        return usage();
+    const doc = (await (await admin("/v1/sessions", {
+        replay: {
+            of: id,
+            ...(flags.fork === "1" ? { fork: true } : {}),
+            ...(after === undefined ? {} : { fork_after: after }),
+        },
+        ...(flags.label ? { label: flags.label } : {}),
+        ...(flags.drill ? { drill: JSON.parse(readFileSync(flags.drill, "utf8")) } : {}),
+    })).json());
+    process.stdout.write(`${JSON.stringify(doc)}\n`);
+    return 0;
+}
+/** Audit S12: an exported bundle, analysed offline: it must verify first, then the summary, the
+ * findings it recorded, and the findings this SDK's analyses find in it now. */
+async function analyzeCommand(rest) {
+    const { flags, positional } = parse(rest, []);
+    if (positional.length !== 1)
+        return usage();
+    let bundle;
+    try {
+        bundle = JSON.parse(readFileSync(positional[0], "utf8"));
+    }
+    catch (error) {
+        process.stdout.write(`${JSON.stringify({ ok: false, error: String(error) })}\n`);
+        return 2;
+    }
+    // Loaded here, not at startup: the CLI also runs as a hook on every tool call.
+    const { analyze } = await import("./analysis/index.js");
+    const { loadPrices } = await import("./cost/index.js");
+    const { aggregateFindings, sessionSummary } = await import("./fleet/index.js");
+    // Audit K3: the bodies it reads are checked against the chain, with the rest of the record.
+    const bodies = bodiesIn(flags.bodies);
+    const report = await verifyBundle(bundle, { body: bodies });
+    if (!report.ok) {
+        process.stdout.write(`${JSON.stringify({ ok: false, error: "the bundle doesn't verify" })}\n`);
+        return 2;
+    }
+    // Without a price table, every call is reported as unpriced, never guessed (spec/cost.md §1).
+    const prices = loadPrices(flags.prices
+        ? readFileSync(flags.prices)
+        : Buffer.from('{"currency":"USD","unit":"micro_usd_per_mtok","models":{}}'));
+    const lines = bundle.lines;
+    const open = JSON.parse(lines[0]).meta;
+    const budget = typeof open.budget_micro_usd === "number" ? open.budget_micro_usd : undefined;
+    const counts = new Map();
+    for (const f of analyze(lines, {
+        bodies,
+        prices,
+        now: Number.POSITIVE_INFINITY,
+        ...(budget ? { budgetMicroUsd: budget } : {}),
+    }))
+        counts.set(f.code, (counts.get(f.code) ?? 0) + 1);
+    const recomputed = [...counts.entries()]
+        .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+        .map(([code, count]) => ({ code, count }));
+    process.stdout.write(`${JSON.stringify({
+        ok: true,
+        events: lines.length,
+        summary: sessionSummary(lines, bodies, prices),
+        findings: { recorded: aggregateFindings(lines), recomputed },
+    })}\n`);
+    return 0;
+}
+/** spec/preflight.md §2: the checklist; exit 0 for a go, 1 for a no-go. */
+async function preflightCommand(rest) {
+    const { flags, positional } = parse(rest, []);
+    if (positional.length || (!flags.require && !flags.optional))
+        return usage();
+    const q = new URLSearchParams();
+    if (flags.require)
+        q.set("require", flags.require);
+    if (flags.optional)
+        q.set("optional", flags.optional);
+    const doc = await adminJson(`/v1/preflight?${q}`);
+    process.stdout.write(`${JSON.stringify(doc)}\n`);
+    return doc.go === true ? 0 : 1;
+}
+/** Audit S14: checks a signed airworthiness certificate offline (spec/fleet.md §5). */
+async function certificateCommand(rest) {
+    const { flags, positional } = parse(rest, []);
+    if (positional.length !== 1)
+        return usage();
+    let cert;
+    try {
+        cert = JSON.parse(readFileSync(positional[0], "utf8"));
+    }
+    catch (error) {
+        process.stdout.write(`${JSON.stringify({ ok: false, by: null, reason: String(error) })}\n`);
+        return 2;
+    }
+    const { verifyCertificate } = await import("./fleet/index.js");
+    const result = verifyCertificate(cert, flags.did);
+    process.stdout.write(`${JSON.stringify(result)}\n`);
+    return result.ok ? 0 : 1;
+}
+/** spec/investigations.md §2: an independent investigator's signed report, offline. */
+async function investigateCommand(rest) {
+    const { flags, positional } = parse(rest, ["--proofs"]);
+    if (positional.length !== 1)
+        return usage();
+    const fail = (error) => {
+        process.stdout.write(`${JSON.stringify({ ok: false, error: String(error) })}\n`);
+        return 2;
+    };
+    const { investigation, renderInvestigation } = await import("./investigate/index.js");
+    const { loadPrices, sessionCost } = await import("./cost/index.js");
+    const { didFromSeed, sessionSummary, signCertificate } = await import("./fleet/index.js");
+    let raw;
+    let bundle;
+    let directives;
+    let identity;
+    try {
+        raw = readFileSync(positional[0]);
+        bundle = JSON.parse(raw.toString("utf8"));
+        if (!Array.isArray(bundle.lines) || bundle.lines.length === 0)
+            throw new Error("the bundle has no lines");
+        if (flags.directives) {
+            const d = JSON.parse(readFileSync(flags.directives, "utf8"));
+            const list = Array.isArray(d) ? d : d?.directives;
+            if (!Array.isArray(list) ||
+                !list.every((x) => typeof x?.signature === "string" &&
+                    typeof x?.applies_to === "object" &&
+                    x.applies_to !== null))
+                throw new Error("--directives must hold a list of directives");
+            directives = list;
+        }
+        if (flags.identity) {
+            const file = JSON.parse(readFileSync(flags.identity, "utf8"));
+            if (typeof file.private_key !== "string" || !/^[0-9a-f]{64}$/.test(file.private_key))
+                throw new Error("identity file: private_key must be 64 hex characters");
+            const seed = Buffer.from(file.private_key, "hex");
+            if (file.did !== didFromSeed(seed))
+                throw new Error("identity file: did doesn't match private_key");
+            identity = { did: file.did, seed };
+        }
+    }
+    catch (error) {
+        return fail(error instanceof Error ? error.message : error);
+    }
+    // Audit K3: the bodies it reads are checked against the chain (a changed file fails it).
+    const bodies = bodiesIn(flags.bodies);
+    const check = await verifyBundle(bundle, { proofs: flags.proofs === "1", body: bodies });
+    const lines = bundle.lines;
+    // no price table: the report prices nothing (spec/cost.md §1)
+    const prices = loadPrices(Buffer.from('{"version":"none","currency":"USD","unit":"micro_usd_per_mtok","models":{}}'));
+    const models = new Set();
+    for (const c of sessionCost(lines, prices).calls)
+        if (c.model)
+            models.add(c.model);
+    const summary = sessionSummary(lines, bodies, prices);
+    const report = {
+        ...investigation(lines, {
+            summary,
+            models: [...models].sort(),
+            ...(directives ? { directives: directives } : {}),
+        }),
+        verification: {
+            ok: check.ok,
+            identity: check.identity.ok,
+            proofs: flags.proofs === "1" ? "checked" : "not_checked",
+        },
+        investigated_at: new Date().toISOString(),
+        bundle_sha256: createHash("sha256").update(raw).digest("hex"),
+    };
+    const final = identity ? signCertificate(report, identity.did, identity.seed) : report;
+    const prefix = flags.out || `investigation-${summary.session_id}`;
+    try {
+        writeFileSync(`${prefix}.json`, `${JSON.stringify(final)}\n`);
+        writeFileSync(`${prefix}.md`, renderInvestigation(final));
+    }
+    catch (error) {
+        return fail(error instanceof Error ? error.message : error);
+    }
+    process.stdout.write(`${JSON.stringify({
+        ok: check.ok,
+        json: `${prefix}.json`,
+        md: `${prefix}.md`,
+        signed_by: identity?.did ?? null,
+    })}\n`);
+    return check.ok ? 0 : 1;
+}
+/** spec/money.md §2a: the provider's statement for a period, from its cost API. */
+async function statementCommand(rest) {
+    const { flags, positional } = parse(rest, []);
+    const { provider, from, to } = flags;
+    const date = /^\d{4}-\d{2}-\d{2}$/;
+    if (positional.length ||
+        !["anthropic", "openai", "csv", "custom"].includes(provider ?? "") ||
+        !date.test(from ?? "") ||
+        !date.test(to ?? "") ||
+        !(from < to))
+        return usage();
+    const fail = (error) => {
+        process.stdout.write(`${JSON.stringify({ ok: false, error })}\n`);
+        return 2;
+    };
+    const emit = (doc) => {
+        if (flags.out) {
+            writeFileSync(flags.out, `${JSON.stringify(doc)}\n`);
+            process.stdout.write(`${JSON.stringify({ ok: true, out: flags.out, lines: doc.lines.length })}\n`);
+        }
+        else
+            process.stdout.write(`${JSON.stringify(doc)}\n`);
+        return 0;
+    };
+    if (provider === "csv" || provider === "custom") {
+        const got = await statementAny(provider, flags, from, to);
+        if (typeof got === "number")
+            return got;
+        return "error" in got ? fail(got.error) : emit(got.doc);
+    }
+    const env = provider === "anthropic" ? "ANTHROPIC_ADMIN_KEY" : "OPENAI_ADMIN_KEY";
+    const key = process.env[env];
+    if (!key)
+        return fail(`${env} must be set`);
+    const { anthropicStatement, openaiStatement } = await import("./money/index.js");
+    const pages = [];
+    let page = null;
+    try {
+        for (let n = 0; n < 100; n++) {
+            let url;
+            let headers;
+            if (provider === "anthropic") {
+                url = new URL("/v1/organizations/cost_report", process.env.BLACKBOX_ANTHROPIC_API_URL || "https://api.anthropic.com");
+                url.searchParams.set("starting_at", `${from}T00:00:00Z`);
+                url.searchParams.set("ending_at", `${to}T00:00:00Z`);
+                url.searchParams.set("bucket_width", "1d");
+                url.searchParams.append("group_by[]", "description");
+                headers = { "x-api-key": key, "anthropic-version": "2023-06-01" };
+            }
+            else {
+                url = new URL("/v1/organization/costs", process.env.BLACKBOX_OPENAI_API_URL || "https://api.openai.com");
+                url.searchParams.set("start_time", String(Date.parse(`${from}T00:00:00Z`) / 1000));
+                url.searchParams.set("end_time", String(Date.parse(`${to}T00:00:00Z`) / 1000));
+                url.searchParams.set("bucket_width", "1d");
+                url.searchParams.set("group_by", "line_item");
+                headers = { authorization: `Bearer ${key}` };
+            }
+            url.searchParams.set("limit", "31");
+            if (page)
+                url.searchParams.set("page", page);
+            const res = await fetch(url, {
+                headers: { ...headers, "user-agent": `zanii-blackbox/${VERSION}` },
+                signal: AbortSignal.timeout(30_000),
+            });
+            const text = await res.text();
+            if (!res.ok)
+                return fail(`${provider} ${url.pathname}: HTTP ${res.status} ${text.slice(0, 200)}`);
+            const body = JSON.parse(text);
+            pages.push(body);
+            if (body.has_more !== true || typeof body.next_page !== "string") {
+                page = null;
+                break;
+            }
+            page = body.next_page;
+        }
+        if (page)
+            return fail("more than 100 pages; ask for a shorter period");
+        const statement = provider === "anthropic" ? anthropicStatement(pages) : openaiStatement(pages);
+        return emit({ provider, from, to, lines: statement.lines });
+    }
+    catch (error) {
+        return fail(error instanceof Error ? error.message : String(error));
+    }
+}
+/** spec/money.md §2b: a statement from a CSV export or a declarative connector. */
+async function statementAny(provider, flags, from, to) {
+    const money = await import("./money/index.js");
+    const message = (e) => ({ error: e instanceof Error ? e.message : String(e) });
+    if (provider === "csv") {
+        const model = flags["model-column"];
+        const amount = flags["amount-column"];
+        const unit = flags.unit;
+        const delimiter = flags.delimiter;
+        if (!flags.file ||
+            !model ||
+            !amount ||
+            !unit ||
+            (delimiter !== undefined && delimiter.length !== 1))
+            return usage();
+        try {
+            const text = readFileSync(flags.file, "utf8");
+            const statement = money.csvStatement(text, {
+                model_column: model,
+                amount_column: amount,
+                unit,
+                ...(delimiter ? { delimiter } : {}),
+            });
+            return { doc: { provider: "csv", from, to, lines: statement.lines } };
+        }
+        catch (e) {
+            return message(e);
+        }
+    }
+    if (!flags.connector)
+        return usage();
+    let connector;
+    try {
+        connector = JSON.parse(readFileSync(flags.connector, "utf8"));
+    }
+    catch (e) {
+        return message(e);
+    }
+    const bad = money.checkConnector(connector);
+    if (bad)
+        return { error: `connector: ${bad}` };
+    const headers = {};
+    for (const [k, v] of Object.entries(connector.request.headers ?? {})) {
+        let missing = null;
+        headers[k] = v.replace(/\{env:([A-Za-z_][A-Za-z0-9_]*)\}/g, (_, name) => {
+            const value = process.env[name];
+            if (!value)
+                missing = name;
+            return value ?? "";
+        });
+        if (missing)
+            return { error: `${missing} must be set` };
+    }
+    try {
+        const pages = [];
+        for (;;) {
+            const r = money.requestFor(connector, pages, from, to);
+            if (r === null)
+                break;
+            if (pages.length >= 100)
+                return { error: "more than 100 pages; ask for a shorter period" };
+            const url = new URL(r.url);
+            for (const [k, v] of r.query)
+                url.searchParams.set(k, v);
+            const res = await fetch(url, {
+                method: r.method,
+                headers: {
+                    ...headers,
+                    ...(r.content_type ? { "content-type": r.content_type } : {}),
+                    "user-agent": `zanii-blackbox/${VERSION}`,
+                },
+                ...(r.body !== undefined ? { body: r.body } : {}),
+                signal: AbortSignal.timeout(30_000),
+            });
+            const text = await res.text();
+            if (!res.ok)
+                return { error: `${connector.name}: HTTP ${res.status} ${text.slice(0, 200)}` };
+            pages.push(connector.format === "xml" ? money.parseXml(text) : JSON.parse(text));
+        }
+        const statement = money.customStatement(pages, connector);
+        return { doc: { provider: `custom:${connector.name}`, from, to, lines: statement.lines } };
+    }
+    catch (e) {
+        return message(e);
+    }
+}
+function table(head, rows, indent = "") {
+    const widths = head.map((h, i) => Math.max(h.length, ...rows.map((r) => (r[i] ?? "").length)));
+    for (const r of [head, ...rows])
+        process.stdout.write(`${indent}${r
+            .map((c, i) => c.padEnd(widths[i]))
+            .join("  ")
+            .trimEnd()}\n`);
+}
+// ---------------------------------------------------------------- operator commands (audit K21, K20, K13, K5)
+/** V16: every session created in [from, to) as NDJSON bundles, page by page, into one file. */
+async function exportAllCommand(rest) {
+    const { flags, positional } = parse(rest, []);
+    if (positional.length || !flags.from || !flags.to || !flags.out)
+        return usage();
+    writeFileSync(flags.out, "");
+    let sessions = 0;
+    let before = "";
+    for (;;) {
+        const q = new URLSearchParams({ from: flags.from, to: flags.to });
+        if (before)
+            q.set("before", before);
+        const lines = (await (await admin(`/v1/export?${q}`)).text()).split("\n").filter(Boolean);
+        const last = lines.at(-1) ? JSON.parse(lines.at(-1)) : undefined;
+        const more = last?.more === true;
+        const page = more ? lines.slice(0, -1) : lines;
+        if (page.length)
+            appendFileSync(flags.out, `${page.join("\n")}\n`);
+        sessions += page.length;
+        if (!more)
+            break;
+        before = String(last?.before);
+    }
+    process.stdout.write(`${JSON.stringify({ ok: true, sessions })}\n`);
+    return 0;
+}
+async function occurrencePackCommand(rest) {
+    const { flags, positional } = parse(rest, []);
+    const id = positional[0] ?? "";
+    if (positional.length !== 1 || !SESSION_ID.test(id) || !flags.framework)
+        return usage();
+    return printJson(`/v1/sessions/${id}/occurrence/pack?${new URLSearchParams({ framework: flags.framework })}`);
+}
+async function fileCommand(rest) {
+    const { flags, positional } = parse(rest, []);
+    const id = positional[0] ?? "";
+    if (positional.length !== 1 || !SESSION_ID.test(id) || !flags.framework || !flags.reference)
+        return usage();
+    const doc = await (await admin(`/v1/sessions/${id}/occurrence/filings`, {
+        framework: flags.framework,
+        reference: flags.reference,
+        ...(flags.channel ? { channel: flags.channel } : {}),
+        ...(flags["filed-at"] ? { filed_at: flags["filed-at"] } : {}),
+    })).json();
+    process.stdout.write(`${JSON.stringify(doc)}\n`);
+    return 0;
+}
+/** The control calls, each one POST (spec/control.md, spec/approvals.md, spec/api.md). */
+async function controlCommand(command, rest) {
+    const { flags, positional } = parse(rest, ["--force"]);
+    const id = positional[0] ?? "";
+    if (!SESSION_ID.test(id))
+        return usage();
+    const note = flags.note ? { note: flags.note } : {};
+    let path = `/v1/sessions/${id}/${command}`;
+    let body;
+    if (command === "close") {
+        const outcome = flags.outcome;
+        if (outcome !== undefined && !["success", "failure", "abandoned"].includes(outcome))
+            return usage();
+        body = { ...(outcome ? { outcome } : {}), ...note };
+    }
+    else if (command === "resume") {
+        body = {
+            ...(flags.token ? { token: flags.token } : {}),
+            ...(flags.force === "1" ? { force: true } : {}),
+            ...note,
+        };
+    }
+    else if (command === "decide") {
+        const [, approvalId, decision] = positional;
+        if (positional.length !== 3 || (decision !== "approve" && decision !== "reject"))
+            return usage();
+        path = `/v1/sessions/${id}/approvals/${encodeURIComponent(approvalId)}`;
+        body = { decision, ...note };
+    }
+    else
+        body = note;
+    if (command !== "decide" && positional.length !== 1)
+        return usage();
+    const doc = await (await admin(path, body)).json();
+    process.stdout.write(`${JSON.stringify(doc)}\n`);
+    return 0;
+}
+/** Audit K13: the session's events live, one stored line per line, until it closes. */
+async function tailCommand(rest) {
+    const { flags, positional } = parse(rest, []);
+    const id = positional[0] ?? "";
+    const after = flags["after-seq"];
+    if (positional.length !== 1 || !SESSION_ID.test(id))
+        return usage();
+    if (after !== undefined && !/^-?\d+$/.test(after))
+        return usage();
+    // No timeout: a live tail lasts as long as the session does (admin() would cut it at 30 s).
+    const url = process.env.BLACKBOX_URL;
+    const key = process.env.BLACKBOX_ADMIN_KEY;
+    if (!url || !key)
+        throw new ServerError("BLACKBOX_URL and BLACKBOX_ADMIN_KEY must be set");
+    const path = `/v1/sessions/${id}/stream${after !== undefined ? `?after_seq=${after}` : ""}`;
+    const res = await fetch(`${url.replace(/\/+$/, "")}${path}`, {
+        headers: { authorization: `Bearer ${key}` },
+    }).catch((error) => {
+        throw new ServerError(`can't reach ${url}: ${error instanceof Error ? error.message : error}`);
+    });
+    if (!res.ok)
+        throw new ServerError(`${path}: HTTP ${res.status} ${(await res.text()).slice(0, 200)}`);
+    const reader = res.body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = "";
+    for (;;) {
+        const { value, done } = await reader.read();
+        if (done)
+            return 0;
+        buffer += decoder.decode(value, { stream: true });
+        for (let end = buffer.indexOf("\n\n"); end !== -1; end = buffer.indexOf("\n\n")) {
+            const frame = buffer.slice(0, end);
+            buffer = buffer.slice(end + 2);
+            if (/^event: end$/m.test(frame))
+                return 0;
+            for (const l of frame.split("\n"))
+                if (l.startsWith("data: "))
+                    process.stdout.write(`${l.slice(6)}\n`);
+        }
+    }
+}
+/** Audit K5: ships what stopped agents left in the spool (BLACKBOX_URL; no key: the kept tokens). */
+async function drainCommand(rest) {
+    const { flags, positional } = parse(rest, []);
+    const url = process.env.BLACKBOX_URL;
+    if (positional.length || !url)
+        return usage();
+    const { drainSpools } = await import("./session/drain.js");
+    const results = await drainSpools({
+        url,
+        ...(flags["spool-dir"] ? { spoolDir: flags["spool-dir"] } : {}),
+    });
+    process.stdout.write(`${JSON.stringify({ ok: results.every((r) => r.shipped), sessions: results })}\n`);
+    return results.every((r) => r.shipped) ? 0 : 2;
+}
+/** spec/data.md §10: the session's record against a touched system's own audit-log export, run
+ *  here so the export never leaves this machine. Exits 1 on any finding. */
+async function reconcileSystemCommand(rest) {
+    const { flags, positional } = parse(rest, []);
+    const id = positional[0] ?? "";
+    if (positional.length !== 1 || !SESSION_ID.test(id) || !flags.connector || !flags.log)
+        return usage();
+    const { checkAuditConnector, parseAuditLog, reconcileSystem, CORE_EVIDENCE } = await import("./data/index.js");
+    const { packData } = await import("./packs/index.js");
+    const connector = JSON.parse(readFileSync(flags.connector, "utf8"));
+    const bad = checkAuditConnector(connector);
+    if (bad)
+        throw new ServerError(`--connector: ${bad}`);
+    const evidence = flags.pack
+        ? packData([JSON.parse(readFileSync(flags.pack, "utf8"))]).evidence
+        : CORE_EVIDENCE;
+    const c = connector;
+    const rows = parseAuditLog(readFileSync(flags.log, "utf8"), c);
+    const bundle = (await adminJson(`/v1/sessions/${id}/bundle`));
+    // Only the bodies the comparison reads: tool calls and results, and SDK events.
+    const bodies = new Map();
+    for (const line of bundle.lines) {
+        const e = JSON.parse(line);
+        if (!["tool.call", "tool.result", "sdk.event"].includes(e.kind) || bodies.has(e.body_hash))
+            continue;
+        if (!/^sha256:[0-9a-f]{64}$/.test(e.body_hash))
+            continue;
+        const res = await admin(`/v1/bodies/${e.body_hash}`, undefined, [404, 410]);
+        if (res.status === 200)
+            bodies.set(e.body_hash, Buffer.from(await res.arrayBuffer()));
+    }
+    const report = reconcileSystem(bundle.lines, (h) => bodies.get(h), rows, c, evidence);
+    process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+    return report.findings.length > 0 ? 1 : 0;
+}
+function usage() {
+    process.stderr.write(`${USAGE}\n`);
+    return 2;
+}
+main(process.argv.slice(2)).then((code) => {
+    process.exitCode = code;
+}, (error) => {
+    process.stderr.write(`blackbox: ${error instanceof Error ? error.message : String(error)}\n`);
+    process.exitCode = 2;
+});