@compaction/cli 0.2.0 → 0.3.1

package/dist/cli/commands/optimize-hosted.d.ts

@@ -0,0 +1,54 @@
+import { buildOptimizeRequest, type ApiConfig, type ToolName } from "../../core/api-client/index.js";
+import type { AgentTrace } from "../../core/types.js";
+/**
+ * V0.4 — the smallest CLI → hosted-API upgrade loop for `optimize openai-agents` (open-core).
+ *
+ * UPGRADE PATH (design `docs/design/cli-to-hosted-api-upgrade-path.md`): when — and ONLY when —
+ * both `COMPACTION_API_URL` and `COMPACTION_API_KEY` are set, `optimize` routes through the
+ * existing pure-HTTP `api-client` to the hosted Compaction API instead of the local engine /
+ * degrade path. There is NO engine import here (pure HTTP + the FREE capture adapter), so the
+ * open-core boundary is unchanged and the public npm package stays engine-free.
+ *
+ * HARD RAILS: default request is CONTENT-FREE (`metrics_only`) — the trace content is NOT
+ * uploaded. The API key is attached as `Authorization: Bearer` by the client and is NEVER logged,
+ * printed, persisted, or placed in an error. The request body never appears in an error. A hosted
+ * failure exits non-zero with a concise, actionable message and NEVER pretends a local
+ * optimization happened. No billing-confirmed or semantic-correctness claim is made.
+ */
+/** True iff BOTH the hosted URL and key are configured — the explicit opt-in to the hosted path. */
+export declare function hostedConfigured(env?: NodeJS.ProcessEnv): boolean;
+/**
+ * Build a CONTENT-FREE (`metrics_only`) optimize request from a captured trace. No inline trace
+ * content is attached — only local token-count estimates, a local reference, and CONTENT-FREE
+ * attribution (tool/provider/model identifiers). Content-free ⇒ the api-client sends without a
+ * consent/confirm gate. Attribution is only attached when actually known; the model is taken from
+ * the captured trace (never inferred).
+ */
+export declare function buildContentFreeOptimizeBody(trace: AgentTrace, reference: string, attribution?: {
+    tool?: ToolName;
+    provider?: string;
+}): import("../../core/api-client/types.js").OptimizeRequest;
+export type HostedOptimizeResult = {
+    kind: "ok";
+    status: number;
+    body: unknown;
+} | {
+    kind: "error";
+    message: string;
+};
+/**
+ * Send a pre-built content-free optimize body to the hosted API. Returns a sanitized result —
+ * an error `message` NEVER contains the API key, the Authorization header, or the request body.
+ */
+export declare function sendHostedOptimize(config: ApiConfig, body: ReturnType<typeof buildOptimizeRequest>): Promise<HostedOptimizeResult>;
+/** Render the hosted result honestly. No key/body in any line; the API's own honest labels only. */
+export declare function renderHostedOptimizeLines(result: HostedOptimizeResult): string[];
+/**
+ * Orchestrate the hosted optimize loop: capture LOCALLY (free, no engine, no upload) → build a
+ * content-free request → send via the api-client → render honestly. Sets a non-zero exit code on
+ * any failure and never claims a local optimization occurred.
+ */
+export declare function runHostedOptimizeOpenAIAgents(opts: {
+    out: string;
+    commandParts: string[];
+}): Promise<void>;

package/dist/cli/commands/optimize-hosted.js

