@compaction/cli 0.2.0 → 0.3.0

package/dist/cli/commands/capture.js

@@ -1,8 +1,110 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
 import chalk from "chalk";
 import { captureOpenAIAgentsCommand, captureOpenAIAgentsExport } from "../../core/openai-agents-capture.js";
-import { captureClaudeCodeCommand, discoverClaudeCodeCommand } from "./capture-claude-code.js";
+import { captureCodexCommand, captureCodexExport } from "../../core/codex-capture.js";
+import { captureCursorCommand, captureCursorExport } from "../../core/cursor-capture.js";
+import { gateCursorLiveRun } from "../cursor-live-preflight.js";
+import { readCursorExportFile } from "../cursor-export-read.js";
+import { buildRunFlowTokenReport, formatRunFlowTokenReport } from "../../core/run-flow-report.js";
+import { recordCaptureContentFree, captureTokenSource } from "../../core/capture-record.js";
+import { attachOutputShapingToCommand } from "../../core/output-shaping-attach.js";
+import { OUTPUT_SHAPING_HONESTY_NOTE } from "../../core/output-shaping.js";
+import { buildCaptureUsageSidecar } from "../../core/output-shaping-ab.js";
+import { resolveApiConfig } from "../../core/api-client/index.js";
+import { hostedConfigured } from "./optimize-hosted.js";
+import { describeTokenMetadata } from "../../core/usage-metadata.js";
+import { captureClaudeCodeCommand, captureClaudeCodeFromHook, captureClaudeCodeFromPromptHook, discoverClaudeCodeCommand } from "./capture-claude-code.js";
 import { captureProviderUsageCommand } from "./capture-provider-usage.js";
+import { bridgeCodexShimActivity, bridgeCursorShimActivity } from "../../core/shim-capture-bridge.js";
 import { DEFAULT_CREDENTIAL_ENV_VAR } from "../../core/provider-usage/provider-usage-adapter.js";
