pi-ghost-autocomplete 0.3.1 → 0.3.2

package/README.md

@@ -14,8 +14,8 @@ Four provider modes ship in the same package:
 | --- | --- | --- | --- |
 | `cloud` | Groq / Cerebras / OpenRouter via `@earendil-works/pi-ai` | 150 ms | `groq/llama-3.1-8b-instant` |
 | `local` | Ollama / vLLM (OpenAI-compatible) | 400 ms | `qwen2.5-coder:1.5b` on `http://localhost:11434` |
-| `openai-compat` | Any OpenAI-compatible REST API (e.g. Mercury Edit) — available as a race member only | 150 ms | provider-specific |
-| `race` | Multiple providers in parallel; first valid response wins | 150 ms | per-member defaults |
+| `openai-compat` | Any OpenAI-compatible REST API (e.g. Mercury Edit) — also used as the **default** provider | 150 ms | `mercury-edit-2` on `https://api.inceptionlabs.ai/v1` |
+| `race` | Multiple providers in parallel; first valid response wins | 400 ms | per-member defaults |
 
 ## Getting started
 
@@ -70,7 +70,17 @@ Start typing at the prompt. A dim ghost text should appear to the right of your
 Run `/ghost` to confirm the extension loaded and see the active configuration:
 
 ```
-Pi Ghost: enabled · openai-compat=mercury-edit/mercury-edit-2 debounce=150ms
+Pi Ghost: enabled
+  minChars=3
+  maxLineLength=240
+  mode=openai-compat
+  provider=mercury-edit
+  baseUrl=https://api.inceptionlabs.ai/v1
+  model=mercury-edit-2
+  apiKey=4e24***
+  debounceMs=150
+  maxTokens=64
+  maxRecentMessages=4
 ```
 
 ### 4. (Optional) Load the extension without installing
@@ -104,9 +114,37 @@ All knobs are environment variables — no extra config file needed:
 | `PI_GHOST_RECENT` | 4 (cloud) / 2 (local) | Number of recent user/assistant messages bundled as context |
 | `PI_GHOST_MIN_CHARS` | 3 | Minimum draft length before a prediction fires |
 | `PI_GHOST_MAX_LINE` | 240 | Predictions skipped if the current line exceeds this length |
