@compaction/cli 0.2.0 → 0.3.1

package/dist/core/cursor-capture.d.ts

@@ -0,0 +1,54 @@
+import { type UsageMetadata } from "./usage-metadata.js";
+import type { AgentTrace } from "./types.js";
+import { type LocalCommandRun } from "./command-runner.js";
+/**
+ * Extract the assistant `result` text + session id from Cursor headless output. Supports the single
+ * JSON object (`--output-format json`) and a stream-json stream (scans lines for a `result` object).
+ * Returns `outputSeparable: false` when no `result` field can be safely isolated.
+ */
+export declare function parseCursorAgentOutput(rawOutput: string): {
+    resultText?: string;
+    sessionId?: string;
+    outputSeparable: boolean;
+};
+/**
+ * Best-effort prompt extraction from the wrapped Cursor invocation: the non-flag positional args,
+ * excluding the executable + known subcommand keywords. Used ONLY for a local-estimate of input tokens
+ * (content-free count of text WE passed). Returns undefined when no prompt can be identified.
+ */
+export declare function extractCursorPrompt(commandParts: string[]): string | undefined;
+export interface CursorNormalizationResult {
+    trace: AgentTrace;
+    usageMetadata: UsageMetadata;
+    /** "present" when a prompt was identified (input locally estimated from it), else "unavailable". */
+    inputStatus: "present" | "unavailable";
+    /**
+     * The TRUE reason input is unavailable (set iff `inputStatus === "unavailable"`). Export-only runs
+     * (no invocation declared) get a DIFFERENT reason from declared-but-unidentifiable invocations, so the
+     * operator is never told "no prompt in the wrapped invocation" when there was no wrapped invocation.
+     */
+    inputUnavailableReason?: string;
+    /** "present" when the result field was separable (output estimated), else "unavailable". */
+    outputStatus: "present" | "unavailable";
+    /**
+     * The TRUE reason output is unavailable (set iff `outputStatus === "unavailable"`), so callers print
+     * the honest reason (e.g. "the captured output is empty") — never a hardcoded, possibly-wrong one.
+     */
+    outputUnavailableReason?: string;
+    warnings: string[];
+}
+/** Build an `AgentTrace` + LOCAL-ESTIMATE usage from captured Cursor headless output. */
+export declare function normalizeCursorAgentOutput(params: {
+    captureId: string;
+    rawOutput: string;
+    commandParts?: string[];
+    commandRun?: LocalCommandRun;
+    generatedAt?: string;
+}): CursorNormalizationResult;
+export interface CursorCaptureResult extends CursorNormalizationResult {
+    commandRun?: LocalCommandRun;
+}
+/** Live wrapper: spawn the Cursor headless CLI (no manual export), capture stdout, normalize. */
+export declare function captureCursorCommand(commandParts: string[], generatedAt?: string): Promise<CursorCaptureResult>;
+/** Offline/fallback: normalize a saved Cursor headless output (json / stream-json) string. */
+export declare function captureCursorExport(rawOutput: string, commandParts?: string[], generatedAt?: string): CursorCaptureResult;

package/dist/core/cursor-capture.js

