@compaction/cli 0.1.4 → 0.3.0

package/dist/cli/commands/init.js

@@ -1,11 +1,16 @@
 import { existsSync } from "node:fs";
 import { readFile } from "node:fs/promises";
+import { homedir } from "node:os";
 import { fileURLToPath } from "node:url";
 import path from "node:path";
 import chalk from "chalk";
 import { defaultProjectsDir, discoverClaudeCodeSessions } from "../../core/adapters/claude-code-discovery.js";
+import { connectClaudeCodeHook } from "../../core/claude-code-connect.js";
+import { SHIM_TOOLS, installToolShim, uninstallToolShim, verifyShimActive, resolveExecutableOnPath, writeShellConfigPathLine, removeShellConfigPathLine } from "../../core/tool-shim.js";
 import { BRAND_HEX, VALUE_PROMISE, STATUS_PILLS, PRIMARY, SECONDARY, FREE_FLOW, HONESTY_LINES, FOOTER_LINES, ALL_WORKFLOW_KEYS } from "../onboarding/model.js";
 import { decideInteractiveTuiFromProcess } from "../onboarding/should-use-tui.js";
+import { runGatewayStart, parseListen } from "./gateway.js";
+import { planGatewayConfigure, formatConfigurePlan } from "../../core/gateway/configure.js";
 /**
  * `compaction init` — first-run, value-led terminal onboarding.
  *
@@ -110,7 +115,10 @@ function afterCaptureBlock() {
         chalk.dim(`  ${HONESTY_LINES[2]}`),
         "",
         chalk.dim(`  ${HONESTY_LINES[3]}`),
-        chalk.dim(`  ${HONESTY_LINES[4]}`)
+        chalk.dim(`  ${HONESTY_LINES[4]}`),
+        "",
+        chalk.dim("  Optional — auto-capture content-free usage on each Claude Code Stop:"),
+        `  ${ACCENT("compaction hooks install")}  ${chalk.dim("(consented, merge-not-replace, --dry-run; nothing is written until you run it)")}`
     ];
 }
 function footerBlock() {
@@ -182,13 +190,306 @@ function printSelection(card) {
     ];
     console.log(out.join("\n"));
 }
+/** Human labels + the honest per-tool token-source line shown in the shim connect block. */
+const SHIM_TOOL_LABELS = {
+    codex: {
+        title: "Codex",
+        connectNum: "2",
+        measurableForm: "codex exec --json",
+        tokenNote: "provider-reported tokens (codex exec --json turn.completed.usage) — NOT billing-confirmed"
+    },
+    cursor: {
+        title: "Cursor",
+        connectNum: "3",
+        measurableForm: "cursor-agent … --output-format json",
+        tokenNote: "LOCAL-ESTIMATE tokens only (Cursor emits no provider usage) — never provider-reported; output unavailable when the result is not separable"
+    }
+};
+const CONNECT_ALIASES = {
+    "1": "claude-code",
+    "2": "codex",
+    "3": "cursor",
+    "4": "all",
+    "5": "skip",
+    "claude-code": "claude-code",
+    codex: "codex",
+    cursor: "cursor",
+    all: "all",
+    skip: "skip"
+};
+/** Honest per-tool line: whether the real binary is on PATH and whether OUR shim is verified active. */
+function shimDetectLine(tool, label) {
+    const shimName = SHIM_TOOLS[tool].shimName;
+    const realBin = resolveExecutableOnPath(shimName, process.env, [verifyShimActive(tool).shimDir]);
+    const v = verifyShimActive(tool);
+    if (v.active)
+        return chalk.green(`    [x] ${label.padEnd(17)} connected (shim active → ${shimName})`);
+    if (v.installed)
+        return chalk.yellow(`    [~] ${label.padEnd(17)} shim installed, NOT yet on PATH (run --connect ${SHIM_TOOL_LABELS[tool].connectNum} to finish)`);
+    if (realBin)
+        return `    [ ] ${label.padEnd(17)} ${shimName} found — not connected (run --connect ${SHIM_TOOL_LABELS[tool].connectNum})`;
+    return `    [ ] ${label.padEnd(17)} not found on PATH`;
+}
+/**
+ * Detection block. Claude Code is scanned (read-only, session discovery). Codex/Cursor are detected
+ * by the presence of the real binary on PATH AND whether Compaction's PATH shim is verified active
+ * (resolve-check, never assumed). The browser is "not connected / not checked" — NEVER "not
+ * installed": Compaction does not scan Chrome profiles.
+ */
+function connectDetectionBlock(det) {
+    const claude = det.claudeDetected
+        ? chalk.green(`    [x] Claude Code       detected (${det.sessionCount} session(s))`)
+        : `    [ ] Claude Code       not detected here`;
+    return [
+        header("Detected AI tools on this machine"),
+        "",
+        claude,
+        shimDetectLine("codex", "Codex"),
+        shimDetectLine("cursor", "Cursor"),
+        "    [ ] Browser extension not connected / not checked",
+        "",
+        chalk.dim("  Codex and Cursor connect via a Compaction-owned PATH shim (reversible; verified by"),
+        chalk.dim("  resolving the tool name). The browser extension is 'not connected / not checked' —"),
+        chalk.dim("  Compaction never scans your Chrome profiles to guess whether it is installed.")
+    ];
+}
+function connectMenuBlock() {
+    return [
+        header("Enable Compaction for"),
+        "",
+        "    [1] Claude Code",
+        "    [2] Codex",
+        "    [3] Cursor",
+        "    [4] All supported CLI tools",
+        "    [5] Skip"
+    ];
+}
+/**
+ * The Codex/Cursor PATH-shim install-result block. HONEST by status: it claims "connected" ONLY when
+ * the shim is verified ACTIVE (the tool name resolves to our shim on PATH). When the shim is installed
+ * but the shim dir is not yet on PATH, it prints the ONE exact export line and says "not yet active" —
+ * never a false success. It scopes "measured automatically" to the MEASURABLE batch form and states
+ * plainly that interactive/other invocations are NOT measured. The real binary is never replaced.
+ */
+function shimConnectBlock(result, wroteShellConfig) {
+    const meta = SHIM_TOOL_LABELS[result.tool];
+    const title = meta.title;
+    if (result.status === "installed-active" || result.status === "already-active") {
+        const lines = [
+            `  ${chalk.bold("▸ " + title)} ${chalk.green("— connected")}`,
+            "",
+            chalk.green(`    Compaction is now active for ${title} (PATH shim: ${result.shimPath} → real ${result.shimName}: ${result.realBin ?? "recorded"}).`),
+            `    From now on, ${chalk.bold(meta.measurableForm)} runs are measured automatically — no manual import needed.`,
+            chalk.dim(`    Interactive / other ${result.shimName} invocations pass through untouched and are NOT measured (never faked).`),
+            chalk.dim(`    Token source: ${meta.tokenNote}.`),
+            chalk.dim("    Metrics-only; no prompt or response content is stored or uploaded."),
+            "",
+            chalk.dim("    See your runs anytime:  compaction activity"),
+            chalk.dim(`    Fallback/debug (per-invocation, not needed once connected):  compaction run ${result.tool} -- <cmd>`),
+            chalk.dim(`    Disconnect (reversible):  compaction init --disconnect ${meta.connectNum}`)
+        ];
+        return lines;
+    }
+    if (result.status === "installed-not-on-path") {
+        const resolved = result.verification.resolvedPath;
+        const out = [
+            `  ${chalk.bold("▸ " + title)} ${chalk.yellow("— installed, NOT yet active")}`,
+            "",
+            chalk.yellow(`    The shim is installed at ${result.shimPath}, but its directory is not on your PATH yet,`),
+            chalk.yellow(`    so \`${result.shimName}\` still resolves to ${resolved ?? "the real binary"} — NOT the shim.`),
+            "    Add this ONE line to activate it (prepends the shim dir so it wins), then re-run to verify:",
+            `      ${ACCENT(result.exportLine)}`,
+            `      ${ACCENT(`compaction init --connect ${meta.connectNum}`)}`
+        ];
+        if (wroteShellConfig) {
+            out.push("", chalk.green(`    --write-shell-config: ${wroteShellConfig.status} the line in ${wroteShellConfig.rcPath}` + (wroteShellConfig.backupPath ? ` (backup: ${wroteShellConfig.backupPath}).` : ".")), chalk.dim("    Open a new shell (or `source` that file), then re-run `compaction init --connect " + meta.connectNum + "` to verify."), chalk.dim(`    Undo:  compaction init --disconnect ${meta.connectNum}  (removes the shim and restores the backup).`));
+        }
+        else {
+            out.push("", chalk.dim("    Prefer Compaction append it for you? Re-run with --write-shell-config (writes a reversible .bak backup first)."));
+        }
+        return out;
+    }
+    if (result.status === "no-real-binary") {
+        return [
+            `  ${chalk.bold("▸ " + title)} ${chalk.dim("— not found")}`,
+            "",
+            chalk.dim(`    No \`${result.shimName}\` binary was found on your PATH, so there is nothing to measure yet.`),
+            chalk.dim(`    Install ${title} first, then re-run \`compaction init --connect ${meta.connectNum}\`. Nothing was written.`)
+        ];
+    }
+    // verify-failed — NEVER claim connected.
+    return [
+        `  ${chalk.bold("▸ " + title)} ${chalk.red("— NOT connected")}`,
+        "",
+        chalk.red(`    A shim write to ${result.shimPath} was attempted but re-reading it did not confirm the shim.`),
+        "    Nothing is claimed connected. Check permissions on the Compaction shim directory and re-run."
+    ];
+}
+/** The reversible disconnect block for a Codex/Cursor shim. */
+function shimDisconnectBlock(tool, removed, shimPath, rc) {
+    const meta = SHIM_TOOL_LABELS[tool];
+    const lines = [
+        `  ${chalk.bold("▸ " + meta.title)} ${chalk.green("— disconnected")}`,
+        "",
+        removed
+            ? chalk.green(`    Removed the ${meta.title} shim (${shimPath}). The real ${SHIM_TOOLS[tool].shimName} binary was never touched.`)
+            : chalk.dim(`    No ${meta.title} shim was installed (${shimPath}); nothing to remove.`)
+    ];
+    if (rc && rc.status === "removed") {
+        lines.push(chalk.green(`    Reverted the shell-rc PATH line in ${rc.rcPath}` + (rc.backupRestored ? ` (restored from ${rc.backupRestored}).` : ".")));
+    }
+    lines.push(chalk.dim("    Open a new shell so the PATH change takes effect."));
+    return lines;
+}
+function skipBlock() {
+    return [
+        header("Skipped"),
+        "",
+        chalk.dim("  Nothing was installed or changed. Re-run `compaction init --connect 1` anytime to"),
+        chalk.dim("  connect Claude Code, or `compaction hooks install` to install the Stop hook directly.")
+    ];
+}
+/**
+ * The Claude Code install-result block. HONEST TENSE by status: it says "now active" ONLY when a
+ * re-read verified the hook landed (`installed` / `already-present`), and NEVER claims connected on
+ * a failed/unverified install — it prints the one exact manual command instead. Scope is stated
+ * explicitly (this project vs all your projects), with the required reload caveat.
+ */
+function claudeInstallBlock(result, user) {
+    const scopeParenthetical = user ? "all your projects" : "this project";
+    const scopeSuffix = user ? "in any project" : "in this project";
+    const manualCmd = `compaction hooks install${user ? " --user" : ""}`;
+    if (result.status === "installed" || result.status === "already-present") {
+        const headline = result.status === "already-present"
+            ? `    Compaction is already active for Claude Code (${scopeParenthetical}: ${result.settingsPath}).`
+            : `    Compaction is now active for Claude Code (${scopeParenthetical}: ${result.settingsPath}).`;
+        return [
+            `  ${chalk.bold("▸ Claude Code")} ${chalk.green("— connected")}`,
+            "",
+            chalk.green(headline),
+            `    From now on, supported Claude Code sessions ${scopeSuffix} are measured automatically —`,
+            "    no manual import needed. Reload Claude Code once (open /hooks or restart) to load the hook.",
+            chalk.dim("    Metrics-only; no prompt or response content is stored or uploaded."),
+            "",
+            chalk.dim("    See your runs anytime:  compaction activity")
+        ];
+    }
+    if (result.status === "dry-run") {
+        return [
+            `  ${chalk.bold("▸ Claude Code")} ${chalk.yellow("— dry run (nothing written)")}`,
+            "",
+            chalk.yellow(`    --dry-run: the hook was NOT installed. It would be merged into ${result.settingsPath}:`),
+            chalk.dim(JSON.stringify(result.wouldWrite ?? {}, null, 2)),
+            "",
+            chalk.dim("    Re-run without --dry-run to connect.")
+        ];
+    }
+    // verify-failed | error — NEVER claim connected. Print the one exact manual command.
+    const why = result.status === "error"
+        ? `Could not install safely: ${result.error ?? "unknown error"}. Nothing was written.`
+        : `A write to ${result.settingsPath} was attempted but re-reading it did not find the hook.`;
+    return [
+        `  ${chalk.bold("▸ Claude Code")} ${chalk.red("— NOT connected")}`,
+        "",
+        chalk.red(`    ${why}`),
+        "    Nothing is claimed connected. Install it yourself, then re-run to verify:",
+        `      ${ACCENT(manualCmd)}`
+    ];
+}
+/**
+ * Activation copy — the capability summary. `before-call` compaction is honestly hedged "where
+ * supported" (the Claude Code Stop hook is a post-session event, so before-call apply is NOT on
+ * this path — see docs/ops/always-on-followups.md). Auto-apply is OFF by default.
+ */
+function activationCopyBlock() {
+    return [
+        header("What Compaction does once connected"),
+        "",
+        "    - measure input/output tokens (metrics-only)",
+        "    - detect avoidable context",
+        "    - recommend safe compaction before the call where supported",
+        "    - ask before applying",
+        "    - remember auto-apply preferences only after explicit approval",
+        "    - record metrics-only activity for history (compaction activity)",
+        "",
+        chalk.dim("  Metrics only. No prompt or response content is stored or uploaded."),
+        chalk.dim("  Nothing is ever changed without asking you first. Auto-apply is off by default.")
+    ];
+}
+/** The static header (wordmark + detection + menu) shown above the per-choice action block. */
+function connectHeaderLines(det) {
+    return [
+        "",
+        `  ${WORDMARK}`,
+        "",
+        `  ${VALUE_PROMISE}`,
+        "",
+        RULE,
+        "",
+        ...connectDetectionBlock(det),
+        "",
+        ...connectMenuBlock(),
+        "",
+        RULE,
+        ""
+    ];
+}
+/**
+ * "Run a command through the Gateway" (preferred routing) — copy-ready guidance. The TUI takes no text
+ * input, so we print the exact `compaction gateway run -- <command>` form; running it starts/reuses the
+ * gateway, injects the base URL into the child (never a key), and reports whether traffic was observed.
+ */
+function printGatewayDevGuidance(listen) {
+    const out = [
+        "",
+        `  ${chalk.bold("▸ Run a command through the Gateway")}`,
+        chalk.dim("  The no-copy path: Compaction starts (or reuses) the local gateway, points your command's"),
+        chalk.dim("  OpenAI base URL at it, runs your command unchanged, and reports whether traffic was observed."),
+        "",
+        chalk.dim("  Run this next (replace with your dev/run command):"),
+        `    ${ACCENT("compaction gateway run -- npm run dev")}`,
+        `    ${ACCENT("compaction gateway run -- node app.js")}`,
+        "",
+        chalk.dim("  Your provider API key stays on the child process — the gateway never reads or stores it."),
+        chalk.dim("  Already running? Compaction cannot attach to a live process unless it already points at the"),
+        chalk.dim("  gateway — restart it through `compaction gateway run --` to route future calls."),
+        "",
+        chalk.dim(`  See traffic anytime:  ${ACCENT("compaction gateway status")}   ·   listen: ${listen}`),
+        ""
+    ];
+    console.log(out.join("\n"));
+}
+/**
+ * "Configure this project" (approval-gated) — plan-only preview. Detects the project's OpenAI-config
+ * surface and prints the exact diff that WOULD be written; it writes nothing. The user applies it with
+ * `compaction gateway configure --apply` (which backs up first).
+ */
+function printGatewayConfigurePreview(listen) {
+    const { host, port } = parseListen(listen);
+    const baseUrl = `http://${host}:${port}/v1`;
+    const plan = planGatewayConfigure(process.cwd(), baseUrl);
+    const out = ["", `  ${chalk.bold("▸ Configure this project")}`, ""];
+    for (const line of formatConfigurePlan(plan))
+        out.push(`  ${chalk.dim(line)}`);
+    out.push("", chalk.dim("  Nothing was written. This is a preview — apply it yourself when ready."), "");
+    console.log(out.join("\n"));
+}
 export function registerInitCommand(program) {
     program
-        .command("init")
+        // isDefault: bare `compaction` (no subcommand) opens onboarding — the interactive TUI in a real
+        // terminal (workflow chooser + Gateway setup), or the static screen elsewhere. `--help` still shows help.
+        .command("init", { isDefault: true })
         .description("First-run onboarding: an interactive workflow chooser in a real terminal (TUI), or the " +
-        "value promise + exact next commands as a static screen elsewhere. Guidance + one read-only " +
-        "local detection only — writes nothing, no network, no credentials.")
+        "value promise + exact next commands as a static screen elsewhere. The default screen writes " +
+        "nothing (read-only local detection, no network, no credentials). `--connect 1` installs the " +
+        "consented Claude Code Stop hook (merge-not-replace) and verifies it; `--connect 2`/`3` install " +
+        "+ verify a reversible Codex/Cursor PATH shim — connect-once always-on.")
         .option("--path <path>", "Focus one input path: claude-code | openai-agents | codex | import")