+/**
+ * Shared content-free `--from-shim` handler (the PATH-shim always-on bridge — charter 2026-07-04-run-9).
+ * Reads the shim's temp copy of the tool's OWN stdout, appends ONE metrics-only activity event, writes
+ * NO trace artifact and NO content. Best-effort + fail-open: a bad/missing file is a non-fatal skip so
+ * the transparent shim can never break the wrapped command. `commandParts` (Cursor only) carries the
+ * ORIGINAL invocation so input can be locally estimated (counted, never stored).
+ */
+async function handleCaptureFromShim(tool, fromShimPath, commandParts) {
+    let rawOutput;
+    try {
+        rawOutput = await readFile(fromShimPath, "utf8");
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        console.log(`compaction shim: skipped (non-fatal: could not read the captured output — ${message}).`);
+        return;
+    }
+    try {
+        if (tool === "codex") {
+            const { result, tokenMetadataStatus } = await bridgeCodexShimActivity({ rawOutput, cwd: process.cwd() });
+            const label = tokenMetadataStatus === "present" ? "provider-reported" : "usage unavailable (not invented)";
+            console.log(result.appended
+                ? `compaction shim: recorded metrics-only activity (surface=codex, ${label}, id ${result.activity_event_id.slice(0, 12)}…) — see 'compaction activity'.`
+                : `compaction shim: activity not appended (${result.reason}).`);
+        }
+        else {
+            const { result, outputStatus } = await bridgeCursorShimActivity({
+                rawOutput,
+                commandParts: commandParts.length > 0 ? commandParts : undefined,
+                cwd: process.cwd()
+            });
+            const label = `local-estimate; output ${outputStatus === "present" ? "local-estimate" : "unavailable"}`;
+            console.log(result.appended
+                ? `compaction shim: recorded metrics-only activity (surface=cursor, ${label}, id ${result.activity_event_id.slice(0, 12)}…) — see 'compaction activity'.`
+                : `compaction shim: activity not appended (${result.reason}).`);
+        }
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        console.log(`compaction shim: skipped (non-fatal: ${message}).`);
+    }
+}
+/**
+ * Apply the opt-in output-shaping flag to a wrapped command BEFORE generation (increment 3). Returns the
+ * (possibly modified) commandParts + console lines. Surfaces NO output-savings number — a savings figure
+ * requires the private measured-A/B + short-but-sufficient eval gate. Original command is never mutated.
+ */
+function applyOutputShapingFlag(commandParts, options) {
+    if (!options.outputShaping)
+        return { commandParts, lines: [], policyNames: [] };
+    const budget = options.verbosityBudget !== undefined ? Number.parseInt(options.verbosityBudget, 10) : undefined;
+    const policies = options.outputShapingPolicies
+        ? options.outputShapingPolicies.split(",").map((s) => s.trim()).filter(Boolean)
+        : undefined;
+    const att = attachOutputShapingToCommand(commandParts, {
+        ...(budget !== undefined && Number.isFinite(budget) ? { verbosityBudgetTokens: budget } : {}),
+        ...(policies ? { policies } : {})
+    });
+    const lines = att.attached
+        ? [
+            chalk.green(`  Attached output-shaping policy to the prompt BEFORE generation: ${att.applied.map((a) => a.policy_name).join(", ")}`),
+            chalk.gray(`  ${OUTPUT_SHAPING_HONESTY_NOTE}`)
+        ]
+        : [chalk.yellow(`  Output-shaping NOT attached: ${att.reason}.`)];
+    return { commandParts: att.commandParts, lines, policyNames: att.applied.map((a) => a.policy_name) };
+}
+/**
+ * Write a content-free `capture-usage.json` sidecar next to the capture artifact (operator-side evidence).
+ * It carries provider-reported token counts + honest source + (treatment) output-shaping policy names so a
+ * later `compaction output-shaping-ab add` can link this run into an A/B arm. NO content is written.
+ */
+async function writeCaptureUsageSidecar(outDir, tool, usage, policyNames) {
+    const sidecar = buildCaptureUsageSidecar({
+        tool,
+        ...(usage.provider ? { provider: usage.provider } : {}),
+        ...(usage.model ? { model: usage.model } : {}),
+        ...(typeof usage.input_tokens === "number" ? { inputTokens: usage.input_tokens } : {}),
+        ...(typeof usage.output_tokens === "number" ? { outputTokens: usage.output_tokens } : {}),
+        providerReported: usage.provider_reported_tokens === true,
+        tokenSource: captureTokenSource(usage),
+        tokenMetadataStatus: usage.provider_reported_tokens === true ? "present" : "missing",
+        ...(policyNames.length > 0 ? { policyNames } : {})
+    });
+    const sidecarPath = path.join(outDir, "capture-usage.json");
+    await writeFile(sidecarPath, JSON.stringify(sidecar, null, 2), "utf8");
+    return sidecarPath;
+}
 export function registerCaptureCommand(program) {
     const capture = program.command("capture").description("Capture local integration traces into compaction.dev AgentTrace format.");
     capture
@@ -26,6 +128,175 @@ export function registerCaptureCommand(program) {
             process.exitCode = 1;
         }
     });