@@ -0,0 +1,215 @@
+/**
+ * Cursor live-wrapper capture (PUBLIC CLI/SDK code — engine-free, ships in the npm package).
+ *
+ * Wraps a real Cursor **headless CLI agent** run (e.g. `cursor agent -p "<prompt>" --output-format
+ * json`) and normalizes its output to an `AgentTrace`. Design: `docs/design/cursor-live-wrapper.md`
+ * (accepted 2026-06-28) + the amended honesty matrix in `docs/design/unified-run-flow.md` (founder D2).
+ *
+ * HONESTY (the defining rails of this module):
+ * - **NO provider-reported tokens.** Cursor's CLI emits no usage; tokens here are **LOCAL-ESTIMATE
+ *   only** (chars/4), never provider-reported, never billing-confirmed.
+ * - **Input** is locally estimated from the prompt extracted from the wrapped invocation (where
+ *   available). **Output** is locally estimated from the headless **`result`** field when the output
+ *   can be safely separated (`--output-format json`); when it cannot, output is **UNAVAILABLE** (left
+ *   absent, with a stated reason) — never silently zero, never fabricated.
+ * - **NO output-token savings** (that is gated on the output-shaping policy family + eval).
+ * - **NO SQLite / private-storage reverse engineering.** Only the wrapped CLI's own stdout is read.
+ *
+ * Evidence tier: `source: "local_command"` (the same `imported_local` tier as the import path; below
+ * `real_captured`). The cross-tool record attributes `tool: "cursor"`, `token_source: local-estimate`.
+ */
+import { CURRENT_AGENT_TRACE_ARTIFACT_VERSION } from "./trace-parser.js";
+import { createUsageMetadata } from "./usage-metadata.js";
+import { estimateTextTokens } from "./token-estimator.js";
+import { executeLocalCommand, parseRunCommand } from "./command-runner.js";
+function toRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value) ? value : null;
+}
+function stringValue(value) {
+    return typeof value === "string" && value.trim() !== "" ? value : undefined;
+}
+/**
+ * Extract the assistant `result` text + session id from Cursor headless output. Supports the single
+ * JSON object (`--output-format json`) and a stream-json stream (scans lines for a `result` object).
+ * Returns `outputSeparable: false` when no `result` field can be safely isolated.
+ */
+export function parseCursorAgentOutput(rawOutput) {
+    // A saved export may carry a UTF-8 BOM (e.g. written on Windows). Strip it so a real, parseable
+    // `result` object is not silently mislabeled "unavailable" — the label must match the evidence.
+    const trimmed = rawOutput.replace(/^\uFEFF/, "").trim();
+    // Case 1: a single JSON result object.
+    const whole = (() => {
+        try {
+            return toRecord(JSON.parse(trimmed));
+        }
+        catch {
+            return null;
+        }
+    })();
+    if (whole) {
+        const resultText = stringValue(whole.result);
+        return { resultText, sessionId: stringValue(whole.session_id), outputSeparable: resultText !== undefined };
+    }
+    // Case 2: stream-json — scan lines for a `result` object (last one wins) + a session id.
+    let resultText;
+    let sessionId;
+    for (const line of trimmed.split(/\r?\n/)) {
+        const t = line.trim();
+        if (!t.startsWith("{") || !t.endsWith("}"))
+            continue;
+        let rec;
+        try {
+            rec = toRecord(JSON.parse(t));
+        }
+        catch {
+            continue;
+        }
+        if (!rec)
+            continue;
+        sessionId = sessionId ?? stringValue(rec.session_id);
+        const r = stringValue(rec.result);
+        if (r !== undefined)
+            resultText = r;
+    }
+    return { resultText, sessionId, outputSeparable: resultText !== undefined };
+}
+/**
+ * Best-effort prompt extraction from the wrapped Cursor invocation: the non-flag positional args,
+ * excluding the executable + known subcommand keywords. Used ONLY for a local-estimate of input tokens
+ * (content-free count of text WE passed). Returns undefined when no prompt can be identified.
+ */
+export function extractCursorPrompt(commandParts) {
+    const KEYWORDS = new Set(["cursor", "cursor-agent", "agent", "chat", "exec", "run"]);
+    // Boolean flags take no value, so the token after them is still a positional (e.g. the prompt).
+    // (Cursor selects machine output via `--output-format json` — a value-taking flag, handled below —
+    // so a bare `--json` boolean is intentionally NOT assumed here.)
+    const BOOLEAN_FLAGS = new Set(["-p", "--print", "--force"]);
+    const positionals = [];
+    let skipNext = false;
+    for (let i = 1; i < commandParts.length; i++) {
+        const part = commandParts[i];
+        if (skipNext) {
+            skipNext = false; // the value of a preceding value-taking flag (e.g. `--output-format json`)
+            continue;
+        }
+        if (part.startsWith("-")) {
+            if (!BOOLEAN_FLAGS.has(part) && !part.includes("="))
+                skipNext = true;
+            continue;
+        }
+        if (KEYWORDS.has(part))
+            continue;
+        positionals.push(part);
+    }
+    const prompt = positionals.join(" ").trim();
+    return prompt === "" ? undefined : prompt;
+}
+function addMessage(messages, role, content, timestamp, metadata) {
+    messages.push({ id: `cursor_msg_${messages.length + 1}`, role, content, timestamp, metadata });
+}
+const CURSOR_LOCAL_ESTIMATE_NOTE = "Cursor CLI emits no provider usage; tokens are LOCAL-ESTIMATE only (chars/4) — never provider-reported, never billing-confirmed.";
+/** Build an `AgentTrace` + LOCAL-ESTIMATE usage from captured Cursor headless output. */
+export function normalizeCursorAgentOutput(params) {
+    const generatedAt = params.generatedAt ?? new Date().toISOString();
+    const startedAt = params.commandRun?.startedAt ?? generatedAt;
+    const { resultText, sessionId, outputSeparable } = parseCursorAgentOutput(params.rawOutput);
+    const prompt = params.commandParts ? extractCursorPrompt(params.commandParts) : undefined;
+    const warnings = [];
+    const messages = [];
+    addMessage(messages, "system", "Cursor headless CLI capture (command wrapper).", startedAt, {
+        integration: "cursor",
+        captureMode: "command wrapper"
+    });
+    if (prompt)
+        addMessage(messages, "user", prompt, startedAt, { eventType: "prompt", tokenSource: "local-estimate" });
+    if (resultText)
+        addMessage(messages, "assistant", resultText, generatedAt, { eventType: "result", tokenSource: "local-estimate" });
+    // Input: local-estimate from the prompt where available. Output: local-estimate from the separable
+    // result field, else UNAVAILABLE (absent + a stated reason). Never provider-reported, never fabricated.
+    const inputTokens = prompt ? estimateTextTokens(prompt) : undefined;
+    const outputTokens = resultText ? estimateTextTokens(resultText) : undefined;
+    // The TRUE per-run unavailability reason: an EMPTY export/captured output is a different failure from
+    // present-but-not-separable output, and the guidance differs (`--output-format json` cannot fix an
+    // empty file). Stated exactly so the operator is never sent down the wrong path.
+    const outputUnavailableReason = outputSeparable
+        ? undefined
+        : params.rawOutput.trim() === ""
+            ? "the Cursor headless output is empty (no output was captured/saved — nothing to count)"
+            : "no separable `result` field in the Cursor headless output (use `--output-format json`)";
+    // The TRUE per-run reason input is unavailable. Export-only (no invocation declared at all) is a
+    // DIFFERENT situation from a declared invocation in which no prompt could be identified — the reason
+    // and the fix differ, so both are stated precisely (never a bare "unknown", never a fabricated count).
+    // The documented Cursor headless output (json / stream-json) carries result/session_id/duration —
+    // NOT the prompt — so input can never be derived from the export itself without format-guessing.
+    const inputUnavailableReason = prompt
+        ? undefined
+        : params.commandParts === undefined
+            ? "a saved Cursor export does not contain the prompt (the documented headless output carries the result, not the user input), and no invocation was declared after --"
+            : "no prompt could be identified in the wrapped invocation";
+    if (inputUnavailableReason) {
+        warnings.push(`Input tokens UNAVAILABLE: ${inputUnavailableReason}.`, params.commandParts === undefined
+            ? 'To get a LOCAL-ESTIMATE input count (chars/4 of the prompt YOU declare — never provider-reported), re-declare the original invocation after --: compaction run cursor --out <dir> --export <file> -- cursor agent -p "<your prompt>" --output-format json (same for capture cursor).'
+            : 'To get a LOCAL-ESTIMATE input count, pass the prompt in the invocation (e.g. cursor agent -p "<your prompt>" --output-format json).');
+    }
+    if (outputUnavailableReason) {
+        warnings.push(`Output tokens UNAVAILABLE: ${outputUnavailableReason}. ` +
+            "Provider-reported output is unavailable (Cursor emits no usage).");
+    }
+    const limitations = [CURSOR_LOCAL_ESTIMATE_NOTE];
+    // Both per-axis unavailability reasons ride in limitations so the SAME reason reaches every surface
+    // that renders this capture (CLI stdout notes, the local run record's notes, the summary rollup).
+    if (inputUnavailableReason)
+        limitations.push(`Input tokens are unavailable for this run (${inputUnavailableReason}).`);
+    if (outputUnavailableReason)
+        limitations.push(`Output tokens are unavailable for this run (${outputUnavailableReason}).`);
+    const usageMetadata = createUsageMetadata({
+        ...(inputTokens !== undefined ? { inputTokens } : {}),
+        ...(outputTokens !== undefined ? { outputTokens } : {}),
+        providerReportedTokens: false,
+        estimatedTokens: true,
+        provider: "cursor",
+        limitations
+    });
+    const trace = {
+        id: sessionId ?? `trace_cursor_${params.captureId}`,
+        title: "Cursor headless captured trace",
+        artifactVersion: CURRENT_AGENT_TRACE_ARTIFACT_VERSION,
+        source: "local_command",
+        createdAt: startedAt,
+        generatedAt,
+        model: "cursor-unknown-model",
+        command: params.commandRun
+            ? { command: params.commandRun.command.executable, args: params.commandRun.command.args, cwd: process.cwd() }
+            : { command: "cursor-export", args: [], cwd: process.cwd() },
+        durationMs: params.commandRun?.durationMs ?? 0,
+        exitCode: params.commandRun?.exitCode ?? 0,
+        messages
+    };
+    return {
+        trace,
+        usageMetadata,
+        inputStatus: prompt ? "present" : "unavailable",
+        ...(inputUnavailableReason !== undefined ? { inputUnavailableReason } : {}),
+        outputStatus: outputSeparable ? "present" : "unavailable",
+        ...(outputUnavailableReason !== undefined ? { outputUnavailableReason } : {}),
+        warnings
+    };
+}
+/** Live wrapper: spawn the Cursor headless CLI (no manual export), capture stdout, normalize. */
+export async function captureCursorCommand(commandParts, generatedAt) {
+    const parsed = parseRunCommand(commandParts);
+    const commandRun = await executeLocalCommand(parsed);
+    const result = normalizeCursorAgentOutput({
+        captureId: `${parsed.executable}-${commandRun.startedAt}`,
+        rawOutput: commandRun.rawOutput,
+        commandParts,
+        commandRun,
+        generatedAt
+    });
+    return { ...result, commandRun };
+}
+/** Offline/fallback: normalize a saved Cursor headless output (json / stream-json) string. */
+export function captureCursorExport(rawOutput, commandParts, generatedAt) {
+    return normalizeCursorAgentOutput({ captureId: "cursor-export", rawOutput, commandParts, generatedAt });
+}
+//# sourceMappingURL=cursor-capture.js.map