+        .option("--connect <choice>", "Connect-once menu: 1|claude-code, 2|codex, 3|cursor, 4|all, 5|skip. `1`/`all` installs + verifies the consented Claude Code Stop hook; `2`/`3` install + VERIFY a reversible Codex/Cursor PATH shim (never claims active without resolving the tool name).")
+        .option("--disconnect <choice>", "Reversibly remove a Codex/Cursor PATH shim: 2|codex, 3|cursor (restores any shell-rc backup). The real binary is never touched.")
+        .option("--write-shell-config", "With --connect 2/3: append the shim PATH line to your shell rc (zsh/bash), writing a reversible .bak backup first. Off by default — the default only PRINTS the line.")
+        .option("--user", "With --connect: install the Claude Code hook into ~/.claude/settings.json (all your projects) instead of the project's .claude/settings.json.")
+        .option("--dry-run", "With --connect: show what the Claude Code hook install would write, but write nothing.")
         .option("--projects-dir <dir>", "Claude Code projects directory to detect against (default: the standard local location)")
         .option("--interactive", "prefer the interactive TUI; if no TTY is available, show the static screen and why")
         .option("--static", "always show the plain static screen (no TUI)")
@@ -204,6 +505,72 @@ export function registerInitCommand(program) {
         // Read-only local detection (no writes, no network).
         const projectsDir = options.projectsDir ?? defaultProjectsDir();
         const det = await detectClaudeCode(projectsDir);
+        // --disconnect: reversibly remove a Codex/Cursor shim (2|codex, 3|cursor). Restores any rc backup.
+        if (options.disconnect !== undefined) {
+            const choice = CONNECT_ALIASES[options.disconnect.trim().toLowerCase()];
+            const shimTool = choice === "codex" ? "codex" : choice === "cursor" ? "cursor" : undefined;
+            if (!shimTool) {
+                console.error(`unknown --disconnect '${options.disconnect}'. Valid: 2|codex, 3|cursor`);
+                process.exitCode = 1;
+                return;
+            }
+            const uninstalled = uninstallToolShim(shimTool);
+            const rc = removeShellConfigPathLine();
+            const lines = shimDisconnectBlock(shimTool, uninstalled.status === "removed", uninstalled.shimPath, rc);
+            console.log([...connectHeaderLines(det), ...lines, "", RULE, ""].join("\n"));
+            return;
+        }
+        // --connect: the connect-once menu. `1`/`all` (Claude Code) installs + verifies the consented
+        // Stop hook; `2`/`3` install + VERIFY a reversible Codex/Cursor PATH shim; skip changes nothing.
+        if (options.connect !== undefined) {
+            const resolved = CONNECT_ALIASES[options.connect.trim().toLowerCase()];
+            if (!resolved) {
+                console.error(`unknown --connect '${options.connect}'. Valid: 1|claude-code, 2|codex, 3|cursor, 4|all, 5|skip`);
+                process.exitCode = 1;
+                return;
+            }
+            const actionLines = [];
+            if (resolved === "skip") {
+                actionLines.push(...skipBlock());
+            }
+            else {
+                // Claude Code (or "all") is the ONE install-capable choice: real merge-not-replace install
+                // into project .claude/settings.json (or ~/.claude/settings.json with --user), then a
+                // re-read VERIFY. This is the only init path that writes — running it IS the consent.
+                if (resolved === "claude-code" || resolved === "all") {
+                    const settingsPath = options.user
+                        ? path.join(homedir(), ".claude", "settings.json")
+                        : path.join(process.cwd(), ".claude", "settings.json");
+                    const result = await connectClaudeCodeHook({
+                        settingsPath,
+                        ...(options.dryRun ? { dryRun: true } : {})
+                    });
+                    actionLines.push(...claudeInstallBlock(result, Boolean(options.user)));
+                    // Honesty: a failed/unverified install must not exit 0 as if connected.
+                    if (result.status === "verify-failed" || result.status === "error")
+                        process.exitCode = 1;
+                    actionLines.push("");
+                }
+                // Codex/Cursor: install + VERIFY a reversible PATH shim (the run-8 pattern applied to a shim).
+                // "connected" is claimed ONLY when the shim resolves active; otherwise the exact export line
+                // is printed and it is honestly reported "not yet active". Auto-apply stays OFF (no apply path).
+                const shimTools = resolved === "all" ? ["codex", "cursor"] : resolved === "codex" ? ["codex"] : resolved === "cursor" ? ["cursor"] : [];
+                for (const shimTool of shimTools) {
+                    const install = installToolShim(shimTool);
+                    let wroteShellConfig;
+                    if (options.writeShellConfig && install.status === "installed-not-on-path") {
+                        const rc = writeShellConfigPathLine();
+                        wroteShellConfig = { rcPath: rc.rcPath, status: rc.status, ...(rc.backupPath ? { backupPath: rc.backupPath } : {}) };
+                    }
+                    actionLines.push(...shimConnectBlock(install, wroteShellConfig), "");
+                    // Honesty: an unverified/failed shim write must not exit 0 as if connected.
+                    if (install.status === "verify-failed")
+                        process.exitCode = 1;
+                }
+            }
+            console.log([...connectHeaderLines(det), ...actionLines, RULE, "", ...activationCopyBlock(), ""].join("\n"));
+            return;
+        }
         // Decide static vs interactive. A focused path (--path) or --static always
         // serves static; --interactive forces the TUI iff a TTY is present;
         // otherwise auto-detect.
@@ -216,21 +583,59 @@ export function registerInitCommand(program) {
         if (wantTui) {
             // Dynamic import keeps Ink/React off every non-TTY code path.
             const { runInitTui } = await import("../onboarding/InitTui.js");
-            const result = await runInitTui({
-                version,
-                detection: {
-                    detected: det.claudeDetected,
-                    sessionCount: det.sessionCount,
-                    projectsDir: det.projectsDir
+            // Loop so "Back" from the Gateway setup flow returns to the workflow chooser.
+            for (;;) {
+                const result = await runInitTui({
+                    version,
+                    detection: {
+                        detected: det.claudeDetected,
+                        sessionCount: det.sessionCount,
+                        projectsDir: det.projectsDir
+                    }
+                });
+                if (result.action !== "select") {
+                    console.log(chalk.dim("\nNo workflow selected. Run `compaction` anytime.\n"));
+                    return;
                 }
-            });
-            if (result.action === "select") {
-                printSelection(result.card);
-            }
-            else {
-                console.log(chalk.dim("\nNo workflow selected. Run `compaction init` anytime.\n"));
+                if (result.card.key !== "gateway") {
+                    printSelection(result.card);
+                    return;
+                }
+                // Gateway setup card → guided flow (a sibling Ink screen). The routing step resolves to one of:
+                // dev (preferred, no-copy), configure (approval-gated), or start (manual routing).
+                const { runGatewayTui } = await import("../onboarding/GatewayTui.js");
+                const g = await runGatewayTui();
+                if (g.action === "back")
+                    continue; // back to the chooser
+                if (g.action === "dev") {
+                    printGatewayDevGuidance(g.config.listen);
+                    return;
+                }
+                if (g.action === "configure") {
+                    printGatewayConfigurePreview(g.config.listen);
+                    return;
+                }
+                if (g.action !== "start") {
+                    console.log(chalk.dim("\nNo gateway started. Run `compaction` anytime.\n"));
+                    return;
+                }
+                try {
+                    const listen = parseListen(g.config.listen);
+                    await runGatewayStart({
+                        provider: g.config.provider,
+                        upstream: g.config.upstream,
+                        mode: g.config.mode, // record by default; apply only when explicitly armed + confirmed in the TUI
+                        ...(g.config.policy ? { policy: g.config.policy } : {}),
+                        host: listen.host,
+                        port: listen.port
+                    });
+                }
+                catch (err) {
+                    console.error(`error: could not start the gateway — ${err.message}`);
+                    process.exitCode = 1;
+                }
+                return;
             }
-            return;
         }
         // If the user explicitly asked for --interactive but we are not in a TTY,
         // tell them why we fell back, then serve the static screen.

package/dist/cli/commands/input-compaction-ab.d.ts

@@ -0,0 +1,2 @@
+import { Command } from "commander";
+export declare function registerInputCompactionAbCommand(program: Command): void;

package/dist/cli/commands/input-compaction-ab.js

@@ -0,0 +1,125 @@
+/**
+ * `compaction input-compaction-ab` — the operator-run path to produce + ingest a real provider-reported
+ * INPUT-compaction A/B for Codex (control = full input context, treatment = Compaction-compacted context),
+ * gated for a confirmed claim on a CONTEXT-PRESERVATION eval. Design: `docs/design/input-compaction-ab.md`.
+ * Mirrors `output-shaping-ab` but for INPUT tokens with a different (context-preservation) eval.
+ *
+ *   compaction input-compaction-ab init   --experiment <id> --out <file> [--task-shape <label>]
+ *   compaction input-compaction-ab add    --experiment <file> --arm control|treatment --usage <capture-usage.json>
+ *                                         [treatment: --context-preserved <yes|no> --task-solved <yes|no>
+ *                                          --source-recoverable <yes|no> --commitment-preserved <yes|no>
+ *                                          --context-complete <yes|no>]   // --context-complete = no material loss
+ *   compaction input-compaction-ab status --experiment <file>
+ *
+ * Honesty (binding): this PUBLIC CLI shows the OBSERVED input-token delta + a conservative confidence; it
+ * NEVER shows a confirmed input-savings number (the engine gate does). Output-token delta is shown as
+ * secondary only. Input eval = context-preservation (NOT short-but-sufficient).
+ */
+import { readFile, writeFile } from "node:fs/promises";
+import chalk from "chalk";
+import { addInputCompactionAbRun, initInputCompactionAbExperiment, runFromSidecar, summarizeInputCompactionAb } from "../../core/input-compaction-ab.js";
+const PRIVACY_NOTE = "Operator-run, local-first. compaction.dev makes NO provider call, reads NO credential, and has NO network access. " +
+    "Token counts come from YOUR capture artifacts. This CLI shows the OBSERVED input-token A/B only — a CONFIRMED " +
+    "input-savings number is produced solely by the engine gate (provider-reported, measured criterion, context-preservation pass).";
+async function loadExperiment(file) {
+    return JSON.parse(await readFile(file, "utf8"));
+}
+async function saveExperiment(file, experiment) {
+    await writeFile(file, JSON.stringify(experiment, null, 2), "utf8");
+}
+function resolveArm(arm) {
+    if (arm !== "control" && arm !== "treatment")
+        throw new Error('--arm must be "control" or "treatment".');
+    return arm;
+}
+/** Parse a yes/no flag into a tri-state outcome: "yes"→true, "no"→false, absent→null (not evaluated). */
+function yesNo(value, flag) {
+    if (value === undefined)
+        return null;
+    const v = value.toLowerCase();
+    if (v === "yes" || v === "true" || v === "pass")
+        return true;
+    if (v === "no" || v === "false" || v === "fail")
+        return false;
+    throw new Error(`${flag} must be "yes" or "no".`);
+}
+export function registerInputCompactionAbCommand(program) {
+    const ab = program
+        .command("input-compaction-ab")
+        .description("Operator-run, content-free INPUT-compaction A/B harness: link a control arm (full context) and a " +
+        "treatment arm (Compaction-compacted context) of Codex captures and show the OBSERVED provider-reported " +
+        "INPUT-token delta, gated for a confirmed claim on a CONTEXT-PRESERVATION eval (NOT output sufficiency). " +
+        "Shows confirmed savings NEVER — the engine gate does that.");
+    ab.command("init")
+        .description("Create a new input-compaction A/B experiment file.")
+        .requiredOption("--experiment <id>", "Experiment id (a short label, not content).")
+        .requiredOption("--out <file>", "Path to write the experiment JSON.")
+        .option("--task-shape <label>", "Short generic label of the shared task/context SHAPE (not prompt content).", "unspecified-task-shape")
+        .action(async (options) => {
+        console.log(chalk.cyan("compaction input-compaction-ab init"));
+        console.log(PRIVACY_NOTE);
+        const experiment = initInputCompactionAbExperiment({ experimentId: options.experiment, taskShape: options.taskShape ?? "unspecified-task-shape" });
+        await saveExperiment(options.out, experiment);
+        console.log(chalk.green(`Wrote ${options.out}`));
+        console.log("  Next: run both arms (full vs Compaction-compacted context), then `add` each capture-usage.json.");
+        console.log("    1. compaction compact <trace> --eval --out <dir>            # context-preservation eval");
+        console.log("    2. compaction apply-context <trace> --approve-in-workflow-use --out <dir>   # compacted context");
+        console.log('    control:   compaction capture codex --out runs/c1 -- codex exec --json "<task> + FULL context"');
+        console.log('    treatment: compaction capture codex --out runs/t1 -- codex exec --json "<task> + COMPACTED context"');
+    });
+    ab.command("add")
+        .description("Ingest a capture-usage.json into an arm. For treatment, record the context-preservation outcome.")
+        .requiredOption("--experiment <file>", "Path to the experiment JSON (from `init`).")
+        .requiredOption("--arm <arm>", 'Which arm: "control" (full context) or "treatment" (compacted context).')
+        .requiredOption("--usage <file>", "Path to a capture-usage.json sidecar written by `compaction capture codex`.")
+        .option("--context-preserved <yes|no>", "Treatment: task-critical context preserved?")
+        .option("--task-solved <yes|no>", "Treatment: did the treatment output still solve the same task?")
+        .option("--source-recoverable <yes|no>", "Treatment: source recoverability preserved (from `compact --eval`)?")
+        .option("--commitment-preserved <yes|no>", "Treatment: instruction/commitment preservation (from `compact --eval`)?")
+        .option("--context-complete <yes|no>", "Treatment: no material context loss (the compacted context is complete for the task)?")
+        .action(async (options) => {
+        console.log(chalk.cyan("compaction input-compaction-ab add"));
+        const arm = resolveArm(options.arm);
+        const sidecar = JSON.parse(await readFile(options.usage, "utf8"));
+        const run = runFromSidecar(arm, sidecar, arm === "treatment"
+            ? {
+                contextPreserved: yesNo(options.contextPreserved, "--context-preserved"),
+                taskSolved: yesNo(options.taskSolved, "--task-solved"),
+                sourceRecoverability: yesNo(options.sourceRecoverable, "--source-recoverable"),
+                commitmentPreservation: yesNo(options.commitmentPreserved, "--commitment-preserved"),
+                noMaterialLoss: yesNo(options.contextComplete, "--context-complete")
+            }
+            : {}, options.usage);
+        const experiment = addInputCompactionAbRun(await loadExperiment(options.experiment), run);
+        await saveExperiment(options.experiment, experiment);
+        const src = run.providerReported ? chalk.green("provider-reported") : chalk.yellow(`${run.tokenSource} (not provider-reported)`);
+        console.log(`  Added ${chalk.bold(arm)} run: input=${run.inputTokens ?? "unavailable"} output=${run.outputTokens ?? "unavailable"} tokens, source=${src}.`);
+        if (!run.providerReported)
+            console.log(chalk.yellow("  ! this arm is not provider-reported → it can never produce a confirmed input-savings number."));
+    });
+    ab.command("status")
+        .description("Show the OBSERVED input-token A/B + conservative confidence (never a confirmed savings number).")
+        .requiredOption("--experiment <file>", "Path to the experiment JSON.")
+        .action(async (options) => {
+        console.log(chalk.cyan("compaction input-compaction-ab status"));
+        console.log(PRIVACY_NOTE);
+        const s = summarizeInputCompactionAb(await loadExperiment(options.experiment));
+        const fmt = (n) => (n === null ? chalk.gray("unavailable") : `${Math.round(n)}`);
+        console.log(`  experiment:                 ${s.experimentId}`);
+        console.log(`  N (control / treatment):    ${s.nControl} / ${s.nTreatment}`);
+        console.log(`  input_tokens_before:        ${fmt(s.inputTokensBefore)}`);
+        console.log(`  input_tokens_after:         ${fmt(s.inputTokensAfter)}`);
+        console.log(`  input_token_delta:          ${fmt(s.inputTokenDelta)}  ${chalk.gray("(observed, not confirmed)")}`);
+        console.log(`  input_token_reduction_pct:  ${s.inputTokenReductionPct === null ? chalk.gray("unavailable") : `${s.inputTokenReductionPct.toFixed(1)}%`}  ${chalk.gray("(observed)")}`);
+        console.log(`  output_token_delta:         ${fmt(s.outputTokenDelta)}  ${chalk.gray("(observed, SECONDARY — not the input claim)")}`);
+        console.log(`  token_source:               ${s.tokenSource}`);
+        console.log(`  context-preservation eval:  ${s.contextPreservation}  ${chalk.gray("(recoverability + commitment + no-material-loss + task-solved; NOT short-but-sufficient)")}`);
+        console.log(`  semantic eval:              ${s.semanticEval}`);
+        const conf = s.confidence === "unavailable" ? chalk.gray(s.confidence) : chalk.yellow(s.confidence);
+        console.log(`  confidence:                 ${conf}`);
+        console.log(`  confirmed input savings:    ${chalk.gray("unavailable in the public CLI — the engine gate produces a confirmed number.")}`);
+        for (const reason of s.reasons)
+            console.log(chalk.gray(`    • ${reason}`));
+    });
+}
+//# sourceMappingURL=input-compaction-ab.js.map