+    capture
+        .command("codex")
+        .description("Capture a LIVE `codex exec --json` run (or a saved export) into AgentTrace — no manual import. " +
+        "Provider-reported tokens from turn.completed.usage; local only, no upload, no proxying.")
+        .option("--out <dir>", "Output directory for capture artifacts")
+        .option("--export <file>", "Read a saved `codex exec --json` JSONL export instead of running a command")
+        .option("--from-shim <file>", "INTERNAL (used by the connect-once PATH shim): read a captured `codex exec --json` output copy and append ONE metrics-only, CONTENT-FREE activity event (no trace artifact, no content). Fail-open.")
+        .option("--output-shaping", "Attach the output-shaping policy to the prompt BEFORE generation (opt-in; no savings claimed)")
+        .option("--verbosity-budget <tokens>", "Soft output-token budget for the output-shaping policy")
+        .option("--output-shaping-policies <names>", "Comma-separated output-shaping policy names (default: the default-on set)")
+        .argument("[commandParts...]", 'Command and args to execute after -- (e.g. -- codex exec --json "do X")')
+        .allowUnknownOption(true)
+        .action(async (commandPartsRaw, options) => {
+        // Always-on shim bridge: content-free, writes only a metrics-only activity event. Handled first,
+        // before any artifact-writing path, and before the "provide a command" guard.
+        if (options.fromShim) {
+            await handleCaptureFromShim("codex", options.fromShim, commandPartsRaw);
+            return;
+        }
+        console.log(chalk.cyan("compaction capture codex"));
+        console.log("Capturing a local codex exec --json run. No upload, no proxying. Review the artifact before sharing (it may contain code/output).");
+        if (!options.out) {
+            console.error("error: --out <dir> is required (except with --from-shim).");
+            process.exitCode = 1;
+            return;
+        }
+        if (!options.export && commandPartsRaw.length === 0) {
+            console.error('error: provide a command after -- (e.g. -- codex exec --json "do X") or use --export <file>.');
+            process.exitCode = 1;
+            return;
+        }
+        const outDir = options.out;
+        // Opt-in: attach the output-shaping policy to the prompt BEFORE generation (no savings claimed).
+        const shaped = applyOutputShapingFlag(commandPartsRaw, options);
+        for (const line of shaped.lines)
+            console.log(line);
+        const result = options.export
+            ? captureCodexExport(await readFile(options.export, "utf8"))
+            : await captureCodexCommand(shaped.commandParts);
+        await mkdir(outDir, { recursive: true });
+        const tracePath = path.join(outDir, "captured-trace.json");
+        await writeFile(tracePath, JSON.stringify(result.trace, null, 2), "utf8");
+        // Honest token labels: provider-reported (from turn.completed.usage) or honest missing — never invented.
+        for (const line of describeTokenMetadata(result.usageMetadata))
+            console.log(`  ${line}`);
+        for (const warning of result.warnings)
+            console.log(chalk.yellow(`  ! ${warning}`));
+        console.log(chalk.green(`Wrote ${tracePath}`));
+        // Content-free A/B evidence sidecar (provider-reported counts + policy names) for output-shaping-ab.
+        const usagePath = await writeCaptureUsageSidecar(outDir, "codex", result.usageMetadata, shaped.policyNames);
+        console.log(chalk.green(`Wrote ${usagePath}`));
+        // Unified flow: content-free record (input/output separate + honest source) when hosted-configured.
+        // No default network call — only when the user has set COMPACTION_API_URL + COMPACTION_API_KEY.
+        if (hostedConfigured()) {
+            const rec = await recordCaptureContentFree(resolveApiConfig(), { usage: result.usageMetadata, tool: "codex", reference: tracePath });
+            console.log(rec.recorded ? chalk.green(`  Recorded content-free usage (tool=codex, source=${rec.source}).`) : chalk.yellow(`  Not recorded: ${rec.reason}.`));
+        }
+        else {
+            console.log("  Not recorded (set COMPACTION_API_URL + COMPACTION_API_KEY to record content-free usage).");
+        }
+        console.log(`  Next: compaction compact ${tracePath} --eval --out <dir>`);
+        const exitCode = result.commandRun?.exitCode;
+        if (typeof exitCode === "number" && exitCode !== 0)
+            process.exitCode = exitCode;
+    });
+    capture
+        .command("cursor")
+        .description("Capture a LIVE Cursor headless CLI run (or saved output) into AgentTrace — no manual import. " +
+        "LOCAL-ESTIMATE tokens only (Cursor emits no usage); output counted from the result field where " +
+        "separable (use --output-format json), else marked unavailable. Local only, no upload, no SQLite.")
+        .option("--out <dir>", "Output directory for capture artifacts")
+        .option("--export <file>", "Read saved Cursor headless output (json / stream-json) instead of running a command")
+        .option("--from-shim <file>", "INTERNAL (used by the connect-once PATH shim): read a captured Cursor headless output copy and append ONE metrics-only, CONTENT-FREE activity event (local-estimate only, no trace artifact, no content). Fail-open.")
+        .option("--output-shaping", "Attach the output-shaping policy to the prompt BEFORE generation (opt-in; Cursor output is local-estimate, no savings)")
+        .option("--verbosity-budget <tokens>", "Soft output-token budget for the output-shaping policy")
+        .option("--output-shaping-policies <names>", "Comma-separated output-shaping policy names (default: the default-on set)")
+        .argument("[commandParts...]", 'Command and args after -- (e.g. -- cursor agent -p "do X" --output-format json)')
+        .allowUnknownOption(true)
+        .action(async (commandPartsRaw, options) => {
+        // Always-on shim bridge: content-free, writes only a metrics-only activity event (local-estimate).
+        // Handled first; the ORIGINAL invocation after -- lets input be locally estimated (counted, not stored).
+        if (options.fromShim) {
+            await handleCaptureFromShim("cursor", options.fromShim, commandPartsRaw);
+            return;
+        }
+        console.log(chalk.cyan("compaction capture cursor"));
+        console.log("Capturing a local Cursor headless run. LOCAL-ESTIMATE tokens only (Cursor emits no provider usage). No upload, no SQLite. Review the artifact before sharing.");
+        if (!options.out) {
+            console.error("error: --out <dir> is required (except with --from-shim).");
+            process.exitCode = 1;
+            return;
+        }
+        if (!options.export && commandPartsRaw.length === 0) {
+            console.error('error: provide a command after -- (e.g. -- cursor agent -p "do X" --output-format json) or use --export <file>.');
+            process.exitCode = 1;
+            return;
+        }
+        // LIVE path (no --export): run the SAFE preflight FIRST (CLI-presence + capability only; never a
+        // real prompt, never `cursor agent login`, never a CURSOR_API_KEY read). If the CLI is missing or
+        // not capable, print exact guidance and STOP before spawning — no opaque failure, no crash.
+        if (!options.export) {
+            const ready = await gateCursorLiveRun();
+            if (!ready) {
+                process.exitCode = 1;
+                return;
+            }
+        }
+        // Opt-in: attach the output-shaping policy to the prompt BEFORE generation. Cursor output stays
+        // local-estimate (no provider usage) → shaping never yields a savings number for Cursor.
+        const shaped = applyOutputShapingFlag(commandPartsRaw, options);
+        for (const line of shaped.lines)
+            console.log(line);
+        // Export path: read the saved output HONESTLY (a missing/unreadable file is an actionable error,
+        // never a raw errno, never a fabricated capture). Pass the RAW declared command (if the operator
+        // provided one after --) so the LOCAL-ESTIMATE input count matches `run cursor --export` exactly;
+        // shaped parts are NOT used here — nothing was executed, so no shaping was actually attached.
+        let result;
+        if (options.export) {
+            const exportRead = await readCursorExportFile(options.export);
+            if (!exportRead.ok) {
+                for (const line of exportRead.errorLines)
+                    console.error(line);
+                process.exitCode = 1;
+                return;
+            }
+            result = captureCursorExport(exportRead.rawOutput, commandPartsRaw.length > 0 ? commandPartsRaw : undefined);
+        }
+        else {
+            result = await captureCursorCommand(shaped.commandParts);
+        }
+        const outDir = options.out;
+        await mkdir(outDir, { recursive: true });
+        const tracePath = path.join(outDir, "captured-trace.json");
+        await writeFile(tracePath, JSON.stringify(result.trace, null, 2), "utf8");
+        // Print the SAME honest per-field token block `run cursor` prints (input/output SEPARATE, source
+        // explicit, an unavailable axis carries its TRUE per-run reason) — never a bare
+        // "input tokens: unknown" with no reason, never a fabricated count, never provider-reported.
+        const cursorTokenReport = buildRunFlowTokenReport({
+            tool: "cursor",
+            usage: result.usageMetadata,
+            outputStatus: result.outputStatus
+        });
+        const cursorReasons = { input: result.inputUnavailableReason, output: result.outputUnavailableReason };
+        // `capture` does not compact — no input-reduction figures follow, so that line is omitted.
+        const cursorTokenLines = formatRunFlowTokenReport(cursorTokenReport, {
+            reasons: cursorReasons,
+            inputReductionFollows: false
+        });
+        for (const line of cursorTokenLines)
+            console.log(`  ${line}`);
+        for (const warning of result.warnings)
+            console.log(chalk.yellow(`  ! ${warning}`));
+        console.log(chalk.green(`Wrote ${tracePath}`));
+        // Content-free sidecar. Cursor is local-estimate (providerReported=false) → A/B treats it as
+        // unavailable for a provider-reported savings number; it can never produce a confirmed claim.
+        const usagePath = await writeCaptureUsageSidecar(outDir, "cursor", result.usageMetadata, shaped.policyNames);
+        console.log(chalk.green(`Wrote ${usagePath}`));
+        if (hostedConfigured()) {
+            const rec = await recordCaptureContentFree(resolveApiConfig(), { usage: result.usageMetadata, tool: "cursor", reference: tracePath });
+            console.log(rec.recorded ? chalk.green(`  Recorded content-free usage (tool=cursor, source=${rec.source}).`) : chalk.yellow(`  Not recorded: ${rec.reason}.`));
+        }
+        else {
+            console.log("  Not recorded (set COMPACTION_API_URL + COMPACTION_API_KEY to record content-free usage).");
+        }
+        console.log(`  Next: compaction compact ${tracePath} --eval --out <dir>`);
+        const exitCode = result.commandRun?.exitCode;
+        if (typeof exitCode === "number" && exitCode !== 0)
+            process.exitCode = exitCode;
+    });
     capture
         .command("claude-code")
         .description("Capture a Claude Code session JSONL file into compaction.dev AgentTrace format (source: real_captured). Local only — no network calls, no upload.")