@@ -0,0 +1,123 @@
+import chalk from "chalk";
+import { ApiNotConfirmedError, ApiTransportError, buildOptimizeRequest, ConsentError, resolveApiConfig, sendRequest } from "../../core/api-client/index.js";
+import { captureOpenAIAgentsCommand } from "../../core/openai-agents-capture.js";
+import { estimateTraceTokens } from "../../core/token-estimator.js";
+/**
+ * V0.4 — the smallest CLI → hosted-API upgrade loop for `optimize openai-agents` (open-core).
+ *
+ * UPGRADE PATH (design `docs/design/cli-to-hosted-api-upgrade-path.md`): when — and ONLY when —
+ * both `COMPACTION_API_URL` and `COMPACTION_API_KEY` are set, `optimize` routes through the
+ * existing pure-HTTP `api-client` to the hosted Compaction API instead of the local engine /
+ * degrade path. There is NO engine import here (pure HTTP + the FREE capture adapter), so the
+ * open-core boundary is unchanged and the public npm package stays engine-free.
+ *
+ * HARD RAILS: default request is CONTENT-FREE (`metrics_only`) — the trace content is NOT
+ * uploaded. The API key is attached as `Authorization: Bearer` by the client and is NEVER logged,
+ * printed, persisted, or placed in an error. The request body never appears in an error. A hosted
+ * failure exits non-zero with a concise, actionable message and NEVER pretends a local
+ * optimization happened. No billing-confirmed or semantic-correctness claim is made.
+ */
+/** True iff BOTH the hosted URL and key are configured — the explicit opt-in to the hosted path. */
+export function hostedConfigured(env = process.env) {
+    const url = (env.COMPACTION_API_URL ?? "").trim();
+    const key = (env.COMPACTION_API_KEY ?? "").trim();
+    return url !== "" && key !== "";
+}
+/**
+ * Build a CONTENT-FREE (`metrics_only`) optimize request from a captured trace. No inline trace
+ * content is attached — only local token-count estimates, a local reference, and CONTENT-FREE
+ * attribution (tool/provider/model identifiers). Content-free ⇒ the api-client sends without a
+ * consent/confirm gate. Attribution is only attached when actually known; the model is taken from
+ * the captured trace (never inferred).
+ */
+export function buildContentFreeOptimizeBody(trace, reference, attribution = {}) {
+    const tokens = estimateTraceTokens(trace);
+    const model = typeof trace.model === "string" && trace.model.trim() !== "" ? trace.model : undefined;
+    return buildOptimizeRequest({
+        trace: { redacted: true, reference },
+        payloadClass: "metrics_only",
+        tokenSource: "local-estimate",
+        inputTokens: tokens.inputTokens,
+        outputTokens: tokens.outputTokens,
+        optimizationMode: "recommend",
+        ...(attribution.tool ? { tool: attribution.tool } : {}),
+        ...(attribution.provider ? { provider: attribution.provider } : {}),
+        ...(model ? { model } : {})
+    });
+}
+/**
+ * Send a pre-built content-free optimize body to the hosted API. Returns a sanitized result —
+ * an error `message` NEVER contains the API key, the Authorization header, or the request body.
+ */
+export async function sendHostedOptimize(config, body) {
+    try {
+        const response = await sendRequest(config, "/v0/optimize", body);
+        if (!response.ok) {
+            const code = response.body?.error ?? "error";
+            const hint = response.status === 401
+                ? "unauthorized — check that COMPACTION_API_KEY is valid for this endpoint"
+                : `HTTP ${response.status} (${code})`;
+            return { kind: "error", message: `hosted optimize rejected: ${hint}` };
+        }
+        return { kind: "ok", status: response.status, body: response.body };
+    }
+    catch (error) {
+        // Sanitized — never echo the key, headers, or body. Map known client errors to a hint.
+        if (error instanceof ApiTransportError) {
+            return { kind: "error", message: "could not reach the hosted Compaction API (transport error); check COMPACTION_API_URL" };
+        }
+        if (error instanceof ConsentError || error instanceof ApiNotConfirmedError) {
+            return { kind: "error", message: "request refused before sending by the no-auto-upload gate (content-free path should not hit this)" };
+        }
+        return { kind: "error", message: "hosted optimize failed" };
+    }
+}
+/** Render the hosted result honestly. No key/body in any line; the API's own honest labels only. */
+export function renderHostedOptimizeLines(result) {
+    if (result.kind === "error") {
+        return [
+            chalk.red(`Hosted optimize error: ${result.message}.`),
+            "Nothing was applied; NO local optimization was performed."
+        ];
+    }
+    return [
+        chalk.green("Hosted optimize OK (review-only; nothing applied)."),
+        JSON.stringify(result.body, null, 2),
+        "Labels above are the hosted API's own: token deltas are local-estimate, cost is " +
+            "token-estimated-cost — NOT billing-confirmed, NOT a semantic-preservation claim, and not " +
+            "extrapolated to any time period."
+    ];
+}
+/**
+ * Orchestrate the hosted optimize loop: capture LOCALLY (free, no engine, no upload) → build a
+ * content-free request → send via the api-client → render honestly. Sets a non-zero exit code on
+ * any failure and never claims a local optimization occurred.
+ */
+export async function runHostedOptimizeOpenAIAgents(opts) {
+    const config = resolveApiConfig();
+    console.log(chalk.cyan("compaction optimize openai-agents (hosted)"));
+    console.log(`Hosted Compaction API: ${config.url}`);
+    console.log("Content-free request (metrics_only): your trace content is NOT uploaded. No auto-apply, no billing claim.");
+    // 1. Capture the trace LOCALLY (free adapter — no engine, no upload).
+    const capture = await captureOpenAIAgentsCommand(opts.commandParts, opts.out);
+    if (!capture.trace) {
+        console.error(chalk.red("Hosted optimize: local capture produced no trace (see the capture report for per-event reasons)."));
+        console.error("Nothing was applied; NO local optimization was performed.");
+        process.exitCode = 1;
+        return;
+    }
+    // 2. Content-free body + 3. send (Bearer key attached by the client; never logged).
+    //    Attribution is the OpenAI Agents capture adapter's known identity — tool + provider only;
+    //    the model rides along from the captured trace inside buildContentFreeOptimizeBody.
+    const body = buildContentFreeOptimizeBody(capture.trace, capture.paths.capturedTracePath, {
+        tool: "openai-agents",
+        provider: "openai"
+    });
+    const result = await sendHostedOptimize(config, body);
+    // 4. Render honestly.
+    for (const line of renderHostedOptimizeLines(result))
+        console.log(line);
+    if (result.kind === "error")
+        process.exitCode = 1;
+}
+//# sourceMappingURL=optimize-hosted.js.map

