@fanzhen/agent-audit 0.3.0

package/README.md

@@ -0,0 +1,142 @@
+# agentaudit
+
+**npm audit for your AI coding agents.**
+
+One command scans your local Claude Code session history and reports every
+dangerous action your agents ever took — destructive commands, credential
+access, data exfiltration, persistence installs, unsafe downloads.
+
+```bash
+npx @fanzhen/agent-audit # audit ~/.claude/projects immediately
+agent-audit --demo      # no Claude Code? try the built-in demo
+```
+
+```
+───────────────────── agentaudit ─────────────────────
+files 42 · sessions 87 · events 12,340 · findings 23
+ 4 CRITICAL   9 HIGH   6 MEDIUM   4 LOW
+──────────────────────────────────────────────────────
+```
+
+## What it detects (28 rules)
+
+| Category | Examples |
+|---|---|
+| 🟥 Destructive | `rm -rf`, `git reset --hard`, force push, disk erase |
+| 🔑 Credential access | reading `.env`, `id_rsa`, `~/.aws`, keychain queries |
+| 📤 Exfiltration | `cat .env \| curl`, uploads to paste sites/webhooks |
+| 🚪 Bypass & persistence | loosened `settings.json`, `.bashrc` edits, cron, `authorized_keys` |
+| ⚠️ Unsafe execution | `curl \| sh`, base64 payloads, cloud metadata endpoints, reverse shells |
+
+`agentaudit --list-rules` shows all of them with severities.
+
+## Why
+
+Agents run shell commands all day. In April 2026, Claude Code's deny rules
+were shown to be silently bypassable and multiple command-injection flaws
+were disclosed. Nobody reviews what their agent already did — until now.
+
+## Install & usage
+
+Requires Node 18+.
+
+```bash
+npx @fanzhen/agent-audit   # run without installing, or: npm i -g @fanzhen/agent-audit
+agent-audit                # audit default location
+agent-audit ~/somewhere    # audit a custom projects dir / .jsonl file
+agent-audit --json         # machine-readable output
+agent-audit --severity high --rules E,C
+agent-audit --session <id> # one session only
+agent-audit --share        # print a shareable summary card
+agent-audit --watch        # LIVE egress monitor (Windows; see below)
+agent-audit --footprint    # what Qoder indexed locally (see below)
+```
+
+Python 3.10+ alternative: `uvx agent-audit` (no install) or
+`pipx install agent-audit` (command name: `agentaudit`).
+
+- 100% local parsing. No network calls, no telemetry, ever.
+- Works on Windows, macOS and Linux.
+
+## Watch mode (v0.2.x, Windows only)
+
+Besides auditing history, agent-audit can also watch what your AI coding
+tools are connecting to RIGHT NOW: it polls the TCP table (each poll spawns a PowerShell query — effective cadence is a few seconds) for the
+watched processes' established connections, labels each target against a
+built-in registry of known-agent domains (`model-api` / `telemetry` /
+`update` / `captcha` / `community`), and alerts on anything outside it.
+
+```bash
+agent-audit --watch                          # watch all known AI tools, 60s
+agent-audit --watch --proc ZCode,QoderCN     # specific processes (no .exe)
+agent-audit --watch --seconds 300 --csv out.csv   # record to CSV
+```
+
+```
+[10:13:37] claude(11852) → 160.79.104.10:443 api.anthropic.com (model-api)
+[!] [10:13:37] claude(11852) → 47.96.134.91:443 (unknown — no DNS mapping observed)
+──── agent-audit watch ────
+watched 14s · procs 3 · polls 5 · new connections 3 · dns entries 11
+by category: model-api 1 · unknown 2
+[!] unknown targets: 47.96.134.91:443 (claude)
+```
+
+Hostnames come from the Windows DNS cache sampled during the watch — an IP
+that never resolves there is reported as unknown, never guessed. Ctrl+C stops
+early and still prints the summary. On non-Windows platforms `--watch` exits
+with code 2 (`watch: Windows-only in v0.2.x`).
+
+Exit codes: `0` on success (findings do NOT change the exit code yet — a
+`--fail-on` flag is planned), `2` on bad options or missing data dir.
+
+## Footprint mode (v0.2.x): what has Qoder collected?
+
+`--footprint` answers a different question than the audit: not "what did an
+agent DO" but "what does a tool hold FROM you". For Qoder CN it inventories
+the local index stores under `~/.qoder-cn/shared_client/`: per repo it reads
+the vector index's chunk table (absolute file paths — metadata
+only), counts completion-index `.zap` segments (which hold recoverable source
+text — reported as files + bytes, never opened), git/graph index sizes,
+project-memory file names, and workspace memory notes.
+
+```bash
+agent-audit --footprint                  # inventory ~/.qoder-cn
+agent-audit --footprint --json           # machine-readable (includes the file list)
+agent-audit --footprint --agent qoder    # explicit (only qoder in v0.2.x)
+```
+
+Privacy: the report LISTS what was collected (repos, file paths, chunk
+counts, index timestamps) — it never reads or prints file CONTENT. Exits 2
+for any other `--agent`.
+
+## Non-goals (v0.2.x, stated plainly)
+
+- **A tool's own background network traffic at content level**: TLS-encrypted
+  on the wire; `--watch` reports WHO it talks to, not WHAT it sends. For
+  content-level proof use the canary method (unique marker strings planted in
+  a throwaway repo, then searched in the tool's local stores and captured
+  traffic).
+- **Trae chat history**: stored locally in an encrypted database — not
+  auditable until the format opens up.
+- **Qoder chat history**: lives server-side; only the local data footprint
+  (see `--footprint`) is visible.
+
+## Implementation note
+
+v0.2 rewrote agent-audit in TypeScript as the canonical implementation
+(`npm/`) — output-equivalent to the Python original on the v0.1 surface,
+verified by an automated equivalence harness on the demo, boundary corpora,
+and real session data (v0.2.x adds TS-only summary fields such as `by_agent`,
+which the harness normalizes out of the parity comparison). The Python
+implementation (`src/agentaudit`) is frozen at v0.1.1 as the porting
+reference and spec.
+
+## Roadmap
+
+- v0.2: done — TypeScript/npm canonical port (byte-for-byte equivalent to the Python original)
+- v0.2.x: Codex CLI parser (done in 0.3.0) · Gemini CLI (pending one verification session) · SARIF export
+- v0.3: guard mode — block dangerous actions before they run (PreToolUse hooks)
+
+## License
+
+MIT

