@compaction/cli 0.2.0 → 0.3.1

package/dist/core/policy-preferences.d.ts

@@ -0,0 +1,99 @@
+/** Default local preference file (under the gitignored `.compaction/`). */
+export declare const DEFAULT_POLICY_PREFERENCES_DIRECTORY = ".compaction";
+export declare const POLICY_PREFERENCES_FILENAME = "policy-preferences.json";
+/** The binary preference (mirror of `AUTO_APPLY_PREFERENCES` in activity-event.ts). Default = ask. */
+export declare const POLICY_PREFERENCE_VALUES: readonly ["ask-each-time", "auto-when-gates-pass"];
+export type PolicyPreferenceValue = (typeof POLICY_PREFERENCE_VALUES)[number];
+/** Tool values that are NEVER an allowed scope — a preference is never global or cross-tool. */
+export declare const REJECTED_GLOBAL_TOOL_VALUES: readonly string[];
+/**
+ * The safety gates a preference's auto-apply WOULD require (founder decision: "explicit opt-in +
+ * matching scope + original retained + capsule provenance + recoverability pass + threshold + risk
+ * checks + evidence label emitted + rollback path"). POPULATED for provenance/explanation; NOT
+ * EVALUATED this cycle — no gate engine exists, so no preference can drive an application.
+ */
+export declare const DEFAULT_GATES_REQUIRED: readonly string[];
+/** The inferred safest scope of a preference: one tool/workflow, optionally one repo, one policy type. */
+export interface PolicyPreferenceScope {
+    /** REQUIRED. The workflow/tool this preference is scoped to (never "global"/"all"/cross-tool). */
+    tool: string;
+    /** OPTIONAL. The repo the preference is scoped to, when detectable (content-free identifier). */
+    repo?: string;
+    /** REQUIRED. Which policy type this preference concerns (content-free identifier). */
+    policy_type: string;
+}
+/** One stored preference record. Content-free; no wall-clock; id is deterministic over the scope. */
+export interface PolicyPreference {
+    /** Deterministic content-free id: `pref-` + 24 hex of sha-256 over the canonical scope. */
+    id: string;
+    scope: PolicyPreferenceScope;
+    preference: PolicyPreferenceValue;
+    /** Whether this preference is live. `disable` sets this false; there is NO enable in the CLI. */
+    enabled: boolean;
+    /** Safety gates the (future) gated auto-apply slice would require. POPULATED, NOT EVALUATED here. */
+    gates_required: string[];
+}
+/** Input to save a preference — id, enabled default, and gates_required are derived when absent. */
+export interface SavePolicyPreferenceInput {
+    scope: PolicyPreferenceScope;
+    preference: PolicyPreferenceValue;
+    /** Defaults to true (the record is stored so the future live ask can honor it); disable turns it off. */
+    enabled?: boolean;
+    /** Defaults to `DEFAULT_GATES_REQUIRED`; a caller may pass a narrower list (never evaluated here). */
+    gates_required?: string[];
+}
+export interface PolicyPreferenceValidation {
+    problems: string[];
+}
+/** The longest a content-free scope/gate identifier may be — anything longer looks like content. */
+export declare const POLICY_PREFERENCE_MAX_STRING_LENGTH = 200;
+/**
+ * Validate a scope: `tool` and `policy_type` REQUIRED and content-free; `repo` optional; the tool
+ * is NEVER a global/all/cross-tool value (case-insensitive). Report-only (never throws).
+ */
+export declare function validatePolicyPreferenceScope(scope: unknown): PolicyPreferenceValidation;
+/** Deterministic content-free id over the scope only (so a scope has ONE preference record). */
+export declare function computePolicyPreferenceId(scope: PolicyPreferenceScope): string;
+export declare const POLICY_PREFERENCE_ID_PATTERN: RegExp;
+/** Read all stored preferences. A missing file means "none saved yet" (empty, not an error). */
+export declare function readPolicyPreferences(directory?: string): Promise<{
+    preferences: PolicyPreference[];
+}>;
+export type SavePolicyPreferenceResult = {
+    saved: true;
+    preference: PolicyPreference;
+    path: string;
+    replacedExisting: boolean;
+} | {
+    saved: false;
+    problems: string[];
+};
+/**
+ * Save (upsert by deterministic scope id) ONE preference to the local store. Fail-closed: an
+ * invalid scope saves NOTHING. THIS DOES NOT APPLY ANYTHING — it writes one JSON file and returns;
+ * there is no application path here (proven by the fail-closed test).
+ */
+export declare function savePolicyPreference(input: SavePolicyPreferenceInput, directory?: string): Promise<SavePolicyPreferenceResult>;
+export type DisablePolicyPreferenceResult = {
+    disabled: true;
+    preference: PolicyPreference;
+    path: string;
+    alreadyDisabled: boolean;
+} | {
+    disabled: false;
+    reason: string;
+};
+/**
+ * Disable a preference by id (set enabled=false). The safe management verb — disabling can only
+ * ever REDUCE what could apply, so it is always safe. Unknown id → a clear error, nothing changed.
+ * Idempotent: disabling an already-disabled preference is a reported no-op (no throw).
+ */
+export declare function disablePolicyPreference(id: string, directory?: string): Promise<DisablePolicyPreferenceResult>;
+/** Look up one preference by id (read-only). */
+export declare function findPolicyPreference(id: string, directory?: string): Promise<PolicyPreference | undefined>;
+/**
+ * Plain-language explanation of what a preference MEANS — honest that auto-apply is NOT YET ACTIVE
+ * (the preference is stored; application is pending the gated auto-apply slice, which does not
+ * exist yet). No wall-clock, no content — scope, policy, gates, recovery, and how to disable.
+ */
+export declare function explainPolicyPreference(preference: PolicyPreference): string;

