@compaction/cli 0.2.0 → 0.3.1

package/dist/cli/commands/capture-claude-code.js

@@ -1,6 +1,18 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
 import { writeJsonArtifact, writeTextArtifact } from "../../core/artifact-writer.js";
 import { ClaudeCodeAdapter, PRIVACY_WARNING } from "../../core/adapters/claude-code-adapter.js";
 import { discoverClaudeCodeSessions, DISCOVERY_PRIVACY_NOTE } from "../../core/adapters/claude-code-discovery.js";
+import { recordCaptureContentFree } from "../../core/capture-record.js";
+import { buildRunFlowTokenReport, formatRunFlowTokenReport } from "../../core/run-flow-report.js";
+import { buildRunCrossSurfaceEvent } from "../../core/cross-surface-event.js";
+import { buildMeasureOnlyActivityEvent } from "../../core/activity-event.js";
+import { appendActivityEvent } from "../../core/activity-store.js";
+import { detectAvoidableContext } from "../../core/before-call.js";
+import { parseUserPromptSubmitPayload, buildClaudeCodeBeforeCallEvent } from "../../core/claude-code-before-call.js";
+import { resolveApiConfig } from "../../core/api-client/index.js";
+import { hostedConfigured } from "./optimize-hosted.js";
+import { buildClaudeCodeHookRecord, computeDedupKey, emptyLedger, isAlreadyRecorded, parseStopPayload, resolveTranscriptPath } from "../../core/claude-code-hook-record.js";
 function buildOutputDir(sessionPath, out) {
     if (out)
         return out;
@@ -120,6 +132,16 @@ export async function captureClaudeCodeCommand(options) {
         console.log("      figures shown by 'spend' and 'compact' are deterministic LOCAL ESTIMATES (chars/4) — a");
         console.log("      different measurement, labeled there as local estimates; neither figure is billing-confirmed.");
     }
+    // 6b-iii. Shared UNIFIED-FLOW honest token report (docs/design/unified-run-flow.md, D1/D3): the SAME
+    // block that `run codex` / `run cursor` print, so all three tools present ONE honest `token_source`
+    // summary. Claude Code usage is PROVIDER-REPORTED and whole (no per-field unavailable split, like
+    // Codex), so outputStatus is "present"; when a session lacks provider usage the shared builder honestly
+    // downgrades to local-estimate / unavailable — it never labels anything stronger than the evidence. This
+    // is a reporting surface only: input/output are shown SEPARATELY with an explicit source, and output is
+    // shown as TOKENS ONLY (never a saving). No logic, adapter, or record behavior changes here.
+    const runFlowReport = buildRunFlowTokenReport({ tool: "claude-code", usage, outputStatus: "present" });
+    for (const line of formatRunFlowTokenReport(runFlowReport))
+        console.log(line);
     // 6c. Per-run distinctness fingerprint (a one-way digest over canonical normalized
     // content — NOT raw content). Lets a re-capture of the same session be told apart
     // from a genuinely new one; when unavailable, distinctness is `not_verified`.
@@ -138,6 +160,20 @@ export async function captureClaudeCodeCommand(options) {
     await writeTextArtifact(outDir, "capture-report.md", markdownReport);
     // 7. Print artifacts written
     console.log(`Artifacts written to: ${outDir}/`);
+    // Unified flow (docs/design/unified-run-flow.md): content-free record (input/output separate +
+    // honest source) when hosted-configured. No default network call — only when COMPACTION_API_URL +
+    // COMPACTION_API_KEY are set. Claude Code session usage is provider-reported.
+    if (hostedConfigured()) {
+        const rec = await recordCaptureContentFree(resolveApiConfig(), {
+            usage,
+            tool: "claude-code",
+            reference: `${outDir}/captured-trace.json`
+        });
+        console.log(rec.recorded ? `Recorded content-free usage (tool=claude-code, source=${rec.source}).` : `Not recorded: ${rec.reason}.`);
+    }
+    else {
+        console.log("Not recorded (set COMPACTION_API_URL + COMPACTION_API_KEY to record content-free usage).");
+    }
     // 8. Print next step — chain into the verified strong-MVP Claude Code flow:
     //    spend (where the spend goes) → compact --eval (compaction + strong apply-readiness:
     //    deterministic recoverability + commitment-preservation + fixture task-check + token/cost).
@@ -151,6 +187,176 @@ export async function captureClaudeCodeCommand(options) {
     console.log("     # fixture task-check, and token/cost accounting — nothing is applied automatically.");
     console.log(`  (or: compaction analyze ${outDir}/captured-trace.json   for a quick read-only estimate)`);
 }
+async function readAllStdin() {
+    if (process.stdin.isTTY)
+        return "";
+    const chunks = [];
+    for await (const chunk of process.stdin)
+        chunks.push(Buffer.from(chunk));
+    return Buffer.concat(chunks).toString("utf8");
+}
+async function defaultHookNormalize(transcriptPath) {
+    const adapter = new ClaudeCodeAdapter();
+    const { trace, usage, provenance } = await adapter.normalize({ sourcePath: transcriptPath });
+    return {
+        usage,
+        messageCount: trace.messages.length,
+        ...(provenance.traceFingerprint ? { fingerprint: provenance.traceFingerprint.content_sha256 } : {})
+    };
+}
+function hookDir(cwd) {
+    return path.join(cwd, ".compaction", "hooks", "claude-code");
+}
+async function loadLedger(cwd) {
+    try {
+        const raw = await readFile(path.join(hookDir(cwd), "ledger.json"), "utf8");
+        const parsed = JSON.parse(raw);
+        return Array.isArray(parsed.entries) ? parsed : emptyLedger();
+    }
+    catch {
+        return emptyLedger();
+    }
+}
+/**
+ * Append ONE metrics-only activity event for a Stop-hook capture (the always-on bridge). Builds the
+ * `claude_code` cross-surface event from the SAME honest token report the record uses, then the
+ * measure-only activity extension, and appends it to `.compaction/activity/` under the hook's cwd
+ * (so tmp-cwd tests and real projects both scope correctly). Content-free and best-effort: any
+ * local failure is swallowed here so it can NEVER break the fail-open hook.
+ */
+async function appendClaudeCodeHookActivity(input) {
+    try {
+        // outputStatus "present": buildRunFlowTokenReport honestly downgrades a missing output axis to
+        // unavailable — a genuinely-absent field is never labeled provider-reported (no silent zero).
+        const tokenReport = buildRunFlowTokenReport({ tool: "claude-code", usage: input.usage, outputStatus: "present" });
+        const crossSurfaceEvent = buildRunCrossSurfaceEvent("claude_code", {
+            // run_id is the deterministic content-free dedup key → deterministic activity_event_id → the
+            // store dedupes a re-captured session (same state = one event).
+            runId: `claude-code-${input.dedupKey}`,
+            tokenReport,
+            reasons: {
+                input: "the Claude Code session usage did not report input tokens for this session state",
+                output: "the Claude Code session usage did not report output tokens for this session state"
+            },
+            ...(input.usage.model ? { modelLabel: input.usage.model } : {})
+        });
+        // session_id rides on the event too (content-free identity), when the Stop payload carried one.
+        const eventWithSession = input.sessionId
+            ? { ...crossSurfaceEvent, session_id: input.sessionId }
+            : crossSurfaceEvent;
+        // Measurement only: nothing was applied or retained by Compaction, so original_retained=false.
+        const activityEvent = buildMeasureOnlyActivityEvent(eventWithSession, { original_retained: false });
+        const result = await appendActivityEvent(activityEvent, path.join(input.cwd, ".compaction", "activity"));
+        console.log(result.appended
+            ? `compaction hook: recorded metrics-only activity (surface=claude_code, id ${result.activity_event_id.slice(0, 12)}…) — see 'compaction activity'.`
+            : `compaction hook: activity not appended (${result.reason}).`);
+    }
+    catch {
+        // Best-effort local append — never fail the fail-open hook on a filesystem/store error.
+    }
+}
+/**
+ * `compaction capture claude-code --from-hook`. Reads the Stop payload from stdin, resolves the session
+ * JSONL via `transcript_path`, and records CONTENT-FREE usage only — never message content, never
+ * `last_assistant_message`. Idempotent via a content-free dedup ledger. FAIL-OPEN by contract: any error is
+ * swallowed and the process exits 0 so the hook can never break Claude Code.
+ */
+export async function captureClaudeCodeFromHook(options = {}, deps = {}) {
+    const cwd = deps.cwd ?? process.cwd();
+    const now = deps.now ?? (() => new Date().toISOString());
+    const readStdin = deps.readStdin ?? readAllStdin;
+    const normalize = deps.normalize ?? defaultHookNormalize;
+    const hostedIsConfigured = deps.hostedConfigured ?? hostedConfigured;
+    try {
+        const payload = parseStopPayload(await readStdin());
+        const transcriptPath = resolveTranscriptPath(payload);
+        if (!transcriptPath) {
+            console.log("compaction hook: no transcript_path in the Stop payload — nothing recorded (content-free).");
+            return;
+        }
+        const sessionId = typeof payload?.session_id === "string" ? payload.session_id : undefined;
+        const { usage, messageCount, fingerprint } = await normalize(transcriptPath);
+        const dedupKey = computeDedupKey({
+            sessionId,
+            fingerprint,
+            messageCount,
+            inputTokens: typeof usage.input_tokens === "number" ? usage.input_tokens : null,
+            outputTokens: typeof usage.output_tokens === "number" ? usage.output_tokens : null
+        });
+        const ledger = await loadLedger(cwd);
+        if (isAlreadyRecorded(ledger, dedupKey)) {
+            console.log(`compaction hook: already recorded this session state (dedup ${dedupKey.slice(0, 8)}…) — skipped.`);
+            return;
+        }
+        const record = buildClaudeCodeHookRecord({ usage, ...(sessionId ? { sessionId } : {}), messageCount, dedupKey, recordedAt: now() });
+        if (options.dryRun) {
+            console.log("compaction hook --dry-run: would record (content-free, nothing written):");
+            console.log(JSON.stringify(record, null, 2));
+            return;
+        }
+        const dir = hookDir(cwd);
+        await mkdir(path.join(dir, "records"), { recursive: true });
+        await writeFile(path.join(dir, "records", `${dedupKey}.json`), `${JSON.stringify(record, null, 2)}\n`, "utf8");
+        ledger.entries.push({ dedupKey, ...(sessionId ? { sessionId } : {}), recordedAt: record.recordedAt });
+        await writeFile(path.join(dir, "ledger.json"), `${JSON.stringify(ledger, null, 2)}\n`, "utf8");
+        console.log(`compaction hook: recorded content-free usage (source=${record.tokenSource}, dedup ${dedupKey.slice(0, 8)}…).`);
+        // ALWAYS-ON BRIDGE (charter 2026-07-04-run-8): the Stop hook runs this command at session end,
+        // so the SAME content-free usage ALSO appends ONE metrics-only activity event to the local
+        // activity store (.compaction/activity/). THIS is what makes a subsequent Claude Code session
+        // appear in `compaction activity` with NO manual import. Honesty: surface "claude_code",
+        // provider "anthropic", token axes copied VERBATIM from the SAME token report (provider-reported
+        // where the session usage carried them, else unavailable-with-reason — never a silent zero);
+        // measure-only, so approval "not-required", auto_apply OFF (not eligible, "ask-each-time",
+        // applied_automatically false — no auto-apply logic exists), sync "local-only", recovery
+        // original_retained=false (measurement only — Compaction modified/retained nothing). The event
+        // id is DETERMINISTIC from session state (run_id = the content-free dedup key), so a re-captured
+        // session yields the SAME id and the store dedupes it. Best-effort + content-free; a local
+        // filesystem failure here never breaks the hook.
+        await appendClaudeCodeHookActivity({ cwd, usage, dedupKey, sessionId });
+        if (hostedIsConfigured()) {
+            const rec = await recordCaptureContentFree(resolveApiConfig(), { usage, tool: "claude-code", reference: `hook:${dedupKey}` });
+            console.log(rec.recorded ? `compaction hook: also recorded to hosted (source=${rec.source}).` : `compaction hook: hosted not recorded: ${rec.reason}.`);
+        }
+    }
+    catch (error) {
+        // FAIL-OPEN: never propagate — the hook must not break Claude Code.
+        const message = error instanceof Error ? error.message : String(error);
+        console.log(`compaction hook: skipped (non-fatal: ${message}).`);
+    }
+}
+/**
+ * `compaction capture claude-code --from-prompt-hook` — the BEFORE-CALL recommendation path (charter
+ * 2026-07-04-run-13). The Claude Code **UserPromptSubmit** hook runs this BEFORE the model processes the
+ * prompt (a genuine pre-call event — NOT the post-session Stop hook). It reads the UserPromptSubmit
+ * payload from stdin, analyzes the pending PROMPT for avoidable duplicated context IN-PROCESS
+ * (content-free), and — when present — records ONE metrics-only `claude_code` before-call RECOMMENDATION
+ * activity event so it appears in `compaction activity`. Apply is a PROVEN BLOCKER on this surface (no
+ * hook can reduce the model's context; hooks are non-interactive) → recommendation-only; the original
+ * prompt ALWAYS runs UNCHANGED.
+ *
+ * CRITICAL: this path writes NOTHING to stdout — on UserPromptSubmit, a hook's stdout is ADDED to the
+ * model's context, so injecting anything would be both intrusive and self-defeating for a compaction
+ * tool. It is silent and transparent; the recommendation lives in `compaction activity`. FAIL-OPEN +
+ * CONTENT-FREE: any error is swallowed and the process exits 0; the prompt text is never persisted.
+ */
+export async function captureClaudeCodeFromPromptHook(deps = {}) {
+    const readStdin = deps.readStdin ?? readAllStdin;
+    try {
+        const payload = parseUserPromptSubmitPayload(await readStdin());
+        if (!payload)
+            return; // malformed/absent payload → nothing recorded (fail-open)
+        const result = detectAvoidableContext(payload.prompt);
+        if (!result.has_avoidable_context)
+            return; // honest no-op → no activity noise, no stdout
+        const cwd = payload.cwd ?? deps.cwd ?? process.cwd();
+        const event = buildClaudeCodeBeforeCallEvent(result, payload.sessionId ? { sessionId: payload.sessionId } : {});
+        await appendActivityEvent(event, path.join(cwd, ".compaction", "activity"));
+        // No stdout (would inject into the model context); the recommendation is in `compaction activity`.
+    }
+    catch {
+        // FAIL-OPEN: never propagate — the before-call hook must not break Claude Code.
+    }
+}
 /**
  * Discover local Claude Code sessions (metadata only) and print, for each, the
  * ready-to-run `capture claude-code --session <path>` command (guided capture).

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;