package/dist/agents.js

@@ -0,0 +1,197 @@
+// Agent registry: per-agent session discovery + parser (v0.2.x multi-agent
+// plan, M1). TS canonical — the Python side is frozen at v0.1.1.
+//
+// Error policy (binding plan decision):
+//   - claude-code.find() THROWS DataDirNotFoundError when its root is missing
+//     (back-compat with the v0.1 CLI error path and its tests);
+//   - kimi.find() silently returns [] — an optional install must never fail
+//     an audit. The CLI demotes a missing DEFAULT root to a stderr hint when
+//     several agents are selected, and keeps failing loudly for an explicit
+//     path the user pointed at.
+//   - zcode.find() follows the kimi policy (missing store -> []) plus a
+//     node:sqlite runtime gate: without the builtin it returns [] with a
+//     single stderr hint (parsers/zcode.ts rejects loudly if called anyway).
+import { existsSync, readdirSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { comparePaths, findSessionFiles } from "./discovery.js";
+import { iterEvents as iterClaudeEvents, } from "./parsers/claude-code.js";
+import { iterEvents as iterCodexEvents } from "./parsers/codex.js";
+import { iterEvents as iterKimiEvents } from "./parsers/kimi.js";
+import { iterEvents as iterZcodeEvents, loadNodeSqlite } from "./parsers/zcode.js";
+// Kimi-Code session store (real-data verified 2026-09-20):
+//   ~/.kimi-code/sessions/wd_<dirname>_<hash>/session_<uuid>/agents/main/wire.jsonl
+export function defaultKimiSessionsDir() {
+    // Python parity with discovery.default_claude_projects_dir: Path.home()/...
+    return join(homedir(), ".kimi-code", "sessions");
+}
+function listDirDirs(dir) {
+    try {
+        return readdirSync(dir, { withFileTypes: true })
+            .filter((e) => e.isDirectory() && !e.isSymbolicLink())
+            .map((e) => e.name);
+    }
+    catch {
+        // racy removal / permission error: treat as absent (kimi discovery is
+        // best-effort by policy)
+        return [];
+    }
+}
+// Exact-shape walk (NOT rglob): only wd_*/session_*/agents/main/wire.jsonl
+// counts. Subagent transcripts (agents/<other>/) are out of scope for v0.2.x.
+// Missing root -> empty list (silent skip), NOT an error.
+function findKimiSessionFiles(root) {
+    const base = root || defaultKimiSessionsDir();
+    if (!existsSync(base)) {
+        return [];
+    }
+    const out = [];
+    for (const wd of listDirDirs(base)) {
+        if (!wd.startsWith("wd_")) {
+            continue;
+        }
+        const wdPath = join(base, wd);
+        for (const sess of listDirDirs(wdPath)) {
+            if (!sess.startsWith("session_")) {
+                continue;
+            }
+            const wire = join(wdPath, sess, "agents", "main", "wire.jsonl");
+            if (existsSync(wire)) {
+                out.push(wire);
+            }
+        }
+    }
+    return out.sort(comparePaths);
+}
+// Codex CLI session store (format ground truth:
+// docs/superpowers/research/2026-09-20-codex-format.md):
+//   ~/.codex/sessions/<YYYY>/<MM>/<DD>/rollout-<compact-ts>-<thread-uuid>.jsonl
+//   + fork names rollout-<ts>-<thread-uuid>_<rollout-id>.jsonl
+// Newer builds may compress cold rollouts to .jsonl.zst; v0.2.x does not
+// decompress zstd, so discovery EXCLUDES them (the parser would only see
+// binary garbage — better than counting unparseable files).
+export function defaultCodexSessionsDir() {
+    // Python parity with discovery.default_claude_projects_dir: Path.home()/...
+    return join(homedir(), ".codex", "sessions");
+}
+// rglob("*.jsonl") over the sessions tree — same case-sensitive suffix rule
+// and no-symlink-follow as discovery.walk (the YYYY/MM/DD nesting makes an
+// exact-shape walk pointless; rollout files only live under sessions/).
+// Missing root -> empty list (silent skip), NOT an error (optional agent).
+function findCodexSessionFiles(root) {
+    const base = root || defaultCodexSessionsDir();
+    if (!existsSync(base)) {
+        return [];
+    }
+    const out = [];
+    const walk = (dir) => {
+        let entries;
+        try {
+            entries = readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            // racy removal / permission error: best-effort, like kimi discovery
+            return;
+        }
+        for (const entry of entries) {
+            const full = join(dir, entry.name);
+            if (entry.isDirectory()) {
+                if (!entry.isSymbolicLink()) {
+                    walk(full);
+                }
+            }
+            else if (entry.isFile() && entry.name.endsWith(".jsonl")) {
+                out.push(full); // .jsonl.zst does NOT end in .jsonl — excluded here
+            }
+        }
+    };
+    walk(base);
+    return out.sort(comparePaths);
+}
+// ZCode (Z.ai desktop IDE) session store — ONE sqlite db file, not a tree:
+//   ~/.zcode/cli/db/db.sqlite (+ live -wal/-shm siblings; the parser copies
+//   them before reading, see parsers/zcode.ts). Explicit roots: the db file
+//   itself, or a directory containing db.sqlite.
+export function defaultZcodeDbPath() {
+    // Python parity with discovery.default_claude_projects_dir: Path.home()/...
+    return join(homedir(), ".zcode", "cli", "db", "db.sqlite");
+}
+// node:sqlite availability hint must print at most once per process even if
+// find() runs several times (--list-agents, multi-agent discovery).
+let zcodeGateHinted = false;
+function findZcodeSessionFiles(root) {
+    let target;
+    if (root) {
+        let isFile = false;
+        try {
+            isFile = statSync(root).isFile();
+        }
+        catch {
+            // not stat-able -> treat as a directory and look for db.sqlite inside
+        }
+        target = isFile ? root : join(root, "db.sqlite");
+    }
+    else {
+        target = defaultZcodeDbPath();
+    }
+    if (!existsSync(target)) {
+        return []; // optional agent: silent skip, NOT an error
+    }
+    // Runtime gate: the store is sqlite, so without the node:sqlite builtin
+    // (Node >= 22.5) there is no way to read it. Skip for `all` runs with a
+    // single stderr hint (stderr keeps --json stdout pure); an explicitly
+    // pointed-at path still yields [] here — the parser itself rejects loudly
+    // when called directly without the builtin.
+    if (loadNodeSqlite() === null) {
+        if (!zcodeGateHinted) {
+            zcodeGateHinted = true;
+            process.stderr.write("zcode: node:sqlite unavailable on this Node runtime (>= 22.5 required); skipping the ZCode store\n");
+        }
+        return [];
+    }
+    return [target];
+}
+export const AGENTS = {
+    "claude-code": {
+        id: "claude-code",
+        displayName: "Claude Code",
+        find: (root) => findSessionFiles(root),
+        parser: { iterEvents: (path, stats) => iterClaudeEvents(path, stats) },
+    },
+    kimi: {
+        id: "kimi",
+        displayName: "Kimi Code",
+        find: (root) => findKimiSessionFiles(root),
+        parser: { iterEvents: (path, stats) => iterKimiEvents(path, stats) },
+    },
+    codex: {
+        id: "codex",
+        displayName: "Codex CLI",
+        find: (root) => findCodexSessionFiles(root),
+        parser: { iterEvents: (path, stats) => iterCodexEvents(path, stats) },
+    },
+    zcode: {
+        id: "zcode",
+        displayName: "ZCode",
+        find: (root) => findZcodeSessionFiles(root),
+        parser: { iterEvents: (path, stats) => iterZcodeEvents(path, stats) },
+    },
+};
+// Discovery over the selected agents' DEFAULT roots (explicit per-agent roots
+// are a CLI concern). Entries are sorted with the same pathlib-style compare
+// as discovery so multi-agent runs are deterministic. Per-descriptor error
+// policy applies: a missing kimi root contributes nothing, a missing claude
+// root throws.
+export function findAgentFiles(ids) {
+    const entries = [];
+    for (const id of ids) {
+        const agent = AGENTS[id];
+        if (!agent) {
+            throw new Error(`unknown agent id: ${id} (known: ${Object.keys(AGENTS).join(", ")})`);
+        }
+        for (const path of agent.find()) {
+            entries.push({ agent: id, path });
+        }
+    }
+    return entries.sort((a, b) => comparePaths(a.path, b.path));
+}

package/dist/cli.js

@@ -0,0 +1,330 @@
+#!/usr/bin/env node
+// agentaudit CLI entry point. Faithful port of src/agentaudit/cli.py
+// (typer -> commander; Python implementation is the spec).
+//
+// MUST keep `import "./tty-gate.js"` as the first import: ESM evaluates
+// imports in declaration order, and picocolors (via report.js) decides color
+// support ONCE at import time — the gate needs to set NO_COLOR before that
+// for piped (non-TTY) runs (ledger M).
+import "./tty-gate.js";
+import { mkdtempSync, rmSync, statSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+import { Command, CommanderError } from "commander";
+import Table from "cli-table3";
+import { AGENTS } from "./agents.js";
+import { writeDemoSession } from "./demo.js";
+import { DataDirNotFoundError, comparePaths } from "./discovery.js";
+import { runAudit } from "./engine.js";
+import { SEVERITY_ORDER } from "./events.js";
+import { qoderFootprint, renderFootprint } from "./footprint.js";
+import { SEV_LABEL, renderTerminal, shareCard, toDict } from "./report.js";
+import { CATEGORY_TITLES, allRules } from "./rules/index.js";
+import { defaultWatchDeps } from "./watch-poller.js";
+import { DEFAULT_WATCH_PROCS, WATCH_DEFAULT_SECONDS, WatchUnsupportedError, parseWatchProcs, renderWatchSummary, runWatch, } from "./watch.js";
+// Keep in sync with npm/package.json "version" (importing package.json would
+// need JSON import attributes, which Node 18 does not support).
+export const VERSION = "0.3.0";
+const description = "npm audit for your AI coding agents - audit dangerous actions in agent history.";
+export async function main(argv, io = {}) {
+    const stdout = io.stdout ?? ((chunk) => process.stdout.write(chunk));
+    const stderr = io.stderr ?? ((chunk) => process.stderr.write(chunk));
+    let exitCode;
+    const program = new Command();
+    program
+        .name("agent-audit")
+        .description(description)
+        // main() never calls process.exit; commander's exit paths (help, usage
+        // errors) are surfaced as CommanderError instead
+        .exitOverride()
+        .configureOutput({ writeOut: stdout, writeErr: stderr })
+        .argument("[path]", "Claude Code projects dir (default ~/.claude/projects) or a .jsonl file")
+        .option("--json", "JSON output for scripts/CI")
+        .option("--severity <level>", "Minimum severity to show: critical|high|medium|low|info", "low")
+        .option("--session <id>", "Audit one session id")
+        .option("--rules <prefixes>", "Rule category prefixes, comma separated (D,C,E,B,U)")
+        .option("--list-rules", "List all rules and exit")
+        .option("--agent <ids>", "Agents to audit, comma separated: claude-code|kimi|codex|zcode|all (--footprint: qoder only)", "all")
+        .option("--list-agents", "List known agents and exit")
+        .option("--share", "Print a shareable summary card")
+        .option("--demo", "Run on built-in demo data")
+        // M5 watch mode: live per-process TCP egress monitoring (Windows only
+        // in v0.2.x; watch is a MODE on the single-command CLI, not a
+        // subcommand). Audit flags are ignored in watch mode and vice versa.
+        .option("--watch", "Watch AI-tool processes' live TCP egress (Windows only)")
+        .option("--proc <names>", "Watch: process names, comma separated (.exe stripped); default: all known AI tools")
+        .option("--seconds <n>", "Watch: how long to poll, seconds", String(WATCH_DEFAULT_SECONDS))
+        .option("--csv <path>", "Watch: append one CSV row per new connection")
+        // M6 footprint mode: local-data inventory report (Qoder CN only in
+        // v0.2.x). Like --watch, a MODE on the single-command CLI: audit flags
+        // do not apply. The positional [path] overrides the Qoder data root.
+        .option("--footprint", "Inventory what a tool collected locally (Qoder index stores)")
+        .option("--version", "Show version")
+        .action(async (pathArg, opts) => {
+        exitCode = await auditCommand(pathArg, opts, stdout, stderr, io.watchDeps);
+    });
+    try {
+        // argv is user-typed args only (bin wrapper slices process.argv)
+        await program.parseAsync(argv, { from: "user" });
+    }
+    catch (err) {
+        if (err instanceof CommanderError) {
+            // help/version paths exit 0; click/typer (the spec) uses exit code 2
+            // for every usage error (unknown option, bad value), commander uses 1
+            return err.exitCode === 0 ? 0 : 2;
+        }
+        throw err;
+    }
+    return exitCode ?? 0;
+}
+// Python: audit(...) — the single typer command body
+async function auditCommand(pathArg, opts, stdout, stderr, watchInject) {
+    if (opts.version) {
+        stdout(`agent-audit ${VERSION}\n`);
+        return 0;
+    }
+    // M5: watch is a mode on this command; audit flags below do not apply.
+    if (opts.watch) {
+        return watchCommand(opts, stdout, stderr, watchInject);
+    }
+    // M6: footprint is a mode too (checked before the watch-flag hint below so
+    // `--footprint` never falls through into an audit).
+    if (opts.footprint) {
+        return footprintCommand(opts, pathArg, stdout, stderr);
+    }
+    if (opts.proc !== undefined || opts.csv !== undefined) {
+        // common typo guard: --proc/--csv silently doing nothing would confuse
+        stderr("note: --proc/--seconds/--csv apply to --watch mode; ignored\n");
+    }
+    if (opts.listRules) {
+        // Python: rich Table(title=f"agentaudit rules ({len(all_rules())})")
+        const rules = allRules();
+        stdout(`agentaudit rules (${rules.length})\n`);
+        const table = new Table({
+            head: ["ID", "SEVERITY", "CATEGORY", "TITLE"],
+            style: { head: [], border: [] },
+        });
+        for (const rule of rules) {
+            table.push([
+                rule.id,
+                SEV_LABEL[rule.severity],
+                CATEGORY_TITLES.get(rule.id[0]) ?? "",
+                rule.title,
+            ]);
+        }
+        stdout(`${table.toString()}\n`);
+        return 0;
+    }
+    if (opts.listAgents) {
+        // v0.2.x (TS-only flag, no Python parity): informational listing of the
+        // agent registry with per-agent default-root file counts. A missing data
+        // root just shows 0 — this is a listing, not an audit.
+        const agents = Object.values(AGENTS);
+        stdout(`agentaudit agents (${agents.length})\n`);
+        const table = new Table({
+            head: ["ID", "NAME", "SESSION FILES"],
+            style: { head: [], border: [] },
+        });
+        for (const agent of agents) {
+            let count = 0;
+            try {
+                count = agent.find().length;
+            }
+            catch {
+                count = 0;
+            }
+            table.push([agent.id, agent.displayName, String(count)]);
+        }
+        stdout(`${table.toString()}\n`);
+        return 0;
+    }
+    // Python: _parse_severity — typer.BadParameter exits 2 with this message
+    const severityValue = opts.severity.toLowerCase();
+    if (!SEVERITY_ORDER.includes(severityValue)) {
+        stderr(`error: must be one of: ${SEVERITY_ORDER.join("|")}\n`);
+        return 2;
+    }
+    const floor = severityValue;
+    // Python: {c.strip().upper() for c in rules.split(",") if c.strip()} or None
+    const prefixes = opts.rules
+        ? new Set(opts.rules
+            .split(",")
+            .map((c) => c.trim())
+            .filter((c) => c)
+            .map((c) => c.toUpperCase()))
+        : undefined;
+    // v0.2.x: --agent id[,id...]|all (default all = every registered agent).
+    // "all" expands to registry order; unknown ids exit 2 (typer usage-error code).
+    const agentNames = [...new Set(opts.agent.split(",").map((s) => s.trim()).filter(Boolean))];
+    const ids = agentNames.includes("all") ? Object.keys(AGENTS) : agentNames;
+    if (ids.length === 0) {
+        stderr(`error: no agent ids given (known: ${Object.keys(AGENTS).join(", ")})\n`);
+        return 2;
+    }
+    const unknownId = ids.find((id) => !AGENTS[id]);
+    if (unknownId) {
+        stderr(`error: unknown agent "${unknownId}" (known: ${Object.keys(AGENTS).join(", ")})\n`);
+        return 2;
+    }
+    let result;
+    if (opts.demo) {
+        // Python: tempfile.TemporaryDirectory() context manager
+        const tmp = mkdtempSync(join(tmpdir(), "agentaudit-demo-"));
+        try {
+            const files = [writeDemoSession(tmp)];
+            result = await runAudit(files, prefixes, opts.session);
+        }
+        finally {
+            rmSync(tmp, { recursive: true, force: true });
+        }
+    }
+    else {
+        // Python: if path is not None and path.is_file() -> [path], else
+        // find_session_files(path); DataDirNotFound -> "error: ..." + exit 2.
+        // v0.2.x: discovery runs per selected agent over {agent, path} entries so
+        // the engine can route each file to the right parser.
+        let entries = null;
+        if (pathArg !== undefined) {
+            try {
+                if (statSync(pathArg).isFile()) {
+                    // explicit file: route through the FIRST selected agent (default
+                    // "all" -> claude-code, preserving v0.1 behavior for file args)
+                    entries = [{ agent: ids[0], path: pathArg }];
+                }
+            }
+            catch {
+                // not stat-able == Python's is_file() False -> fall through to discovery
+            }
+        }
+        if (entries === null) {
+            entries = [];
+            try {
+                for (const id of ids) {
+                    try {
+                        for (const path of AGENTS[id].find(pathArg)) {
+                            entries.push({ agent: id, path });
+                        }
+                    }
+                    catch (err) {
+                        // Error policy: an explicitly given path that cannot be scanned
+                        // still fails loudly (v0.1 behavior, asserted by tests). Only a
+                        // MISSING DEFAULT root (no path argument) demotes a single agent
+                        // to a stderr hint when several were selected.
+                        if (err instanceof DataDirNotFoundError && pathArg === undefined && ids.length > 1) {
+                            stderr(`skipping ${id}: data directory not found\n`);
+                            continue;
+                        }
+                        throw err;
+                    }
+                }
+            }
+            catch (err) {
+                if (err instanceof DataDirNotFoundError) {
+                    // Python: DataDirNotFound -> "error: ..." + exit 2
+                    stderr(`error: ${err.message}\n`);
+                    return 2;
+                }
+                throw err;
+            }
+            // deterministic interleaving of per-agent discoveries (pathlib compare)
+            entries.sort((a, b) => comparePaths(a.path, b.path));
+        }
+        // stderr keeps --json stdout pure; real dirs can take ~10s before output
+        stderr(`scanning ${entries.length} session file(s)...\n`);
+        result = await runAudit(entries, prefixes, opts.session);
+    }
+    // (ADJUSTMENT B) severity floor applies to BOTH terminal and JSON modes
+    result.findings = result.findings.filter((f) => SEVERITY_ORDER.indexOf(f.severity) >= SEVERITY_ORDER.indexOf(floor));
+    if (opts.json) {
+        // plain stdout, no color; JSON.stringify is natively unicode, matching
+        // Python's json.dumps(ensure_ascii=False)
+        stdout(`${JSON.stringify(toDict(result), null, 2)}\n`);
+    }
+    else {
+        renderTerminal(result, floor, stdout);
+    }
+    if (opts.share && !opts.json) {
+        // card would corrupt the machine-readable JSON stream on stdout
+        stdout("\n");
+        stdout(`${shareCard(result)}\n`);
+    }
+    return 0;
+}
+// M5 watch mode: poll Get-NetTCPConnection via a PowerShell child once per
+// ~700ms, label targets against the domain registry, print a live line per
+// NEW connection, a summary at the end (and on Ctrl+C), append CSV rows.
+// Windows-only in v0.2.x — anything else exits 2 with the reason.
+async function watchCommand(opts, stdout, stderr, inject) {
+    // default list = every known AI-tool process name; --proc replaces it
+    const procs = opts.proc !== undefined ? parseWatchProcs(opts.proc) : [...DEFAULT_WATCH_PROCS];
+    if (procs.length === 0) {
+        stderr("error: --proc must name at least one process (comma separated)\n");
+        return 2;
+    }
+    const seconds = Number(opts.seconds);
+    if (!Number.isFinite(seconds) || seconds <= 0) {
+        stderr(`error: --seconds must be a positive number (got "${opts.seconds}")\n`);
+        return 2;
+    }
+    const deps = {
+        ...defaultWatchDeps(),
+        // live lines go through the SAME injected writer as everything else
+        writeLine: (line) => stdout(`${line}\n`),
+        ...(inject ?? {}),
+    };
+    // Ctrl+C: abort the watch, runWatch returns the partial result and the
+    // summary below still prints (same output as a natural end).
+    const controller = new AbortController();
+    const onSigint = () => controller.abort();
+    process.on("SIGINT", onSigint);
+    try {
+        stdout(`watching ${procs.join(", ")} for ${seconds}s (Ctrl+C to stop) — ` +
+            "unknown targets are flagged [!]\n");
+        const result = await runWatch({ procs, seconds, csvPath: opts.csv, signal: controller.signal }, deps);
+        stdout(renderWatchSummary(result, opts.csv));
+        return 0;
+    }
+    catch (err) {
+        if (err instanceof WatchUnsupportedError) {
+            stderr(`${err.message}\n`);
+            return 2;
+        }
+        throw err;
+    }
+    finally {
+        process.removeListener("SIGINT", onSigint);
+    }
+}
+// M6 footprint mode: inventory the local index stores of one tool (Qoder CN
+// only in v0.2.x — anything else exits 2 with the reason). NOT an audit: the
+// report lists what the tool collected (repos, file paths, counts, times);
+// see src/footprint.ts for the privacy posture. The positional [path]
+// overrides the tool's default data root (also how tests point at fixtures).
+function footprintCommand(opts, pathArg, stdout, stderr) {
+    const ids = opts.agent
+        .split(",")
+        .map((s) => s.trim())
+        .filter(Boolean);
+    // "all" is the commander default, i.e. literally the bare `--footprint`
+    // form — it maps to the only supported tool, qoder.
+    const unsupported = ids.filter((id) => id !== "qoder" && id !== "all");
+    if (unsupported.length > 0) {
+        stderr(`error: footprint only supports --agent qoder in v0.2.x (got: ${unsupported.join(", ")})\n`);
+        return 2;
+    }
+    const report = qoderFootprint(pathArg);
+    if (opts.json) {
+        stdout(`${JSON.stringify(report, null, 2)}\n`);
+    }
+    else {
+        stdout(renderFootprint(report));
+    }
+    return 0;
+}
+// Bin wiring: run only when invoked directly as `node dist/cli.js` (or via the
+// npm bin shim), never when imported (tests call main() with injected writers).
+const entry = process.argv[1];
+if (entry && import.meta.url === pathToFileURL(entry).href) {
+    process.exitCode = await main(process.argv.slice(2));
+}