@compaction/cli 0.1.2 → 0.2.0

package/dist/cli/commands/run.js

@@ -1,6 +1,7 @@
 import chalk from "chalk";
 import { parseRunCommand, executeLocalCommand, persistLocalCommandRun } from "../../core/command-runner.js";
-import { writeJsonArtifact } from "../../core/artifact-writer.js";
+import { writeJsonArtifact, writeTextArtifact } from "../../core/artifact-writer.js";
+import { formatCompactionMarkdownReport, withSavingsEvidence, withTraceFingerprint } from "../../core/report-generator.js";
 import { localCommandRunToAgentTrace } from "../../core/run-trace-converter.js";
 import { runEngineCommand } from "../engine-degrade.js";
 export function registerRunCommand(program) {
@@ -23,6 +24,17 @@ export function registerRunCommand(program) {
             const trace = localCommandRunToAgentTrace(run);
             const tracePath = await writeJsonArtifact(persistedRun.outputDirectory, "trace.json", trace);
             const artifacts = await writeCompactionArtifacts(trace, persistedRun.outputDirectory, run.runId);
+            // Attribution/integrity + per-run evidence label (V0.2 savings-evidence): re-persist
+            // report.json with the trace fingerprint (attribution/dedup) and the composed
+            // `savings_evidence` record (per-run label). `run` figures are local estimates (chars/4) —
+            // `local_estimate` rung 1. Additive; no existing report field/label changes.
+            const evidenceReport = withSavingsEvidence(withTraceFingerprint(artifacts.report, trace), {
+                costSource: "local_estimate"
+            });
+            await writeJsonArtifact(persistedRun.outputDirectory, "report.json", evidenceReport);
+            // Re-render report.md from the ENRICHED report so the per-run savings_evidence record
+            // appears in the human-readable artifact too (engine rendered it from the base report).
+            await writeTextArtifact(persistedRun.outputDirectory, "report.md", formatCompactionMarkdownReport(evidenceReport, artifacts.policy));
             console.log(`Exit code: ${run.exitCode ?? "none"}`);
             console.log(`Signal: ${run.signal ?? "none"}`);
             console.log(`Duration: ${run.durationMs} ms`);

package/dist/cli/index.js

@@ -11,6 +11,7 @@ import { registerBillingDeltaCommand } from "./commands/billing-delta.js";
 import { registerInitCommand } from "./commands/init.js";
 import { registerCaptureCommand } from "./commands/capture.js";
 import { registerCompactCommand } from "./commands/compact.js";
+import { registerContextCommand } from "./commands/context.js";
 import { registerEvalCommand } from "./commands/eval.js";
 import { registerExportSessionSeedCommand } from "./commands/export-session-seed.js";
 import { registerFeedbackCommand } from "./commands/feedback.js";
@@ -27,7 +28,7 @@ const program = new Command();
 program
     .name("compaction")
     .description("CLI-first trace compaction tools for AI agent workflows.")
-    .version("0.1.2");
+    .version("0.2.0");
 registerAnalyzeCommand(program);
 registerAdapterCommand(program);
 registerAggregateCommand(program);
@@ -39,6 +40,7 @@ registerBillingDeltaCommand(program);
 registerInitCommand(program);
 registerCaptureCommand(program);
 registerCompactCommand(program);
+registerContextCommand(program);
 registerEvalCommand(program);
 registerExportSessionSeedCommand(program);
 registerFeedbackCommand(program);
@@ -62,6 +64,7 @@ const PUBLIC_COMMANDS = new Set([
     "capture",
     "import",
     "analyze",
+    "context",
     "spend",
     "summary",
     "aggregate",

package/dist/cli/onboarding/InitTui.d.ts

@@ -0,0 +1,52 @@
+import React from "react";
+import { type WorkflowCard } from "./model.js";
+/**
+ * Interactive first-run TUI for `compaction init` (Ink/React) — a minimal,
+ * premium, left-aligned, dark-terminal-first workflow chooser.
+ *
+ * Progressive enhancement gated behind a real TTY (see `decideInteractiveTui`):
+ * it NEVER runs in pipes/CI/NO_COLOR/dumb terminals or the test runner — those
+ * get the static screen — so it may freely rely on color and Unicode.
+ *
+ * The big COMPACTION wordmark is the visual hero; everything below is quiet and
+ * compact. Palette is restrained Compaction-blue only (no teal/cyan). The full
+ * UI is short and rendered into the alternate screen buffer (see `runInitTui`)
+ * so resizing repaints in place and never duplicates the wordmark.
+ *
+ * Invariants (identical to the static path): writes nothing, no network call,
+ * no credential read, features ONLY the free local-first workflows. It is a
+ * chooser, not an agent: no text input, no model call, nothing uploaded.
+ */
+export interface InitTuiDetection {
+    detected: boolean;
+    sessionCount: number;
+    projectsDir: string;
+}
+export type InitTuiResult = {
+    action: "select";
+    card: WorkflowCard;
+} | {
+    action: "quit";
+};
+interface AppProps {
+    version: string;
+    detection: InitTuiDetection;
+    onDone: (result: InitTuiResult) => void;
+}
+export declare function App({ version, detection, onDone }: AppProps): React.ReactElement;
+/**
+ * Render the TUI and resolve with the user's choice. Resolves to `{action:"quit"}`
+ * if the user exits without selecting. The caller prints the chosen command to
+ * the scrollback after this resolves.
+ *
+ * Renders into the terminal's ALTERNATE SCREEN BUFFER (like vim/less/fzf): no
+ * scrollback, so a reflow can never push a stale frame up into history. Resize
+ * redraw is handled INSIDE the component (reactive terminal size → re-render),
+ * so Ink owns the clear/repaint and the screen stays visible across resizes. On
+ * exit the screen is restored and the selected next-command prints normally.
+ */
+export declare function runInitTui(props: {
+    version: string;
+    detection: InitTuiDetection;
+}): Promise<InitTuiResult>;
+export {};

package/dist/cli/onboarding/InitTui.js

@@ -0,0 +1,153 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useMemo, useState } from "react";
+import { Box, Text, useApp, useInput, useStdout, render } from "ink";
+import { VALUE_PROMISE, STATUS_PILLS, WORKFLOW_CARDS, FREE_FLOW, PRIMARY } from "./model.js";
+import { renderWordmark, fillGradient } from "./wordmark.js";
+// Restrained Compaction-blue palette only.
+const BLUE = "#3231cd"; // brand accent / wordmark fill (bottom of gradient)
+const OUTLINE = "#232185"; // one darker brand-blue tone for the framed-outline strokes
+const DIM = "gray";
+const FRAME_MAX = 96;
+function Wordmark({ version, maxWidth }) {
+    const mark = useMemo(() => renderWordmark(maxWidth), [maxWidth]);
+    // Blue-only vertical gradient for the solid fill; the framed-outline strokes
+    // are one darker brand-blue tone (inline 3D depth, no contrasting colour).
+    const grad = useMemo(() => fillGradient(mark.height), [mark.height]);
+    return (_jsxs(Box, { flexDirection: "column", children: [mark.rows.map((row, r) => (_jsx(Text, { children: row.map((seg, i) => {
+                    if (seg.layer === "fill") {
+                        return (_jsx(Text, { color: grad[r], bold: true, children: seg.text }, i));
+                    }
+                    if (seg.layer === "outline") {
+                        return (_jsx(Text, { color: OUTLINE, children: seg.text }, i));
+                    }
+                    return _jsx(Text, { children: seg.text }, i);
+                }) }, r))), _jsxs(Box, { marginTop: 1, children: [_jsxs(Text, { color: BLUE, bold: true, children: ["v", version] }), _jsx(Text, { color: DIM, children: "   the Compaction CLI" })] })] }));
+}
+function StatusRow() {
+    return (_jsx(Box, { marginTop: 1, children: STATUS_PILLS.map((pill, i) => (_jsxs(Box, { children: [_jsx(Text, { color: BLUE, children: "\u25CF" }), _jsx(Text, { color: DIM, children: ` ${pill}` }), i < STATUS_PILLS.length - 1 ? _jsx(Text, { color: DIM, children: "   " }) : null] }, pill))) }));
+}
+function badge(card, det, dim) {
+    if (card.key !== PRIMARY.key)
+        return null;
+    if (det.detected) {
+        return _jsx(Text, { color: dim ? DIM : BLUE, children: `  ✓ ${det.sessionCount} session(s) found` });
+    }
+    return _jsx(Text, { color: DIM, children: "  · no sessions found yet" });
+}
+// The single highlighted card for the focused workflow. It hugs its content
+// (alignSelf flex-start) so it reads as a card, not a full-width bar.
+function ActiveCard({ card, det }) {
+    const recommended = card.key === PRIMARY.key;
+    return (_jsxs(Box, { flexDirection: "column", marginTop: 1, children: [_jsx(Text, { color: BLUE, bold: true, children: recommended ? "▌ RECOMMENDED" : "▌ WORKFLOW" }), _jsxs(Box, { alignSelf: "flex-start", borderStyle: "round", borderColor: BLUE, paddingX: 1, flexDirection: "column", children: [_jsxs(Box, { children: [_jsx(Text, { color: "white", bold: true, children: card.title }), recommended ? _jsx(Text, { color: BLUE, children: "  ★" }) : null, badge(card, det, false)] }), _jsx(Text, { color: BLUE, children: card.command })] })] }));
+}
+// Quiet, compact, borderless row for an unfocused workflow.
+function QuietRow({ card, det }) {
+    const recommended = card.key === PRIMARY.key;
+    return (_jsxs(Box, { children: [_jsx(Text, { color: DIM, children: "  ○ " }), _jsx(Text, { color: DIM, children: card.title }), recommended ? _jsx(Text, { color: DIM, children: "  ★ recommended" }) : null, badge(card, det, true)] }));
+}
+// Below this width the full chooser cannot lay out cleanly; show a compact
+// recovery message instead. It re-renders into the full UI when widened again.
+const NARROW_MIN = 44;
+// Reactive terminal size: re-render the tree on `resize` (debounced) so the
+// layout recomputes against the new width and Ink redraws cleanly. Reading the
+// size into React state (rather than poking the terminal with escape codes) is
+// what keeps the TUI visible across resizes. Guards columns/rows === 0/undefined.
+function useTerminalSize() {
+    const { stdout } = useStdout();
+    const read = () => {
+        const c = stdout && typeof stdout.columns === "number" && stdout.columns > 0 ? stdout.columns : FRAME_MAX;
+        const r = stdout && typeof stdout.rows === "number" && stdout.rows > 0 ? stdout.rows : 24;
+        return { cols: c, rows: r };
+    };
+    const [size, setSize] = useState(read);
+    useEffect(() => {
+        if (!stdout || typeof stdout.on !== "function")
+            return;
+        let t = null;
+        const onResize = () => {
+            if (t)
+                clearTimeout(t);
+            t = setTimeout(() => setSize(read()), 24); // debounce bursts of resize events
+        };
+        stdout.on("resize", onResize);
+        return () => {
+            if (t)
+                clearTimeout(t);
+            if (typeof stdout.off === "function")
+                stdout.off("resize", onResize);
+        };
+        // read() closes over `stdout`; re-subscribe only if the stream changes.
+    }, [stdout]);
+    return size;
+}
+export function App({ version, detection, onDone }) {
+    const [index, setIndex] = useState(0);
+    const [showHelp, setShowHelp] = useState(false);
+    const [showCommands, setShowCommands] = useState(false);
+    const { exit } = useApp();
+    const { cols } = useTerminalSize();
+    const maxWidth = Math.min(cols, FRAME_MAX) - 2;
+    useInput((input, key) => {
+        if (key.upArrow || input === "k") {
+            setIndex((i) => (i - 1 + WORKFLOW_CARDS.length) % WORKFLOW_CARDS.length);
+        }
+        else if (key.downArrow || input === "j") {
+            setIndex((i) => (i + 1) % WORKFLOW_CARDS.length);
+        }
+        else if (key.return) {
+            onDone({ action: "select", card: WORKFLOW_CARDS[index] });
+            exit();
+        }
+        else if (input === "q" || key.escape) {
+            onDone({ action: "quit" });
+            exit();
+        }
+        else if (input === "?") {
+            setShowHelp((h) => !h);
+        }
+        else if (input === "/") {
+            setShowCommands((c) => !c);
+        }
+    });
+    // Too-narrow recovery: a clean compact message that re-expands into the full
+    // chooser when the terminal is widened again. q / Esc still quits (useInput
+    // above runs on every path).
+    if (cols < NARROW_MIN) {
+        return (_jsxs(Box, { flexDirection: "column", paddingLeft: 1, paddingTop: 1, children: [_jsx(Text, { color: BLUE, bold: true, children: "COMPACTION" }), _jsx(Text, { color: DIM, children: "Terminal too narrow \u2014 widen the window to use the chooser," }), _jsx(Text, { color: DIM, children: "or run `compaction init --static`.   (q / Esc to quit)" })] }));
+    }
+    const freeFlow = FREE_FLOW.map((f) => f.command.replace("compaction ", "")).join("  ·  ");
+    // Left-aligned, compact, no centering — the wordmark anchors the top-left.
+    return (_jsxs(Box, { flexDirection: "column", paddingLeft: 1, paddingTop: 1, children: [_jsx(Wordmark, { version: version, maxWidth: maxWidth }), _jsx(StatusRow, {}), _jsx(Box, { marginTop: 1, children: _jsx(Text, { color: "white", children: VALUE_PROMISE }) }), _jsx(Box, { flexDirection: "column", children: WORKFLOW_CARDS.map((card, i) => i === index ? (_jsx(ActiveCard, { card: card, det: detection }, card.key)) : (_jsx(QuietRow, { card: card, det: detection }, card.key))) }), _jsxs(Box, { marginTop: 1, children: [_jsx(Text, { color: DIM, children: "Free local flow   " }), _jsx(Text, { color: DIM, children: freeFlow })] }), _jsxs(Box, { marginTop: 1, children: [_jsx(Text, { color: BLUE, bold: true, children: "Choose a workflow, press Enter" }), _jsx(Text, { color: DIM, children: "    / commands    ? help    " }), _jsx(Text, { color: BLUE, children: "\u25CD local mode" })] }), _jsx(Text, { color: DIM, children: "↑/↓ · j/k move   ·   Enter select   ·   q / Esc quit" }), showCommands ? (_jsxs(Box, { marginTop: 1, flexDirection: "column", children: [_jsx(Text, { color: DIM, children: "Free local flow, once you have a trace:" }), FREE_FLOW.map((f) => (_jsxs(Text, { children: [_jsx(Text, { color: BLUE, children: `  ${f.command}` }), _jsx(Text, { color: DIM, children: `  — ${f.desc}` })] }, f.command)))] })) : null, showHelp ? (_jsxs(Box, { marginTop: 1, flexDirection: "column", children: [_jsx(Text, { color: DIM, children: `Enter prints the exact next command for ${WORKFLOW_CARDS[index].title} — copy & run` }), _jsx(Text, { color: DIM, children: "it. The CLI never runs it for you. Local-first: no network, no credentials, no upload." }), _jsx(Text, { color: DIM, children: "Nothing is called a saving until it is measured." })] })) : null] }));
+}
+const ALT_SCREEN_ENTER = "[?1049h";
+const ALT_SCREEN_LEAVE = "[?1049l";
+/**
+ * Render the TUI and resolve with the user's choice. Resolves to `{action:"quit"}`
+ * if the user exits without selecting. The caller prints the chosen command to
+ * the scrollback after this resolves.
+ *
+ * Renders into the terminal's ALTERNATE SCREEN BUFFER (like vim/less/fzf): no
+ * scrollback, so a reflow can never push a stale frame up into history. Resize
+ * redraw is handled INSIDE the component (reactive terminal size → re-render),
+ * so Ink owns the clear/repaint and the screen stays visible across resizes. On
+ * exit the screen is restored and the selected next-command prints normally.
+ */
+export async function runInitTui(props) {
+    const out = process.stdout;
+    const useAlt = Boolean(out.isTTY);
+    if (useAlt)
+        out.write(ALT_SCREEN_ENTER);
+    let result = { action: "quit" };
+    try {
+        const app = render(_jsx(App, { version: props.version, detection: props.detection, onDone: (r) => {
+                result = r;
+            } }));
+        await app.waitUntilExit();
+    }
+    finally {
+        if (useAlt)
+            out.write(ALT_SCREEN_LEAVE);
+    }
+    return result;
+}
+//# sourceMappingURL=InitTui.js.map

package/dist/cli/onboarding/model.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Shared onboarding model — the single source of truth for both the static
+ * `compaction init` fallback screen and the interactive Ink TUI.
+ *
+ * This module holds DATA ONLY (no chalk, no React) so it is trivially testable
+ * and importable from both the plain renderer and the .tsx component. The two
+ * surfaces must always feature the same workflows, the same free follow-ups,
+ * and the same honest claim labels — keeping them here guarantees that.
+ *
+ * Free-CLI scope: onboarding features ONLY the free, local-first commands
+ * (capture / import / analyze / spend / summary / feedback). The optimization
+ * & verification engine commands (recommend / compact / inspect / approve /
+ * apply-context) are the opt-in Compaction API — NOT in the free CLI — and so
+ * are deliberately ABSENT from this model on every surface.
+ */
+export declare const BRAND_HEX = "#3231cd";
+export declare const VALUE_PROMISE = "Find and reduce avoidable context spend in real agent workflows, locally.";
+export declare const STATUS_PILLS: readonly ["local-first", "no telemetry", "no upload by default"];
+export interface WorkflowCard {
+    key: string;
+    title: string;
+    /** The exact, copy-pasteable next command for this workflow. */
+    command: string;
+    /** One-line description of what running this workflow gets you. */
+    blurb: string;
+}
+export declare const PRIMARY: WorkflowCard;
+export declare const SECONDARY: WorkflowCard[];
+/** All workflow cards, primary first — the order shown in the TUI chooser. */
+export declare const WORKFLOW_CARDS: WorkflowCard[];
+/** Lookup a card by key (used by `--path` focus and TUI selection). */
+export declare function findWorkflow(key: string): WorkflowCard | undefined;
+export declare const ALL_WORKFLOW_KEYS: string[];
+export declare const FREE_FLOW: Array<{
+    command: string;
+    desc: string;
+}>;
+export declare const HONESTY_LINES: readonly ["Token counts are provider-reported when the run carries usage metadata,", "otherwise a local estimate (chars/4) — labeled as such. Cost is a", "price-table estimate; nothing is called a saving until it is measured.", "Optimization & verification are the opt-in Compaction API — not in the", "free CLI and not a hosted service yet. The free CLI measures and reports."];
+export declare const FOOTER_LINES: readonly ["Local-first: no network, no credentials, no repo access for any of the above.", "A provider credential is only ever used if YOU explicitly run", "`compaction capture provider-usage` or enter operator-run records."];

package/dist/cli/onboarding/model.js

@@ -0,0 +1,77 @@
+/**
+ * Shared onboarding model — the single source of truth for both the static
+ * `compaction init` fallback screen and the interactive Ink TUI.
+ *
+ * This module holds DATA ONLY (no chalk, no React) so it is trivially testable
+ * and importable from both the plain renderer and the .tsx component. The two
+ * surfaces must always feature the same workflows, the same free follow-ups,
+ * and the same honest claim labels — keeping them here guarantees that.
+ *
+ * Free-CLI scope: onboarding features ONLY the free, local-first commands
+ * (capture / import / analyze / spend / summary / feedback). The optimization
+ * & verification engine commands (recommend / compact / inspect / approve /
+ * apply-context) are the opt-in Compaction API — NOT in the free CLI — and so
+ * are deliberately ABSENT from this model on every surface.
+ */
+// Brand accent. Used by both surfaces; chalk/ink down-sample or no-op it on
+// terminals without truecolor, so the text is never lost.
+export const BRAND_HEX = "#3231cd";
+export const VALUE_PROMISE = "Find and reduce avoidable context spend in real agent workflows, locally.";
+// The three short status pills shown under the wordmark on both surfaces.
+export const STATUS_PILLS = ["local-first", "no telemetry", "no upload by default"];
+// Real-workflow paths only. compaction operates on the user's OWN agent
+// workflow; there is no demo / synthetic first-value path here.
+export const PRIMARY = {
+    key: "claude-code",
+    title: "Claude Code",
+    command: "compaction capture claude-code --discover",
+    blurb: "Capture a local Claude Code session (recommended first run)."
+};
+export const SECONDARY = [
+    {
+        key: "openai-agents",
+        title: "OpenAI Agents SDK",
+        command: "compaction capture openai-agents --out ./my-trace -- <your-command>",
+        blurb: "Capture an OpenAI Agents SDK run."
+    },
+    {
+        key: "codex",
+        title: "Codex / local import",
+        command: "codex exec --json '<task>' > run.jsonl  &&  compaction import run.jsonl --source codex-exec-jsonl --out ./my-trace",
+        blurb: "Import a Codex exec JSONL export."
+    },
+    {
+        key: "import",
+        title: "Local trace import",
+        command: "compaction import --list-sources   # then: import <file> --source <source> --out ./my-trace",
+        blurb: "Import any local trace / JSONL you already have."
+    }
+];
+/** All workflow cards, primary first — the order shown in the TUI chooser. */
+export const WORKFLOW_CARDS = [PRIMARY, ...SECONDARY];
+/** Lookup a card by key (used by `--path` focus and TUI selection). */
+export function findWorkflow(key) {
+    return WORKFLOW_CARDS.find((c) => c.key === key);
+}
+export const ALL_WORKFLOW_KEYS = WORKFLOW_CARDS.map((c) => c.key);
+// The follow-up sequence once a trace exists — FREE commands only.
+export const FREE_FLOW = [
+    { command: "compaction analyze", desc: "input/output tokens + estimated spend, with honest labels" },
+    { command: "compaction spend", desc: "where the context spend came from (attribution)" },
+    { command: "compaction summary", desc: "roll up your local runs" },
+    { command: "compaction feedback --redact", desc: "build a redacted, local-only share bundle (never uploaded)" }
+];
+// Honest claim labels, shown verbatim on both surfaces.
+export const HONESTY_LINES = [
+    "Token counts are provider-reported when the run carries usage metadata,",
+    "otherwise a local estimate (chars/4) — labeled as such. Cost is a",
+    "price-table estimate; nothing is called a saving until it is measured.",
+    "Optimization & verification are the opt-in Compaction API — not in the",
+    "free CLI and not a hosted service yet. The free CLI measures and reports."
+];
+export const FOOTER_LINES = [
+    "Local-first: no network, no credentials, no repo access for any of the above.",
+    "A provider credential is only ever used if YOU explicitly run",
+    "`compaction capture provider-usage` or enter operator-run records."
+];
+//# sourceMappingURL=model.js.map

package/dist/cli/onboarding/should-use-tui.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Decide whether `compaction init` should launch the interactive Ink TUI or
+ * fall back to the plain static screen.
+ *
+ * The TUI is a progressive enhancement: it renders only in a real interactive
+ * terminal. Everywhere else — pipes, CI, NO_COLOR, dumb terminals, the test
+ * runner, or when the operator opts out — we serve the byte-stable static
+ * screen so scripts, snapshots, and smoke tests never see a control sequence.
+ *
+ * Pure function over an explicit environment snapshot so it is trivially unit
+ * testable without touching the real process.
+ */
+export interface TuiEnv {
+    stdoutIsTTY: boolean;
+    stdinIsTTY: boolean;
+    env: NodeJS.ProcessEnv;
+}
+export interface TuiDecision {
+    useTui: boolean;
+    /** Machine-readable reason the TUI was declined (for tests / --help intuition). */
+    reason: "ok" | "not-a-tty" | "no-color" | "ci" | "dumb-term" | "opted-out" | "test-env";
+}
+export declare function decideInteractiveTui(e: TuiEnv): TuiDecision;
+/** Convenience wrapper over the live process. */
+export declare function decideInteractiveTuiFromProcess(): TuiDecision;

package/dist/cli/onboarding/should-use-tui.js

@@ -0,0 +1,35 @@
+export function decideInteractiveTui(e) {
+    // Raw-mode keyboard navigation requires BOTH a TTY stdin and stdout.
+    if (!e.stdoutIsTTY || !e.stdinIsTTY)
+        return { useTui: false, reason: "not-a-tty" };
+    // Honor NO_COLOR (no-color.org): present, regardless of value → plain output.
+    if (e.env.NO_COLOR != null)
+        return { useTui: false, reason: "no-color" };
+    // CI systems are non-interactive even when a pseudo-TTY is attached.
+    if (e.env.CI != null && e.env.CI !== "" && e.env.CI !== "false" && e.env.CI !== "0") {
+        return { useTui: false, reason: "ci" };
+    }
+    // Terminals that cannot render cursor movement / styling.
+    if (e.env.TERM === "dumb")
+        return { useTui: false, reason: "dumb-term" };
+    // Test runner — keep first-value output deterministic for snapshots.
+    if (e.env.VITEST != null || e.env.NODE_ENV === "test") {
+        return { useTui: false, reason: "test-env" };
+    }
+    // Explicit operator escape hatch. Accept any truthy value (1/true/yes/…),
+    // matching the lenient CI convention; "0"/"false"/"" do not opt out.
+    const optOut = e.env.COMPACTION_NO_TUI;
+    if (optOut != null && optOut !== "" && optOut !== "0" && optOut !== "false") {
+        return { useTui: false, reason: "opted-out" };
+    }
+    return { useTui: true, reason: "ok" };
+}
+/** Convenience wrapper over the live process. */
+export function decideInteractiveTuiFromProcess() {
+    return decideInteractiveTui({
+        stdoutIsTTY: Boolean(process.stdout.isTTY),
+        stdinIsTTY: Boolean(process.stdin.isTTY),
+        env: process.env
+    });
+}
+//# sourceMappingURL=should-use-tui.js.map

package/dist/cli/onboarding/wordmark.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Deterministic, dependency-free framed-outline block wordmark for the
+ * COMPACTION TUI hero.
+ *
+ * This restores the earlier "framed-outline / inline-outline" 3D treatment: the
+ * exact glyph art of figlet's "ANSI Shadow" font for the fixed word COMPACTION,
+ * BAKED IN as a constant (no figlet dependency — lean, deterministic, testable).
+ * Each glyph is a solid '█' fill framed by box-drawing outline strokes
+ * (╗ ╔ ═ ╝ ║ ╚) that give the inline 3D depth — NOT a separate offset shadow,
+ * NOT a dotted/ghost backdrop.
+ *
+ * The component paints the FILL with a restrained 2–3 shade Compaction-blue
+ * vertical gradient and the OUTLINE strokes with one darker brand-blue tone.
+ */
+export type Layer = "fill" | "outline" | "empty";
+export interface Segment {
+    text: string;
+    layer: Layer;
+}
+export interface Wordmark {
+    rows: Segment[][];
+    /** "block" (framed-outline glyphs) or "text" (spaced fallback for narrow terminals). */
+    kind: "block" | "text";
+    width: number;
+    height: number;
+}
+export declare function renderWordmark(maxWidth: number): Wordmark;
+export declare function fillGradient(rowCount: number): string[];

package/dist/cli/onboarding/wordmark.js

@@ -0,0 +1,72 @@
+/**
+ * Deterministic, dependency-free framed-outline block wordmark for the
+ * COMPACTION TUI hero.
+ *
+ * This restores the earlier "framed-outline / inline-outline" 3D treatment: the
+ * exact glyph art of figlet's "ANSI Shadow" font for the fixed word COMPACTION,
+ * BAKED IN as a constant (no figlet dependency — lean, deterministic, testable).
+ * Each glyph is a solid '█' fill framed by box-drawing outline strokes
+ * (╗ ╔ ═ ╝ ║ ╚) that give the inline 3D depth — NOT a separate offset shadow,
+ * NOT a dotted/ghost backdrop.
+ *
+ * The component paints the FILL with a restrained 2–3 shade Compaction-blue
+ * vertical gradient and the OUTLINE strokes with one darker brand-blue tone.
+ */
+// Baked "ANSI Shadow" rendering of COMPACTION (figlet). Do not hand-edit the
+// box-drawing characters; regenerate from figlet if the word ever changes.
+const LINES = [
+    " ██████╗ ██████╗ ███╗   ███╗██████╗  █████╗  ██████╗████████╗██╗ ██████╗ ███╗   ██╗",
+    "██╔════╝██╔═══██╗████╗ ████║██╔══██╗██╔══██╗██╔════╝╚══██╔══╝██║██╔═══██╗████╗  ██║",
+    "██║     ██║   ██║██╔████╔██║██████╔╝███████║██║        ██║   ██║██║   ██║██╔██╗ ██║",
+    "██║     ██║   ██║██║╚██╔╝██║██╔═══╝ ██╔══██║██║        ██║   ██║██║   ██║██║╚██╗██║",
+    "╚██████╗╚██████╔╝██║ ╚═╝ ██║██║     ██║  ██║╚██████╗   ██║   ██║╚██████╔╝██║ ╚████║",
+    " ╚═════╝ ╚═════╝ ╚═╝     ╚═╝╚═╝     ╚═╝  ╚═╝ ╚═════╝   ╚═╝   ╚═╝ ╚═════╝ ╚═╝  ╚═══╝"
+];
+const FILL = "█";
+const BLOCK_W = 83;
+const SPACED = "C O M P A C T I O N";
+// Classify each cell: solid fill, outline frame stroke, or empty.
+function buildGrid() {
+    return LINES.map((line) => {
+        const padded = line.padEnd(BLOCK_W, " ");
+        const segs = [];
+        let cur = null;
+        for (const ch of padded) {
+            const layer = ch === " " ? "empty" : ch === FILL ? "fill" : "outline";
+            if (cur && cur.layer === layer)
+                cur.text += ch;
+            else {
+                cur = { layer, text: ch };
+                segs.push(cur);
+            }
+        }
+        return segs;
+    });
+}
+const BLOCK = buildGrid();
+export function renderWordmark(maxWidth) {
+    if (maxWidth >= BLOCK_W) {
+        return { rows: BLOCK, kind: "block", width: BLOCK_W, height: BLOCK.length };
+    }
+    return {
+        rows: [[{ text: SPACED, layer: "fill" }]],
+        kind: "text",
+        width: SPACED.length,
+        height: 1
+    };
+}
+// Restrained blue-only vertical gradient for the FILL — at most three
+// blue/indigo shades, no teal/cyan. One hex per row, sampled to the row count.
+const BLUE_RAMP = ["#6d6bff", "#4f46e5", "#3231cd"];
+export function fillGradient(rowCount) {
+    if (rowCount <= 1)
+        return [BLUE_RAMP[0]];
+    const out = [];
+    for (let i = 0; i < rowCount; i++) {
+        const t = i / (rowCount - 1);
+        const idx = Math.min(BLUE_RAMP.length - 1, Math.round(t * (BLUE_RAMP.length - 1)));
+        out.push(BLUE_RAMP[idx]);
+    }
+    return out;
+}
+//# sourceMappingURL=wordmark.js.map

package/dist/core/aggregate-format.d.ts

@@ -8,7 +8,7 @@
  * copies raw trace text, prompts, completions, tool output, file paths, run ids, or report
  * paths into it. Like the feedback bundle, it is a LOCAL FILE ONLY: no network, no upload.
  */
-import type { AggregateReport, AggregateTotals, VerificationCounts } from "./session-aggregate.js";
+import type { AggregateReport, AggregateTotals, DistinctnessSummary, VerificationCounts } from "./session-aggregate.js";
 import { AGGREGATE_EVIDENCE_LABELS } from "./session-aggregate.js";
 import type { RunLabels } from "./run-labels.js";
 export declare const SHARE_BUNDLE_VERSION = "1.0.0";
@@ -41,6 +41,8 @@ export interface AggregateShareBundle {
     session_count: number;
     totals: AggregateTotals;
     verification: VerificationCounts;
+    /** Duplicate-safety summary (distinct N of M by content fingerprint) — counts only, no run ids. */
+    distinctness: DistinctnessSummary;
     /** Provider/runtime breakdown — short label keys + numbers only (no run ids). */
     by_provider: ShareBundleBreakdownEntry[];
     by_project: ShareBundleBreakdownEntry[];

package/dist/core/aggregate-format.js

@@ -32,6 +32,18 @@ function totalsLines(totals) {
         `estimated savings:     ${usd(totals.total_estimated_savings_usd)} (estimated, summed over ${totals.compactions} recorded run(s); NOT billing-confirmed, NOT realized, NOT extrapolated)`
     ];
 }
+/**
+ * One honest distinctness line: "distinct runs N of M (K duplicates detected)" plus the
+ * fingerprint coverage. This is a count of distinct captured runs by content fingerprint — NOT a
+ * billing/provider/semantic claim. The headline savings are computed over the distinct set.
+ */
+function distinctnessLine(d) {
+    const noFp = d.runs_without_fingerprint > 0
+        ? `; ${d.runs_without_fingerprint} run(s) without a fingerprint counted as distinct (cannot de-duplicate)`
+        : "";
+    return (`distinct runs ${d.distinct_runs} of ${d.total_runs} (${d.duplicate_runs} duplicate(s) detected by content fingerprint, ` +
+        `excluded from the headline so savings are not double-counted)${noFp}`);
+}
 function verificationLines(v) {
     return [
         `readiness: ready ${v.ready}, conditional ${v.conditional}, not_ready ${v.not_ready}, not_evaluated ${v.not_evaluated}`,
@@ -54,6 +66,7 @@ export function formatAggregateReport(report) {
     lines.push(`Sessions: ${report.session_count}`);
     lines.push("");
     lines.push("Cross-session totals");
+    lines.push(`- ${distinctnessLine(report.distinctness)}`);
     for (const line of totalsLines(report.totals))
         lines.push(`- ${line}`);
     lines.push("");
@@ -79,6 +92,7 @@ export function formatAggregateReport(report) {
                 labelBits.push(`labels: ${session.labels.user_labels.join("/")}`);
             if (labelBits.length)
                 lines.push(`  - ${labelBits.join("; ")}`);
+            lines.push(`  - ${distinctnessLine(session.distinctness)}`);
             for (const line of totalsLines(session.totals))
                 lines.push(`  - ${line}`);
             for (const line of verificationLines(session.verification))
@@ -141,6 +155,7 @@ export function formatAggregateMarkdown(report) {
     lines.push("");
     lines.push("## Cross-session totals");
     lines.push("");
+    lines.push(`- Distinct runs: ${distinctnessLine(report.distinctness)}`);
     lines.push(`- Runs (compactions): ${t.compactions}`);
     lines.push(`- Token-evidence split: provider-reported ${t.runs_provider_reported}, local-estimate ${t.runs_local_estimate}, unknown ${t.runs_unknown_token_evidence}`);
     lines.push(`- Total input tokens before: ${t.total_input_tokens_before}`);
@@ -219,6 +234,7 @@ export function formatAggregateMarkdown(report) {
 }
 const SHARE_INCLUDES = [
     "aggregate token totals (input before/after/saved; output where recorded)",
+    "distinct-run count (distinct N of M by content fingerprint; duplicate-run count) — counts only",
     "token-evidence split (provider-reported vs local-estimate run counts)",
     "estimated cost + estimated savings totals (price-table estimate; NOT billing-confirmed)",
     "compaction count + session count",
@@ -271,6 +287,7 @@ export function buildAggregateShareBundle(report, generatedAt = new Date().toISO
         session_count: report.session_count,
         totals: report.totals,
         verification: report.verification,
+        distinctness: report.distinctness,
         by_provider: breakdownEntries(report.by_provider),
         by_project: breakdownEntries(report.by_project),
         by_workflow: breakdownEntries(report.by_workflow),
@@ -299,6 +316,7 @@ export function formatShareBundleMarkdown(bundle) {
     lines.push("");
     lines.push("## Aggregate value (estimated, summed over recorded runs)");
     lines.push("");
+    lines.push(`- Distinct runs: ${distinctnessLine(bundle.distinctness)}`);
     lines.push(`- Compactions: ${t.compactions}`);
     lines.push(`- Token-evidence split: provider-reported ${t.runs_provider_reported}, local-estimate ${t.runs_local_estimate}, unknown ${t.runs_unknown_token_evidence}`);
     lines.push(`- Input tokens saved: ${t.total_input_tokens_saved}`);

package/dist/core/context-store-eval-cases.d.ts

@@ -0,0 +1,6 @@
+import type { ContextStoreEvalFixture } from "./context-store-eval.js";
+export declare const CONTEXT_STORE_EVAL_FIXTURES: ContextStoreEvalFixture[];
+export declare const CONTEXT_STORE_EVAL_RICHER_FIXTURES: ContextStoreEvalFixture[];
+export declare const CONTEXT_STORE_EVAL_EDGE_FIXTURES: ContextStoreEvalFixture[];
+/** Every fixture (healthy + richer + edge), for the internal sufficiency report. */
+export declare const CONTEXT_STORE_ALL_EVAL_FIXTURES: ContextStoreEvalFixture[];