package/dist/core/cursor-preflight-probe.d.ts

@@ -0,0 +1,8 @@
+import type { CursorProbe } from "./cursor-preflight.js";
+/** True when EVERY arg is a recognized safe help/version token (no prompt, no `-p`, no `login`). */
+export declare function isSafeProbeArgs(args: string[]): boolean;
+/**
+ * Create the real SAFE probe. The returned probe spawns `<candidate> <args>` ONLY when `args` is a
+ * recognized safe help probe; otherwise it refuses (returns `resolved:false` without spawning).
+ */
+export declare function createSafeCursorProbe(timeoutMs?: number): CursorProbe;

package/dist/core/cursor-preflight-probe.js

@@ -0,0 +1,88 @@
+/**
+ * SAFE real probe adapter for the Cursor live-prep preflight (`cursor-preflight.ts`).
+ *
+ * This is the ONLY place the preflight spawns a child process, and it spawns ONLY a `--help`/`-v`-style
+ * capability probe. Defense-in-depth: it hard-rejects any arg set that is not a recognized safe help
+ * probe, so it can NEVER be coaxed into a real `-p` prompt, `cursor agent login`, or a credential read.
+ *
+ * - No stdin (closed): a probe never waits for input.
+ * - stdout/stderr captured only to inspect for the headless flags in --help text (content-free).
+ * - CURSOR_API_KEY is never read, set, or forwarded specially — the probe inherits the caller's env
+ *   unchanged (we never touch the key), and never prints env values.
+ * - Fail-friendly: an ENOENT / spawn error resolves to `resolved:false`, never a throw.
+ */
+import { spawn } from "node:child_process";
+/** Only these tokens may appear in a probe arg list. Anything else is refused (never spawned). */
+const SAFE_PROBE_TOKENS = new Set(["agent", "--help", "-h", "--version", "-v"]);
+/** True when EVERY arg is a recognized safe help/version token (no prompt, no `-p`, no `login`). */
+export function isSafeProbeArgs(args) {
+    if (args.length === 0)
+        return false;
+    return args.every((a) => SAFE_PROBE_TOKENS.has(a));
+}
+/**
+ * Create the real SAFE probe. The returned probe spawns `<candidate> <args>` ONLY when `args` is a
+ * recognized safe help probe; otherwise it refuses (returns `resolved:false` without spawning).
+ */
+export function createSafeCursorProbe(timeoutMs = 5000) {
+    return (candidate, args) => {
+        return new Promise((resolve) => {
+            const notRun = (helpText) => ({ candidate, resolved: false, helpText, exitCode: null });
+            // Defense-in-depth: refuse anything that is not a pure help/version probe.
+            if (!isSafeProbeArgs(args)) {
+                resolve(notRun("refused: non-help probe args (safety guard)"));
+                return;
+            }
+            let helpText = "";
+            let settled = false;
+            let child;
+            try {
+                child = spawn(candidate, args, {
+                    shell: false,
+                    windowsHide: true,
+                    // Closed stdin so a probe never blocks waiting for input; capture stdout/stderr to read --help.
+                    stdio: ["ignore", "pipe", "pipe"]
+                });
+            }
+            catch {
+                resolve(notRun(""));
+                return;
+            }
+            const finish = (result) => {
+                if (settled)
+                    return;
+                settled = true;
+                resolve(result);
+            };
+            const timer = setTimeout(() => {
+                try {
+                    child.kill("SIGKILL");
+                }
+                catch {
+                    /* ignore */
+                }
+                // A hung help probe: treat as resolved (it spawned) but with whatever text we saw.
+                finish({ candidate, resolved: true, helpText, exitCode: null });
+            }, timeoutMs);
+            timer.unref?.();
+            child.stdout?.setEncoding("utf8");
+            child.stderr?.setEncoding("utf8");
+            child.stdout?.on("data", (c) => {
+                helpText += c;
+            });
+            child.stderr?.on("data", (c) => {
+                helpText += c;
+            });
+            child.on("error", () => {
+                // ENOENT / not executable → the binary is not resolvable. Fail-friendly, never throw.
+                clearTimeout(timer);
+                finish(notRun(""));
+            });
+            child.on("close", (exitCode) => {
+                clearTimeout(timer);
+                finish({ candidate, resolved: true, helpText, exitCode: exitCode ?? null });
+            });
+        });
+    };
+}
+//# sourceMappingURL=cursor-preflight-probe.js.map