package/dist/core/policy-preferences.js

@@ -0,0 +1,232 @@
+/**
+ * LOCAL auto-apply PREFERENCE store (charter 2026-07-04-run-7, lane 4: "compaction policies
+ * list/disable/explain" + "auto-apply preference model: binary ask-after-approve, inferred safest
+ * scope, fail-closed gates scaffold, tests proving OFF by default").
+ *
+ * WHAT THIS IS — and, more importantly, WHAT IT IS NOT:
+ * This module STORES and READS a user's binary auto-apply *preference* (the one the founder's live
+ * post-approval ask would save: "Apply this automatically next time for this workflow when safety
+ * gates pass? [yes/no, default no]"). It is a PREFERENCE record only. It is NOT an application
+ * engine:
+ *
+ *   FAIL-CLOSED INVARIANT: a preference EXISTING (even enabled=true, even
+ *   preference="auto-when-gates-pass") does NOT cause anything to be applied anywhere. There is no
+ *   apply path in this module — it imports nothing that mutates a user session, trace, run record,
+ *   or context, and it exports no apply function. `gates_required` is POPULATED but NEVER EVALUATED
+ *   this cycle (no gate engine exists). Proven by `tests/core/policy-preferences.test.ts`
+ *   (the fail-closed proof: saving/enabling a preference mutates ONLY this store's JSON file and
+ *   invokes no application).
+ *
+ * SCOPE IS NEVER GLOBAL AND NEVER CROSS-TOOL (founder decision): `tool` is REQUIRED, and a
+ * "global"/"all"/"*" tool value is REJECTED at validation. A preference is always scoped to one
+ * workflow/tool (+ repo where detectable + policy type).
+ *
+ * NO WALL-CLOCK: the record carries no `created_at` — the id is DETERMINISTIC over the scope, so
+ * the same scope always maps to the same preference record (an upsert key, content-free).
+ *
+ * LOCAL FILE I/O ONLY: one JSON file under `.compaction/` (already gitignored). No network, no new
+ * dependencies.
+ */
+import { createHash } from "node:crypto";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+/** Default local preference file (under the gitignored `.compaction/`). */
+export const DEFAULT_POLICY_PREFERENCES_DIRECTORY = ".compaction";
+export const POLICY_PREFERENCES_FILENAME = "policy-preferences.json";
+/** The binary preference (mirror of `AUTO_APPLY_PREFERENCES` in activity-event.ts). Default = ask. */
+export const POLICY_PREFERENCE_VALUES = ["ask-each-time", "auto-when-gates-pass"];
+/** Tool values that are NEVER an allowed scope — a preference is never global or cross-tool. */
+export const REJECTED_GLOBAL_TOOL_VALUES = ["global", "all", "*", "any", "cross-tool"];
+/**
+ * The safety gates a preference's auto-apply WOULD require (founder decision: "explicit opt-in +
+ * matching scope + original retained + capsule provenance + recoverability pass + threshold + risk
+ * checks + evidence label emitted + rollback path"). POPULATED for provenance/explanation; NOT
+ * EVALUATED this cycle — no gate engine exists, so no preference can drive an application.
+ */
+export const DEFAULT_GATES_REQUIRED = [
+    "scope-match",
+    "original-retained",
+    "capsule-provenance",
+    "recoverability-pass",
+    "reduction-threshold",
+    "risk-checks",
+    "evidence-label-emitted",
+    "rollback-path"
+];
+function isNonEmptyString(value) {
+    return typeof value === "string" && value.trim() !== "";
+}
+/** The longest a content-free scope/gate identifier may be — anything longer looks like content. */
+export const POLICY_PREFERENCE_MAX_STRING_LENGTH = 200;
+/**
+ * Validate a scope: `tool` and `policy_type` REQUIRED and content-free; `repo` optional; the tool
+ * is NEVER a global/all/cross-tool value (case-insensitive). Report-only (never throws).
+ */
+export function validatePolicyPreferenceScope(scope) {
+    const problems = [];
+    if (typeof scope !== "object" || scope === null || Array.isArray(scope)) {
+        return { problems: ["scope: must be an object ({ tool, repo?, policy_type })"] };
+    }
+    const record = scope;
+    if (!isNonEmptyString(record.tool)) {
+        problems.push("scope.tool: required — a preference is always scoped to one workflow/tool (never global)");
+    }
+    else if (REJECTED_GLOBAL_TOOL_VALUES.includes(record.tool.trim().toLowerCase())) {
+        problems.push(`scope.tool: "${record.tool}" is rejected — a preference is NEVER global and NEVER cross-tool (founder rule); scope it to one tool`);
+    }
+    if (!isNonEmptyString(record.policy_type)) {
+        problems.push("scope.policy_type: required — which policy this preference concerns (content-free identifier)");
+    }
+    if (record.repo !== undefined && !isNonEmptyString(record.repo)) {
+        problems.push("scope.repo: when present, must be a non-empty content-free repo identifier");
+    }
+    for (const [key, value] of Object.entries(record)) {
+        if (!["tool", "repo", "policy_type"].includes(key)) {
+            problems.push(`scope.${key}: not an allowed scope field (only tool, repo, policy_type)`);
+            continue;
+        }
+        if (typeof value === "string" && value.length > POLICY_PREFERENCE_MAX_STRING_LENGTH) {
+            problems.push(`scope.${key}: string exceeds the content-free bound (${value.length} chars) — that is content-sized`);
+        }
+    }
+    return { problems };
+}
+/** Deterministic content-free id over the scope only (so a scope has ONE preference record). */
+export function computePolicyPreferenceId(scope) {
+    const canonical = JSON.stringify({
+        policy_type: scope.policy_type,
+        repo: scope.repo ?? null,
+        tool: scope.tool
+    });
+    const digest = createHash("sha256").update(canonical).digest("hex");
+    return `pref-${digest.slice(0, 24)}`;
+}
+export const POLICY_PREFERENCE_ID_PATTERN = /^pref-[0-9a-f]{24}$/;
+function preferencesPath(directory) {
+    return join(directory, POLICY_PREFERENCES_FILENAME);
+}
+/** Read all stored preferences. A missing file means "none saved yet" (empty, not an error). */
+export async function readPolicyPreferences(directory = DEFAULT_POLICY_PREFERENCES_DIRECTORY) {
+    let raw;
+    try {
+        raw = await readFile(preferencesPath(directory), "utf8");
+    }
+    catch (error) {
+        const code = typeof error === "object" && error !== null && "code" in error ? String(error.code) : "unknown";
+        if (code === "ENOENT")
+            return { preferences: [] };
+        throw error;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new Error(`${preferencesPath(directory)} is not valid JSON — refusing to guess (fail-closed)`);
+    }
+    const list = Array.isArray(parsed)
+        ? parsed
+        : typeof parsed === "object" && parsed !== null && Array.isArray(parsed.preferences)
+            ? parsed.preferences
+            : [];
+    const preferences = list.filter((entry) => {
+        if (typeof entry !== "object" || entry === null)
+            return false;
+        const candidate = entry;
+        return (typeof candidate.id === "string" &&
+            typeof candidate.enabled === "boolean" &&
+            POLICY_PREFERENCE_VALUES.includes(candidate.preference) &&
+            validatePolicyPreferenceScope(candidate.scope).problems.length === 0);
+    });
+    return { preferences };
+}
+/**
+ * Save (upsert by deterministic scope id) ONE preference to the local store. Fail-closed: an
+ * invalid scope saves NOTHING. THIS DOES NOT APPLY ANYTHING — it writes one JSON file and returns;
+ * there is no application path here (proven by the fail-closed test).
+ */
+export async function savePolicyPreference(input, directory = DEFAULT_POLICY_PREFERENCES_DIRECTORY) {
+    const problems = validatePolicyPreferenceScope(input.scope).problems;
+    if (!POLICY_PREFERENCE_VALUES.includes(input.preference)) {
+        problems.push(`preference: must be one of ${POLICY_PREFERENCE_VALUES.join(" | ")} (exact)`);
+    }
+    if (problems.length > 0)
+        return { saved: false, problems };
+    const scope = {
+        tool: input.scope.tool,
+        policy_type: input.scope.policy_type,
+        ...(input.scope.repo !== undefined ? { repo: input.scope.repo } : {})
+    };
+    const record = {
+        id: computePolicyPreferenceId(scope),
+        scope,
+        preference: input.preference,
+        enabled: input.enabled ?? true,
+        gates_required: input.gates_required ? [...input.gates_required] : [...DEFAULT_GATES_REQUIRED]
+    };
+    const { preferences } = await readPolicyPreferences(directory);
+    const existingIndex = preferences.findIndex((entry) => entry.id === record.id);
+    const replacedExisting = existingIndex >= 0;
+    const next = replacedExisting
+        ? preferences.map((entry, index) => (index === existingIndex ? record : entry))
+        : [...preferences, record];
+    const path = preferencesPath(directory);
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, `${JSON.stringify({ preferences: next }, null, 2)}\n`, "utf8");
+    return { saved: true, preference: record, path, replacedExisting };
+}
+/**
+ * Disable a preference by id (set enabled=false). The safe management verb — disabling can only
+ * ever REDUCE what could apply, so it is always safe. Unknown id → a clear error, nothing changed.
+ * Idempotent: disabling an already-disabled preference is a reported no-op (no throw).
+ */
+export async function disablePolicyPreference(id, directory = DEFAULT_POLICY_PREFERENCES_DIRECTORY) {
+    const { preferences } = await readPolicyPreferences(directory);
+    const index = preferences.findIndex((entry) => entry.id === id);
+    if (index < 0) {
+        return { disabled: false, reason: `no preference with id "${id}" — nothing changed (run "compaction policies list")` };
+    }
+    const target = preferences[index];
+    if (target.enabled === false) {
+        return { disabled: true, preference: target, path: preferencesPath(directory), alreadyDisabled: true };
+    }
+    const updated = { ...target, enabled: false };
+    const next = preferences.map((entry, i) => (i === index ? updated : entry));
+    const path = preferencesPath(directory);
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, `${JSON.stringify({ preferences: next }, null, 2)}\n`, "utf8");
+    return { disabled: true, preference: updated, path, alreadyDisabled: false };
+}
+/** Look up one preference by id (read-only). */
+export async function findPolicyPreference(id, directory = DEFAULT_POLICY_PREFERENCES_DIRECTORY) {
+    const { preferences } = await readPolicyPreferences(directory);
+    return preferences.find((entry) => entry.id === id);
+}
+/**
+ * Plain-language explanation of what a preference MEANS — honest that auto-apply is NOT YET ACTIVE
+ * (the preference is stored; application is pending the gated auto-apply slice, which does not
+ * exist yet). No wall-clock, no content — scope, policy, gates, recovery, and how to disable.
+ */
+export function explainPolicyPreference(preference) {
+    const scopeLine = preference.scope.repo
+        ? `the "${preference.scope.tool}" workflow in repo "${preference.scope.repo}"`
+        : `the "${preference.scope.tool}" workflow`;
+    const lines = [
+        `Preference ${preference.id}`,
+        ``,
+        `Scope:      ${scopeLine}`,
+        `Policy:     ${preference.scope.policy_type}`,
+        `Preference: ${preference.preference}`,
+        `Enabled:    ${preference.enabled ? "yes" : "no (disabled)"}`,
+        ``
+    ];
+    if (preference.preference === "auto-when-gates-pass") {
+        lines.push(`What it would mean: for ${scopeLine}, you chose "apply automatically next time WHEN ALL`, `safety gates pass". Auto-apply would happen ONLY if every one of these gates passes:`, ...preference.gates_required.map((gate) => `  - ${gate}`), ``, `NOT YET ACTIVE: no auto-apply engine exists yet. This preference is STORED only; nothing is`, `applied automatically today. When the gated auto-apply slice ships, an application will run`, `ONLY inside these gates, the original will be retained, and every application will be`, `recoverable and logged with an evidence label.`);
+    }
+    else {
+        lines.push(`What it means: for ${scopeLine}, Compaction ASKS every time before applying anything`, `(the default). Nothing is ever applied automatically under this preference.`);
+    }
+    lines.push(``, `Originals are always retained; every application (once the gated slice exists) is reversible.`, `To turn this preference off:  compaction policies disable ${preference.id}`);
+    return lines.join("\n");
+}
+//# sourceMappingURL=policy-preferences.js.map

