@pretense/cli 0.6.12 → 0.6.14

package/README.md

@@ -35,6 +35,10 @@ pretending.
      docs-exec:skip "curl -fsSL https://www.pretense.ai/install.sh | sh" — downloads and installs a binary from the network
      docs-exec:skip "pretense start" — long-running server; it would outlive the suite holding port 9339
      docs-exec:skip "pretense start --port 9500" — long-running server; it would outlive the suite holding port 9500
+     docs-exec:skip `pretense run claude "explain this repo"` — starts a proxy and a third-party tool that would outlive the suite
+     docs-exec:skip "pretense run cursor" — starts a proxy and a third-party tool that would outlive the suite
+     docs-exec:skip `pretense run gemini "summarise the changes"` — starts a proxy and a third-party tool that would outlive the suite
+     docs-exec:skip "pretense run --provider openai mytool" — starts a proxy and a third-party tool that would outlive the suite
      docs-exec:skip "curl -s http://localhost:9339/health" — needs the proxy from the preceding line, which cannot be started here
      docs-exec:skip "claude" — third-party CLI that is not a dependency of this repo
      docs-exec:skip `curl -fsSLO "${BASE}/SHA256SUMS"` — network fetch from the release host
@@ -103,20 +107,30 @@ binary has no Node requirement.
 
 ```bash
 pretense scan <file|dir>              # what would leak
-pretense mutate <file> --map m.json -i  # swap it before the AI sees it
-pretense reverse <file> --map m.json -i # put the real values back
+pretense mutate <file>                # swap secrets in place, keep a reversal map (auto)
+pretense reverse <file>               # put the real values back (finds the map itself)
 pretense start                        # proxy mode (npm install only, see below)
 pretense scan <file> --policy hipaa   # the flag most people type
 ```
 