package/dist/core/cursor-preflight.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Cursor LIVE-PREP preflight/diagnostics (PUBLIC CLI code — engine-free, ships in the npm package).
+ *
+ * A content-free readiness check surfaced when a LIVE `run cursor` / `capture cursor` is requested
+ * (no `--export`). It answers two questions and prints exact actionable guidance so a live Cursor run
+ * validates cleanly once the operator authenticates — WITHOUT this tool ever authenticating or spending:
+ *
+ *   1. **CLI resolvable?**  Is a Cursor headless CLI binary on PATH (`cursor` / `cursor-agent`) or at a
+ *      known macOS app path (`/Applications/Cursor.app/Contents/Resources/app/bin/cursor`)?
+ *   2. **Capability present?**  Does `<cli> agent --help` (or `--help`) advertise the headless flags we
+ *      need (`-p`/`--print` + `--output-format`)?
+ *
+ * HARD SAFETY RAILS (the defining constraints of this module):
+ * - **SAFE probes only.** Probing is limited to `--help` / `-v` / `--version` style invocations. This
+ *   module NEVER runs a real `-p` prompt, NEVER runs `cursor agent login`, and NEVER reads, sets, or
+ *   prints `CURSOR_API_KEY`.
+ * - **Auth-state is NOT detected.** Cursor's auth state cannot be observed without a real (spending)
+ *   call, so this module detects **CLI-presence + capability only** and tells the operator to run
+ *   `cursor agent login` (or set `CURSOR_API_KEY`) and retry. It never guesses "authenticated".
+ * - **Fail friendly.** A probe that errors/crashes is treated as "not detectable", never a thrown
+ *   exception — the pure logic here is total over its synthetic inputs.
+ * - **Content-free.** No prompt, no output, no credential value is ever read or emitted.
+ *
+ * Honesty binding (unchanged): Cursor = LOCAL-ESTIMATE only; provider-reported UNAVAILABLE; never a
+ * savings claim. This module surfaces none of those figures — it is a readiness check + guidance only.
+ *
+ * Design: `docs/design/cursor-live-wrapper.md` (Verify-first precondition V) + the honesty rails in
+ * `docs/ops/cursor-support-matrix.md`.
+ */
+/** Candidate CLI locations, in probe order. Kept as data so the pure logic is fully testable. */
+export declare const CURSOR_CLI_PATH_CANDIDATES: readonly ["cursor-agent", "cursor"];
+export declare const CURSOR_CLI_KNOWN_MACOS_PATH = "/Applications/Cursor.app/Contents/Resources/app/bin/cursor";
+/** The exact command an operator runs once authed (surfaced verbatim in the guidance). */
+export declare const CURSOR_EXAMPLE_RUN_COMMAND = "compaction run cursor --out <dir> -- cursor agent -p \"<your prompt>\" --output-format json";
+/**
+ * Result of a single SAFE probe of one candidate binary. `helpText` comes from a `--help`/`-v`-style
+ * invocation only. `resolved` is false when the binary could not be spawned at all (ENOENT / not
+ * executable). This is the ONLY input the pure classifier consumes — so tests can feed synthetic probe
+ * outputs with no live `cursor agent` call.
+ */
+export interface CursorProbeResult {
+    /** The candidate that was probed (a PATH name or an absolute path). */
+    candidate: string;
+    /** True when the binary spawned (even if it exited non-zero); false on ENOENT / spawn failure. */
+    resolved: boolean;
+    /** Combined help/version text observed from the SAFE probe (stdout + stderr). Content-free (help text). */
+    helpText: string;
+    /** Exit code of the SAFE probe, or null if it never ran. */
+    exitCode: number | null;
+}
+/**
+ * A probe function: given a candidate + safe args, returns what the SAFE probe observed. Injected so
+ * the classifier is pure/testable; the real adapter (`createSafeCursorProbe`) spawns `--help`/`-v` only.
+ */
+export type CursorProbe = (candidate: string, args: string[]) => Promise<CursorProbeResult>;
+export interface CursorPreflightReport {
+    /** Whether a Cursor CLI binary could be resolved (PATH or known macOS app path). */
+    cliResolvable: boolean;
+    /** The resolved binary path/name, if any. */
+    resolvedCli?: string;
+    /** Whether the resolved CLI advertises the headless capability (`-p`/`--print` + `--output-format`). */
+    capabilityPresent: boolean;
+    /**
+     * Auth is intentionally NEVER probed (would require a real, spending call). Always "not-checked" so
+     * no caller can mistake this for an "authenticated" signal.
+     */
+    authState: "not-checked";
+    /** Overall readiness of the LOCAL PREP surface: ready = CLI resolvable AND capability present. */
+    ready: boolean;
+    /** Human-readable, content-free diagnostic + guidance lines (safe to print to stdout). */
+    guidance: string[];
+}
+/**
+ * PURE classifier: given the SAFE probe results for the CLI candidates, decide resolvable/capable and
+ * build the exact guidance. No I/O, no spawning, no env reads — this is what the tests target directly.
+ *
+ * A candidate is "capable" when its help text advertises BOTH `-p`/`--print` AND `--output-format`.
+ */
+export declare function classifyCursorPreflight(probes: CursorProbeResult[]): CursorPreflightReport;
+/**
+ * Run the preflight using an injectable probe. Tries each candidate with a SAFE capability probe
+ * (`agent --help`), then classifies. Pure over `probe` — the default real adapter
+ * (`createSafeCursorProbe`) is the only place a child process is spawned, and only with `--help`-style
+ * args. The candidate order puts the known macOS app path LAST as a fallback when PATH names miss.
+ */
+export declare function runCursorPreflight(probe: CursorProbe, candidates?: readonly string[]): Promise<CursorPreflightReport>;

