@compaction/cli 0.1.4 → 0.3.0

package/dist/cli/commands/run.js

@@ -1,13 +1,33 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
 import chalk from "chalk";
 import { parseRunCommand, executeLocalCommand, persistLocalCommandRun } from "../../core/command-runner.js";
-import { writeJsonArtifact } from "../../core/artifact-writer.js";
-import { withTraceFingerprint } from "../../core/report-generator.js";
+import { writeJsonArtifact, writeTextArtifact } from "../../core/artifact-writer.js";
+import { formatCompactionMarkdownReport, withSavingsEvidence, withTraceFingerprint } from "../../core/report-generator.js";
 import { localCommandRunToAgentTrace } from "../../core/run-trace-converter.js";
 import { runEngineCommand } from "../engine-degrade.js";
+import { CODEX_UNKNOWN_MODEL, 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 { buildLocalRunTokenRecord, writeLocalRunTokenRecord } from "../../core/local-run-record.js";
+import { buildRunCrossSurfaceEvent } from "../../core/cross-surface-event.js";
+import { buildMeasureOnlyActivityEvent } from "../../core/activity-event.js";
+import { appendActivityEvent } from "../../core/activity-store.js";
+import { createUsageMetadata } from "../../core/usage-metadata.js";
+import { estimateTraceTokens } from "../../core/token-estimator.js";
+/**
+ * The exact honest reason bare-run OUTPUT tokens are unavailable — shared VERBATIM by the printed
+ * limitation note and the cross-surface event's output axis, so the reason can never diverge
+ * between what the operator reads and what the record carries.
+ */
+const BARE_RUN_OUTPUT_UNAVAILABLE_REASON = "a raw command's captured stdout/stderr is not safely separable as genuine model output";
 export function registerRunCommand(program) {
-    program
+    const run = program
         .command("run")
-        .description("Run a local command, capture output locally, convert it to a trace, and write compaction artifacts.")
+        .description("Unified capture→compact→report flow. Bare `run -- <cmd>` wraps any local command (local-estimate). " +
+        "Per-tool front-ends: `run codex -- …` (provider-reported) and `run cursor -- …` (local-estimate/unavailable).")
         .argument("[commandParts...]", "Command and arguments to execute after --")
         .allowUnknownOption(true)
         .action(async (commandParts) => {
@@ -15,22 +35,85 @@ export function registerRunCommand(program) {
             // `run`'s value IS the compaction report it produces, which needs the proprietary engine.
             // Lazy-load it FIRST so a public install degrades immediately — before spawning the child
             // command — rather than running the command and then failing to compact.
-            const { writeCompactionArtifacts } = await import("../../engine/compaction-artifacts.js");
+            const { writeCompactionArtifacts } = await import("../../core/compaction-artifacts.js");
             const command = parseRunCommand(commandParts);
             console.log(chalk.cyan("compaction run"));
             console.log("Running local command and capturing stdout/stderr locally. Child output is not printed by compaction.");
-            const run = await executeLocalCommand(command);
-            const persistedRun = await persistLocalCommandRun(run);
-            const trace = localCommandRunToAgentTrace(run);
+            const runResult = await executeLocalCommand(command);
+            const persistedRun = await persistLocalCommandRun(runResult);
+            const trace = localCommandRunToAgentTrace(runResult);
             const tracePath = await writeJsonArtifact(persistedRun.outputDirectory, "trace.json", trace);
-            const artifacts = await writeCompactionArtifacts(trace, persistedRun.outputDirectory, run.runId);
-            // Attribution/integrity (V0.2 savings-evidence): re-persist report.json with the content-addressed
-            // trace fingerprint so `aggregate`/`summary` attribute each saving to a verifiable run and
-            // de-duplicate a re-counted run. Additive; no existing report field/label changes.
-            await writeJsonArtifact(persistedRun.outputDirectory, "report.json", withTraceFingerprint(artifacts.report, trace));
-            console.log(`Exit code: ${run.exitCode ?? "none"}`);
-            console.log(`Signal: ${run.signal ?? "none"}`);
-            console.log(`Duration: ${run.durationMs} ms`);
+            // Shared HONEST token report — the SAME block the per-tool front-ends print, so output is
+            // consistent across every `run` path (unified-run-flow D1/D2). A bare wrapped command is an
+            // UNKNOWN tool with NO provider usage, so tokens are LOCAL-ESTIMATE (chars/4) — like Cursor.
+            // Genuine model output is NOT safely separable from a raw command's captured stdout/stderr
+            // (those are tool-role lines counted as input; the trace's single assistant message is a
+            // compaction-synthesized summary, not the command's output), so output is `unavailable` with
+            // a reason — never a silent zero, never provider-reported. Output is shown as TOKENS ONLY,
+            // NEVER a saving; the input before/after reduction below is the real (estimate-labeled) saving.
+            // Input is estimated locally (chars/4) from the trace; output is intentionally NOT carried so no
+            // synthesized-summary count is ever surfaced as if it were the command's model output.
+            const bareUsage = createUsageMetadata({
+                inputTokens: estimateTraceTokens(trace).inputTokens,
+                providerReportedTokens: false,
+                estimatedTokens: true,
+                model: trace.model,
+                limitations: [
+                    "Bare `run -- <cmd>` wraps an arbitrary command with no provider usage; input is a local chars/4 estimate.",
+                    `Output tokens are unavailable: ${BARE_RUN_OUTPUT_UNAVAILABLE_REASON}.`
+                ]
+            });
+            const bareTokenReport = buildRunFlowTokenReport({ tool: "command", usage: bareUsage, outputStatus: "unavailable" });
+            for (const line of formatRunFlowTokenReport(bareTokenReport))
+                console.log(line);
+            // LOCAL record step (unified-run-flow, local layer): persist the SAME honest token report as a
+            // content-free local record — counts + token_source only, no content, no savings figure — so runs
+            // accumulate under .compaction/run-records and `compaction summary` can roll them up per tool.
+            // Local file writes only; no hosted config read, no network.
+            // Cross-surface writers completion (charter 2026-07-03-run-5, completes #582 residual #5):
+            // the bare-run record additionally carries the ADDITIVE optional `cross_surface_event` —
+            // surface "cli", provider "other" (no observable provider), input LOCAL-ESTIMATE, output
+            // UNAVAILABLE with the exact command-surface reason above, cost UNAVAILABLE (no billing
+            // surface). Axes are copied VERBATIM from the SAME token report the record embeds. Record
+            // file content only — zero stdout change.
+            const bareCrossSurfaceEvent = buildRunCrossSurfaceEvent("cli", {
+                runId: runResult.runId,
+                tokenReport: bareTokenReport,
+                reasons: { output: BARE_RUN_OUTPUT_UNAVAILABLE_REASON }
+            });
+            const bareRecordPaths = await writeLocalRunTokenRecord(buildLocalRunTokenRecord({
+                runId: runResult.runId,
+                tokenReport: bareTokenReport,
+                crossSurfaceEvent: bareCrossSurfaceEvent
+            }), persistedRun.outputDirectory);
+            // ACTIVITY step (charter 2026-07-04-run-7, lane "shared activity/event model"): the SAME
+            // cross-surface event, extended measure-only, appends ONE metrics-only activity event to
+            // the local store (.compaction/activity/activity.jsonl). Measure-only honesty: nothing was
+            // applied, so approval_status "not-required"; auto_apply not eligible + default
+            // "ask-each-time" + applied_automatically false (no auto-apply logic exists);
+            // sync_status "local-only"; recovery = the trace artifact just written (what the record
+            // honestly knows). Best-effort local append — never fails the run, ZERO stdout change.
+            try {
+                await appendActivityEvent(buildMeasureOnlyActivityEvent(bareCrossSurfaceEvent, { original_retained: true, location: tracePath }));
+            }
+            catch {
+                // A local filesystem failure here must never fail the user's run (record-only step).
+            }
+            const artifacts = await writeCompactionArtifacts(trace, persistedRun.outputDirectory, runResult.runId);
+            // Attribution/integrity + per-run evidence label (V0.2 savings-evidence): re-persist
+            // report.json with the trace fingerprint (attribution/dedup) and the composed
+            // `savings_evidence` record (per-run label). `run` figures are local estimates (chars/4) —
+            // `local_estimate` rung 1. Additive; no existing report field/label changes.
+            const evidenceReport = withSavingsEvidence(withTraceFingerprint(artifacts.report, trace), {
+                costSource: "local_estimate"
+            });
+            await writeJsonArtifact(persistedRun.outputDirectory, "report.json", evidenceReport);
+            // Re-render report.md from the ENRICHED report so the per-run savings_evidence record
+            // appears in the human-readable artifact too (engine rendered it from the base report).
+            await writeTextArtifact(persistedRun.outputDirectory, "report.md", formatCompactionMarkdownReport(evidenceReport, artifacts.policy));
+            console.log(`Exit code: ${runResult.exitCode ?? "none"}`);
+            console.log(`Signal: ${runResult.signal ?? "none"}`);
+            console.log(`Duration: ${runResult.durationMs} ms`);
             console.log(chalk.green(`Wrote ${persistedRun.stdoutPath}`));
             console.log(chalk.green(`Wrote ${persistedRun.stderrPath}`));
             console.log(chalk.green(`Wrote ${persistedRun.rawOutputPath}`));
@@ -45,10 +128,219 @@ export function registerRunCommand(program) {
             console.log(chalk.green(`Wrote ${artifacts.paths.safetyReportPath}`));
             console.log(chalk.green(`Wrote ${artifacts.paths.safetyMarkdownReportPath}`));
             console.log(chalk.green(`Wrote ${artifacts.paths.prCommentReportPath}`));
-            if (run.exitCode !== 0 && run.exitCode !== null) {
-                process.exitCode = run.exitCode;
+            console.log(chalk.green(`Wrote ${bareRecordPaths.artifactPath}`));
+            console.log(`  Local run record accumulated at ${bareRecordPaths.accumulatedPath} (content-free: token counts + sources only). ` +
+                "Roll runs up per tool with `compaction summary`.");
+            if (runResult.exitCode !== 0 && runResult.exitCode !== null) {
+                process.exitCode = runResult.exitCode;
             }
         });
     });
+    registerRunToolFrontEnds(run);
+}
+/**
+ * Register the per-tool front-ends of the unified flow (accepted design D1: unify the back half with
+ * per-tool front-ends). `run codex` / `run cursor` route to the EXISTING capture code (no duplication),
+ * then compact via the SAME engine artifact writer as bare `run`, then print the shared HONEST token
+ * report (`token_source` explicit; input/output SEPARATE; output as tokens, NEVER a saving).
+ *
+ * Local-only: no record wiring is added here (that is roadmap item 5 / `/app`, separately gated). Hosted
+ * recording remains on the `capture codex` / `capture cursor` commands, gated on URL+key as before.
+ */
+function registerRunToolFrontEnds(run) {
+    run
+        .command("codex")
+        .description("Unified flow for Codex: wrap a LIVE `codex exec --json` run (or --export a saved one), compact, and " +
+        "report. Tokens are PROVIDER-REPORTED (turn.completed.usage). Local only — no upload, no proxying.")
+        .requiredOption("--out <dir>", "Output directory for capture + compaction artifacts")
+        .option("--export <file>", "Read a saved `codex exec --json` JSONL export instead of running a command")
+        .argument("[commandParts...]", 'Command and args after -- (e.g. -- codex exec --json "do X")')
+        .allowUnknownOption(true)
+        .action(async (commandParts, options) => {
+        await runToolFrontEnd({
+            tool: "codex",
+            label: "compaction run codex",
+            intro: "Capturing a live codex exec --json run, then compacting + reporting. No upload, no proxying. " +
+                "Review artifacts before sharing (they may contain code/output).",
+            options,
+            commandParts,
+            capture: async () => {
+                const result = options.export
+                    ? captureCodexExport(await readFile(options.export, "utf8"))
+                    : await captureCodexCommand(commandParts);
+                return {
+                    trace: result.trace,
+                    usage: result.usageMetadata,
+                    // Codex has no per-field "unavailable" output split; provider-reported usage is whole.
+                    outputStatus: "present",
+                    warnings: result.warnings,
+                    exitCode: result.commandRun?.exitCode
+                };
+            }
+        });
+    });
+    run
+        .command("cursor")
+        .description("Unified flow for Cursor: wrap a LIVE Cursor headless run (or --export saved output), compact, and " +
+        "report. Tokens are LOCAL-ESTIMATE only (Cursor emits no usage); output is counted where separable " +
+        "(use --output-format json), else UNAVAILABLE. Local only — no upload, no SQLite.")
+        .requiredOption("--out <dir>", "Output directory for capture + compaction artifacts")
+        .option("--export <file>", "Read saved Cursor headless output (json / stream-json) instead of running a command")
+        .argument("[commandParts...]", 'Command and args after -- (e.g. -- cursor agent -p "do X" --output-format json)')
+        .allowUnknownOption(true)
+        .action(async (commandParts, options) => {
+        // LIVE path (no --export) with a command to run: run the SAFE preflight FIRST (CLI-presence +
+        // capability only; never a real prompt, never login, never a CURSOR_API_KEY read). If the CLI is
+        // missing/incapable, print guidance and STOP before spawning — the operator sees exact next steps,
+        // not an opaque failure. (A bare `run cursor` with no command + no --export falls through to the
+        // existing usage error inside runToolFrontEnd.)
+        if (!options.export && commandParts.length > 0) {
+            console.log(chalk.cyan("compaction run cursor"));
+            console.log("Preflight for a LIVE Cursor headless run. LOCAL-ESTIMATE tokens only (Cursor emits no provider usage).");
+            const ready = await gateCursorLiveRun();
+            if (!ready) {
+                process.exitCode = 1;
+                return;
+            }
+        }
+        // Export path: read the saved output HONESTLY up front — a missing/unreadable --export file is an
+        // actionable error (what failed, which path, what a valid export is), exit 1; never a raw errno,
+        // never a fabricated capture, no artifacts written.
+        let exportRawOutput;
+        if (options.export) {
+            const exportRead = await readCursorExportFile(options.export);
+            if (!exportRead.ok) {
+                console.log(chalk.cyan("compaction run cursor"));
+                for (const line of exportRead.errorLines)
+                    console.error(line);
+                process.exitCode = 1;
+                return;
+            }
+            exportRawOutput = exportRead.rawOutput;
+        }
+        await runToolFrontEnd({
+            tool: "cursor",
+            label: "compaction run cursor",
+            intro: "Capturing a live Cursor headless run, then compacting + reporting. LOCAL-ESTIMATE tokens only " +
+                "(Cursor emits no provider usage). No upload, no SQLite. Review artifacts before sharing.",
+            options,
+            commandParts,
+            capture: async () => {
+                const result = exportRawOutput !== undefined
+                    ? captureCursorExport(exportRawOutput, commandParts.length > 0 ? commandParts : undefined)
+                    : await captureCursorCommand(commandParts);
+                return {
+                    trace: result.trace,
+                    usage: result.usageMetadata,
+                    outputStatus: result.outputStatus,
+                    // TRUE per-axis unavailability reasons (e.g. export-only input) so the printed token lines
+                    // say WHY an axis is unavailable — never a bare "unavailable" with a generic guess.
+                    inputUnavailableReason: result.inputUnavailableReason,
+                    outputUnavailableReason: result.outputUnavailableReason,
+                    warnings: result.warnings,
+                    exitCode: result.commandRun?.exitCode
+                };
+            }
+        });
+    });
+}
+/**
+ * Shared per-tool front-end body: capture (existing code) → compact (existing engine writer) → HONEST
+ * report. The engine is lazy-loaded through `runEngineCommand` so a public (engine-free) install degrades
+ * with the sanctioned boundary message instead of crashing — identical posture to bare `run`.
+ */
+async function runToolFrontEnd(params) {
+    await runEngineCommand(async () => {
+        const { writeCompactionArtifacts } = await import("../../core/compaction-artifacts.js");
+        console.log(chalk.cyan(params.label));
+        console.log(params.intro);
+        if (!params.options.export && params.commandParts.length === 0) {
+            console.error("error: provide a command after -- or use --export <file>.");
+            process.exitCode = 1;
+            return;
+        }
+        const captured = await params.capture();
+        const outDir = params.options.out;
+        await mkdir(outDir, { recursive: true });
+        const tracePath = path.join(outDir, "captured-trace.json");
+        await writeFile(tracePath, JSON.stringify(captured.trace, null, 2), "utf8");
+        console.log(chalk.green(`Wrote ${tracePath}`));
+        // Shared HONEST token report: token_source explicit per field; input/output SEPARATE; output as
+        // tokens only (NEVER a saving). This is printed for every tool front-end.
+        const tokenReport = buildRunFlowTokenReport({ tool: params.tool, usage: captured.usage, outputStatus: captured.outputStatus });
+        const unavailableReasons = { input: captured.inputUnavailableReason, output: captured.outputUnavailableReason };
+        for (const line of formatRunFlowTokenReport(tokenReport, { reasons: unavailableReasons }))
+            console.log(line);
+        for (const warning of captured.warnings)
+            console.log(chalk.yellow(`  ! ${warning}`));
+        const runId = `${params.tool}-${Date.now()}`;
+        // LOCAL record step (unified-run-flow, local layer): persist the SAME honest token report as a
+        // content-free local record (counts + per-field token_source only — no prompt/output text, no
+        // savings figure). One copy stays with the run's --out artifacts; one accumulates under
+        // .compaction/run-records so `compaction summary` rolls runs up per tool. Local writes only —
+        // this is NOT the hosted record step (that stays on `capture <tool>`, gated on URL+key).
+        // Cross-surface event writers (contract docs/ops/cross-surface-evidence-contract.md): every
+        // `run` front-end record additionally carries the ADDITIVE optional `cross_surface_event`,
+        // built from the SAME token report so per-axis sources/reasons can never diverge (Cursor
+        // shipped first — D3, charter 2026-07-03-run-5; codex completes #582 residual #5). Axis
+        // sources are copied VERBATIM (never laundered); cost_source is UNAVAILABLE with the exact
+        // per-surface reason on every `run` path (no billing data exists here). Record file content
+        // only — zero stdout change.
+        const eventSurface = params.tool === "codex" ? "codex" : params.tool === "cursor" ? "cursor" : undefined;
+        const crossSurfaceEvent = eventSurface !== undefined
+            ? buildRunCrossSurfaceEvent(eventSurface, {
+                runId,
+                tokenReport,
+                reasons: unavailableReasons,
+                // model_label only where the capture HONESTLY knows the model: the codex event stream
+                // may report one; codex's "codex-unknown-model" placeholder maps to the contract's
+                // canonical "unknown" (unknown stays unknown — a placeholder is not a model id).
+                // Cursor stays "unknown" (never inferred — D3).
+                ...(params.tool === "codex" &&
+                    captured.usage.model !== undefined &&
+                    captured.usage.model !== CODEX_UNKNOWN_MODEL
+                    ? { modelLabel: captured.usage.model }
+                    : {})
+            })
+            : undefined;
+        const recordPaths = await writeLocalRunTokenRecord(buildLocalRunTokenRecord({ runId, tokenReport, ...(crossSurfaceEvent !== undefined ? { crossSurfaceEvent } : {}) }), outDir);
+        // ACTIVITY step (charter 2026-07-04-run-7, lane "shared activity/event model"): every front-end
+        // that builds a cross-surface event (codex/cursor) also appends ONE metrics-only activity event
+        // to the local store — measure-only, so approval_status "not-required", auto_apply not eligible
+        // + default "ask-each-time" + applied_automatically false (no auto-apply logic exists),
+        // sync_status "local-only", recovery = the captured-trace artifact written above (what the
+        // record honestly knows). Best-effort local append — never fails the run, ZERO stdout change.
+        if (crossSurfaceEvent !== undefined) {
+            try {
+                await appendActivityEvent(buildMeasureOnlyActivityEvent(crossSurfaceEvent, { original_retained: true, location: tracePath }));
+            }
+            catch {
+                // A local filesystem failure here must never fail the user's run (record-only step).
+            }
+        }
+        console.log(chalk.green(`Wrote ${recordPaths.artifactPath}`));
+        console.log(`  Local run record accumulated at ${recordPaths.accumulatedPath} (content-free: token counts + sources only). ` +
+            "Roll runs up per tool with `compaction summary`.");
+        // Compact via the SAME engine artifact writer as bare `run` (input reduction = the REAL saving).
+        const artifacts = await writeCompactionArtifacts(captured.trace, outDir, runId);
+        console.log(artifacts.consoleReport);
+        console.log(`Input reduction above is ${tokenReport.input_reduction_label} (input before/after — a real compaction saving). ` +
+            "No output-token savings is shown (gated on measured + eval-confirmed output-shaping).");
+        console.log(chalk.green(`Wrote ${artifacts.paths.reportPath}`));
+        console.log(chalk.green(`Wrote ${artifacts.paths.markdownReportPath}`));
+        console.log(chalk.green(`Wrote ${artifacts.paths.policyPath}`));
+        console.log(chalk.green(`Wrote ${artifacts.paths.capsulePath}`));
+        console.log(chalk.green(`Wrote ${artifacts.paths.compactedTracePath}`));
+        console.log(chalk.green(`Wrote ${artifacts.paths.safetyReportPath}`));
+        console.log(chalk.green(`Wrote ${artifacts.paths.safetyMarkdownReportPath}`));
+        console.log(chalk.green(`Wrote ${artifacts.paths.prCommentReportPath}`));
+        // Local-only: this front-end does NOT record to the hosted control-plane (roadmap item 5, gated).
+        // The run record written above is LOCAL accumulation only — never an upload.
+        console.log(`  Not recorded to the hosted control-plane from \`run\` (local-only). To record content-free usage there, ` +
+            `use \`capture ${params.tool}\` with COMPACTION_API_URL + COMPACTION_API_KEY set.`);
+        console.log(`  Next: compaction compact ${tracePath} --eval --out <dir>`);
+        if (typeof captured.exitCode === "number" && captured.exitCode !== 0)
+            process.exitCode = captured.exitCode;
+    });
 }
 //# sourceMappingURL=run.js.map

package/dist/cli/commands/upgrade-status.d.ts

@@ -0,0 +1,42 @@
+import { Command } from "commander";
+import { type EnvLike } from "../../core/api-client/index.js";
+/**
+ * `compaction upgrade` + `compaction status` — the key-first hosted-upgrade UX (charter
+ * 2026-07-04-run-7, founder hosted-upgrade decision).
+ *
+ * HONESTY / HARD RAILS:
+ *  - There is NO live public hosted endpoint. The default URL is the LOCAL-dev server. A `--key`
+ *    with no private endpoint FAILS GRACEFULLY with the exact `NO_LIVE_ENDPOINT_MESSAGE` — it never
+ *    pretends `api.compaction.dev` (or any remote) is live.
+ *  - The API key is validated against `GET <url>/v0/status` with a short timeout. Config is
+ *    persisted (0600) ONLY on a 200. A 401 fails CLOSED and persists nothing. Transport/timeout/
+ *    other failures persist nothing.
+ *  - The full API key is NEVER printed, logged, or written anywhere except the 0600 config file.
+ *    Every user-facing surface shows `maskKey(...)` only.
+ */
+/**
+ * EXACT graceful-failure message for a `--key` with no private endpoint configured. Printed
+ * verbatim (no color wrapping) so it is byte-stable regardless of TTY.
+ */
+export declare const NO_LIVE_ENDPOINT_MESSAGE = "no public hosted Compaction endpoint is live yet; hosted access is private-beta; pass `--api-url <url>` (private-beta/staging/self-hosted) or set `COMPACTION_API_URL`.";
+/**
+ * Run `compaction upgrade`. Validates a key against a configured private endpoint and persists
+ * `{api_url, api_key}` (0600) ONLY on success. Sets a non-zero exit code on every failure path and
+ * persists NOTHING on any failure. Never prints/logs the key (masked only).
+ */
+export declare function runUpgrade(opts: {
+    key?: string;
+    apiUrl?: string;
+    env?: EnvLike;
+}): Promise<void>;
+/**
+ * Run `compaction status`. Reports local core + whether a hosted endpoint is configured (masked key
+ * + host only) + a LIVE reachability re-check. Hosted-tier capabilities are shown ONLY when
+ * reachable, phrased as what the tier UNLOCKS (not per-capability liveness). Never prints the key.
+ */
+export declare function runStatus(opts?: {
+    env?: EnvLike;
+    version?: string;
+}): Promise<void>;
+export declare function registerUpgradeCommand(program: Command): void;
+export declare function registerStatusCommand(program: Command): void;

package/dist/cli/commands/upgrade-status.js

@@ -0,0 +1,152 @@
+import chalk from "chalk";
+import { ApiTransportError, apiStatus, healthCheckConfig, isLocalDefaultUrl, maskKey, resolveTarget, urlHost, writePersistedConfig } from "../../core/api-client/index.js";
+/**
+ * `compaction upgrade` + `compaction status` — the key-first hosted-upgrade UX (charter
+ * 2026-07-04-run-7, founder hosted-upgrade decision).
+ *
+ * HONESTY / HARD RAILS:
+ *  - There is NO live public hosted endpoint. The default URL is the LOCAL-dev server. A `--key`
+ *    with no private endpoint FAILS GRACEFULLY with the exact `NO_LIVE_ENDPOINT_MESSAGE` — it never
+ *    pretends `api.compaction.dev` (or any remote) is live.
+ *  - The API key is validated against `GET <url>/v0/status` with a short timeout. Config is
+ *    persisted (0600) ONLY on a 200. A 401 fails CLOSED and persists nothing. Transport/timeout/
+ *    other failures persist nothing.
+ *  - The full API key is NEVER printed, logged, or written anywhere except the 0600 config file.
+ *    Every user-facing surface shows `maskKey(...)` only.
+ */
+/**
+ * EXACT graceful-failure message for a `--key` with no private endpoint configured. Printed
+ * verbatim (no color wrapping) so it is byte-stable regardless of TTY.
+ */
+export const NO_LIVE_ENDPOINT_MESSAGE = "no public hosted Compaction endpoint is live yet; hosted access is private-beta; pass `--api-url <url>` (private-beta/staging/self-hosted) or set `COMPACTION_API_URL`.";
+/**
+ * Live health check via the shared api-client (`GET /v0/status`, Bearer key attached by the client,
+ * bounded timeout). Never leaks the key: the returned reason is our own concise string, never the
+ * raw request/headers.
+ */
+async function healthCheck(target) {
+    try {
+        const res = await apiStatus(healthCheckConfig(target));
+        if (res.ok)
+            return { kind: "ok" };
+        if (res.status === 401)
+            return { kind: "unauthorized" };
+        return { kind: "http-error", status: res.status };
+    }
+    catch (err) {
+        // ApiTransportError's message contains the URL (never the key); we still surface only a concise
+        // reason so nothing incidental leaks.
+        return {
+            kind: "unreachable",
+            reason: err instanceof ApiTransportError ? "transport error or timeout" : "unexpected error"
+        };
+    }
+}
+/**
+ * Run `compaction upgrade`. Validates a key against a configured private endpoint and persists
+ * `{api_url, api_key}` (0600) ONLY on success. Sets a non-zero exit code on every failure path and
+ * persists NOTHING on any failure. Never prints/logs the key (masked only).
+ */
+export async function runUpgrade(opts) {
+    const env = opts.env ?? process.env;
+    const target = resolveTarget({ flagUrl: opts.apiUrl, flagKey: opts.key, env });
+    console.log(chalk.cyan("compaction upgrade"));
+    if (!target.apiKey) {
+        console.error(chalk.red("hosted upgrade needs an API key: pass --key <key> or set COMPACTION_API_KEY. Nothing was saved."));
+        process.exitCode = 1;
+        return;
+    }
+    // Key present, but the resolved URL is the LOCAL-dev default → NO private endpoint configured.
+    // Fail gracefully; persist NOTHING. Printed verbatim (no chalk) for a byte-stable exact message.
+    if (isLocalDefaultUrl(target.url)) {
+        console.error(NO_LIVE_ENDPOINT_MESSAGE);
+        process.exitCode = 1;
+        return;
+    }
+    const host = urlHost(target.url);
+    console.log(`Validating the API key against ${host} …`); // host only; never the key
+    const health = await healthCheck(target);
+    switch (health.kind) {
+        case "ok": {
+            const path = writePersistedConfig({ api_url: target.url, api_key: target.apiKey }, env);
+            console.log(chalk.green("Hosted upgrade configured (endpoint reachable, key accepted)."));
+            console.log(`  Endpoint: ${host}`);
+            console.log(`  API key:  ${maskKey(target.apiKey)} (masked; the full key is saved only to the local 0600 config)`);
+            console.log(`  Saved to: ${path} (mode 0600)`);
+            console.log("Mode: private beta (hosted). Run `compaction status` to re-check reachability any time.");
+            return;
+        }
+        case "unauthorized":
+            console.error(chalk.red("hosted upgrade failed: the endpoint rejected this API key (HTTP 401). Nothing was saved."));
+            process.exitCode = 1;
+            return;
+        case "http-error":
+            console.error(chalk.red(`hosted upgrade failed: the endpoint returned HTTP ${health.status}. Nothing was saved.`));
+            process.exitCode = 1;
+            return;
+        case "unreachable":
+            console.error(chalk.red(`hosted upgrade failed: could not reach ${host} (${health.reason}). Nothing was saved.`));
+            process.exitCode = 1;
+            return;
+    }
+}
+/**
+ * Run `compaction status`. Reports local core + whether a hosted endpoint is configured (masked key
+ * + host only) + a LIVE reachability re-check. Hosted-tier capabilities are shown ONLY when
+ * reachable, phrased as what the tier UNLOCKS (not per-capability liveness). Never prints the key.
+ */
+export async function runStatus(opts = {}) {
+    const env = opts.env ?? process.env;
+    const version = opts.version ?? "0.3.0";
+    const target = resolveTarget({ env });
+    const configured = target.apiKey !== undefined && !isLocalDefaultUrl(target.url);
+    console.log(chalk.cyan("compaction status"));
+    console.log(`Local core: enabled (compaction v${version})`);
+    if (!configured) {
+        console.log("Hosted API: not configured");
+        console.log("Mode: local-only");
+        console.log("Connect a private-beta / self-hosted endpoint: compaction upgrade --key <key> --api-url <url>");
+        return;
+    }
+    const host = urlHost(target.url);
+    console.log(`Hosted API: configured — ${host} · key ${maskKey(target.apiKey)}`);
+    const health = await healthCheck(target);
+    switch (health.kind) {
+        case "ok":
+            console.log("  Reachability: reachable");
+            break;
+        case "unauthorized":
+            console.log("  Reachability: unreachable (endpoint returned HTTP 401 — key may be invalid)");
+            break;
+        case "http-error":
+            console.log(`  Reachability: unreachable (endpoint returned HTTP ${health.status})`);
+            break;
+        case "unreachable":
+            console.log(`  Reachability: unreachable (${health.reason})`);
+            break;
+    }
+    console.log("Mode: private beta (hosted)");
+    if (health.kind === "ok") {
+        console.log("Capabilities (unlocked by the hosted tier): hosted optimize · hosted evaluate · report sync · " +
+            "policy-managed auto-apply — unlocked by the hosted tier (not individually confirmed live here).");
+    }
+}
+export function registerUpgradeCommand(program) {
+    program
+        .command("upgrade")
+        .description("Connect the CLI to a private-beta / self-hosted Compaction endpoint (validate + save an API key).")
+        .option("--key <key>", "API key for the hosted endpoint (or set COMPACTION_API_KEY)")
+        .option("--api-url <url>", "Hosted endpoint base URL — advanced (or set COMPACTION_API_URL)")
+        .action(async (options) => {
+        await runUpgrade({ key: options.key, apiUrl: options.apiUrl });
+    });
+}
+export function registerStatusCommand(program) {
+    program
+        .command("status")
+        .description("Show local core status and whether a hosted endpoint is configured + reachable.")
+        .action(async () => {
+        await runStatus({ version: program.version() ?? "0.3.0" });
+    });
+}
+//# sourceMappingURL=upgrade-status.js.map

package/dist/cli/cursor-export-read.d.ts

@@ -0,0 +1,13 @@
+export type CursorExportRead = {
+    ok: true;
+    rawOutput: string;
+} | {
+    ok: false;
+    errorLines: string[];
+};
+/**
+ * Read a saved Cursor headless output for `--export`. On failure returns honest, actionable
+ * error lines for the caller to print (stderr) alongside `process.exitCode = 1` — never a throw,
+ * never a stack trace, never a fabricated capture.
+ */
+export declare function readCursorExportFile(exportPath: string): Promise<CursorExportRead>;

package/dist/cli/cursor-export-read.js

@@ -0,0 +1,53 @@
+/**
+ * Honest `--export <file>` read for the Cursor commands (`capture cursor` / `run cursor`).
+ *
+ * Before this helper, an unreadable export surfaced as a raw Node errno line (e.g.
+ * "ENOENT: no such file or directory, open '…'") with no guidance. This wraps the read so a
+ * missing / unreadable / directory / too-large export produces an ACTIONABLE, honest error:
+ * what failed, on which path, and what a valid Cursor export is — then exit code 1.
+ *
+ * Honesty rails (unchanged by this helper): a failed read NEVER fabricates a trace or token
+ * counts — nothing is written, nothing is counted, no silent zeros. Tokens on the Cursor path
+ * remain LOCAL-ESTIMATE / unavailable-with-reason only (Cursor emits no provider usage).
+ */
+import { readFile } from "node:fs/promises";
+/** One-line errno-ish reason without the raw stack/prefix noise. */
+function readFailureReason(error) {
+    const code = error?.code;
+    switch (code) {
+        case "ENOENT":
+            return "file not found";
+        case "EACCES":
+        case "EPERM":
+            return "permission denied";
+        case "EISDIR":
+            return "path is a directory, not a file";
+        case "EFBIG":
+        case "ERR_FS_FILE_TOO_LARGE":
+            return "file is too large to read into memory";
+        default:
+            return error instanceof Error ? error.message : String(error);
+    }
+}
+/**
+ * Read a saved Cursor headless output for `--export`. On failure returns honest, actionable
+ * error lines for the caller to print (stderr) alongside `process.exitCode = 1` — never a throw,
+ * never a stack trace, never a fabricated capture.
+ */
+export async function readCursorExportFile(exportPath) {
+    try {
+        return { ok: true, rawOutput: await readFile(exportPath, "utf8") };
+    }
+    catch (error) {
+        return {
+            ok: false,
+            errorLines: [
+                `error: could not read --export file '${exportPath}': ${readFailureReason(error)}.`,
+                "  Expected a saved Cursor headless output file: the stdout of `cursor agent -p \"…\" --output-format json` (or stream-json).",
+                "  Nothing was captured or counted (no artifacts written). Fix the path/file and retry,",
+                "  or run the LIVE path instead (preflight included): compaction run cursor --out <dir> -- cursor agent -p \"…\" --output-format json"
+            ]
+        };
+    }
+}
+//# sourceMappingURL=cursor-export-read.js.map

package/dist/cli/cursor-live-preflight.d.ts

@@ -0,0 +1,19 @@
+import { type CursorPreflightReport } from "../core/cursor-preflight.js";
+/**
+ * Run the preflight (safe probes) and return the report. Never throws.
+ *
+ * `COMPACTION_CURSOR_BIN` (optional): when set to a non-empty path, it is used as the SOLE candidate the
+ * safe probe checks — instead of the default PATH names + the hardcoded macOS app path. This is (a) a real
+ * operator override for a non-standard Cursor CLI location, and (b) what makes this path deterministic in
+ * tests: pointing it at a non-existent binary makes the probe fail fast (ENOENT) so the CLI never spawns
+ * the real, possibly-hanging Cursor binary. Still a `--help`/`-v` capability probe only — never `-p`,
+ * never `login`, never a key read.
+ */
+export declare function cursorLivePreflight(): Promise<CursorPreflightReport>;
+/**
+ * Print the preflight guidance and decide whether the live run may proceed.
+ * - CLI not resolvable OR capability absent → print guidance, return false (do NOT spawn a live run).
+ * - CLI present + capable → print the auth reminder, return true (proceed; auth verified only by a real
+ *   run the operator has authorized).
+ */
+export declare function gateCursorLiveRun(): Promise<boolean>;