package/dist/core/run-aggregator.d.ts

@@ -1,3 +1,4 @@
+import { type PerToolRunRecordRollup } from "./local-run-record.js";
 import type { CompactionReport, WasteFinding } from "./types.js";
 /**
  * Duplicate-safety summary for the `summary` rollup, by content fingerprint. A count of DISTINCT
@@ -83,6 +84,15 @@ export interface RunSummary extends RunSummaryBucket {
      * are never inflated. Runs without a fingerprint are each counted as distinct.
      */
     distinctness: RunDistinctnessSummary;
+    /**
+     * ADDITIVE (unified-run-flow LOCAL layer, 2026-07-02): per-tool rollup of the locally accumulated
+     * per-run token_source records (`.compaction/run-records/*.json`). Observed token COUNTS + their
+     * honest per-axis `token_source` tiers ONLY (mirrors docs/ops/app-source-status-contract.md) —
+     * no cost figures, and `output_savings` is the LITERAL "unavailable" for every tool (gated).
+     */
+    per_tool_token_records: PerToolRunRecordRollup[];
+    run_records_source_glob: string;
+    run_record_skipped_files: SkippedReportFile[];
     generated_at: string;
     source_glob: string;
 }
@@ -108,7 +118,7 @@ export declare function readCompactionRunReports(runsDirectory?: string): Promis
     skippedFiles: SkippedReportFile[];
 }>;
 export declare function aggregateCompactionReports(reports: LoadedReport[], skippedFiles?: SkippedReportFile[], generatedAt?: string, sourceGlob?: string): RunSummary;
-export declare function createRunSummary(runsDirectory?: string): Promise<RunSummary>;
+export declare function createRunSummary(runsDirectory?: string, recordsDirectory?: string): Promise<RunSummary>;
 export declare function formatRunSummary(summary: RunSummary): string;
 export declare function formatRunSummaryMarkdown(summary: RunSummary): string;
 export {};

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 = [
@@ -211,6 +212,9 @@ export function aggregateCompactionReports(reports, skippedFiles = [], generated
         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
     };
@@ -256,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)}`;
@@ -317,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");
@@ -370,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>;