@compaction/cli 0.1.4 → 0.3.0

package/dist/core/run-aggregator.js

@@ -1,5 +1,6 @@
 import { readdir, readFile } from "node:fs/promises";
 import { join } from "node:path";
+import { DEFAULT_RUN_RECORDS_DIRECTORY, formatPerToolRunRecordLines, PER_TOOL_RECORDS_HEADER, readLocalRunTokenRecords, summarizePerToolRunRecords } from "./local-run-record.js";
 import { classifyDistinctness } from "./trace-fingerprint.js";
 const REQUIRED_STRING_FIELDS = ["run_id", "trace_title", "policy_name"];
 const REQUIRED_NUMBER_FIELDS = [
@@ -26,6 +27,58 @@ function roundTo(value, digits) {
     const factor = 10 ** digits;
     return Math.round((value + Number.EPSILON) * factor) / factor;
 }
+/** Minimum DISTINCT runs for a measured (not single-anecdote) estimate delta. */
+export const MIN_RUNS_FOR_MEASURED_DELTA = 3;
+/**
+ * Compute the measured-across-distinct-runs estimate delta over a set of per-run percent
+ * reductions (PURE). Applies the accepted criterion: N ≥ 3 AND the mean ±2·SE interval excludes
+ * zero. Estimate-class only — the result is NEVER billing-confirmed or eval-backed. Uses the
+ * sample standard deviation (n−1); with n<2 there is no dispersion (SE 0) so it cannot qualify.
+ */
+export function computeMeasuredEstimateDelta(percentReductions) {
+    const n = percentReductions.length;
+    const mean = n === 0 ? 0 : percentReductions.reduce((sum, x) => sum + x, 0) / n;
+    let se = 0;
+    if (n >= 2) {
+        const variance = percentReductions.reduce((sum, x) => sum + (x - mean) ** 2, 0) / (n - 1);
+        se = Math.sqrt(variance) / Math.sqrt(n);
+    }
+    const ciLow = mean - 2 * se;
+    const ciHigh = mean + 2 * se;
+    const excludesZero = ciLow > 0;
+    const qualifies = n >= MIN_RUNS_FOR_MEASURED_DELTA && excludesZero;
+    const meanR = roundTo(mean, 2);
+    const lowR = roundTo(ciLow, 2);
+    const highR = roundTo(ciHigh, 2);
+    let label;
+    if (qualifies) {
+        label =
+            `Measured-caveated ESTIMATE delta across ${n} distinct runs: mean ${meanR}% reduction ` +
+                `(±2·SE [${lowR}%, ${highR}%], excludes zero). Estimate (chars/4 + price-table) — ` +
+                "NOT billing-confirmed, NOT eval-backed, NOT realized savings, NOT extrapolated.";
+    }
+    else if (n < MIN_RUNS_FOR_MEASURED_DELTA) {
+        label =
+            `Single-run/anecdote estimate (${n} distinct run(s); need ≥${MIN_RUNS_FOR_MEASURED_DELTA} ` +
+                "for a measured delta). Local estimate — NOT billing-confirmed.";
+    }
+    else {
+        label =
+            `Estimate delta across ${n} distinct runs does NOT meet the measured bar ` +
+                `(±2·SE [${lowR}%, ${highR}%] includes zero — dispersion too wide). Local estimate — NOT billing-confirmed.`;
+    }
+    return {
+        distinct_run_count: n,
+        mean_percent_reduction: meanR,
+        std_error: roundTo(se, 4),
+        ci_low: lowR,
+        ci_high: highR,
+        excludes_zero: excludesZero,
+        qualifies,
+        evidence_rung: qualifies ? "measured_caveated_estimate_delta" : "local_estimate_single_run",
+        label
+    };
+}
 /** Read the OPTIONAL content fingerprint digest from a report (older reports have none). */
 function fingerprintDigestOf(report) {
     const fp = report.trace_fingerprint;
@@ -153,11 +206,15 @@ export function aggregateCompactionReports(reports, skippedFiles = [], generated
     const summary = {
         ...emptyBucket(),
         average_percent_reduction: 0,
+        measured_estimate_delta: computeMeasuredEstimateDelta([]),
         savings_by_policy: {},
         savings_by_waste_pattern: {},
         top_savings_runs: [],
         skipped_files: skippedFiles,
         distinctness,
+        per_tool_token_records: [],
+        run_records_source_glob: `${DEFAULT_RUN_RECORDS_DIRECTORY}/*.json`,
+        run_record_skipped_files: [],
         generated_at: generatedAt,
         source_glob: sourceGlob
     };
@@ -183,6 +240,9 @@ export function aggregateCompactionReports(reports, skippedFiles = [], generated
     }
     summary.average_percent_reduction =
         distinctReports.length === 0 ? 0 : roundTo(percentReductionTotal / distinctReports.length, 2);
+    // V0.2 Increment 2: the measured-across-distinct-runs estimate delta over the DISTINCT runs'
+    // per-run reductions. Qualifies for rung 1.5 only when N≥3 AND the mean ±2·SE excludes zero.
+    summary.measured_estimate_delta = computeMeasuredEstimateDelta(summary.top_savings_runs.map((run) => run.percent_reduction));
     normalizeBucket(summary);
     for (const bucket of Object.values(summary.savings_by_policy)) {
         normalizeBucket(bucket);
@@ -200,9 +260,16 @@ export function aggregateCompactionReports(reports, skippedFiles = [], generated
         .slice(0, 5);
     return summary;
 }
-export async function createRunSummary(runsDirectory = ".compaction/runs") {
+export async function createRunSummary(runsDirectory = ".compaction/runs", recordsDirectory = DEFAULT_RUN_RECORDS_DIRECTORY) {
     const { reports, skippedFiles } = await readCompactionRunReports(runsDirectory);
-    return aggregateCompactionReports(reports, skippedFiles, new Date().toISOString(), `${runsDirectory}/*/report.json`);
+    const summary = aggregateCompactionReports(reports, skippedFiles, new Date().toISOString(), `${runsDirectory}/*/report.json`);
+    // ADDITIVE per-tool token_source rollup from the locally accumulated run records (LOCAL layer of the
+    // unified run flow). Counts + honest sources only — never content, never an output-savings figure.
+    const { records, skipped } = await readLocalRunTokenRecords(recordsDirectory);
+    summary.per_tool_token_records = summarizePerToolRunRecords(records.map((loaded) => loaded.record));
+    summary.run_records_source_glob = `${recordsDirectory}/*.json`;
+    summary.run_record_skipped_files = skipped;
+    return summary;
 }
 function formatCurrency(value) {
     return `$${value.toFixed(6)}`;
@@ -250,6 +317,7 @@ export function formatRunSummary(summary) {
         `- ${distinctnessLine(summary.distinctness)}`,
         ...formatBucketLines(summary).map((line) => `- ${line}`),
         `- average percent reduction: ${summary.average_percent_reduction.toFixed(2)}%`,
+        `- measured estimate delta [${summary.measured_estimate_delta.evidence_rung}]: ${summary.measured_estimate_delta.label}`,
         "",
         "Savings by policy",
         ...(policyLines.length === 0 ? ["- none"] : policyLines),
@@ -260,6 +328,14 @@ export function formatRunSummary(summary) {
         "Top savings runs",
         ...(topRunLines.length === 0 ? ["- none"] : topRunLines),
         "",
+        // LOCAL layer of the unified run flow: per-tool token_source rollup of the accumulated
+        // run records. Counts + sources only — no cost/savings figures in this section.
+        "Per-tool run records (token sources)",
+        `Source: ${summary.run_records_source_glob}`,
+        PER_TOOL_RECORDS_HEADER,
+        ...formatPerToolRunRecordLines(summary.per_tool_token_records),
+        ...summary.run_record_skipped_files.map((file) => `- skipped record ${file.path}: ${file.reason}`),
+        "",
         "Skipped files",
         ...(skippedLines.length === 0 ? ["- none"] : skippedLines)
     ].join("\n");
@@ -288,6 +364,13 @@ export function formatRunSummaryMarkdown(summary) {
         `- Total saving per run: ${formatCurrency(summary.total_saving_per_run)}`,
         `- Saving figures are estimated and summed over the ${summary.distinctness.distinct_runs} distinct recorded run${summary.distinctness.distinct_runs === 1 ? "" : "s"} (${summary.distinctness.duplicate_runs} duplicate(s) detected by content fingerprint and excluded).`,
         "",
+        "## Measured Estimate Delta (across distinct runs)",
+        "",
+        `- Rung: ${summary.measured_estimate_delta.evidence_rung}`,
+        `- Distinct runs: ${summary.measured_estimate_delta.distinct_run_count}`,
+        `- Mean percent reduction: ${summary.measured_estimate_delta.mean_percent_reduction.toFixed(2)}% (±2·SE [${summary.measured_estimate_delta.ci_low.toFixed(2)}%, ${summary.measured_estimate_delta.ci_high.toFixed(2)}%])`,
+        `- ${summary.measured_estimate_delta.label}`,
+        "",
         "## Savings by policy",
         "",
         "| Policy | Runs | Tokens saved | Saving per run |",
@@ -306,6 +389,14 @@ export function formatRunSummaryMarkdown(summary) {
         "| --- | --- | ---: | ---: | ---: |",
         ...(topRunRows.length === 0 ? ["| none | none | 0 | 0.00% | $0.000000 |"] : topRunRows),
         "",
+        "## Per-tool run records (token sources)",
+        "",
+        `- Source: ${summary.run_records_source_glob}`,
+        `- ${PER_TOOL_RECORDS_HEADER}`,
+        "",
+        ...formatPerToolRunRecordLines(summary.per_tool_token_records),
+        ...summary.run_record_skipped_files.map((file) => `- skipped record ${file.path}: ${file.reason}`),
+        "",
         "## Skipped files",
         "",
         "| Path | Reason |",

package/dist/core/run-flow-report.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Shared HONEST report for the unified `compaction run <tool> -- …` flow (PUBLIC CLI/SDK — engine-free).
+ * Design: `docs/design/unified-run-flow.md` (ACCEPTED 2026-06-28, founder D1/D2-amended/D3), specifically
+ * the D2 honesty matrix.
+ *
+ * This renders the per-tool token honesty for a captured run, keeping the THREE axes distinct and never
+ * conflating them (founder D2):
+ *   1. provider-reported tokens (Codex / Claude Code)
+ *   2. locally observed / estimated tokens (Cursor input; Cursor output where separable)
+ *   3. savings                          ← output savings are NEVER shown here
+ *
+ * Binding rails encoded here (see the design's honesty matrix):
+ * - `token_source` is surfaced explicitly as **provider-reported | local-estimate | unavailable**.
+ * - **Input and output tokens are shown SEPARATELY.**
+ * - Output tokens are shown **as tokens, never as a saving** (output-shaping savings are a gated
+ *   first-impl; no output-savings figure until measured + eval-confirmed).
+ * - Input before/after + reduction (the REAL compaction saving) may be shown by the caller from the
+ *   compaction report; this module labels that reduction measured-vs-estimated per the token source.
+ *
+ * This module computes NOTHING proprietary and reads NO engine internals — it only formats counts and
+ * honest source labels already produced by the per-tool capture (`UsageMetadata` + output status).
+ */
+import type { UsageMetadata } from "./usage-metadata.js";
+/** The honest per-FIELD token source, per the D2 honesty matrix. */
+export type RunFlowTokenSource = "provider-reported" | "local-estimate" | "unavailable";
+/** Whether the wrapper could safely separate/count output tokens for this run. */
+export type RunFlowOutputStatus = "present" | "unavailable";
+export interface RunFlowTokenReport {
+    tool: string;
+    /** Source for the INPUT token count (never stronger than the evidence). */
+    input_token_source: RunFlowTokenSource;
+    /** Source for the OUTPUT token count; `unavailable` when the field could not be safely counted. */
+    output_token_source: RunFlowTokenSource;
+    input_tokens?: number;
+    output_tokens?: number;
+    /**
+     * Label for how the (real, input) compaction reduction shown by the caller should be read:
+     * `measured` when the capture is provider-reported, `estimated` when it is a local estimate.
+     */
+    input_reduction_label: "measured" | "estimated";
+    /** Honest notes carried from the capture (e.g. "not billing-confirmed", "no separable result field"). */
+    notes: string[];
+}
+/**
+ * Build the honest per-run token report from a capture's `UsageMetadata` and the wrapper's output status.
+ * `outputStatus === "unavailable"` forces `output_token_source: "unavailable"` regardless of the input
+ * source — a genuinely-missing output field is never silently labeled provider-reported or local-estimate.
+ */
+export declare function buildRunFlowTokenReport(params: {
+    tool: string;
+    usage: UsageMetadata;
+    outputStatus: RunFlowOutputStatus;
+}): RunFlowTokenReport;
+/** Optional TRUE per-axis unavailability reasons from the capture (printed on the token lines). */
+export interface RunFlowUnavailableReasons {
+    input?: string;
+    output?: string;
+}
+export interface RunFlowFormatOptions {
+    reasons?: RunFlowUnavailableReasons;
+    /**
+     * Set false on surfaces that do NOT print a compaction input-reduction below the block (e.g.
+     * `capture cursor`, which captures but does not compact) so the block never points the reader at
+     * reduction figures that are not there. Default true (the `run` front-ends compact + report below).
+     */
+    inputReductionFollows?: boolean;
+}
+/**
+ * Render the shared honest token block for a run-flow front-end. This block:
+ * - states `token_source` explicitly per field (provider-reported | local-estimate | unavailable);
+ * - shows input and output SEPARATELY;
+ * - shows output as TOKENS only — it contains NO output-savings figure and no savings language for output.
+ *
+ * `options.reasons` carries the capture's TRUE per-axis unavailability reasons so an unavailable axis
+ * prints WHY (e.g. "a saved Cursor export does not contain the prompt …") instead of the generic fallback.
+ * The same reasons already ride in `report.notes` (capture limitations), so the persisted run record and
+ * the summary rollup carry the identical reason — no divergence between surfaces.
+ *
+ * The caller prints the (real) INPUT before/after reduction from the compaction report separately; the
+ * `input_reduction_label` in the report tells the caller whether that reduction is measured or estimated.
+ */
+export declare function formatRunFlowTokenReport(report: RunFlowTokenReport, options?: RunFlowFormatOptions): string[];

package/dist/core/run-flow-report.js

@@ -0,0 +1,71 @@
+/**
+ * Map a capture's whole-usage source to the per-field honest token source. Output can independently be
+ * `unavailable` even when input is counted (the Cursor case), so the two fields carry sources separately.
+ */
+function fieldSource(usage) {
+    if (usage.provider_reported_tokens)
+        return "provider-reported";
+    if (usage.estimated_tokens)
+        return "local-estimate";
+    return "unavailable";
+}
+/**
+ * Build the honest per-run token report from a capture's `UsageMetadata` and the wrapper's output status.
+ * `outputStatus === "unavailable"` forces `output_token_source: "unavailable"` regardless of the input
+ * source — a genuinely-missing output field is never silently labeled provider-reported or local-estimate.
+ */
+export function buildRunFlowTokenReport(params) {
+    const source = fieldSource(params.usage);
+    const inputTokens = params.usage.input_tokens;
+    const outputTokens = params.usage.output_tokens;
+    // Input source is `unavailable` when there is no input count at all; otherwise the capture's source.
+    const inputSource = inputTokens === undefined ? "unavailable" : source;
+    // Output source is `unavailable` when the wrapper could not separate output, OR there is no output count.
+    const outputSource = params.outputStatus === "unavailable" || outputTokens === undefined ? "unavailable" : source;
+    return {
+        tool: params.tool,
+        input_token_source: inputSource,
+        output_token_source: outputSource,
+        ...(inputTokens !== undefined ? { input_tokens: inputTokens } : {}),
+        ...(outputTokens !== undefined ? { output_tokens: outputTokens } : {}),
+        input_reduction_label: params.usage.provider_reported_tokens ? "measured" : "estimated",
+        notes: [...params.usage.limitations]
+    };
+}
+function tokenLine(label, tokens, source, reason) {
+    if (source === "unavailable" || tokens === undefined) {
+        // An unavailable axis always carries a reason: the capture's TRUE per-run reason when it has one,
+        // else the generic honest fallback — never a bare "unavailable"/"unknown" with nothing after it.
+        const fallback = source === "unavailable" ? "not safely separable / not reported" : "no count";
+        return `  ${label} tokens: unavailable (${reason ?? fallback})`;
+    }
+    return `  ${label} tokens: ${tokens} (source: ${source})`;
+}
+/**
+ * Render the shared honest token block for a run-flow front-end. This block:
+ * - states `token_source` explicitly per field (provider-reported | local-estimate | unavailable);
+ * - shows input and output SEPARATELY;
+ * - shows output as TOKENS only — it contains NO output-savings figure and no savings language for output.
+ *
+ * `options.reasons` carries the capture's TRUE per-axis unavailability reasons so an unavailable axis
+ * prints WHY (e.g. "a saved Cursor export does not contain the prompt …") instead of the generic fallback.
+ * The same reasons already ride in `report.notes` (capture limitations), so the persisted run record and
+ * the summary rollup carry the identical reason — no divergence between surfaces.
+ *
+ * The caller prints the (real) INPUT before/after reduction from the compaction report separately; the
+ * `input_reduction_label` in the report tells the caller whether that reduction is measured or estimated.
+ */
+export function formatRunFlowTokenReport(report, options) {
+    return [
+        `Token reality for ${report.tool} (honest per-field source):`,
+        tokenLine("input", report.input_tokens, report.input_token_source, options?.reasons?.input),
+        tokenLine("output", report.output_tokens, report.output_token_source, options?.reasons?.output),
+        // The one binding output rail, stated plainly so no reader mistakes observed output for a saving.
+        "  output is shown as TOKENS ONLY — output-token savings are not claimed (gated on measured + eval-confirmed output-shaping).",
+        ...(options?.inputReductionFollows === false
+            ? []
+            : [`  input-reduction figures below are ${report.input_reduction_label} (from the token source above).`]),
+        ...report.notes.map((n) => `  note: ${n}`)
+    ];
+}
+//# sourceMappingURL=run-flow-report.js.map

package/dist/core/safety-report.js

@@ -83,7 +83,14 @@ export function evidenceSourceTypeFromTrace(source) {
     // "real_captured" does), so a passing report on a codex_import trace caps at
     // "conditional". This mirrors the provider_usage classification below
     // (docs/design/provider-api-tracesource-classification.md, Option 2).
-    if (source === "cli_wrapper" || source === "local_command" || source === "codex_import") {
+    //
+    // `cursor_import` is the SAME class for an imported real Cursor EXPORT
+    // (docs/design/cursor-capture-adapter.md, D2): genuine local input, stronger than a
+    // `manual` fixture, strictly BELOW `real_captured`, caps at "conditional".
+    if (source === "cli_wrapper" ||
+        source === "local_command" ||
+        source === "codex_import" ||
+        source === "cursor_import") {
         return "imported_local";
     }
     if (source === "real_captured") {

package/dist/core/shim-capture-bridge.d.ts

@@ -0,0 +1,32 @@
+import { type AppendActivityEventResult } from "./activity-store.js";
+export interface CodexShimBridgeResult {
+    result: AppendActivityEventResult;
+    /** "present" when a turn.completed.usage block was found (provider-reported), else "missing". */
+    tokenMetadataStatus: "present" | "missing";
+}
+/**
+ * Bridge a captured `codex exec --json` output copy into ONE metrics-only activity event.
+ * `surface: "codex"`, `provider: "openai"`; provider-reported tokens where usage existed, else
+ * unavailable-with-reason. Content-free + best-effort: a local failure is returned as an unappended
+ * result, never thrown, so it can never break the transparent shim.
+ */
+export declare function bridgeCodexShimActivity(input: {
+    rawOutput: string;
+    cwd?: string;
+}): Promise<CodexShimBridgeResult>;
+export interface CursorShimBridgeResult {
+    result: AppendActivityEventResult;
+    inputStatus: "present" | "unavailable";
+    outputStatus: "present" | "unavailable";
+}
+/**
+ * Bridge a captured Cursor headless output copy into ONE metrics-only activity event.
+ * `surface: "cursor"`, `provider: "cursor"`; LOCAL-ESTIMATE only (NEVER provider-reported), output
+ * unavailable-with-reason when the result is not separable. `commandParts` (the ORIGINAL invocation)
+ * lets input be locally estimated from the prompt (counted, never stored). Content-free, best-effort.
+ */
+export declare function bridgeCursorShimActivity(input: {
+    rawOutput: string;
+    commandParts?: string[];
+    cwd?: string;
+}): Promise<CursorShimBridgeResult>;

package/dist/core/shim-capture-bridge.js

@@ -0,0 +1,88 @@
+/**
+ * Shim → metrics-only activity BRIDGE (PUBLIC CLI/SDK code — engine-free, ships in the npm package).
+ *
+ * This is the exact analogue of the run-8 from-hook → activity bridge (`appendClaudeCodeHookActivity`
+ * in `src/cli/commands/capture-claude-code.ts`), reused verbatim in shape for the Codex/Cursor PATH
+ * shims (charter 2026-07-04-run-9): parse CONTENT-FREE usage → build the honest per-field token report
+ * → build the cross-surface event → wrap as a measure-only activity event → append ONE line to the
+ * local activity store. THIS is what makes a subsequent `codex exec --json` / `cursor-agent …
+ * --output-format json` run appear in `compaction activity` with NO manual import.
+ *
+ * Honesty (identical rails to the reused parsers/validators):
+ * - Codex: provider-reported tokens from `turn.completed.usage` when present, else
+ *   unavailable-with-reason — never invented, never a silent zero.
+ * - Cursor: LOCAL-ESTIMATE only (chars/4); NEVER provider-reported; output unavailable-with-reason
+ *   when the `result` field is not separable. The cross-surface tier table structurally rejects a
+ *   provider-reported label on the `cursor` surface.
+ * - CONTENT-FREE: only token COUNTS + honest source labels + opaque ids ride on the event. No
+ *   prompt/response/message text is ever read into the event (the raw output is parsed for usage
+ *   fields only, and for Cursor the prompt is counted, never stored).
+ * - Measurement only: approval "not-required", auto-apply OFF (not eligible, ask-each-time,
+ *   applied_automatically false), recovery original_retained=false, sync "local-only".
+ * - Deterministic id → the store DEDUPES a re-parse of the same run (same state = one event).
+ */
+import { createHash } from "node:crypto";
+import path from "node:path";
+import { normalizeCodexExecEvents, CODEX_UNKNOWN_MODEL } from "./codex-capture.js";
+import { normalizeCursorAgentOutput } from "./cursor-capture.js";
+import { buildRunFlowTokenReport } from "./run-flow-report.js";
+import { buildRunCrossSurfaceEvent } from "./cross-surface-event.js";
+import { buildMeasureOnlyActivityEvent } from "./activity-event.js";
+import { appendActivityEvent, DEFAULT_ACTIVITY_DIRECTORY } from "./activity-store.js";
+/** A content-free, deterministic run id from opaque ids + token counts (never any content). */
+function contentFreeRunId(prefix, parts) {
+    const digest = createHash("sha256").update(parts.map((p) => String(p ?? "")).join("|")).digest("hex");
+    return `${prefix}-${digest.slice(0, 16)}`;
+}
+/** The activity directory under a given cwd (mirrors the from-hook bridge: cwd-scoped). */
+function activityDirFor(cwd) {
+    return cwd ? path.join(cwd, ".compaction", "activity") : DEFAULT_ACTIVITY_DIRECTORY;
+}
+const CODEX_MISSING_USAGE_REASON = "the captured codex exec output carried no turn.completed.usage block (provider usage unavailable — not invented)";
+/**
+ * Bridge a captured `codex exec --json` output copy into ONE metrics-only activity event.
+ * `surface: "codex"`, `provider: "openai"`; provider-reported tokens where usage existed, else
+ * unavailable-with-reason. Content-free + best-effort: a local failure is returned as an unappended
+ * result, never thrown, so it can never break the transparent shim.
+ */
+export async function bridgeCodexShimActivity(input) {
+    const norm = normalizeCodexExecEvents({ captureId: "shim", rawOutput: input.rawOutput });
+    const usage = norm.usageMetadata;
+    const present = norm.tokenMetadataStatus === "present";
+    const tokenReport = buildRunFlowTokenReport({ tool: "codex", usage, outputStatus: present ? "present" : "unavailable" });
+    const threadId = norm.trace.id && !norm.trace.id.startsWith("trace_codex_") ? norm.trace.id : undefined;
+    const runId = contentFreeRunId("codex-shim", [threadId, usage.input_tokens, usage.output_tokens, usage.cache_read_input_tokens]);
+    const event = buildRunCrossSurfaceEvent("codex", {
+        runId,
+        tokenReport,
+        reasons: present ? {} : { input: CODEX_MISSING_USAGE_REASON, output: CODEX_MISSING_USAGE_REASON },
+        ...(usage.model && usage.model !== CODEX_UNKNOWN_MODEL ? { modelLabel: usage.model } : {})
+    });
+    const eventWithSession = threadId ? { ...event, session_id: threadId } : event;
+    const activityEvent = buildMeasureOnlyActivityEvent(eventWithSession, { original_retained: false });
+    const result = await appendActivityEvent(activityEvent, activityDirFor(input.cwd));
+    return { result, tokenMetadataStatus: norm.tokenMetadataStatus };
+}
+/**
+ * Bridge a captured Cursor headless output copy into ONE metrics-only activity event.
+ * `surface: "cursor"`, `provider: "cursor"`; LOCAL-ESTIMATE only (NEVER provider-reported), output
+ * unavailable-with-reason when the result is not separable. `commandParts` (the ORIGINAL invocation)
+ * lets input be locally estimated from the prompt (counted, never stored). Content-free, best-effort.
+ */
+export async function bridgeCursorShimActivity(input) {
+    const norm = normalizeCursorAgentOutput({ captureId: "shim", rawOutput: input.rawOutput, commandParts: input.commandParts });
+    const usage = norm.usageMetadata;
+    const tokenReport = buildRunFlowTokenReport({ tool: "cursor", usage, outputStatus: norm.outputStatus });
+    const sessionId = norm.trace.id && !norm.trace.id.startsWith("trace_cursor_") ? norm.trace.id : undefined;
+    const runId = contentFreeRunId("cursor-shim", [sessionId, usage.input_tokens, usage.output_tokens]);
+    const event = buildRunCrossSurfaceEvent("cursor", {
+        runId,
+        tokenReport,
+        reasons: { input: norm.inputUnavailableReason, output: norm.outputUnavailableReason }
+    });
+    const eventWithSession = sessionId ? { ...event, session_id: sessionId } : event;
+    const activityEvent = buildMeasureOnlyActivityEvent(eventWithSession, { original_retained: false });
+    const result = await appendActivityEvent(activityEvent, activityDirFor(input.cwd));
+    return { result, inputStatus: norm.inputStatus, outputStatus: norm.outputStatus };
+}
+//# sourceMappingURL=shim-capture-bridge.js.map

package/dist/core/skill-injection-policy.d.ts

@@ -0,0 +1,72 @@
+import { SKILL_INJECTION_POLICY_NAME, type PolicyMiddlewareStateCapsule, type SkillInjectionProvenance } from "./policy-types.js";
+import type { AgentTrace, StateCapsule, TraceMessage } from "./types.js";
+export { SKILL_INJECTION_POLICY_NAME };
+export type { SkillInjectionProvenance };
+/**
+ * APPROVAL-REQUIRED rung of the role:user skill-injection compaction policy.
+ *
+ * SCOPE (per docs/design/skill-injection-compaction-policy.md §1–§5, approval-required rung):
+ * This module builds the byte-identical, same-skill `role:user` skill-injection compaction
+ * candidates and their state capsules. It is the SECOND, separately-named compaction policy
+ * (`repeated_skill_injection_to_state_capsule`). It NEVER runs by default: `applyCompactionPolicy`
+ * only invokes it when `compactSkillInjections === true`, which is set ONLY on explicit approval
+ * in the existing approve/apply loop (optimization-approval.ts). There is NO auto-apply path.
+ *
+ * Byte-identical-only boundary (design §2): the dedup key is the report-only detector's exact
+ * `skill:normalizeExactContent(content)` key. Near-identical (same skill, divergent trailing
+ * `ARGUMENTS:`) produces a DIFFERENT key and can NEVER be compacted. No prefix/fuzzy matching.
+ *
+ * Provenance (design §5 / Q2): the capture step prefixes SUBAGENT message ids `<agentId>-<uuid>`,
+ * but ROOT-agent injections carry a bare UUID (no encoded agent id). So every compacted skill
+ * injection's capsule carries an ADDITIVE `skillInjectionProvenance` field recording the owning
+ * agent id (parsed from the id prefix, or "root" when absent) AND the replaced copy's trace
+ * position — so a consumer can reconstruct per-agent / per-position receipt even for the bare-UUID
+ * root copies. This is additive metadata on the capsule; it does NOT change the AgentTrace /
+ * TraceSource / TraceMessage schema.
+ */
+/**
+ * A skill-injection compaction candidate: a later byte-identical copy to be replaced by a
+ * `whole_message` state capsule pointing at the FIRST copy of its `skill:exactContent` group.
+ */
+export interface SkillInjectionCompactionCandidate {
+    skillName: string;
+    firstCopyMessage: TraceMessage;
+    firstCopyIndex: number;
+    replacedMessage: TraceMessage;
+    replacedIndex: number;
+    replacedTokens: number;
+}
+/**
+ * Recover the owning agent id of a captured message. Subagent message ids are prefixed
+ * `<agentId>-<uuid>` by the claude-code adapter; root-agent ids are bare UUIDs (no prefix).
+ * Returns "root" with recovered=false when no agent prefix is present.
+ */
+export declare function owningAgentIdForMessage(message: TraceMessage): {
+    owningAgentId: string;
+    recoveredFromPrefix: boolean;
+};
+/**
+ * Find byte-identical, same-skill later skill-injection copies (design §1/§2). First occurrence
+ * of each `skill:exactContent` group is retained; each later exact-key copy is a candidate.
+ * Pure: returns candidates; never mutates the trace.
+ */
+export declare function findSkillInjectionCompactionCandidates(trace: AgentTrace): SkillInjectionCompactionCandidate[];
+/**
+ * Build `whole_message` state capsules for skill-injection candidates, mirroring the tool-output
+ * policy's capsule shape (`PolicyMiddlewareStateCapsule`) and reusing the same SourcePointer /
+ * provenance machinery. Each capsule additionally carries the §5 `skillInjectionProvenance`.
+ */
+export declare function createSkillInjectionCapsules(trace: AgentTrace, candidates: SkillInjectionCompactionCandidate[], baseCapsule: Pick<StateCapsule, "retainedFacts" | "openQuestions" | "safetyNotes">, idOffset?: number): PolicyMiddlewareStateCapsule[];
+/**
+ * Rollback / recovery (design §Q5): re-expand a skill-injection capsule's first-copy pointer to
+ * restore the original later-copy content. Because the bytes are byte-identical by construction,
+ * the restored content equals the retained first copy. Returns the restored content, or null when
+ * the pointer no longer resolves (which a safety check would already have failed).
+ */
+export declare function restoreCompactedSkillInjectionContent(originalTrace: AgentTrace, capsule: PolicyMiddlewareStateCapsule): string | null;
+/**
+ * Round-trip rollback (design §Q5): given the compacted messages and the skill-injection capsules,
+ * restore the ORIGINAL trace messages by re-expanding each capsule pointer back to the first-copy
+ * bytes. Asserts byte-for-byte recovery of the later copies. Pure; returns a restored message list.
+ */
+export declare function rollbackSkillInjectionCompaction(originalTrace: AgentTrace, compactedMessages: TraceMessage[], capsules: PolicyMiddlewareStateCapsule[]): TraceMessage[];