package/dist/core/cursor-preflight.js

@@ -0,0 +1,126 @@
+/**
+ * Cursor LIVE-PREP preflight/diagnostics (PUBLIC CLI code — engine-free, ships in the npm package).
+ *
+ * A content-free readiness check surfaced when a LIVE `run cursor` / `capture cursor` is requested
+ * (no `--export`). It answers two questions and prints exact actionable guidance so a live Cursor run
+ * validates cleanly once the operator authenticates — WITHOUT this tool ever authenticating or spending:
+ *
+ *   1. **CLI resolvable?**  Is a Cursor headless CLI binary on PATH (`cursor` / `cursor-agent`) or at a
+ *      known macOS app path (`/Applications/Cursor.app/Contents/Resources/app/bin/cursor`)?
+ *   2. **Capability present?**  Does `<cli> agent --help` (or `--help`) advertise the headless flags we
+ *      need (`-p`/`--print` + `--output-format`)?
+ *
+ * HARD SAFETY RAILS (the defining constraints of this module):
+ * - **SAFE probes only.** Probing is limited to `--help` / `-v` / `--version` style invocations. This
+ *   module NEVER runs a real `-p` prompt, NEVER runs `cursor agent login`, and NEVER reads, sets, or
+ *   prints `CURSOR_API_KEY`.
+ * - **Auth-state is NOT detected.** Cursor's auth state cannot be observed without a real (spending)
+ *   call, so this module detects **CLI-presence + capability only** and tells the operator to run
+ *   `cursor agent login` (or set `CURSOR_API_KEY`) and retry. It never guesses "authenticated".
+ * - **Fail friendly.** A probe that errors/crashes is treated as "not detectable", never a thrown
+ *   exception — the pure logic here is total over its synthetic inputs.
+ * - **Content-free.** No prompt, no output, no credential value is ever read or emitted.
+ *
+ * Honesty binding (unchanged): Cursor = LOCAL-ESTIMATE only; provider-reported UNAVAILABLE; never a
+ * savings claim. This module surfaces none of those figures — it is a readiness check + guidance only.
+ *
+ * Design: `docs/design/cursor-live-wrapper.md` (Verify-first precondition V) + the honesty rails in
+ * `docs/ops/cursor-support-matrix.md`.
+ */
+/** Candidate CLI locations, in probe order. Kept as data so the pure logic is fully testable. */
+export const CURSOR_CLI_PATH_CANDIDATES = ["cursor-agent", "cursor"];
+export const CURSOR_CLI_KNOWN_MACOS_PATH = "/Applications/Cursor.app/Contents/Resources/app/bin/cursor";
+/** The exact command an operator runs once authed (surfaced verbatim in the guidance). */
+export const CURSOR_EXAMPLE_RUN_COMMAND = 'compaction run cursor --out <dir> -- cursor agent -p "<your prompt>" --output-format json';
+/** True when help text advertises the headless print flag (`-p` or `--print`). */
+function hasPrintFlag(helpText) {
+    return /(^|\s)-p(\s|,|$)/.test(helpText) || /--print\b/.test(helpText);
+}
+/** True when help text advertises `--output-format` (the flag that makes output separable). */
+function hasOutputFormatFlag(helpText) {
+    return /--output-format\b/.test(helpText);
+}
+/**
+ * PURE classifier: given the SAFE probe results for the CLI candidates, decide resolvable/capable and
+ * build the exact guidance. No I/O, no spawning, no env reads — this is what the tests target directly.
+ *
+ * A candidate is "capable" when its help text advertises BOTH `-p`/`--print` AND `--output-format`.
+ */
+export function classifyCursorPreflight(probes) {
+    const resolvedProbes = probes.filter((p) => p.resolved);
+    const cliResolvable = resolvedProbes.length > 0;
+    // Prefer a resolved candidate that ALSO shows the capability; else the first resolved one.
+    const capableProbe = resolvedProbes.find((p) => hasPrintFlag(p.helpText) && hasOutputFormatFlag(p.helpText));
+    const resolvedCli = capableProbe?.candidate ?? resolvedProbes[0]?.candidate;
+    const capabilityPresent = capableProbe !== undefined;
+    const ready = cliResolvable && capabilityPresent;
+    const guidance = [];
+    guidance.push("Cursor live-run preflight (content-free; no prompt run, no login, no API key read):");
+    guidance.push(`  - CLI resolvable: ${cliResolvable ? `yes (${resolvedCli})` : "no"}`);
+    guidance.push(`  - Headless capability (-p/--print + --output-format): ${capabilityPresent ? "yes" : cliResolvable ? "not detected in --help" : "n/a (CLI not resolved)"}`);
+    // Auth is deliberately NOT probed — say so explicitly so nobody reads readiness as "authenticated".
+    guidance.push("  - Auth: NOT checked here (detecting it needs a real, spending call). After the steps below, run `cursor agent login` (or set CURSOR_API_KEY) and retry.");
+    if (!cliResolvable) {
+        guidance.push("");
+        guidance.push("Next steps — the Cursor headless CLI was not found:");
+        guidance.push("  1. Install / locate it: install the Cursor CLI (see cursor.com docs), or if the Cursor app is installed on macOS it ships at:");
+        guidance.push(`       ${CURSOR_CLI_KNOWN_MACOS_PATH}`);
+        guidance.push("     Ensure `cursor` or `cursor-agent` is on your PATH (the `agent` subcommand provides `-p`/`--output-format`).");
+        guidance.push("  2. Authenticate (does NOT happen automatically here): run `cursor agent login`, OR export CURSOR_API_KEY in your shell.");
+        guidance.push("  3. Then run the live flow:");
+        guidance.push(`       ${CURSOR_EXAMPLE_RUN_COMMAND}`);
+    }
+    else if (!capabilityPresent) {
+        guidance.push("");
+        guidance.push(`Next steps — a Cursor CLI was found (${resolvedCli}) but its --help did not advertise the headless flags (-p/--print + --output-format):`);
+        guidance.push("  - This may be the Cursor editor launcher rather than the headless agent CLI. Install/verify the headless `cursor agent` CLI, then retry.");
+        guidance.push("  - Authenticate first (not done here): `cursor agent login`, OR set CURSOR_API_KEY.");
+        guidance.push("  - Then run the live flow:");
+        guidance.push(`       ${CURSOR_EXAMPLE_RUN_COMMAND}`);
+    }
+    else {
+        guidance.push("");
+        guidance.push("The Cursor headless CLI is present and capable. Auth is the only remaining prerequisite (not checked here):");
+        guidance.push("  1. Authenticate: run `cursor agent login`, OR export CURSOR_API_KEY.");
+        guidance.push("  2. Then run the live flow:");
+        guidance.push(`       ${CURSOR_EXAMPLE_RUN_COMMAND}`);
+        guidance.push("  Note: Cursor tokens are LOCAL-ESTIMATE only (Cursor emits no provider usage) — provider-reported tokens are unavailable and no savings is claimed.");
+    }
+    return {
+        cliResolvable,
+        ...(resolvedCli !== undefined ? { resolvedCli } : {}),
+        capabilityPresent,
+        authState: "not-checked",
+        ready,
+        guidance
+    };
+}
+/**
+ * Run the preflight using an injectable probe. Tries each candidate with a SAFE capability probe
+ * (`agent --help`), then classifies. Pure over `probe` — the default real adapter
+ * (`createSafeCursorProbe`) is the only place a child process is spawned, and only with `--help`-style
+ * args. The candidate order puts the known macOS app path LAST as a fallback when PATH names miss.
+ */
+export async function runCursorPreflight(probe, candidates = [...CURSOR_CLI_PATH_CANDIDATES, CURSOR_CLI_KNOWN_MACOS_PATH]) {
+    const probes = [];
+    for (const candidate of candidates) {
+        // SAFE capability probes ONLY. Never a real prompt, never `login`. We try BOTH help forms because
+        // the flags live under different help surfaces across shapes: the standalone `cursor-agent` binary
+        // IS the agent (headless flags on its top-level `--help`), while the editor `cursor` launcher
+        // exposes them under the `agent` subcommand (`cursor agent --help`). A candidate that resolves in
+        // EITHER probe counts as resolved; its help text is the one that best advertises the capability.
+        const subcommandHelp = await probe(candidate, ["agent", "--help"]);
+        const topLevelHelp = await probe(candidate, ["--help"]);
+        probes.push(mergeCandidateProbes(candidate, [subcommandHelp, topLevelHelp]));
+    }
+    return classifyCursorPreflight(probes);
+}
+/** Merge the help forms tried for one candidate: resolved if EITHER spawned; keep the help text that
+ *  advertises the capability (so a candidate is judged capable if ANY safe help form shows the flags). */
+function mergeCandidateProbes(candidate, forms) {
+    const resolved = forms.some((f) => f.resolved);
+    const capableForm = forms.find((f) => f.resolved && hasPrintFlag(f.helpText) && hasOutputFormatFlag(f.helpText));
+    const chosen = capableForm ?? forms.find((f) => f.resolved) ?? forms[0];
+    return { candidate, resolved, helpText: chosen?.helpText ?? "", exitCode: chosen?.exitCode ?? null };
+}
+//# sourceMappingURL=cursor-preflight.js.map