+`mutate <file>` then `reverse <file>` is a byte-exact round trip with **no
+flags**: `mutate` writes an encrypted reversal map to
+`~/.pretense/maps/<hash>.json` (derived from the file's absolute path, mode
+0600), and `reverse` recomputes that same location and finds it. To run any AI
+tool through the mutating proxy with zero setup, use `pretense run` (see
+[Zero-export proxy runner](#zero-export-proxy-runner)).
+
 Two honest caveats about the verbs:
 
 - `mutate` and `reverse` take **one file at a time**. `pretense mutate .` and
   `pretense mutate src` both fail with `Cannot read file: .` and exit 1.
   Directory mutation is not available yet. `scan` does accept a directory.
-- `mutate` **previews by default** — it prints to stdout and leaves the file
-  untouched. `-i` writes in place. `-i` without `--map` is irreversible; there
-  is no global map store to recover from.
+- `mutate` **mutates in place by default** and auto-writes the reversal map, so
+  the round trip is reversible with no `--map` on either side. Use `--stdout` to
+  preview to stdout without touching the file, `-o <path>` to write a copy, and
+  `--map <path>` to override where the map is written. The map lives under
+  `~/.pretense/maps`, deliberately out of the working tree so it is never
+  committed by accident.
 
 ## The 30-second walkthrough
 
@@ -273,6 +287,28 @@ claude
 
 `OPENAI_BASE_URL` works the same way, as does any client that accepts a base URL.
 
+## Zero-export proxy runner
+
+The manual dance above — start a proxy, remember the port, export the *right*
+base-URL variable for your tool, remember to stop it — is what `pretense run`
+does for you. It ensures a healthy proxy exists (reusing a running one, else
+starting one on an auto-found free port), sets the correct base-URL env var, runs
+your tool, and stops the proxy it started when the tool exits.
+
+```bash
+pretense run claude "explain this repo"     # Claude → ANTHROPIC_BASE_URL
+pretense run cursor                          # Cursor / OpenAI-compatible → OPENAI_BASE_URL
+pretense run gemini "summarise the changes"  # Gemini → GEMINI_BASE_URL
+pretense run --provider openai mytool        # force the provider mapping
+```
+
+`pretense with` is an alias for `pretense run`. The tool name selects the
+provider automatically (`claude` → Anthropic, `cursor`/`code` → OpenAI-compatible,
+`gemini` → Google); pass `--provider anthropic|openai|google` to override it, and
+`--port <n>` to prefer a port when a proxy has to be started. If the tool is not
+on your `PATH`, `run` prints an install hint and exits non-zero instead of
+crashing — and it never tears down a proxy it did not start.
+
 Read this before you rely on the proxy:
 
 - **npm install only.** `start` crashes on the `curl | sh` binary
@@ -383,8 +419,10 @@ pretense init                             # 0  — writes pretense.yaml + .prete
 pretense scan <file|dir>                  # 0 clean / 1 findings
 pretense scan <file> --policy <preset>    # 0 clean / 1 findings
 pretense scan <file> --severity high      # 0 clean / 1 findings
-pretense mutate <file>                    # 0  — preview to stdout, file untouched
-pretense mutate <file> --map m.json -i    # 0  — in place, reversible
+pretense mutate <file> --stdout           # 0  — preview to stdout, file untouched
+pretense mutate <file>                     # 0  — in place + auto-map (the default)
+pretense reverse <file>                    # 0  — in place, auto-finds the map
+pretense mutate <file> --map m.json -i    # 0  — explicit map-path override
 pretense reverse <file> --map m.json -i   # 0  — byte-exact restore
 pretense status                           # 0
 pretense audit --limit 20                 # 0
@@ -451,9 +489,13 @@ has edited will not reverse today. Token-substitution reversal is on the roadmap
 
 ## Where the reversal map lives
 
-In the CLI path, a map exists only where you ask for one, via
-`pretense mutate --map <path>`. It is AES-256-GCM encrypted and written mode
-`0600`.
+In the CLI path, `pretense mutate <file>` auto-writes the map to a deterministic
+per-file location — `~/.pretense/maps/<sha256(absolute-path)>.json` — and
+`pretense reverse <file>` recomputes that same path to find it, so neither verb
+needs `--map`. Pass `pretense mutate --map <path>` to override the location. The
+map is AES-256-GCM encrypted and written mode `0600`, and it lives under
+`~/.pretense/maps` (not in the working tree) so it is never committed by
+accident.
 
 In the proxy path the reverse map is held in memory for the life of the request
 and is never written to disk — deliberately, so Pretense never becomes an

package/dist/{chunk-K3L4E6HN.js → chunk-2WW3XY6A.js}

@@ -17,7 +17,7 @@ function versionFromPackageJson() {
     return void 0;
   }
 }
-var PRETENSE_VERSION = (true ? "0.6.12" : void 0) ?? versionFromPackageJson() ?? "0.0.0-unknown";
+var PRETENSE_VERSION = (true ? "0.6.14" : void 0) ?? versionFromPackageJson() ?? "0.0.0-unknown";
 
 export {
   PRETENSE_VERSION

package/dist/index.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   PRETENSE_VERSION
-} from "./chunk-K3L4E6HN.js";
+} from "./chunk-2WW3XY6A.js";
 import {
   __commonJS,
   __toESM,
@@ -221,8 +221,8 @@ var require_brace_expansion = __commonJS({
 
 // src/index.ts
 init_esm_shims();
-import { Command as Command21 } from "commander";
-import chalk20 from "chalk";
+import { Command as Command22 } from "commander";
+import chalk21 from "chalk";
 
 // src/commands/init.ts
 init_esm_shims();
@@ -12171,6 +12171,19 @@ var SECRET_PATTERNS = [
     defaultAction: "block",
     pattern: /\bgithub_pat_[A-Za-z0-9_]{22,}\b/g
   },
+  // FIX 1 (v0.6.13) — HuggingFace access tokens. `hf_` user and fine-grained
+  // access tokens are `hf_` + 34+ base62 chars. Confirmed leaking on 0.6.12:
+  // an `hf_` token in bare prose scanned clean (a real credential egressed to
+  // the LLM) because no `hf_`/`huggingface` pattern existed. The `hf_` prefix
+  // plus a 34+ base62 body is a near-zero-false-positive signal. Critical/block
+  // because a live model-registry token grants push access to private models.
+  {
+    name: "huggingface-token",
+    category: "secret",
+    severity: "critical",
+    defaultAction: "block",
+    pattern: /\bhf_[A-Za-z0-9]{34,}\b/g
+  },
   {
     name: "gitlab-token",
     category: "secret",
@@ -12745,8 +12758,9 @@ var ENV_PATTERNS = [
     // variable references (`$VAR`, `${VAR}`, `process.env.X`, `os.environ…`),
     // connection URLs (handled by `database-url`), and values that begin with a
     // recognised structured-secret prefix (Stripe `sk_`/`pk_`/`rk_`, OpenAI
-    // `sk-`, Slack `xox*`, GitHub `gh*_`/`glpat-`, AWS `AKIA`, Google `AIza`,
-    // Stripe webhook `whsec_`) are deliberately skipped so a generic
+    // `sk-`, Slack `xox*`, GitHub `gh*_`/`glpat-`, HuggingFace `hf_`, AWS
+    // `AKIA`, Google `AIza`, Stripe webhook `whsec_`) are deliberately skipped
+    // so a generic
     // `KEY=variable` reference is not flagged and the dedicated, higher-fidelity
     // patterns above own those matches. Placed last so more-specific patterns
     // win overlap deduplication on ties.
@@ -12760,7 +12774,7 @@ var ENV_PATTERNS = [
     // specific env-var names rather than generic secret-label tails, so they do
     // not belong in the shared vocabulary.
     pattern: new RegExp(
-      `(?<![A-Za-z0-9])(?:[A-Z0-9]+[._-])*(?:${ENV_SECRET_LABEL_ALTERNATION}|DATABASE_URL|VAULT_TOKEN)\\s*[=:]\\s*(?!['"\\s])(?!\\$)(?!process\\.env)(?!os\\.environ)(?![A-Za-z][A-Za-z0-9+.-]*:\\/\\/)(?!sk[-_]|pk_|rk_|whsec_|xox[bpors]-|ghp_|gho_|ghs_|glpat-|AKIA|AIza)[A-Za-z0-9/+._@:!#%^&*?~-]{8,}`,
+      `(?<![A-Za-z0-9])(?:[A-Z0-9]+[._-])*(?:${ENV_SECRET_LABEL_ALTERNATION}|DATABASE_URL|VAULT_TOKEN)\\s*[=:]\\s*(?!['"\\s])(?!\\$)(?!process\\.env)(?!os\\.environ)(?![A-Za-z][A-Za-z0-9+.-]*:\\/\\/)(?!sk[-_]|pk_|rk_|whsec_|xox[bpors]-|ghp_|gho_|ghs_|glpat-|hf_|AKIA|AIza)[A-Za-z0-9/+._@:!#%^&*?~-]{8,}`,
       "gi"
     ),
     // PRECISION: reject `PASSWORD=changeme`, `PASSWORD=<your-password>` and
@@ -13827,6 +13841,8 @@ function overlapsAny(m, sorted) {
 }
 async function scanLevel2(text, language, opts = {}) {
   const lang = language ?? opts.language ?? "typescript";
+  const t0 = performance.now();
+  const elapsed = () => Math.round((performance.now() - t0) * 100) / 100;
   const base = opts.presidioUrl ? await scanWithPresidio(text, opts.presidioUrl, opts) : scan(text, opts);
   const l1Matches = base.matches.map((m) => ({ ...m, level: 1 }));
   const l1Findings = base.findings.map((f) => ({ ...f, level: 1 }));
@@ -13834,6 +13850,8 @@ async function scanLevel2(text, language, opts = {}) {
     ...base,
     matches: l1Matches,
     findings: l1Findings,
+    // Real wall time up to this early return, not the L1 sub-phase alone.
+    durationMs: elapsed(),
     l2: status
   });
   const native = loadNative();
@@ -13911,7 +13929,9 @@ async function scanLevel2(text, language, opts = {}) {
     matches: merged,
     findings: mergedFindings,
     scannedAt: (/* @__PURE__ */ new Date()).toISOString(),
-    durationMs: base.durationMs,
+    // Real elapsed wall time for the full L1+L2 scan (was base.durationMs, the
+    // L1-only time, which undercounted the AST work ~25x — see FIX 3/TASK-16).
+    durationMs: elapsed(),
     patternCount: base.patternCount,
     // Bounded-work state is a property of the underlying scan and MUST survive
     // this merge — dropping it here would re-create the silent-incomplete hole
@@ -16425,11 +16445,11 @@ function versionFromCliPackageJson() {
   return void 0;
 }
 function productVersion() {
-  return override ?? (true ? "0.6.12" : void 0) ?? versionFromCliPackageJson() ?? "0.0.0-unknown";
+  return override ?? (true ? "0.6.14" : void 0) ?? versionFromCliPackageJson() ?? "0.0.0-unknown";
 }
 var UNKNOWN_COMMIT = "unknown";
 function bakedCommitSha() {
-  return "cd2bfc0670d3c8aadaa5a163493ba152391489a1".length > 0 ? "cd2bfc0670d3c8aadaa5a163493ba152391489a1" : UNKNOWN_COMMIT;
+  return "13f5fb3bd88295258e3733458b63315e9382678e".length > 0 ? "13f5fb3bd88295258e3733458b63315e9382678e" : UNKNOWN_COMMIT;
 }
 var FEATURE_TIERS = {
   compliance_export: "pro",
@@ -17881,7 +17901,10 @@ function startProxy(opts = {}) {
 function renderClientEnvLines(port, protocol) {
   const base = `${protocol}://localhost:${port}`;
   return [
-    "  Point your AI client at Pretense:",
+    "  Easiest \u2014 let Pretense wire the env var and run the tool for you:",
+    '    pretense run claude "build me X"      # or: cursor, gemini, any tool',
+    "",
+    "  Or point your AI client at Pretense yourself:",
     `    ANTHROPIC_BASE_URL=${base}`,
     `    OPENAI_BASE_URL=${base}/v1`,
     `    GOOGLE_GEMINI_BASE_URL=${base}`
@@ -17911,6 +17934,33 @@ if (isMain) {
   startProxy();
 }
 
+// src/free-port.ts
+init_esm_shims();
+import net from "net";
+function isPortFree(port) {
+  return new Promise((resolve7) => {
+    const srv = net.createServer();
+    srv.once("error", () => {
+      srv.close(() => resolve7(false));
+      resolve7(false);
+    });
+    srv.once("listening", () => {
+      srv.close(() => resolve7(true));
+    });
+    srv.listen(port);
+  });
+}
+async function findFreePort(start, opts = {}) {
+  const maxTries = opts.maxTries ?? 100;
+  const end = Math.min(start + maxTries - 1, 65535);
+  for (let p = start; p <= end; p += 1) {
+    if (await isPortFree(p)) return p;
+  }
+  throw new Error(
+    `No free port found in [${start}, ${end}] after ${maxTries} attempts.`
+  );
+}
+
 // src/proxy-pidfile.ts
 init_esm_shims();
 import { existsSync as existsSync7, readFileSync as readFileSync6, unlinkSync } from "fs";
@@ -18034,15 +18084,15 @@ function explainAddrInUse(port) {
   );
 }
 function startCommand() {
-  return new Command2("start").description("Start the Pretense proxy server").option("-p, --port <port>", "Port to listen on", "9339").option("--verbose", "Enable verbose logging", false).option("-c, --config <path>", "Path to pretense.yaml").action((opts) => {
-    const port = parseInt(opts.port, 10);
+  return new Command2("start").description("Start the Pretense proxy server").option("-p, --port <port>", "Port to listen on", "9339").option("--verbose", "Enable verbose logging", false).option("-c, --config <path>", "Path to pretense.yaml").option("--strict-port", "Fail if the requested port is busy instead of auto-advancing", false).action(async (opts) => {
+    const requested = parseInt(opts.port, 10);
     const existing = readProxyRecord();
     if (existing) {
       if (isProcessAlive(existing.pid)) {
-        if (existing.port === port) {
+        if (existing.port === requested) {
           console.error(
             chalk2.red(`
-  x Pretense proxy is already running (pid ${existing.pid}, port ${existing.port}).`) + chalk2.dim("\n    Stop it with ") + chalk2.cyan("pretense stop") + chalk2.dim(", or start this one on another port with ") + chalk2.cyan(`--port ${port + 1}`) + "\n"
+  x Pretense proxy is already running (pid ${existing.pid}, port ${existing.port}).`) + chalk2.dim("\n    Stop it with ") + chalk2.cyan("pretense stop") + chalk2.dim(", or start this one on another port with ") + chalk2.cyan(`--port ${requested + 1}`) + "\n"
           );
           process.exit(1);
         }
@@ -18050,6 +18100,25 @@ function startCommand() {
         removeProxyRecord();
       }
     }
+    let port = requested;
+    if (!opts.strictPort) {
+      try {
+        port = await findFreePort(requested);
+      } catch (err) {
+        console.error(chalk2.red(`
+  x ${err.message}
+`));
+        process.exit(1);
+      }
+      if (port !== requested) {
+        console.error(
+          chalk2.yellow(`
+  ! Port ${requested} is busy \u2014 starting Pretense on port ${port} instead.`) + chalk2.dim(`
+    Pass --strict-port to fail instead of auto-advancing.
+`)
+        );
+      }
+    }
     process.on("uncaughtException", (err) => {
       if (err?.code === "EADDRINUSE") {
         const rec = readProxyRecord();
@@ -18323,9 +18392,24 @@ var SKIP_DIRS = /* @__PURE__ */ new Set([
   ".idea",
   ".vscode"
 ]);
+function isSkippableWalkError(err) {
+  const code = err?.code;
+  return code === "EACCES" || code === "EPERM" || code === "ENOENT" || code === "ELOOP" || code === "ENOTDIR";
+}
 function walkDir(dir) {
   const files = [];
-  for (const entry of readdirSync2(dir, { withFileTypes: true })) {
+  let entries;
+  try {
+    entries = readdirSync2(dir, { withFileTypes: true });
+  } catch (err) {
+    if (isSkippableWalkError(err)) {
+      const code = err.code;
+      console.error(chalk4.yellow(`  Skipping unreadable path (${code}): ${dir}`));
+      return files;
+    }
+    throw err;
+  }
+  for (const entry of entries) {
     if (entry.isDirectory()) {
       if (entry.name.startsWith(".") || SKIP_DIRS.has(entry.name)) continue;
       files.push(...walkDir(join7(dir, entry.name)));
@@ -18378,6 +18462,18 @@ function l2LanguageFor(filePath) {
   if (!filePath) return void 0;
   return L2_LANGUAGE_BY_EXT[extname2(filePath).toLowerCase()];
 }
+var L2_LARGE_FILE_WARN_BYTES = 5 * 1024 * 1024;
+function warnIfLargeForL2(byteLength, filePath) {
+  if (byteLength <= L2_LARGE_FILE_WARN_BYTES) return false;
+  const mb = (byteLength / (1024 * 1024)).toFixed(1);
+  const where = filePath ? ` \u2014 ${basename(filePath)}` : "";
+  console.error(
+    chalk4.yellow(
+      `  Note: L2 AST scanning is slow on very large files (${mb}MB${where}); this may take a while.`
+    )
+  );
+  return true;
+}
 async function scanContent(content, opts, filePath) {
   return withLocations(await scanContentRaw(content, opts, filePath), content);
 }
@@ -18421,6 +18517,7 @@ async function scanContentRaw(content, opts, filePath) {
       }
     };
   }
+  warnIfLargeForL2(Buffer.byteLength(content, "utf-8"), filePath);
   const result = await scanLevel2(content, language, scanOpts);
   if (opts.level === 2) {
     const only2 = result.matches.filter((m) => m.level === 2);
@@ -20522,11 +20619,13 @@ function quickstartCommand() {
     }
     console.log(chalk13.dim("  [4/4] Done.\n"));
     console.log(chalk13.bold("  Next steps:\n"));
-    console.log(`  ${chalk13.green("1.")} ${chalk13.cyan("pretense start")}            Start proxy on localhost:9339`);
-    console.log(`  ${chalk13.green("2.")} ${chalk13.cyan("pretense install")}          Install pre-commit + pre-push git hooks`);
-    console.log(`  ${chalk13.green("3.")} Set your LLM client to use the proxy:`);
+    console.log(`  ${chalk13.green("1.")} ${chalk13.cyan('pretense run claude "build me X"')}   Run any AI tool through the proxy \u2014 zero setup`);
+    console.log(`     ${chalk13.dim("(auto-starts the proxy on a free port and sets the base-URL env var for you)")}`);
+    console.log(`  ${chalk13.green("2.")} ${chalk13.cyan("pretense install")}                  Install pre-commit + pre-push git hooks`);
+    console.log(`  ${chalk13.green("3.")} ${chalk13.dim("Prefer to wire it by hand? Start the proxy and set the base URL yourself:")}`);
+    console.log(`     ${chalk13.dim("pretense start")}`);
     console.log(`     ${chalk13.dim("ANTHROPIC_BASE_URL=http://localhost:9339 claude")}`);
-    console.log(`     ${chalk13.dim("OPENAI_BASE_URL=http://localhost:9339/v1 openai ...")}`);
+    console.log(`     ${chalk13.dim("OPENAI_BASE_URL=http://localhost:9339/v1 cursor ...")}`);
     console.log(`     ${chalk13.dim("GOOGLE_GEMINI_BASE_URL=http://localhost:9339 gemini ...")}
 `);
     console.log(chalk13.bold.green("  Protected. Happy coding.\n"));
@@ -20538,7 +20637,7 @@ init_esm_shims();
 import { Command as Command15, Option as Option2 } from "commander";
 import chalk14 from "chalk";
 import { readFileSync as readFileSync15, writeFileSync as writeFileSync7, chmodSync as chmodSync4, existsSync as existsSync15 } from "fs";
-import { createHash as createHash2 } from "crypto";
+import { createHash as createHash3 } from "crypto";
 import { resolve as resolve5, extname as extname4 } from "path";
 
 // src/secret-crypto.ts
@@ -20646,6 +20745,22 @@ function writeFileAtomicSync(targetPath, data, opts = {}) {
   }
 }
 
+// src/default-map.ts
+init_esm_shims();
+import { createHash as createHash2 } from "crypto";
+import { join as join20 } from "path";
+function mapsDir(override2) {
+  return override2 ?? join20(pretenseHome(), "maps");
+}
+function defaultMapPath(absFilePath, override2) {
+  const digest = createHash2("sha256").update(absFilePath, "utf8").digest("hex");
+  return join20(mapsDir(override2), `${digest}.json`);
+}
+function ensureDefaultMapPath(absFilePath, override2) {
+  ensureDirOwnerOnly(mapsDir(override2));
+  return defaultMapPath(absFilePath, override2);
+}
+
 // src/commands/mutate.ts
 var REVERSAL_MAP_VERSION = 3;
 function preflightReversalMap(mapPath, absFile, content, contentSha, force) {
@@ -20710,7 +20825,7 @@ function preflightReversalMap(mapPath, absFile, content, contentSha, force) {
   };
 }
 function sha256Hex2(s) {
-  return createHash2("sha256").update(s, "utf8").digest("hex");
+  return createHash3("sha256").update(s, "utf8").digest("hex");
 }
 var L2_LANGUAGE_BY_EXT2 = {
   ".ts": "typescript",
@@ -20815,6 +20930,8 @@ async function runMutate(file, opts = {}) {
     );
     return 1;
   }
+  const preview = opts.stdout === true;
+  const inPlace = !preview && !opts.output;
   const { findings, unmutatable } = await collectMutationFindings(
     content,
     file,
@@ -20827,16 +20944,24 @@ async function runMutate(file, opts = {}) {
     } else {
       reportUnmutatable(unmutatable);
     }
-    if (!opts.inPlace && !opts.output) process.stdout.write(content);
+    if (preview) process.stdout.write(content);
     return 0;
   }
   reportUnmutatable(unmutatable);
   const absFile = resolve5(file);
   const projectRoot = findProjectRoot(absFile);
   const result = mutateSecrets(content, findings, { projectRoot, keysDir: opts.keysDir });
-  if (opts.map) {
+  let effectiveMap;
+  if (preview) {
+    effectiveMap = void 0;
+  } else if (inPlace) {
+    effectiveMap = opts.map ?? ensureDefaultMapPath(absFile, opts.mapsDir);
+  } else {
+    effectiveMap = opts.map;
+  }
+  if (effectiveMap) {
     const contentSha = sha256Hex2(content);
-    const pre = preflightReversalMap(opts.map, absFile, content, contentSha, opts.forceMap === true);
+    const pre = preflightReversalMap(effectiveMap, absFile, content, contentSha, opts.forceMap === true);
     if (pre.action === "refuse") {
       console.error(
         chalk14.red(`
@@ -20851,7 +20976,7 @@ async function runMutate(file, opts = {}) {
     const isNoop = pre.action === "keep" && pre.expectedMutatedSha === mutatedSha;
     if (isNoop) {
       console.error(
-        chalk14.dim(`  = Reversal map ${opts.map} already describes ${file} at this exact content`) + chalk14.dim(`
+        chalk14.dim(`  = Reversal map ${effectiveMap} already describes ${file} at this exact content`) + chalk14.dim(`
     hash \u2014 left unchanged (mutation is deterministic, so a rewrite would be`) + chalk14.dim(`
     byte-identical).`)
       );
@@ -20874,7 +20999,7 @@ async function runMutate(file, opts = {}) {
           type: m.type
         }))
       };
-      const written = writeReversalMap(opts.map, mapFile);
+      const written = writeReversalMap(effectiveMap, mapFile);
       if (written !== 0) return written;
       if (pre.action === "write" && pre.generation > 1) {
         console.error(
@@ -20888,18 +21013,17 @@ async function runMutate(file, opts = {}) {
       }
     }
   }
-  if (opts.inPlace && !opts.map) {
+  if (inPlace && !effectiveMap) {
     console.error(
-      chalk14.yellow(`
-  ! IRREVERSIBLE: overwriting ${file} in place without a reversal map.`) + chalk14.dim(`
-    Synthetic values are one-way \u2014 this cannot be undone and no copy of`) + chalk14.dim(`
-    the original secrets is kept. Re-run with --map <path> to be able to`) + chalk14.dim(`
-    restore them later with \`pretense reverse\`.
+      chalk14.red(`
+  x Refusing to mutate ${file} in place with no reversal map \u2014 this would be irreversible.`) + chalk14.dim(`
+    Pass --map <path>, or report this as a bug.
 `)
     );
+    return 1;
   }
   try {
-    if (opts.inPlace) {
+    if (inPlace) {
       writeFileAtomicSync(file, result.content);
       console.error(chalk14.green(`  \u2713 Mutated ${result.mutations.length} secrets in ${file} (in-place)`));
     } else if (opts.output) {
@@ -20924,8 +21048,11 @@ async function runMutate(file, opts = {}) {
 }
 function mutateCommand() {
   return new Command15("mutate").description(
-    "Preview mutated secrets on stdout (add -i to write back in place; pair with --map to keep it reversible)"
-  ).argument("<file>", "File to mutate").option("-i, --in-place", "Write back to the input file (irreversible unless --map is also given)").option("-o, --output <path>", "Write mutated content to a specific file").option("--map <path>", "Write the encrypted reversal map (required to ever run `pretense reverse`)").option(
+    "Mutate secrets IN PLACE and auto-write an encrypted reversal map (reverse with `pretense reverse <file>`; --stdout to preview instead)"
+  ).argument("<file>", "File to mutate").option("-i, --in-place", "Write back to the input file (this is the default; kept for compatibility)").option("-o, --output <path>", "Write mutated content to a specific file instead of in place").option("--stdout", "Preview mutated content on stdout and write NOTHING (no file, no map)").option(
+    "--map <path>",
+    "Override where the encrypted reversal map is written (default: ~/.pretense/maps/<hash>.json)"
+  ).option(
     "--force-map",
     "Overwrite an existing reversal map that still covers recoverable data (DESTRUCTIVE: the map it replaces may be the only way back to the real secrets)"
   ).option("--show-map", "Print mutation map JSON to stderr").addOption(
@@ -20957,9 +21084,9 @@ import { Command as Command16 } from "commander";
 import chalk15 from "chalk";
 import { readFileSync as readFileSync16, existsSync as existsSync16, statSync as statSync6 } from "fs";
 import { resolve as resolve6 } from "path";
-import { createHash as createHash3 } from "crypto";
+import { createHash as createHash4 } from "crypto";
 function sha256Hex3(s) {
-  return createHash3("sha256").update(s, "utf8").digest("hex");
+  return createHash4("sha256").update(s, "utf8").digest("hex");
 }
 var SYNTHETIC_MARKERS = [
   /pretense_mut_u[0-9a-z]{6,}:pretense_mut_p[0-9a-z]{6,}@/,
@@ -21015,22 +21142,25 @@ function loadReversalMap(mapPath) {
 }
 function runReverse(file, opts = {}) {
   const absPath = resolve6(file);
-  if (!opts.map) {
-    console.error(
-      chalk15.red(`
-  x reverse requires a reversal map: --map <file>`) + chalk15.dim(`
-  Produce one with: ${chalk15.cyan(`pretense mutate ${file} -i --map <file>`)}
-`)
-    );
-    return 1;
-  }
   if (!existsSync16(absPath) || !statSync6(absPath).isFile()) {
     console.error(chalk15.red(`
   x File not found: ${file}
 `));
     return 1;
   }
-  const mapFile = loadReversalMap(opts.map);
+  const mapPath = opts.map ?? defaultMapPath(absPath, opts.mapsDir);
+  if (!opts.map && !existsSync16(mapPath)) {
+    console.error(
+      chalk15.red(`
+  x No reversal map found for ${absPath}`) + chalk15.dim(`
+    Looked in the default location: ${mapPath}`) + chalk15.dim(`
+    Mutate the file first with ${chalk15.cyan(`pretense mutate ${file}`)}, or pass`) + chalk15.dim(`
+    an explicit ${chalk15.cyan("--map <path>")} if you wrote the map somewhere else.
+`)
+    );
+    return 1;
+  }
+  const mapFile = loadReversalMap(mapPath);
   let plainMutations;
   if (mapFile.encrypted) {
     const projectRoot = findProjectRoot(mapFile.file ?? absPath);
@@ -21136,7 +21266,9 @@ function runReverse(file, opts = {}) {
   }
   const mark = lineage.ok ? chalk15.green("  \u2713 Restored") : chalk15.yellow("  ! Partially restored");
   const detail = `${appliedCount} of ${plainMutations.length} mapped tokens` + (lineage.ok ? "" : " \u2014 to an earlier MUTATED generation, not the original");
-  if (opts.inPlace) {
+  const preview = opts.stdout === true;
+  const inPlace = !preview && !opts.output;
+  if (inPlace) {
     writeFileAtomicSync(absPath, restored);
     console.error(`${mark} ${absPath} (${detail}, in-place)`);
   } else if (opts.output) {
@@ -21163,8 +21295,11 @@ function runReverse(file, opts = {}) {
 }
 function reverseCommand() {
   return new Command16("reverse").description(
-    "Restore a mutated file to its EXACT original bytes using an encrypted reversal map (fails if the file was edited after mutation)"
-  ).argument("<file>", "Mutated file to restore (must be byte-identical to the mutate output)").requiredOption("--map <path>", "Reversal map produced by `pretense mutate --map <path>`").option("-i, --in-place", "Write the restored content back to the input file").option("-o, --output <path>", "Write restored content to a specific file").option("--json", "Emit a JSON summary to stderr").option(
+    "Restore a mutated file to its EXACT original bytes IN PLACE, auto-finding its reversal map (fails if the file was edited after mutation)"
+  ).argument("<file>", "Mutated file to restore (must be byte-identical to the mutate output)").option(
+    "--map <path>",
+    "Override the reversal map to use (default: the one `pretense mutate <file>` auto-wrote)"
+  ).option("-i, --in-place", "Write the restored content back to the input file (this is the default)").option("-o, --output <path>", "Write restored content to a specific file instead of in place").option("--stdout", "Preview restored content on stdout instead of writing the file").option("--json", "Emit a JSON summary to stderr").option(
     "--allow-partial",
     "Apply a map whose originals are themselves synthetics (writes the PREVIOUS MUTATED generation, not the original)"
   ).action((file, opts) => {
@@ -21172,10 +21307,191 @@ function reverseCommand() {
   });
 }
 
-// src/commands/policy.ts
+// src/commands/run.ts
 init_esm_shims();
 import { Command as Command17 } from "commander";
 import chalk16 from "chalk";
+import { spawn } from "child_process";
+import { basename as basename3 } from "path";
+import { fileURLToPath as fileURLToPath4 } from "url";
+var TOOL_PROVIDER = {
+  claude: "anthropic",
+  "claude-code": "anthropic",
+  anthropic: "anthropic",
+  cursor: "openai",
+  code: "openai",
+  codex: "openai",
+  openai: "openai",
+  aider: "openai",
+  gemini: "google",
+  google: "google"
+};
+var PROVIDER_ALIASES = {
+  anthropic: "anthropic",
+  claude: "anthropic",
+  openai: "openai",
+  "openai-compatible": "openai",
+  cursor: "openai",
+  google: "google",
+  gemini: "google"
+};
+function resolveProvider(tool, override2) {
+  if (override2 !== void 0) {
+    const p = PROVIDER_ALIASES[override2.toLowerCase()];
+    if (!p) {
+      throw new Error(
+        `Unknown --provider "${override2}". Expected one of: anthropic, openai, google.`
+      );
+    }
+    return p;
+  }
+  return TOOL_PROVIDER[basename3(tool).toLowerCase()] ?? "anthropic";
+}
+function injectedEnvFor(provider, port) {
+  const base = `http://localhost:${port}`;
+  switch (provider) {
+    case "anthropic":
+      return { ANTHROPIC_BASE_URL: base };
+    case "openai":
+      return { OPENAI_BASE_URL: `${base}/v1` };
+    case "google":
+      return { GEMINI_BASE_URL: base, GOOGLE_GEMINI_BASE_URL: base };
+  }
+}
+function primaryEnvVar(provider) {
+  return provider === "anthropic" ? "ANTHROPIC_BASE_URL" : provider === "openai" ? "OPENAI_BASE_URL" : "GEMINI_BASE_URL";
+}
+var sleep2 = (ms) => new Promise((r) => setTimeout(r, ms));
+async function isProxyHealthy(port, timeoutMs = 800) {
+  const ctrl = new AbortController();
+  const t = setTimeout(() => ctrl.abort(), timeoutMs);
+  try {
+    const res = await fetch(`http://localhost:${port}/health`, { signal: ctrl.signal });
+    return res.ok;
+  } catch {
+    return false;
+  } finally {
+    clearTimeout(t);
+  }
+}
+async function waitHealthy(port, deadlineMs, pollMs = 150) {
+  const deadline = Date.now() + deadlineMs;
+  while (Date.now() < deadline) {
+    if (await isProxyHealthy(port)) return true;
+    await sleep2(pollMs);
+  }
+  return false;
+}
+function spawnProxy(port) {
+  const cliEntry = process.argv[1] ?? fileURLToPath4(import.meta.url);
+  return spawn(process.execPath, [cliEntry, "start", "--port", String(port), "--strict-port"], {
+    stdio: ["ignore", "ignore", "pipe"],
+    env: process.env
+  });
+}
+function runCommand() {
+  return new Command17("run").alias("with").description(
+    "Run an AI tool THROUGH the Pretense proxy with zero setup \u2014 auto-starts the proxy, sets the right base-URL env var, and stops the proxy it started when the tool exits"
+  ).argument("<tool>", "The AI CLI to run (claude, cursor, gemini, \u2026)").argument("[args...]", "Arguments passed through to <tool>").option("--provider <name>", "Force the provider mapping: anthropic | openai | google").option("-p, --port <port>", "Preferred proxy port when starting one (default 9339)").option("--strict-port", "Fail instead of auto-advancing when starting a proxy on a busy port", false).passThroughOptions().allowUnknownOption().action(async (tool, args, opts) => {
+    let provider;
+    try {
+      provider = resolveProvider(tool, opts.provider);
+    } catch (err) {
+      console.error(chalk16.red(`
+  x ${err.message}
+`));
+      process.exit(1);
+    }
+    let port;
+    let proxyChild;
+    let startedByUs = false;
+    const rec = readProxyRecord();
+    if (rec && isProcessAlive(rec.pid) && await isProxyHealthy(rec.port)) {
+      port = rec.port;
+      console.error(chalk16.dim(`  \u21BA Reusing the Pretense proxy already running on port ${port}.`));
+    } else {
+      const preferred = opts.port ? parseInt(opts.port, 10) : 9339;
+      try {
+        port = await findFreePort(preferred);
+      } catch (err) {
+        console.error(chalk16.red(`
+  x ${err.message}
+`));
+        process.exit(1);
+      }
+      proxyChild = spawnProxy(port);
+      startedByUs = true;
+      let proxyStderr = "";
+      proxyChild.stderr?.on("data", (d) => {
+        proxyStderr += d.toString();
+      });
+      const ready = await waitHealthy(port, 15e3);
+      if (!ready) {
+        console.error(
+          chalk16.red(`
+  x Pretense proxy did not become healthy on port ${port} in time.`) + (proxyStderr ? chalk16.dim(`
+${proxyStderr.split("\n").slice(-6).join("\n")}`) : "") + "\n"
+        );
+        proxyChild.kill("SIGTERM");
+        process.exit(1);
+      }
+      console.error(chalk16.green(`  \u2713 Started Pretense proxy on port ${port}.`));
+    }
+    const stopStartedProxy = () => {
+      if (startedByUs && proxyChild && !proxyChild.killed) {
+        proxyChild.kill("SIGTERM");
+      }
+    };
+    const inject = injectedEnvFor(provider, port);
+    console.error(
+      chalk16.dim(
+        `  \u2192 Routing ${basename3(tool)} through the proxy (${primaryEnvVar(provider)}=http://localhost:${port}).
+`
+      )
+    );
+    const child = spawn(tool, args, {
+      stdio: "inherit",
+      env: { ...process.env, ...inject }
+    });
+    const forward = (sig) => () => {
+      if (!child.killed) child.kill(sig);
+    };
+    const onInt = forward("SIGINT");
+    const onTerm = forward("SIGTERM");
+    process.on("SIGINT", onInt);
+    process.on("SIGTERM", onTerm);
+    child.on("error", (err) => {
+      if (err.code === "ENOENT") {
+        console.error(
+          chalk16.red(`
+  x "${tool}" is not on your PATH.`) + chalk16.dim(`
+    Install it (e.g. the ${basename3(tool)} CLI) and try again, or check the name.`) + chalk16.dim(`
+    You can still point a client at the proxy yourself:`) + chalk16.dim(`
+      ${primaryEnvVar(provider)}=http://localhost:${port}
+`)
+        );
+      } else {
+        console.error(chalk16.red(`
+  x Could not run "${tool}": ${err.message}
+`));
+      }
+      stopStartedProxy();
+      process.exit(err.code === "ENOENT" ? 127 : 1);
+    });
+    child.on("exit", (code, signal) => {
+      stopStartedProxy();
+      process.removeListener("SIGINT", onInt);
+      process.removeListener("SIGTERM", onTerm);
+      if (typeof code === "number") process.exit(code);
+      process.exit(signal ? 1 : 0);
+    });
+  });
+}
+
+// src/commands/policy.ts
+init_esm_shims();
+import { Command as Command18 } from "commander";
+import chalk17 from "chalk";
 function listAction(opts) {
   const ids = listPresetIds();
   if (opts.json) {
@@ -21198,21 +21514,21 @@ function listAction(opts) {
     );
     return;
   }
-  console.log(chalk16.cyan("\n  Pretense Compliance Frameworks\n"));
+  console.log(chalk17.cyan("\n  Pretense Compliance Frameworks\n"));
   console.log(
-    chalk16.dim(
+    chalk17.dim(
       "  " + "ID".padEnd(8) + "NAME".padEnd(14) + "TIER".padEnd(12) + "AUDIT".padEnd(8) + "DETECTORS"
     )
   );
-  console.log(chalk16.dim("  " + "\u2500".repeat(64)));
+  console.log(chalk17.dim("  " + "\u2500".repeat(64)));
   for (const id of ids) {
     const p = COMPLIANCE_PRESETS[id];
     console.log(
-      "  " + chalk16.bold(p.id.padEnd(8)) + p.name.padEnd(14) + chalk16.dim(p.minTier.padEnd(12)) + (p.auditRequired ? chalk16.green("yes".padEnd(8)) : chalk16.dim("no".padEnd(8))) + chalk16.dim(`${Object.keys(p.actionOverrides).length} overrides`)
+      "  " + chalk17.bold(p.id.padEnd(8)) + p.name.padEnd(14) + chalk17.dim(p.minTier.padEnd(12)) + (p.auditRequired ? chalk17.green("yes".padEnd(8)) : chalk17.dim("no".padEnd(8))) + chalk17.dim(`${Object.keys(p.actionOverrides).length} overrides`)
     );
   }
-  console.log(chalk16.dim(`
-  Run ${chalk16.cyan("pretense policy show <id>")} for detector-level detail.
+  console.log(chalk17.dim(`
+  Run ${chalk17.cyan("pretense policy show <id>")} for detector-level detail.
 `));
 }
 function showAction(id, opts) {
@@ -21221,8 +21537,8 @@ function showAction(id, opts) {
     preset = loadPreset(id);
   } catch (err) {
     console.error(
-      chalk16.red(`
-  x ${err.message}`) + chalk16.dim(`
+      chalk17.red(`
+  x ${err.message}`) + chalk17.dim(`
   Valid frameworks: ${listPresetIds().join(", ")}
 `)
     );
@@ -21232,24 +21548,24 @@ function showAction(id, opts) {
     console.log(JSON.stringify(preset, null, 2));
     return;
   }
-  console.log(chalk16.cyan(`
-  ${preset.name}  `) + chalk16.dim(`(${preset.id})`));
-  console.log(chalk16.dim(`  ${preset.description}
+  console.log(chalk17.cyan(`
+  ${preset.name}  `) + chalk17.dim(`(${preset.id})`));
+  console.log(chalk17.dim(`  ${preset.description}
 `));
-  console.log(`  Minimum tier:   ${chalk16.bold(preset.minTier)}`);
-  console.log(`  Audit required: ${preset.auditRequired ? chalk16.green("yes") : chalk16.dim("no")}`);
-  console.log(`  Detector sets:  ${chalk16.dim(preset.detectorSets.join(", "))}
+  console.log(`  Minimum tier:   ${chalk17.bold(preset.minTier)}`);
+  console.log(`  Audit required: ${preset.auditRequired ? chalk17.green("yes") : chalk17.dim("no")}`);
+  console.log(`  Detector sets:  ${chalk17.dim(preset.detectorSets.join(", "))}
 `);
   const overrides = Object.entries(preset.actionOverrides);
-  console.log(chalk16.dim(`  Detector actions (${overrides.length}):`));
+  console.log(chalk17.dim(`  Detector actions (${overrides.length}):`));
   for (const [detector, action] of overrides) {
-    const color = action === "block" ? chalk16.red : action === "redact" ? chalk16.yellow : chalk16.dim;
+    const color = action === "block" ? chalk17.red : action === "redact" ? chalk17.yellow : chalk17.dim;
     console.log(`    ${detector.padEnd(24)} ${color(action)}`);
   }
   console.log();
 }
 function policyCommand() {
-  const cmd = new Command17("policy").description(
+  const cmd = new Command18("policy").description(
     "List and inspect the built-in compliance presets (5: hipaa, gdpr, soc2, nist, pci)"
   );
   cmd.command("list").description("List the 5 built-in compliance presets").option("--json", "Output as JSON").action((opts) => listAction(opts));
@@ -21260,10 +21576,10 @@ function policyCommand() {
 
 // src/commands/audit.ts
 init_esm_shims();
-import { Command as Command18 } from "commander";
-import chalk17 from "chalk";
+import { Command as Command19 } from "commander";
+import chalk18 from "chalk";
 import { homedir as homedir10 } from "os";
-import { join as join20 } from "path";
+import { join as join21 } from "path";
 var VALID_FORMATS2 = ["table", "csv", "json", "jsonl"];
 function toSafeAuditRow(e) {
   return {
@@ -21334,18 +21650,18 @@ function resolveFormat2(opts) {
   const raw2 = opts.format?.trim().toLowerCase();
   if (raw2 !== void 0 && !VALID_FORMATS2.includes(raw2)) {
     console.error(
-      chalk17.red(`
+      chalk18.red(`
   x Unknown --format: "${opts.format}"
-`) + chalk17.dim("  Valid formats: table, csv, json (alias: jsonl).\n")
+`) + chalk18.dim("  Valid formats: table, csv, json (alias: jsonl).\n")
     );
     return null;
   }
   const fromFormat = raw2 === void 0 ? void 0 : raw2 === "jsonl" ? "json" : raw2;
   if (opts.json && fromFormat !== void 0 && fromFormat !== "json") {
     console.error(
-      chalk17.red(`
+      chalk18.red(`
   x --json and --format ${fromFormat} request different outputs.
-`) + chalk17.dim("  Pick one.\n")
+`) + chalk18.dim("  Pick one.\n")
     );
     return null;
   }
@@ -21353,7 +21669,7 @@ function resolveFormat2(opts) {
   return opts.json ? "json" : "table";
 }
 function auditCommand() {
-  return new Command18("audit").description(
+  return new Command19("audit").description(
     "Show recent mutation/tokenization audit entries (leak-proof; JSONL with --json, RFC 4180 CSV with --format csv)"
   ).option("-l, --limit <n>", "Number of entries to show", "20").option("--json", "Output as JSONL (one JSON object per line, jq-pipeable)", false).option("--db <path>", "Path to the audit database (default: ~/.pretense/audit.db)").option(
     "--framework <name>",
@@ -21373,21 +21689,21 @@ function auditCommand() {
       framework = resolveFrameworkName(opts.framework);
       if (!framework) {
         console.error(
-          chalk17.red(`
+          chalk18.red(`
   x Unknown framework: "${opts.framework}"
-`) + chalk17.dim("  Run ") + chalk17.cyan("pretense audit --list-frameworks") + chalk17.dim(" to see all 36.\n")
+`) + chalk18.dim("  Run ") + chalk18.cyan("pretense audit --list-frameworks") + chalk18.dim(" to see all 36.\n")
         );
         process.exit(1);
       }
     }
     const limit = parseInt(opts.limit ?? "20", 10);
     if (!Number.isFinite(limit) || limit <= 0) {
-      console.error(chalk17.red(`
+      console.error(chalk18.red(`
   x Invalid --limit: "${opts.limit}". Provide a positive integer.
 `));
       process.exit(1);
     }
-    const dbPath = opts.db ?? join20(homedir10(), ".pretense", "audit.db");
+    const dbPath = opts.db ?? join21(homedir10(), ".pretense", "audit.db");
     let rows;
     try {
       const store = new AuditStore(dbPath);
@@ -21407,8 +21723,8 @@ function auditCommand() {
         console.error("pretense: no audit data \u2014 the audit database has not been initialized yet.");
         return;
       }
-      console.log(chalk17.dim("\n  No audit data available. The audit database has not been initialized yet."));
-      console.log(chalk17.dim("  Run " + chalk17.cyan("pretense start") + " and make some requests first.\n"));
+      console.log(chalk18.dim("\n  No audit data available. The audit database has not been initialized yet."));
+      console.log(chalk18.dim("  Run " + chalk18.cyan("pretense start") + " and make some requests first.\n"));
       return;
     }
     if (format === "csv") {
@@ -21420,23 +21736,23 @@ function auditCommand() {
       return;
     }
     if (rows.length === 0) {
-      console.log(chalk17.dim("\n  No audit entries yet. Run pretense start and make some requests.\n"));
+      console.log(chalk18.dim("\n  No audit entries yet. Run pretense start and make some requests.\n"));
       return;
     }
-    console.log(chalk17.cyan(`
+    console.log(chalk18.cyan(`
   Pretense Mutation Audit \u2014 last ${rows.length} entries
 `));
     console.log(
-      chalk17.dim(
+      chalk18.dim(
         "  " + "TIME".padEnd(10) + "ACTION".padEnd(12) + "PROVIDER".padEnd(14) + "MUTATED".padEnd(10) + "BLOCKED".padEnd(10) + "PII".padEnd(8) + "MS"
       )
     );
-    console.log(chalk17.dim("  " + "\u2500".repeat(72)));
+    console.log(chalk18.dim("  " + "\u2500".repeat(72)));
     for (const row of rows) {
       const time = new Date(row.timestamp).toTimeString().slice(0, 8);
-      const actionColor = row.action === "blocked" ? chalk17.red : row.action === "mutated" ? chalk17.green : row.action === "redacted" ? chalk17.yellow : row.action === "error" ? chalk17.red : chalk17.dim;
+      const actionColor = row.action === "blocked" ? chalk18.red : row.action === "mutated" ? chalk18.green : row.action === "redacted" ? chalk18.yellow : row.action === "error" ? chalk18.red : chalk18.dim;
       console.log(
-        "  " + chalk17.dim(time.padEnd(10)) + actionColor(row.action.padEnd(12)) + chalk17.dim(row.provider.padEnd(14)) + chalk17.green(String(row.mutationsApplied).padEnd(10)) + (row.secretsBlocked > 0 ? chalk17.red(String(row.secretsBlocked).padEnd(10)) : chalk17.dim("0".padEnd(10))) + chalk17.dim(String(row.piiRedacted).padEnd(8)) + chalk17.dim(String(row.scanDurationMs).slice(0, 5))
+        "  " + chalk18.dim(time.padEnd(10)) + actionColor(row.action.padEnd(12)) + chalk18.dim(row.provider.padEnd(14)) + chalk18.green(String(row.mutationsApplied).padEnd(10)) + (row.secretsBlocked > 0 ? chalk18.red(String(row.secretsBlocked).padEnd(10)) : chalk18.dim("0".padEnd(10))) + chalk18.dim(String(row.piiRedacted).padEnd(8)) + chalk18.dim(String(row.scanDurationMs).slice(0, 5))
       );
     }
     console.log();
@@ -21445,9 +21761,9 @@ function auditCommand() {
 
 // src/commands/credits.ts
 init_esm_shims();
-import { Command as Command19 } from "commander";
-import chalk18 from "chalk";
-import { join as join21 } from "path";
+import { Command as Command20 } from "commander";
+import chalk19 from "chalk";
+import { join as join24 } from "path";
 import { homedir as homedir11 } from "os";
 function remaining(used, limit) {
   if (limit === null) return null;
@@ -21457,16 +21773,16 @@ function fmt(n) {
   return n === null ? "unlimited" : n.toLocaleString("en-US");
 }
 function bar(used, limit, width = 24) {
-  if (limit === null) return chalk18.green("\u2588".repeat(width));
+  if (limit === null) return chalk19.green("\u2588".repeat(width));
   const pct = limit <= 0 ? 1 : Math.min(1, used / limit);
   const filled = Math.min(width, Math.round(pct * width));
   const s = "\u2588".repeat(filled) + "\u2591".repeat(width - filled);
-  if (pct >= 1) return chalk18.red(s);
-  if (pct >= 0.8) return chalk18.yellow(s);
-  return chalk18.green(s);
+  if (pct >= 1) return chalk19.red(s);
+  if (pct >= 0.8) return chalk19.yellow(s);
+  return chalk19.green(s);
 }
 function creditsCommand() {
-  return new Command19("credits").alias("tokens").description("Show remaining mutation budget for the current period").option("--db <path>", "Path to audit database", join21(homedir11(), ".pretense", "audit.db")).option("--json", "Output as JSON", false).option("--offline", "Do not contact the plan service to resolve the tier", false).action(async (opts) => {
+  return new Command20("credits").alias("tokens").description("Show remaining mutation budget for the current period").option("--db <path>", "Path to audit database", join24(homedir11(), ".pretense", "audit.db")).option("--json", "Output as JSON", false).option("--offline", "Do not contact the plan service to resolve the tier", false).action(async (opts) => {
     const resolution = await resolvePlanTier({ offline: opts.offline });
     const tier = resolution.tier;
     const collected = collectUsage(opts.db);
@@ -21479,7 +21795,7 @@ function creditsCommand() {
       periodEnd: null
     };
     if (!collected && !opts.json) {
-      console.log(chalk18.dim("\n  No usage recorded yet \u2014 showing your full allowance.\n"));
+      console.log(chalk19.dim("\n  No usage recorded yet \u2014 showing your full allowance.\n"));
     }
     const mutationLimit = tier ? PLAN_CONFIGS[tier].mutationsPerPeriod : null;
     const scanLimit = tier ? PLAN_CONFIGS[tier].scansPerPeriod : null;
@@ -21511,12 +21827,12 @@ function creditsCommand() {
       );
       return;
     }
-    console.log(chalk18.cyan("\n  Pretense Credits"));
-    console.log(chalk18.dim(`  Plan: ${tierLabel(tier)}  |  Resets: ${resetCadenceLabel()}
+    console.log(chalk19.cyan("\n  Pretense Credits"));
+    console.log(chalk19.dim(`  Plan: ${tierLabel(tier)}  |  Resets: ${resetCadenceLabel()}
 `));
     if (!tier) {
       for (const line of unverifiedNote(resolution.detail)) {
-        console.log(chalk18.yellow(`  ${line}`));
+        console.log(chalk19.yellow(`  ${line}`));
       }
       console.log();
       console.log("  " + "Mutations used".padEnd(20) + m.mutationsApplied.toLocaleString("en-US"));
@@ -21525,18 +21841,18 @@ function creditsCommand() {
       return;
     }
     console.log(
-      "  " + "Mutations".padEnd(14) + bar(m.mutationsApplied, mutationLimit) + "  " + chalk18.bold(fmt(mutationsLeft)) + chalk18.dim(` left of ${fmt(mutationLimit)}`)
+      "  " + "Mutations".padEnd(14) + bar(m.mutationsApplied, mutationLimit) + "  " + chalk19.bold(fmt(mutationsLeft)) + chalk19.dim(` left of ${fmt(mutationLimit)}`)
     );
     console.log(
-      "  " + "Requests".padEnd(14) + bar(m.totalScans, scanLimit) + "  " + chalk18.bold(fmt(scansLeft)) + chalk18.dim(` left of ${fmt(scanLimit)}`)
+      "  " + "Requests".padEnd(14) + bar(m.totalScans, scanLimit) + "  " + chalk19.bold(fmt(scansLeft)) + chalk19.dim(` left of ${fmt(scanLimit)}`)
     );
     if (tier !== "enterprise" && mutationLimit !== null && mutationsLeft === 0) {
       console.log(
-        chalk18.red("\n  Mutation budget exhausted for this period.") + chalk18.dim(" Run ") + chalk18.cyan("pretense upgrade") + chalk18.dim(" to compare plans.")
+        chalk19.red("\n  Mutation budget exhausted for this period.") + chalk19.dim(" Run ") + chalk19.cyan("pretense upgrade") + chalk19.dim(" to compare plans.")
       );
     } else if (tier !== "enterprise" && mutationLimit !== null && m.mutationsApplied >= mutationLimit * 0.8) {
       console.log(
-        chalk18.yellow("\n  Running low.") + chalk18.dim(" Run ") + chalk18.cyan("pretense upgrade") + chalk18.dim(" to compare plans.")
+        chalk19.yellow("\n  Running low.") + chalk19.dim(" Run ") + chalk19.cyan("pretense upgrade") + chalk19.dim(" to compare plans.")
       );
     }
     console.log();
@@ -21545,8 +21861,8 @@ function creditsCommand() {
 
 // src/commands/upgrade.ts
 init_esm_shims();
-import { Command as Command20 } from "commander";
-import chalk19 from "chalk";
+import { Command as Command21 } from "commander";
+import chalk20 from "chalk";
 var PRICING_URL = "https://pretense.ai/pricing";
 var TIERS = ["free", "pro", "enterprise"];
 function quota(n) {
@@ -21559,7 +21875,7 @@ function yesNo(b) {
   return b ? "yes" : "\u2014";
 }
 function upgradeCommand() {
-  return new Command20("upgrade").description("Compare Pretense plans and upgrade").option("--json", "Output as JSON", false).option("--offline", "Do not contact the plan service to resolve the tier", false).action(async (opts) => {
+  return new Command21("upgrade").description("Compare Pretense plans and upgrade").option("--json", "Output as JSON", false).option("--offline", "Do not contact the plan service to resolve the tier", false).action(async (opts) => {
     const resolution = await resolvePlanTier({ offline: opts.offline });
     const current = resolution.tier;
     if (opts.json) {
@@ -21587,11 +21903,11 @@ function upgradeCommand() {
       );
       return;
     }
-    console.log(chalk19.cyan("\n  Pretense Plans\n"));
+    console.log(chalk20.cyan("\n  Pretense Plans\n"));
     const col = 16;
     const header = "  " + "".padEnd(18) + TIERS.map((t) => tierName(t).padEnd(col)).join("");
-    console.log(chalk19.bold(header));
-    console.log("  " + chalk19.dim("\u2500".repeat(18 + col * TIERS.length)));
+    console.log(chalk20.bold(header));
+    console.log("  " + chalk20.dim("\u2500".repeat(18 + col * TIERS.length)));
     const rows = [
       ["Price", (t) => priceLabel(t)],
       ["Mutations/7d", (t) => quota(PLAN_CONFIGS[t].mutationsPerPeriod)],
@@ -21603,24 +21919,24 @@ function upgradeCommand() {
     for (const [label, cell] of rows) {
       console.log("  " + label.padEnd(18) + TIERS.map((t) => cell(t).padEnd(col)).join(""));
     }
-    console.log("  " + chalk19.dim("\u2500".repeat(18 + col * TIERS.length)));
+    console.log("  " + chalk20.dim("\u2500".repeat(18 + col * TIERS.length)));
     if (current) {
-      console.log(chalk19.dim(`
+      console.log(chalk20.dim(`
   Current plan: ${tierName(current)}`));
       if (current === "enterprise") {
-        console.log(chalk19.green("  You are on the highest tier \u2014 nothing to upgrade.\n"));
+        console.log(chalk20.green("  You are on the highest tier \u2014 nothing to upgrade.\n"));
         return;
       }
     } else {
       console.log(
-        chalk19.yellow(
+        chalk20.yellow(
           `
   Could not confirm your current plan: ${resolution.detail ?? "unknown reason"}.`
         )
       );
     }
     const from = current ?? "unknown";
-    console.log(chalk19.bold(`
+    console.log(chalk20.bold(`
   \u2192 ${PRICING_URL}?ref=cli_upgrade&from=${from}
 `));
   });
@@ -21653,34 +21969,35 @@ function findClosestCommand(input, knownCommands) {
   }
   return bestDist <= 3 ? best : null;
 }
-var program = new Command21();
-program.name("pretense").description(chalk20.bold("AI firewall") + " \u2014 mutates proprietary code before LLM API calls").version(PRETENSE_VERSION, "-v, --version").addHelpText("after", `
-${chalk20.bold("Quick start:")}
-  ${chalk20.cyan("pretense scan")} ${chalk20.dim("<file|dir>")}        Scan for secrets and PII
-  ${chalk20.cyan("pretense mutate")} ${chalk20.dim("<file>")}           Preview code mutations
-  ${chalk20.cyan("pretense init")}                   Scan codebase and build protection profile
+var program = new Command22();
+program.name("pretense").enablePositionalOptions().description(chalk21.bold("AI firewall") + " \u2014 mutates proprietary code before LLM API calls").version(PRETENSE_VERSION, "-v, --version").addHelpText("after", `
+${chalk21.bold("Quick start:")}
+  ${chalk21.cyan("pretense run claude")} ${chalk21.dim('"build X"')}     Run an AI tool through the proxy (zero setup)
+  ${chalk21.cyan("pretense mutate")} ${chalk21.dim("<file>")}           Mutate secrets in place (reverse with the same path)
+  ${chalk21.cyan("pretense scan")} ${chalk21.dim("<file|dir>")}        Scan for secrets and PII
 
-${chalk20.dim("All commands:")}
-  ${chalk20.cyan("pretense init")}                   Scan codebase and build protection profile
-  ${chalk20.cyan("pretense start")}                  Start proxy on localhost:9339
-  ${chalk20.cyan("pretense stop")}                   Stop the running proxy
-  ${chalk20.cyan("pretense scan src/api.ts")}        Scan file for secrets
-  ${chalk20.cyan("pretense scan ci")}                CI-optimized scan (exit 0=clean, 2=findings)
-  ${chalk20.cyan("pretense status")}                 Show protection status
-  ${chalk20.cyan("pretense review")}                 Preview mutations that would be applied
-  ${chalk20.cyan("pretense review --json")}          Output review as JSON
-  ${chalk20.cyan("pretense mutate f --map m.json")}  Mutate secrets + write reversal map
-  ${chalk20.cyan("pretense reverse f --map m.json")} Restore a mutated file
-  ${chalk20.cyan("pretense policy list")}            List the 5 compliance presets
-  ${chalk20.cyan("pretense audit")}                  Show mutation audit log
-  ${chalk20.cyan("pretense usage")}                  Plan usage vs limits
-  ${chalk20.cyan("pretense credits")}                Remaining mutation budget (alias: tokens)
-  ${chalk20.cyan("pretense upgrade")}                Compare plans / upgrade
-  ${chalk20.cyan("pretense auth login")}             Authenticate with Pretense
-  ${chalk20.cyan("pretense install")}                Install git hooks
-  ${chalk20.cyan("pretense logs --limit 20")}        Show recent audit entries
+${chalk21.dim("All commands:")}
+  ${chalk21.cyan("pretense init")}                   Scan codebase and build protection profile
+  ${chalk21.cyan("pretense run <tool>")}             Run an AI tool through the proxy, no manual export
+  ${chalk21.cyan("pretense start")}                  Start proxy on localhost:9339
+  ${chalk21.cyan("pretense stop")}                   Stop the running proxy
+  ${chalk21.cyan("pretense scan src/api.ts")}        Scan file for secrets
+  ${chalk21.cyan("pretense scan ci")}                CI-optimized scan (exit 0=clean, 2=findings)
+  ${chalk21.cyan("pretense status")}                 Show protection status
+  ${chalk21.cyan("pretense review")}                 Preview mutations that would be applied
+  ${chalk21.cyan("pretense review --json")}          Output review as JSON
+  ${chalk21.cyan("pretense mutate <file>")}          Mutate secrets in place + auto-write reversal map
+  ${chalk21.cyan("pretense reverse <file>")}         Restore a mutated file (auto-finds its map)
+  ${chalk21.cyan("pretense policy list")}            List the 5 compliance presets
+  ${chalk21.cyan("pretense audit")}                  Show mutation audit log
+  ${chalk21.cyan("pretense usage")}                  Plan usage vs limits
+  ${chalk21.cyan("pretense credits")}                Remaining mutation budget (alias: tokens)
+  ${chalk21.cyan("pretense upgrade")}                Compare plans / upgrade
+  ${chalk21.cyan("pretense auth login")}             Authenticate with Pretense
+  ${chalk21.cyan("pretense install")}                Install git hooks
+  ${chalk21.cyan("pretense logs --limit 20")}        Show recent audit entries
 
-${chalk20.dim("Run")} ${chalk20.cyan("pretense <command> --help")} ${chalk20.dim("for command-specific help.")}
+${chalk21.dim("Run")} ${chalk21.cyan("pretense <command> --help")} ${chalk21.dim("for command-specific help.")}
 `);
 var KNOWN_COMMANDS = [
   "init",
@@ -21699,6 +22016,8 @@ var KNOWN_COMMANDS = [
   "quickstart",
   "mutate",
   "reverse",
+  "run",
+  "with",
   "policy",
   "audit",
   "version",
@@ -21734,6 +22053,7 @@ program.addCommand(completionCommand());
 program.addCommand(quickstartCommand());
 program.addCommand(mutateCommand());
 program.addCommand(reverseCommand());
+program.addCommand(runCommand());
 program.addCommand(policyCommand());
 program.addCommand(auditCommand());
 program.addCommand(creditsCommand());
@@ -21741,13 +22061,13 @@ program.addCommand(upgradeCommand());
 program.on("command:*", (operands) => {
   const unknown = operands[0] ?? "";
   const suggestion = findClosestCommand(unknown, KNOWN_COMMANDS);
-  console.error(chalk20.red(`
+  console.error(chalk21.red(`
   x Unknown command: "${unknown}"`));
   if (suggestion) {
-    console.error(chalk20.yellow(`  Did you mean: ${chalk20.bold(`pretense ${suggestion}`)}`));
+    console.error(chalk21.yellow(`  Did you mean: ${chalk21.bold(`pretense ${suggestion}`)}`));
   }
-  console.error(chalk20.dim(`
-  Run ${chalk20.cyan("pretense --help")} to see all available commands.
+  console.error(chalk21.dim(`
+  Run ${chalk21.cyan("pretense --help")} to see all available commands.
 `));
   process.exit(1);
 });

package/dist/postinstall.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   PRETENSE_VERSION
-} from "./chunk-K3L4E6HN.js";
+} from "./chunk-2WW3XY6A.js";
 import {
   init_esm_shims
 } from "./chunk-TWMRHZGM.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pretense/cli",
-  "version": "0.6.12",
+  "version": "0.6.14",
   "description": "Local-first AI firewall that mutates proprietary code before sending to LLM APIs",
   "type": "module",
   "bin": {
@@ -23,8 +23,8 @@
     "tsx": "^4.0.0",
     "typescript": "^5.4.0",
     "vitest": "^1.0.0",
-    "@pretense/compliance-engine": "0.1.0",
     "@pretense/billing": "0.1.0",
+    "@pretense/compliance-engine": "0.1.0",
     "@pretense/protocol": "0.1.0",
     "@pretense/learner": "0.2.0",
     "@pretense/mutator": "0.2.0",