package/dist/cli/commands/optimize.js

@@ -1,5 +1,6 @@
 import chalk from "chalk";
 import { runEngineCommand } from "../engine-degrade.js";
+import { hostedConfigured, runHostedOptimizeOpenAIAgents } from "./optimize-hosted.js";
 export function registerOptimizeCommand(program) {
     const optimize = program.command("optimize").description("Run local trace optimization loops for supported integrations.");
     optimize
@@ -9,6 +10,13 @@ export function registerOptimizeCommand(program) {
         .argument("[commandParts...]", "Command and arguments to execute after --")
         .allowUnknownOption(true)
         .action(async (commandParts, options) => {
+        // UPGRADE PATH: only when BOTH COMPACTION_API_URL + COMPACTION_API_KEY are set, route through
+        // the pure-HTTP api-client to the hosted Compaction API (no engine, no default network). When
+        // unconfigured, the original local-engine-or-degrade path below runs BYTE-IDENTICALLY.
+        if (hostedConfigured()) {
+            await runHostedOptimizeOpenAIAgents({ out: options.out, commandParts });
+            return;
+        }
         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).

package/dist/cli/commands/output-shaping-ab.d.ts

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

package/dist/cli/commands/output-shaping-ab.js

@@ -0,0 +1,132 @@
+/**
+ * `compaction output-shaping-ab` — the operator-run path to produce + ingest a real provider-reported A/B
+ * comparison for the output-shaping policy family (increment 4). Mirrors the `billing-delta` harness:
+ * local-first, content-free, no network, no credentials.
+ *
+ *   compaction output-shaping-ab init   --experiment <id> --out <file> [--task-shape <label>]
+ *   compaction output-shaping-ab add    --experiment <file> --arm control|treatment --usage <capture-usage.json>
+ *                                       [--eval-pass | --eval-fail] [--truncated] [--refused]
+ *   compaction output-shaping-ab status --experiment <file>
+ *
+ * Honesty (binding): this PUBLIC CLI shows only the OBSERVED measurement + a conservative confidence
+ * (unavailable / review_required / observed_not_confirmed / eligible_for_engine_confirmation). It NEVER
+ * shows a confirmed output-savings number — that is produced solely by the private engine gate. A/B arms
+ * without provider-reported output tokens (e.g. Cursor) stay `unavailable`.
+ */
+import { readFile, writeFile } from "node:fs/promises";
+import chalk from "chalk";
+import { addOutputShapingAbRun, initOutputShapingAbExperiment, summarizeOutputShapingAb } from "../../core/output-shaping-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 A/B only — a CONFIRMED output-savings " +
+    "number is produced solely by the engine gate (provider-reported, measured criterion, short-but-sufficient, reduction).";
+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;
+}
+/** Operator-recorded sufficiency outcome: --eval-pass → true, --eval-fail → false, neither → undefined. */
+function resolveEval(options) {
+    if (options.evalPass && options.evalFail)
+        throw new Error("pass --eval-pass OR --eval-fail, not both.");
+    if (options.evalPass)
+        return true;
+    if (options.evalFail)
+        return false;
+    return undefined;
+}
+export function registerOutputShapingAbCommand(program) {
+    const ab = program
+        .command("output-shaping-ab")
+        .description("Operator-run, content-free output-shaping A/B harness: link a control arm (no shaping) and a " +
+        "treatment arm (--output-shaping) of Codex captures and show the OBSERVED provider-reported output-token " +
+        "delta. Shows confirmed savings NEVER — the engine gate does that.");
+    ab.command("init")
+        .description("Create a new output-shaping 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/prompt SHAPE (not prompt content).", "unspecified-task-shape")
+        .action(async (options) => {
+        console.log(chalk.cyan("compaction output-shaping-ab init"));
+        console.log(PRIVACY_NOTE);
+        const experiment = initOutputShapingAbExperiment({ 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, then `output-shaping-ab add` each capture-usage.json.");
+        console.log('    control:   compaction capture codex --out runs/a1 -- codex exec --json "TASK"');
+        console.log('    treatment: compaction capture codex --output-shaping --out runs/b1 -- codex exec --json "TASK"');
+    });
+    ab.command("add")
+        .description("Ingest a capture-usage.json sidecar into an A/B arm (provider-reported tokens + policy names).")
+        .requiredOption("--experiment <file>", "Path to the experiment JSON (from `init`).")
+        .requiredOption("--arm <arm>", 'Which arm: "control" (no shaping) or "treatment" (--output-shaping).')
+        .requiredOption("--usage <file>", "Path to a capture-usage.json sidecar written by `compaction capture`.")
+        .option("--eval-pass", "Record that the treatment output preserved all required task-outcome markers (short-but-sufficient).")
+        .option("--eval-fail", "Record that the treatment output dropped a required marker (shorter-but-lossy — not a saving).")
+        .option("--truncated", "Record that the answer was truncated/incomplete (not a saving).")
+        .option("--refused", "Record that the model refused (not a saving).")
+        .action(async (options) => {
+        console.log(chalk.cyan("compaction output-shaping-ab add"));
+        const arm = resolveArm(options.arm);
+        const evalOutcome = resolveEval(options);
+        const sidecar = JSON.parse(await readFile(options.usage, "utf8"));
+        if (arm === "treatment" && (!sidecar.outputShaping || sidecar.outputShaping.policyNames.length === 0)) {
+            console.log(chalk.yellow("  ! warning: treatment arm but this capture has no output-shaping attribution (was --output-shaping used?)."));
+        }
+        if (arm === "control" && sidecar.outputShaping && sidecar.outputShaping.policyNames.length > 0) {
+            console.log(chalk.yellow("  ! warning: control arm but this capture HAS output-shaping attribution — control should be the no-shaping arm."));
+        }
+        const run = {
+            arm,
+            outputTokens: sidecar.outputTokens,
+            inputTokens: sidecar.inputTokens,
+            providerReported: sidecar.providerReported === true,
+            tokenSource: sidecar.tokenSource,
+            ...(arm === "treatment" && sidecar.outputShaping
+                ? { policyFamily: sidecar.outputShaping.policyFamily, policyNames: sidecar.outputShaping.policyNames }
+                : {}),
+            ...(arm === "treatment" ? { evalMarkersPreserved: evalOutcome ?? null } : {}),
+            ...(options.truncated ? { truncated: true } : {}),
+            ...(options.refused ? { refused: true } : {}),
+            reference: options.usage
+        };
+        const experiment = addOutputShapingAbRun(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: 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 output-savings number."));
+    });
+    ab.command("status")
+        .description("Show the OBSERVED A/B measurement + conservative confidence (never a confirmed savings number).")
+        .requiredOption("--experiment <file>", "Path to the experiment JSON.")
+        .action(async (options) => {
+        console.log(chalk.cyan("compaction output-shaping-ab status"));
+        console.log(PRIVACY_NOTE);
+        const summary = summarizeOutputShapingAb(await loadExperiment(options.experiment));
+        const fmt = (n, unit = "") => (n === null ? chalk.gray("unavailable") : `${Math.round(n)}${unit}`);
+        console.log(`  experiment:                 ${summary.experimentId}`);
+        console.log(`  N (control / treatment):    ${summary.nControl} / ${summary.nTreatment}`);
+        console.log(`  output_tokens_before:       ${fmt(summary.outputTokensBefore)}`);
+        console.log(`  output_tokens_after:        ${fmt(summary.outputTokensAfter)}`);
+        console.log(`  output_token_delta:         ${fmt(summary.outputTokenDelta)}  ${chalk.gray("(observed, not confirmed)")}`);
+        console.log(`  output_token_reduction_pct: ${summary.outputTokenReductionPct === null ? chalk.gray("unavailable") : `${summary.outputTokenReductionPct.toFixed(1)}%`}  ${chalk.gray("(observed)")}`);
+        console.log(`  token_source:               ${summary.tokenSource}`);
+        console.log(`  policy family / names:      ${summary.policyFamily ?? chalk.gray("none")} / ${summary.policyNames.length ? summary.policyNames.join(", ") : chalk.gray("none")}`);
+        console.log(`  eval (short-but-sufficient):${summary.evalStatus}`);
+        // `eligible_for_engine_confirmation` is a PRECONDITION, not a confirmation — keep it amber, not green,
+        // so the public status is never mistaken for a confirmed saving. `unavailable` is gray; the rest amber.
+        const conf = summary.confidence === "unavailable" ? chalk.gray(summary.confidence) : chalk.yellow(summary.confidence);
+        console.log(`  confidence:                 ${conf}`);
+        console.log(`  confirmed output savings:   ${chalk.gray("unavailable in the public CLI — the engine gate produces a confirmed number.")}`);
+        for (const reason of summary.reasons)
+            console.log(chalk.gray(`    • ${reason}`));
+    });
+}
+//# sourceMappingURL=output-shaping-ab.js.map

package/dist/cli/commands/output-shaping.d.ts

@@ -0,0 +1,7 @@
+import { Command } from "commander";
+/**
+ * `compaction output-shaping` — print the deterministic output-shaping instruction block to attach to a
+ * request BEFORE generation. Local, content-free; emits NO output-savings number (savings require a
+ * measured before/after + eval-confirmed sufficiency — the private/gated verification).
+ */
+export declare function registerOutputShapingCommand(program: Command): void;

package/dist/cli/commands/output-shaping.js

@@ -0,0 +1,43 @@
+import chalk from "chalk";
+import { buildOutputShapingPolicy, OUTPUT_SHAPING_POLICIES, OUTPUT_SHAPING_HONESTY_NOTE } from "../../core/output-shaping.js";
+/**
+ * `compaction output-shaping` — print the deterministic output-shaping instruction block to attach to a
+ * request BEFORE generation. Local, content-free; emits NO output-savings number (savings require a
+ * measured before/after + eval-confirmed sufficiency — the private/gated verification).
+ */
+export function registerOutputShapingCommand(program) {
+    program
+        .command("output-shaping")
+        .description("Print a deterministic output-shaping instruction block to attach to your request BEFORE generation " +
+        "(the only mechanism that reduces provider output tokens). Local, content-free; no savings claimed.")
+        .option("--budget <tokens>", "Soft verbosity budget in output tokens (used by the verbosity-budget policy)")
+        .option("--policies <names>", "Comma-separated policy names to apply (default: the default-on set)")
+        .option("--list", "List the available output-shaping policies and exit")
+        .action((options) => {
+        if (options.list) {
+            console.log(chalk.cyan("Output-shaping policies (deterministic, rule-based):"));
+            for (const p of OUTPUT_SHAPING_POLICIES) {
+                console.log(`  ${p.policy_name} [risk: ${p.risk_level}${p.defaultOn ? ", default-on" : ", off by default"}] — ${p.description}`);
+            }
+            console.log(chalk.gray(`\n${OUTPUT_SHAPING_HONESTY_NOTE}`));
+            return;
+        }
+        const budget = options.budget !== undefined ? Number.parseInt(options.budget, 10) : undefined;
+        const policies = options.policies ? options.policies.split(",").map((s) => s.trim()).filter(Boolean) : undefined;
+        const result = buildOutputShapingPolicy({
+            ...(budget !== undefined && Number.isFinite(budget) ? { verbosityBudgetTokens: budget } : {}),
+            ...(policies ? { policies } : {})
+        });
+        if (result.instructions === "") {
+            console.error("error: no matching output-shaping policies (use --list to see available policy names).");
+            process.exitCode = 1;
+            return;
+        }
+        console.log(chalk.cyan("compaction output-shaping"));
+        console.log(result.instructions);
+        console.log("");
+        console.log(chalk.gray(`Applied: ${result.applied.map((a) => a.policy_name).join(", ")}`));
+        console.log(chalk.gray(OUTPUT_SHAPING_HONESTY_NOTE));
+    });
+}
+//# sourceMappingURL=output-shaping.js.map

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

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

package/dist/cli/commands/policies.js

@@ -0,0 +1,80 @@
+import chalk from "chalk";
+import { disablePolicyPreference, explainPolicyPreference, findPolicyPreference, readPolicyPreferences } from "../../core/policy-preferences.js";
+/**
+ * `compaction policies` — READ-ONLY management of stored auto-apply PREFERENCES, plus the single
+ * safe mutating verb `disable`. There is deliberately NO `enable` here: enabling a preference only
+ * ever happens via the future live post-approval ask (the founder's binary question), never as a
+ * CLI gesture. Disabling can only ever REDUCE what could apply, so it is always safe.
+ *
+ * IMPORTANT: none of these commands apply anything. A preference is a stored intent only; no
+ * auto-apply engine exists (see `src/core/policy-preferences.ts`).
+ */
+function scopeLine(preference) {
+    return preference.scope.repo
+        ? `${preference.scope.tool} (repo ${preference.scope.repo})`
+        : preference.scope.tool;
+}
+function formatPreferencesList(preferences) {
+    if (preferences.length === 0) {
+        return "No auto-apply preferences saved. The default is ask-each-time — Compaction asks before applying anything.";
+    }
+    const header = ["id", "scope", "policy", "preference", "enabled", "gates_required"];
+    const rows = preferences.map((preference) => [
+        preference.id,
+        scopeLine(preference),
+        preference.scope.policy_type,
+        preference.preference,
+        preference.enabled ? "yes" : "no",
+        `${preference.gates_required.length} gate(s)`
+    ]);
+    const widths = header.map((cell, col) => Math.max(cell.length, ...rows.map((line) => line[col].length)));
+    const pad = (cells) => cells.map((cell, col) => cell.padEnd(widths[col])).join("  ");
+    const preamble = [
+        `Saved auto-apply preferences (${preferences.length}). These are STORED INTENTS only — no auto-apply`,
+        `engine exists yet, so nothing is applied automatically today.`,
+        ``
+    ];
+    const lines = [pad(header), pad(header.map((_, col) => "-".repeat(widths[col]))), ...rows.map(pad)];
+    return [...preamble, ...lines, ``, `Explain one:  compaction policies explain <id>`, `Turn one off: compaction policies disable <id>`].join("\n");
+}
+export function registerPoliciesCommand(program) {
+    const policies = program
+        .command("policies")
+        .description("View and disable stored auto-apply preferences (read-only + safe disable; no enable, no apply).");
+    policies
+        .command("list")
+        .description("List saved auto-apply preferences (id, scope, policy, preference, enabled, gates_required).")
+        .action(async () => {
+        const { preferences } = await readPolicyPreferences();
+        console.log(chalk.cyan(formatPreferencesList(preferences)));
+    });
+    policies
+        .command("disable <id>")
+        .description("Disable a saved preference by id (always safe — never enables, never applies).")
+        .action(async (id) => {
+        const result = await disablePolicyPreference(id);
+        if (!result.disabled) {
+            console.error(chalk.red(result.reason));
+            process.exitCode = 1;
+            return;
+        }
+        if (result.alreadyDisabled) {
+            console.log(chalk.yellow(`Preference ${id} was already disabled — nothing changed.`));
+            return;
+        }
+        console.log(chalk.green(`Disabled preference ${id}. It will not be honored by any future auto-apply.`));
+    });
+    policies
+        .command("explain <id>")
+        .description("Explain in plain language what a saved preference means and how to disable it.")
+        .action(async (id) => {
+        const preference = await findPolicyPreference(id);
+        if (!preference) {
+            console.error(chalk.red(`No preference with id "${id}" — run "compaction policies list" to see saved ids.`));
+            process.exitCode = 1;
+            return;
+        }
+        console.log(chalk.cyan(explainPolicyPreference(preference)));
+    });
+}
+//# sourceMappingURL=policies.js.map

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

@@ -0,0 +1,19 @@
+import { Command } from "commander";
+import { type BeforeCallRecommendation } from "../../core/before-call.js";
+/** The input-boundary an approved apply would mutate (drives the honest UX + activity wording). */
+export type ApplyBoundary = "prompt-flag" | "stdin";
+/** A minimal injectable terminal I/O surface (so the [y/n/v] decision is unit-testable off /dev/tty). */
+export interface PrecallTty {
+    write(text: string): void;
+    /** Read one trimmed line; empty string on EOF. */
+    readLine(): string;
+}
+export type ApplyChoice = "apply" | "decline";
+/**
+ * Drive the interactive `[y] apply · [n] no · [v] view details` decision on `io`. FAIL-CLOSED to
+ * DECLINE: `y` (and only `y`) approves; `v` shows content-free details then re-prompts; `n`, empty
+ * (Enter), EOF, or ANY other input declines (the original runs unchanged). No default yes. This is the
+ * function the PTY/`[v]` test drives directly with a fake tty stream (charter run-11 fallback).
+ */
+export declare function runApplyDecision(io: PrecallTty, rec: BeforeCallRecommendation, boundary?: ApplyBoundary): ApplyChoice;
+export declare function registerPrecallCommand(program: Command): void;