+| `PI_GHOST_TEMPERATURE` | `0` | Sampling temperature [0, 2]. `0` is best-effort deterministic; see note below |
+| `PI_GHOST_MERCURY_PARALLEL_N` | `1` | Mercury FIM only: fire N parallel candidate completions for cycling. Requires `PI_GHOST_TEMPERATURE > 0` (downgrades silently to 1 at temp=0). Costs scale linearly with N |
+| `PI_GHOST_CONTEXT_MAX_SCAN` | `200` | M6b: cap on the candidate pool scanned for relevance ranking |
+| `PI_GHOST_CONTEXT_MAX_SELECTED` | `8` | M6b: max number of selected context entries |
+| `PI_GHOST_CONTEXT_MAX_CHARS` | `4000` | M6b: total char budget for the selected context window |
+| `PI_GHOST_CONTEXT_BM25_WEIGHT` | `0.3` | M6b: weight of BM25 content score vs recency (0=pure recency, 1=pure relevance) |
+| `PI_GHOST_CONTEXT_TOOL_MAX` | `3` | M6c: max number of tool entries to include in selected context (0 disables tools entirely) |
+| `PI_GHOST_ALLOW_INSECURE` | unset | Set to `1` to allow `http://` provider base URLs on non-localhost hosts. Off by default — API keys + prompts would be sent in clear |
+| `PI_GHOST_PROFILE` | unset | Set to `off` to disable persistent profile capture + reranking. Default: enabled. Profile is local-only — see [Profile](#user-profile) below |
+| `PI_GHOST_PROFILE_DECAY_DAYS` | `90` | Days before an unused profile record's weight halves during compaction |
+| `PI_GHOST_PROVISIONAL` | unset | Set to `off` to disable the 150 ms provisional fallback. Default: enabled |
+| `PI_GHOST_PROVISIONAL_PREFER` | unset | Set to `1`/`true`/`on`/`yes` to bias swap decisions toward the already-displayed provisional. Raises the LLM-vs-provisional swap margin from 0.1 to 0.3, reducing perceived flicker at the cost of recall. Bench reports a `flicker=X%` rate so this knob can be evaluated |
+| `PI_GHOST_MIN_CONFIDENCE` | `0.55` | M3c.1: minimum reranker score for the top candidate to be shown. Range `[0, 1]`. Lower = more lenient, more ghosts shown |
+| `PI_GHOST_RERANK_WEIGHTS` | `0.45,0.25,0.15,0.15` | M3c: reranker weights as `logprob,profileBias,lengthPrior,agreement`. Negative values clamped to 0 |
+| `PI_GHOST_EVAL_CAPTURE` | unset | Set to `1` to capture committed prompts to `.pi/ghost-autocomplete/eval.jsonl` for offline replay (`pi-ghost-replay`). **Sensitive**: contains raw prompt text. Off by default |
+| `PI_GHOST_REGRET_WINDOW_MS` | `3000` | After accept, window in ms during which a >50% deletion of inserted text flags the record `acceptRegret: true` |
+| `PI_GHOST_SHORT_HOVER_MS` | `800` | Enhancement #3: a ghost dismissed within this many ms is flagged `shortHoverDismiss: true` and triggers a soft trie penalty (magnitude 0.25). Tunes the bench `short-hover` rate |
 | `PI_GHOST_METRICS` | unset | Set to `1` to write metrics to `.pi/ghost-autocomplete/metrics.jsonl` |
 | `PI_GHOST_DEBUG_LOG` | unset | Set to `1` to write debug records to `.pi/ghost-autocomplete/debug.jsonl` |
 
+### Note on `temperature=0`
+
+`temperature=0` is the default and asks the provider for greedy decoding so
+the same prefix produces the same completion. This is **best-effort, not
+guaranteed**: vendors batch requests across users and kernel scheduling
+differences can produce different greedy paths from one call to the next.
+The session's in-memory completion cache is the real determinism guarantee
+— retyping the same prefix in the same context will reuse the previous
+ghost rather than re-querying. Raise temperature only if you want
+cache-miss diversity (e.g. `PI_GHOST_TEMPERATURE=0.5`).
+
 Run `/ghost` inside Pi to see the effective config; `/ghost on` and
 `/ghost off` toggle the feature for the current session.
 
@@ -159,6 +197,41 @@ shown, and acceptance outcome (`accepted`, `dismissed`, `stale`, `expired`).
 Raw prompt text and LLM output are never written to the metrics file. Both
 files rotate at 10 MB.
 
+## User profile
+
+The extension keeps a long-lived JSONL store at
+`.pi/ghost-autocomplete/profile.jsonl` to learn slash-command, path, and
+trigram frequencies across sessions. The profile feeds three local-only
+signals:
+
+1. **Slash fast-path.** When the active line starts with `/`, the editor
+   serves the most-typed extension as a ghost before the LLM is queried
+   (mode `trie`, provider `profile-slash`). Press Right to accept.
+2. **Profile-bias rerank (M3c hook).** A `profileBias` score plugs into
+   the multi-candidate reranker. Wired but only takes effect when the
+   provider returns >1 candidate.
+3. **Bounded path boost.** Persistent path frequency adds a small
+   capped boost to deterministic path/fuzzy ranking, capped so it cannot
+   beat a fresh exact path-prefix match.
+
+What's stored: paths (`src/foo.ts`), slash commands (`/review`),
+trigrams from committed prompts, and acceptance records keyed by the
+SHA-256 hash of the prefix. Raw prefixes and raw completions are
+**never** written. Token tuples are tokenized and capped at 4 for
+prefix tails / 8 for completions.
+
+Sanitization runs before persistence: messages with API keys (`sk-…`,
+`ghp_…`, JWT, etc.) or high-entropy tokens (Shannon > 4.0 bits/char,
+length ≥ 20) are dropped entirely. The check is shared with the session
+trie (`src/trie-sanitize.ts`).
+
+Rotation: when the JSONL exceeds 2 MB, the store compacts in place —
+sums weights per `(kind, key)`, halves records older than 90 days
+(configurable via `PI_GHOST_PROFILE_DECAY_DAYS`), drops weights below
+0.1. The original file is preserved as `profile.jsonl.1`.
+
+Set `PI_GHOST_PROFILE=off` to disable capture + use entirely.
+
 ## Benchmark CLI
 
 The `pi-ghost-bench` binary reads a metrics JSONL file and reports p50/p95
@@ -186,11 +259,22 @@ Exit code is `0` when all thresholds pass, `1` when any fail, `2` on I/O error o
 - The path index is built asynchronously at session start via `git ls-files`
   from the repository root, capped at 20 000 files. High-confidence
   basename-prefix matches (score ≥85) preempt the LLM unconditionally; lower-
-  confidence fuzzy matches only activate when an action word (open, edit,
-  read, …) precedes the token.
+  confidence fuzzy matches only activate when an action word (`open`, `edit`,
+  `read`, `show`, `view`, `find`, `check`, `look`, `load`, `import`, `include`,
+  `see`, `run`) precedes the token.
 - Recent agent messages come from `ctx.sessionManager.getBranch()` — only
   user/assistant text, no tool calls. Both providers truncate to a small,
   fixed payload so cloud requests don't ship the whole file.
+- Path mentions are extracted from recent conversation messages (slashed
+  paths, backticked path-like tokens, and bare filenames with known code
+  extensions). These give a ranking boost (+10 exact, +7 basename) to
+  deterministic path completions, so recently discussed files surface
+  higher.
+- For fuzzy filename matches where the typed token is not a prefix of the
+  match, the editor enters **replace mode**: accepting the ghost replaces
+  the typed token with the full matched path. A `→ ` prefix is rendered
+  before the ghost text to signal this behaviour. Prefix-suffix matches
+  still append as usual.
 - `render()` searches for `CURSOR_MARKER` in the lines returned by
   `super.render()` and injects ANSI dim text directly after it. Pi's
   differential renderer redraws only the changed cells — no flicker, no
@@ -201,6 +285,17 @@ Exit code is `0` when all thresholds pass, `1` when any fail, `2` on I/O error o
   handles legacy CSI/SS3 sequences and the Kitty keyboard protocol uniformly,
   so kitty / WezTerm / iTerm2 (Kitty-mode) all work. Otherwise the input
   passes through to `super.handleInput`.
+- **Ctrl+Right** accepts the next *word* of the ghost (PRD §M3f). A "word"
+  is a run of `\w+` characters, or a single non-word non-whitespace char
+  with optional leading whitespace — VS Code's *Cursor Word Right* semantics.
+  Repeated presses peel the ghost off one token at a time; the final press
+  finalises the metric as `accepted-partial`.
+- **Alt+]** / **Alt+[** cycle through ranked candidates when the provider
+  returns more than one (e.g. `openai-compat` with `PI_GHOST_MERCURY_PARALLEL_N>1`
+  and `PI_GHOST_TEMPERATURE>0`). Single-candidate sources (cache, trie,
+  speculative warm, deterministic path, default LLM fire) treat both keys
+  as no-ops. The selected candidate's index is logged as `candidateRank`
+  on accept along with `cycledCount`.
 - Visible-column math uses `string-width` + `strip-ansi`. Ghost text is
   clipped grapheme-aware to the remaining columns on the current visual line
   so wide CJK characters and emoji never overflow the row.
@@ -210,7 +305,7 @@ Exit code is `0` when all thresholds pass, `1` when any fail, `2` on I/O error o
 ```bash
 npm install
 npm run typecheck   # tsc --noEmit against pi-tui / pi-coding-agent v0.74
-npm test            # vitest, ~30 unit tests
+npm test            # vitest, ~170 unit tests
 npm run build       # emits dist/
 ```
 

package/dist/bench-cli.js

@@ -1,7 +1,9 @@
 #!/usr/bin/env node
+import { unwatchFile, watchFile } from "node:fs";
 import { resolve } from "node:path";
-import { formatReport, runBenchmark } from "./bench.js";
+import { formatReport, renderLiveFrame, runBenchmark } from "./bench.js";
 const DEFAULT_PATH = ".pi/ghost-autocomplete/metrics.jsonl";
+const DEFAULT_LIVE_INTERVAL_MS = 2000;
 async function main() {
     const args = process.argv.slice(2);
     if (args.includes("-h") || args.includes("--help")) {
@@ -9,8 +11,17 @@ async function main() {
         return;
     }
     const wantJson = args.includes("--json");
+    const wantLive = args.includes("--live");
+    const intervalFlag = args.find((a) => a.startsWith("--interval="));
+    const intervalMs = intervalFlag
+        ? Math.max(250, Number.parseInt(intervalFlag.slice("--interval=".length), 10) || DEFAULT_LIVE_INTERVAL_MS)
+        : DEFAULT_LIVE_INTERVAL_MS;
     const positional = args.filter((a) => !a.startsWith("-"));
     const target = resolve(process.cwd(), positional[0] ?? DEFAULT_PATH);
+    if (wantLive) {
+        await runLive(target, intervalMs);
+        return;
+    }
     try {
         const report = await runBenchmark(target);
         if (wantJson) {
@@ -32,15 +43,80 @@ async function main() {
         process.exit(2);
     }
 }
+/**
+ * Live mode (Enhancement #6): re-render the report whenever `target` changes.
+ * Polls via `fs.watchFile` rather than `fs.watch` because the latter is
+ * unreliable on Windows for append-only logs. Renders once at startup so
+ * the user sees the current state before the first append.
+ *
+ * Exit on SIGINT. Errors during a refresh are reported inline and the
+ * loop continues — a transient I/O hiccup shouldn't kill the watcher.
+ */
+async function runLive(target, intervalMs) {
+    let frame = 0;
+    let refreshing = false;
+    let pendingRefresh = false;
+    const refresh = async () => {
+        // If a refresh is already in flight, mark the file dirty so we run
+        // one more pass after it completes. Without this, two writes during
+        // the same render would render only once; subsequent writes wouldn't
+        // trigger anything until the watcher saw another mtime change.
+        if (refreshing) {
+            pendingRefresh = true;
+            return;
+        }
+        refreshing = true;
+        try {
+            const report = await runBenchmark(target);
+            frame++;
+            const frameText = renderLiveFrame(report, {
+                now: new Date(),
+                frameNumber: frame,
+                watchedPath: target,
+            });
+            // ANSI: clear screen + cursor home. Plain-text fallback would just
+            // scroll, which is fine in a non-TTY pipe.
+            const clearSeq = process.stdout.isTTY ? "\x1b[2J\x1b[H" : "";
+            process.stdout.write(`${clearSeq}${frameText}\n`);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            process.stderr.write(`pi-ghost-bench --live: refresh error: ${msg}\n`);
+        }
+        finally {
+            refreshing = false;
+            if (pendingRefresh) {
+                pendingRefresh = false;
+                void refresh();
+            }
+        }
+    };
+    process.on("SIGINT", () => {
+        unwatchFile(target);
+        process.stdout.write("\npi-ghost-bench --live: stopped.\n");
+        // Exit with 128 + signal number (130 = 128 + SIGINT/2). Matches the
+        // convention shells use when reporting a Ctrl-C terminated process.
+        process.exit(130);
+    });
+    await refresh();
+    watchFile(target, { interval: intervalMs }, (curr, prev) => {
+        if (curr.mtimeMs !== prev.mtimeMs || curr.size !== prev.size) {
+            void refresh();
+        }
+    });
+}
 function usage() {
     return [
-        "pi-ghost-bench [path] [--json]",
+        "pi-ghost-bench [path] [--json] [--live] [--interval=MS]",
         "",
-        "  path     JSONL metrics file (default: .pi/ghost-autocomplete/metrics.jsonl)",
-        "  --json   emit JSON instead of formatted text",
-        "  -h       show this help",
+        "  path           JSONL metrics file (default: .pi/ghost-autocomplete/metrics.jsonl)",
+        "  --json         Emit JSON instead of formatted text",
+        "  --live         Watch the file and re-render on each change (Ctrl+C to exit)",
+        "  --interval=MS  Poll interval for --live (default: 2000, min: 250)",
+        "  -h             Show this help",
         "",
         "Exit code: 0 if all PRD thresholds pass, 1 if any fail, 2 on I/O error.",
+        "--live runs until interrupted (no exit code gating).",
         "",
     ].join("\n");
 }

package/dist/bench-cli.js.map

@@ -1 +1 @@
-{"version":3,"file":"bench-cli.js","sourceRoot":"","sources":["../src/bench-cli.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAExD,MAAM,YAAY,GAAG,sCAAsC,CAAC;AAE5D,KAAK,UAAU,IAAI;IAClB,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IACnC,IAAI,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC;QACpD,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC,CAAC;QAC9B,OAAO;IACR,CAAC;IACD,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;IACzC,MAAM,UAAU,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC;IAC1D,MAAM,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,UAAU,CAAC,CAAC,CAAC,IAAI,YAAY,CAAC,CAAC;IAErE,IAAI,CAAC;QACJ,MAAM,MAAM,GAAG,MAAM,YAAY,CAAC,MAAM,CAAC,CAAC;QAC1C,IAAI,QAAQ,EAAE,CAAC;YACd,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC;QAC9D,CAAC;aAAM,CAAC;YACP,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,YAAY,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;QACnD,CAAC;QACD,IAAI,MAAM,CAAC,OAAO,KAAK,CAAC,EAAE,CAAC;YAC1B,OAAO,CAAC,MAAM,CAAC,KAAK,CACnB,wCAAwC,MAAM,2BAA2B,CACzE,CAAC;YACF,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QACjB,CAAC;QACD,MAAM,OAAO,GAAG,MAAM,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;QACvD,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAC/B,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACd,MAAM,GAAG,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QAC7D,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,mBAAmB,GAAG,IAAI,CAAC,CAAC;QACjD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IACjB,CAAC;AACF,CAAC;AAED,SAAS,KAAK;IACb,OAAO;QACN,gCAAgC;QAChC,EAAE;QACF,+EAA+E;QAC/E,gDAAgD;QAChD,2BAA2B;QAC3B,EAAE;QACF,yEAAyE;QACzE,EAAE;KACF,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACd,CAAC;AAED,KAAK,IAAI,EAAE,CAAC"}
+{"version":3,"file":"bench-cli.js","sourceRoot":"","sources":["../src/bench-cli.ts"],"names":[],"mappings":"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"}

package/dist/bench.d.ts

@@ -1,4 +1,4 @@
-import type { MetricsRecord } from "./metrics.js";
+import { type MetricsRecord } from "./metrics.js";
 /**
  * PRD §Success Metrics initial candidate thresholds. These are red/green
  * targets, not gates — the harness reports compliance but never errors out.
@@ -9,6 +9,15 @@ export declare const THRESHOLDS: {
     readonly deterministicP50Ms: 30;
     readonly validOutputRate: 0.85;
     readonly badOutputRate: 0.15;
+    /**
+     * Enhancement #6 hard gate: fraction of accepted-or-shown ghosts whose
+     * `estimatedTimeSavedMs` came out negative — i.e. the user spent more
+     * time waiting for the ghost than the keystrokes the accept could ever
+     * save. <10% is healthy, 10–20% warns, ≥20% fails. Calibrated against
+     * Yeh/Laban "saved-time" surveys and our own M5 data.
+     */
+    readonly negativeTimeSavedYellow: 0.1;
+    readonly negativeTimeSavedRed: 0.2;
 };
 export interface ProviderStats {
     provider: string;
@@ -28,8 +37,9 @@ export interface ProviderStats {
     /** (empty + rejected + error) / count */
     badRate: number;
 }
+export type AnyMode = "deterministic" | "llm" | "cache" | "trie" | "speculative-warm" | "provisional";
 export interface ModeStats {
-    mode: "deterministic" | "llm";
+    mode: AnyMode;
     count: number;
     shown: number;
     accepted: number;
@@ -39,17 +49,121 @@ export interface ModeStats {
     acceptanceRate: number;
     providers: ProviderStats[];
 }
+/**
+ * Advanced metrics from M5a fields. All optional — values are populated only
+ * when the records carry the required field. Skipping rather than zeroing
+ * keeps a sparse session from looking artificially well-instrumented.
+ */
+export interface AdvancedStats {
+    /** Time-to-first-token (LLM modes), p50/p95 in ms. */
+    ttftMs?: {
+        p50: number;
+        p95: number;
+        n: number;
+    };
+    /** Estimated typing time saved per accepted ghost, p50/p95 in ms. */
+    timeSavedMs?: {
+        p50: number;
+        p95: number;
+        total: number;
+        n: number;
+    };
+    /**
+     * Enhancement #6 hard gate: fraction of `estimatedTimeSavedMs` samples
+     * that came out negative. `severity`:
+     *  - "ok": fraction < THRESHOLDS.negativeTimeSavedYellow
+     *  - "yellow": yellow ≤ fraction < red
+     *  - "red": fraction ≥ THRESHOLDS.negativeTimeSavedRed
+     * `n` is the denominator (records with `estimatedTimeSavedMs`).
+     */
+    negativeTimeSaved?: {
+        count: number;
+        fraction: number;
+        n: number;
+        severity: "ok" | "yellow" | "red";
+    };
+    /**
+     * Accept-regret rate per PRD §M5b: fraction of accepted ghosts the user
+     * deleted >50% of within the regret window. Calibration target: <10%.
+     * `n` is the denominator (accepted + accepted-partial outcomes).
+     */
+    acceptRegretRate?: {
+        rate: number;
+        n: number;
+    };
+    /**
+     * Enhancement #3: fraction of *dismissed* ghosts where the user dismissed
+     * within `PI_GHOST_SHORT_HOVER_MS` (default 800 ms). High rate signals
+     * the rerank/confidence gate is letting through low-value candidates.
+     * `n` is the denominator (dismissed outcomes).
+     */
+    shortHoverDismissRate?: {
+        rate: number;
+        n: number;
+    };
+    /**
+     * Enhancement #5: fraction of stale records where the user typed at
+     * least `TYPED_PAST_DIVERGENT_THRESHOLD` consecutive divergent
+     * characters past the served ghost. High rate is a strong signal that
+     * the suggestions are off-target for this user's style. `n` is the
+     * denominator (stale outcomes).
+     */
+    typedPastDivergentRate?: {
+        rate: number;
+        n: number;
+    };
+    /**
+     * Provisional-fallback stats per PRD §M5b: how often provisional fired,
+     * what fraction the LLM ended up matching, and mean swap latency for
+     * the cases that did swap.
+     */
+    provisional?: {
+        shown: number;
+        swapped: number;
+        correctRate: number;
+        meanSwapMs: number;
+        /**
+         * Fraction of `swapped` events where the user dismissed/aborted within
+         * `SWAP_FLICKER_WINDOW_MS` — visual jumps that didn't help. With
+         * `PREFER` margin now the default, this should converge to a low
+         * single-digit % under normal use.
+         */
+        flickerRate?: number;
+        /** Per-source counts of provisional shows that survived to outcome
+         *  WITHOUT being superseded by the LLM (i.e., `mode === "provisional"`
+         *  on the final record). Keys: `trie`, `profile-accept`,
+         *  `session-cache`. Provisional+LLM-swap cases are counted under
+         *  `swapped` instead, because the final shownMetric is the LLM's. */
+        bySource?: Record<string, number>;
+        /** Accept rate over `shown` — i.e., provisionals that survived alone
+         *  to outcome (no LLM swap). Measures how good the local guess is
+         *  when the LLM doesn't take over. Production target: ≥45 %. */
+        acceptRate?: number;
+    };
+    /** Fraction of shown ghosts accepted at first display (rank 0). */
+    savedAt1?: number;
+    /** Same, after cycling up to 3 candidates. */
+    savedAt3?: number;
+    /** Same, after 5. */
+    savedAt5?: number;
+}
 export interface BenchmarkReport {
     source: string;
     records: number;
     parseErrors: number;
     deterministic: ModeStats;
     llm: ModeStats;
+    /** All non-zero modes from the records, keyed by mode name. */
+    byMode: ModeStats[];
+    advanced: AdvancedStats;
     thresholds: Array<{
         name: string;
         target: string;
         observed: string;
         pass: boolean;
+        /** Present when the threshold has a yellow band. "warn" means observed
+         *  is past the yellow line but still under the red line — pass=true. */
+        severity?: "warn";
     }>;
 }
 /**
@@ -90,4 +204,18 @@ export declare function formatReport(report: BenchmarkReport): string;
  * One-shot helper: load a JSONL file and produce a report. Used by the CLI.
  */
 export declare function runBenchmark(path: string): Promise<BenchmarkReport>;
+/**
+ * Enhancement #6: a single rendered "frame" for `pi-ghost-bench --live`.
+ * The frame is a self-contained block of text — caller clears the screen
+ * and prints it on every metrics-file change. ANSI escapes are emitted by
+ * the CLI, not this helper, so the function stays pure and unit-testable.
+ *
+ * Format: banner with timestamp + frame counter, then the standard
+ * formatted report, then a footer with the watched path.
+ */
+export declare function renderLiveFrame(report: BenchmarkReport, opts: {
+    now: Date;
+    frameNumber: number;
+    watchedPath: string;
+}): string;
 //# sourceMappingURL=bench.d.ts.map

package/dist/bench.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"bench.d.ts","sourceRoot":"","sources":["../src/bench.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAqB,aAAa,EAAkC,MAAM,cAAc,CAAC;AAErG;;;GAGG;AACH,eAAO,MAAM,UAAU;;;;;;CAMb,CAAC;AAEX,MAAM,WAAW,aAAa;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC;IACrD,uBAAuB;IACvB,SAAS,EAAE,MAAM,CAAC;IAClB,yCAAyC;IACzC,OAAO,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,SAAS;IACzB,IAAI,EAAE,eAAe,GAAG,KAAK,CAAC;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,cAAc,EAAE,MAAM,CAAC;IACvB,SAAS,EAAE,aAAa,EAAE,CAAC;CAC3B;AAED,MAAM,WAAW,eAAe;IAC/B,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,EAAE,SAAS,CAAC;IACzB,GAAG,EAAE,SAAS,CAAC;IACf,UAAU,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;CACrF;AAED;;;;GAIG;AACH,wBAAsB,WAAW,CAChC,IAAI,EAAE,MAAM,GACV,OAAO,CAAC;IAAE,OAAO,EAAE,aAAa,EAAE,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,CAAC,CAG5D;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG;IAC/C,OAAO,EAAE,aAAa,EAAE,CAAC;IACzB,WAAW,EAAE,MAAM,CAAC;CACpB,CAcA;AAaD;;;;GAIG;AACH,wBAAgB,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAM5D;AAED;;;;;;;GAOG;AACH,wBAAgB,SAAS,CACxB,OAAO,EAAE,aAAa,EAAE,EACxB,MAAM,SAAa,EACnB,WAAW,SAAI,GACb,eAAe,CAajB;AAqHD;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,eAAe,GAAG,MAAM,CA8B5D;AAMD;;GAEG;AACH,wBAAsB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC,CAGzE"}
+{"version":3,"file":"bench.d.ts","sourceRoot":"","sources":["../src/bench.ts"],"names":[],"mappings":"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"}