package/dist/core/gateway/apply-activation.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Compaction Gateway APPLY activation resolver (PUBLIC CLI/SDK core — engine-free). Charter run-17.2.
+ *
+ * Apply mode is OPT-IN and EXPLICIT. It activates only through explicit user intent — the gateway's
+ * `--mode apply --policy deterministic-dedupe` OR the per-request headers `x-compaction-mode: apply` +
+ * `x-compaction-policy: deterministic-dedupe`. When the server's configured intent and the request
+ * headers CONFLICT, this resolver FAILS CLOSED (falls back to record, records the reason). Default is
+ * always record (byte-safe, no mutation).
+ */
+import { type ApplyPolicyName } from "./apply-policy.js";
+export type GatewayEffectiveMode = "record" | "apply" | "dry-run";
+export interface ApplyActivation {
+    /** The mode the server will actually execute. Forced to "record" whenever we fail closed. */
+    mode: GatewayEffectiveMode;
+    /** True when apply OR dry-run was requested (by server config or header) — even if we fail closed. */
+    requested: boolean;
+    /** The resolved policy (only `deterministic-dedupe` is known). */
+    policy?: ApplyPolicyName;
+    /** Content-free label for the receipt's approval_status / activation source. */
+    activation: "record" | "explicit-mode" | "explicit-header" | "dry-run-mode" | "dry-run-header" | "fail-closed";
+    /** Set when apply/dry-run was requested but we fell back to record (conflict / unknown policy). */
+    failClosedReason?: string;
+}
+/**
+ * Resolve the effective apply activation from the server config + request headers. PURE.
+ *
+ * Precedence + conflict rules (fail closed on any disagreement):
+ *  - Default server mode `record` carries no mutating intent → a header alone may activate apply/dry-run.
+ *  - If BOTH the server AND a header express a mutating intent and they DIFFER (mode or policy) → conflict.
+ *  - An explicit header `record` is an opt-OUT → record (never a conflict).
+ *  - Apply/dry-run requires the known policy `deterministic-dedupe`; anything else fails closed.
+ *  - An unknown mode value fails closed.
+ */
+export declare function resolveApplyActivation(params: {
+    serverMode: string;
+    serverPolicy?: string;
+    headerMode?: string;
+    headerPolicy?: string;
+}): ApplyActivation;