@@ -35,7 +306,18 @@ export function registerCaptureCommand(program) {
         .option("--out <dir>", "Output directory for captured artifacts (default: .compaction/runs/<session-id-prefix>/)")
         .option("--max-tool-result-chars <N>", "Maximum characters to extract from each tool result before truncation (default: 32000)")
         .option("--include-subagents", "Include subagent JSONL files from <session-id>/subagents/ directory, merging their messages and usage into the captured trace")
+        .option("--from-hook", "Read a Claude Code Stop payload from stdin and record CONTENT-FREE usage via its transcript_path (used by `compaction hooks install`). Fail-open, idempotent.")
+        .option("--from-prompt-hook", "BEFORE-CALL (run-13): read a Claude Code UserPromptSubmit payload from stdin and record a CONTENT-FREE before-call RECOMMENDATION (used by the UserPromptSubmit hook). Recommendation-only (apply is a proven blocker on this surface); the prompt runs unchanged. Fail-open, silent (no stdout).")
+        .option("--dry-run", "With --from-hook: print what would be recorded without writing anything.")
         .action(async (options) => {
+        if (options.fromPromptHook) {
+            await captureClaudeCodeFromPromptHook();
+            return;
+        }
+        if (options.fromHook) {
+            await captureClaudeCodeFromHook({ dryRun: options.dryRun });
+            return;
+        }
         if (options.discover) {
             await discoverClaudeCodeCommand({ projectsDir: options.projectsDir });
             return;

package/dist/cli/commands/compact.js

@@ -109,11 +109,12 @@ export function registerCompactCommand(program) {
         .description("Compact a trace and write local artifacts.")
         .action(async (traceFile, options) => {
         await runEngineCommand(async () => {
-            // Lazy-load the proprietary engine: present in-repo/API, excluded from the public package.
-            // When absent, runEngineCommand prints the boundary message and exits cleanly (no stack trace).
-            const { writeCompactionArtifacts } = await import("../../engine/compaction-artifacts.js");
-            const { applyCompactionPolicy } = await import("../../engine/policy-middleware.js");
-            const { evaluateCompactionResult, evaluateStrongCompactionResult, formatStrongEvalMarkdownReport } = await import("../../engine/eval-harness.js");
+            // Basic deterministic compaction is PUBLIC (src/core): the transform + policy application +
+            // artifact writing ship in the npm package, so `compact` works with no private engine build.
+            // Only `--eval` (deterministic recoverability/strong eval) lazy-loads the private engine below;
+            // when the engine is absent, runEngineCommand prints the boundary message and exits cleanly.
+            const { writeCompactionArtifacts } = await import("../../core/compaction-artifacts.js");
+            const { applyCompactionPolicy } = await import("../../core/policy-middleware.js");
             const trace = await parseTraceFile(traceFile);
             const reviewerType = options.reviewer;
             const reviewSummaryPresent = typeof options.reviewSummary === "string" && options.reviewSummary.length > 0;
@@ -189,6 +190,9 @@ export function registerCompactCommand(program) {
             // (no disk round-trip, no hand-assembled bundle) and print the combined summary. Fail closed:
             // a failing recoverability verdict exits non-zero, identical to standalone `compaction eval`.
             if (options.eval === true) {
+                // The recoverability/strong eval stays PRIVATE (src/engine): lazy-loaded only when --eval is
+                // requested, so basic compaction above never needs the engine. Absent engine ⇒ clean degrade.
+                const { evaluateCompactionResult, evaluateStrongCompactionResult, formatStrongEvalMarkdownReport } = await import("../../engine/eval-harness.js");
                 const evalResult = evaluateCompactionResult(trace, policyResult, runId);
                 printCombinedEvalSummary(evalResult);
                 // Strong eval (Tracks B/C/D): commitment-preservation recoverability + fixture task-check +

package/dist/cli/commands/dev.d.ts

@@ -0,0 +1,17 @@
+import { Command } from "commander";
+export interface RunThroughGatewayOptions {
+    provider?: string;
+    upstream?: string;
+    listen?: string;
+}
+/**
+ * Run `command` through the local Compaction Gateway. Shared by `gateway run` (the public gateway-native
+ * form) and the hidden `dev` compatibility alias — `label` only changes the message prefix + usage hint.
+ * Calls `process.exit(code)` with the child's exit code (so it is a terminal action).
+ */
+export declare function runThroughGateway(command: string[], options: RunThroughGatewayOptions, label?: string): Promise<void>;
+/**
+ * Register the hidden `dev` compatibility alias. The PUBLIC gateway-native form is `gateway run`
+ * (registered in gateway.ts); `dev` is kept for backward compatibility and hidden from top-level help.
+ */
+export declare function registerDevCommand(program: Command): void;

package/dist/cli/commands/dev.js

@@ -0,0 +1,131 @@
+/**
+ * Gateway-native "run a workflow through the gateway" runner (PUBLIC CLI). Charter run-17.1 / run-18A.
+ *
+ * The public gateway-native entry point is `compaction gateway run -- <command>`. `compaction dev -- …`
+ * remains as a hidden compatibility alias (same behavior). Both call `runThroughGateway`.
+ *
+ * Runs any command with its OpenAI base URL pointed at the local Compaction Gateway, so an
+ * OpenAI-compatible app/SDK routes through Compaction with NO manual baseURL copy-paste:
+ *   compaction gateway run -- npm run dev
+ *   compaction gateway run -- node app.js
+ *
+ * Behavior: start (or REUSE) the local gateway → inject the gateway endpoint env into the child (never a
+ * key) → run the child with stdio inherited (stdout/stderr/stdin pass through UNCHANGED) → exit with the
+ * child's exit code → print a content-free "traffic observed" summary (receipts recorded during this run).
+ * It NEVER reads/stores a provider key, NEVER mutates files, and NEVER mutates requests/responses.
+ */
+import { spawn } from "node:child_process";
+import { runGatewayStart, parseListen } from "./gateway.js";
+import { getGatewayStatus, readReceipts } from "../../core/gateway/status.js";
+import { summarizeCacheProof } from "../../core/gateway/cache-proof.js";
+import { formatFreshBilledInputReduction } from "../../core/gateway/receipt.js";
+/** The OpenAI-compatible base-url env vars the SDKs read. We set the base only — never a key. */
+function injectionEnv(base) {
+    const v1 = `${base}/v1`;
+    return { OPENAI_BASE_URL: v1, OPENAI_API_BASE: v1 };
+}
+/** True when SOME provider key is present in the environment (we never read its value). */
+function hasProviderKey(env) {
+    return Boolean((env.OPENAI_API_KEY && env.OPENAI_API_KEY.trim()) || (env.OPENAI_KEY && env.OPENAI_KEY.trim()));
+}
+/**
+ * Run `command` through the local Compaction Gateway. Shared by `gateway run` (the public gateway-native
+ * form) and the hidden `dev` compatibility alias — `label` only changes the message prefix + usage hint.
+ * Calls `process.exit(code)` with the child's exit code (so it is a terminal action).
+ */
+export async function runThroughGateway(command, options, label = "compaction gateway run") {
+    const parts = command ?? [];
+    if (parts.length === 0) {
+        console.error(`error: no command given. Usage: ${label} -- <command>   (e.g. ${label} -- npm run dev)`);
+        process.exitCode = 1;
+        return;
+    }
+    const cwd = process.cwd();
+    const provider = options.provider ?? "openai";
+    const upstream = options.upstream ?? "https://api.openai.com/v1";
+    // Reuse a gateway already running in this project, else start our own (ephemeral, quiet).
+    const status = await getGatewayStatus(cwd);
+    let base;
+    let ownGateway = null;
+    if (status.running && status.base) {
+        base = status.base;
+        console.error(`${label}: reusing the running gateway at ${base}`);
+        // Honest note: this runner itself always starts in RECORD; if it reuses a gateway the user explicitly
+        // started in a mutating mode, say so plainly (it does not silently change that mode).
+        if (status.mode && status.mode !== "record") {
+            console.error(`${label}: note — the reused gateway is running in '${status.mode}' mode (you started it explicitly); this is not changing that.`);
+        }
+    }
+    else {
+        const port = options.listen ? parseListen(options.listen).port : 0; // 0 → ephemeral (no port conflicts)
+        try {
+            const g = await runGatewayStart({ provider, upstream, mode: "record", host: "127.0.0.1", port, cwd, installSignals: false, log: () => { } });
+            base = g.base;
+            ownGateway = g;
+            console.error(`${label}: started a local gateway at ${base} (record mode; byte-safe; content-free receipts)`);
+        }
+        catch (err) {
+            console.error(`error: could not start a local gateway — ${err.message}`);
+            process.exitCode = 1;
+            return;
+        }
+    }
+    const childEnv = { ...process.env, ...injectionEnv(base) };
+    console.error(`${label}: routing → OPENAI_BASE_URL=${base}/v1  (your provider key stays on the child; the gateway never stores it)`);
+    if (!hasProviderKey(process.env)) {
+        console.error(`${label}: Gateway is ready, but the child process still needs its provider API key (e.g. OPENAI_API_KEY). Compaction never injects or stores keys.`);
+    }
+    // Snapshot receipts so we can report ONLY the traffic observed during this run (content-free).
+    const before = new Set(readReceipts(cwd).map((r) => r.receipt_id));
+    const child = spawn(parts[0], parts.slice(1), { stdio: "inherit", env: childEnv, cwd });
+    const code = await new Promise((resolve) => {
+        child.on("exit", (c, signal) => resolve(typeof c === "number" ? c : signal ? 1 : 0));
+        child.on("error", (err) => {
+            console.error(`${label}: failed to run '${parts[0]}' — ${err.message}`);
+            resolve(127);
+        });
+    });
+    if (ownGateway) {
+        try {
+            await ownGateway.close();
+        }
+        catch {
+            /* best-effort */
+        }
+    }
+    // Content-free traffic summary: only the receipts recorded during this run.
+    const observed = readReceipts(cwd).filter((r) => !before.has(r.receipt_id));
+    console.error("");
+    if (observed.length > 0) {
+        const summary = summarizeCacheProof(observed);
+        console.error(`${label}: ✓ traffic observed through Compaction — ${observed.length} request(s) this run.`);
+        console.error(`  best provider-backed fresh/billed input reduction:  ${formatFreshBilledInputReduction(summary.bestReduction)}`);
+        console.error("  run 'compaction gateway status' for the full content-free rollup.");
+    }
+    else {
+        console.error(`${label}: ○ no requests were observed through Compaction this run.`);
+        console.error("  If your app has its own OpenAI base URL configured, it may have bypassed OPENAI_BASE_URL.");
+        console.error("  Point your client at the injected base URL, or use 'compaction gateway configure' to set it.");
+    }
+    process.exit(code);
+}
+/**
+ * Register the hidden `dev` compatibility alias. The PUBLIC gateway-native form is `gateway run`
+ * (registered in gateway.ts); `dev` is kept for backward compatibility and hidden from top-level help.
+ */
+export function registerDevCommand(program) {
+    program
+        .command("dev")
+        .description("Compatibility alias for 'compaction gateway run -- <command>'. Runs a command with its OpenAI base " +
+        "URL pointed at the local Compaction Gateway (starts/reuses the gateway, injects the endpoint — never " +
+        "a key, streams output unchanged, preserves the exit code, prints a content-free traffic summary).")
+        .option("--provider <name>", "Provider (OpenAI-compatible only).", "openai")
+        .option("--upstream <url>", "Upstream provider base URL.", "https://api.openai.com/v1")
+        .option("--listen <url>", "Local listen address when starting a gateway (default: an ephemeral local port).")
+        .argument("[command...]", "The command to run through the gateway (after --), e.g. -- npm run dev")
+        .allowUnknownOption(true)
+        .action(async (command, options) => {
+        await runThroughGateway(command, options, "compaction dev");
+    });
+}
+//# sourceMappingURL=dev.js.map

package/dist/cli/commands/gateway.d.ts

@@ -0,0 +1,31 @@
+import { Command } from "commander";
+import { type GatewayServerMode } from "../../core/gateway/server.js";
+/** Parse `--listen http://127.0.0.1:8787` (or `127.0.0.1:8787`) into host + port. */
+export declare function parseListen(listen: string): {
+    host: string;
+    port: number;
+};
+export interface GatewayStartConfig {
+    provider: string;
+    upstream: string;
+    mode: GatewayServerMode;
+    /** Deterministic apply policy (required for apply/dry-run). Only `deterministic-dedupe` is implemented. */
+    policy?: string;
+    host: string;
+    port: number;
+    cwd?: string;
+    log?: (line: string) => void;
+    /** Install SIGINT/SIGTERM handlers that close the server + remove the pidfile (default true). */
+    installSignals?: boolean;
+}
+export interface RunningGateway {
+    base: string;
+    close: () => Promise<void>;
+}
+/**
+ * Start the gateway from a validated config: bind the server, write the content-free pidfile (so
+ * `status`/`stop` work), print the honest banner, and install shutdown handlers that remove the pidfile.
+ * Reused by both `gateway start` and the guided onboarding. Throws on bind failure (the caller reports it).
+ */
+export declare function runGatewayStart(config: GatewayStartConfig): Promise<RunningGateway>;
+export declare function registerGatewayCommand(program: Command): void;