@gonrocca/zero-pi 0.1.9 → 0.1.11

package/README.md

@@ -134,14 +134,24 @@ re-tune `~/.pi/zero.json` for you.
 
 **The metrics log — `~/.pi/zero-runs.jsonl`.** Every completed SDD run appends
 one JSON line to this file: the feature slug, the per-phase models the run used,
-the final verdict, and the build/veredicto round count. It is append-only and
-never rewritten. This local log is the only thing zero learns from — a run
-abandoned before it reaches a verdict adds no line.
+the final verdict, the build/veredicto round count, and the ordered per-round
+verdict sequence. It is append-only and never rewritten. This local log is the
+only thing zero learns from — a run abandoned before it reaches a verdict adds
+no line.
+
+**Phase attribution (v2).** The per-round verdict sequence makes blame precise:
+a `corregir` round re-runs — and so blames — the `build` phase, and a
+`replantear` round blames the `plan` phase. Autotune aggregates that sequence
+per phase and upgrades **only the phase at fault**, one tier at a time — a
+`build` problem no longer drags `plan` up with it. The `explore` and `veredicto`
+phases are never tuned.
 
 **Autotune modes.** At each pi session start zero aggregates the log and, once a
 phase has accumulated enough run data to cross a confidence threshold, decides
-whether that phase's model should change. The `autotune` mode in `~/.pi/zero.json`
-controls what happens next:
+whether that phase's model should change. Until a phase has accumulated enough
+v2 runs of its own, autotune deliberately stays quiet — a one-time, silent
+cold-start after upgrading, not a regression. The `autotune` mode in
+`~/.pi/zero.json` controls what happens next:
 
 | Mode | Behaviour |
 | ---- | --------- |
@@ -171,26 +181,103 @@ the most recent recommendation.
 `skill-loop.md` gives the agent a closed learning loop so solutions are reused
 instead of re-derived.
 
+### ZERO terminal theme (`themes/zero-sdd.json`)
+
+`zero-pi` ships a Pi theme named `zero-sdd`: a dark, high-contrast terminal
+palette with cyan, amber, mint, rose, and violet accents tuned for SDD work.
+Select it from `/settings`, or set `"theme": "zero-sdd"` in Pi settings.
+
 ### Startup banner (`extensions/startup-banner.ts`)
 
-Renders the `ZERO` wordmark in ANSI Shadow figlet style with a purple → amber
-shimmer sweep the moment a pi session starts, then settles into a static
-gradient glow. Pure ANSI 24-bit colour, no runtime dependencies.
+Renders the `ZERO` wordmark as ASCII-safe Tetris cells. In the default animated
+mode, the cells assemble from the bottom up when a pi session starts, then
+settle into the completed ZERO banner. Pure ANSI 24-bit colour, no runtime
+dependencies.
 
 The render runs synchronously before pi draws its UI, so the animation never
 fights pi's renderer.
 
+### Working-phrase ticker (`extensions/working-phrases.ts`)
+
+Pi shows a single static `Working...` line while the agent is busy. This
+extension replaces it with a context-aware, rotating phrase:
+
+- **While a tool runs** — a tool-specific line: `Leyendo archivos…`,
+  `Ejecutando comandos…`, `Buscando en el código…`. MCP tools are named by
+  server (`Consultando un MCP…`).
+- **While a zero sub-agent runs** — the SDD phase it owns:
+  `Explorando el código…`, `Planeando la solución…`,
+  `Construyendo la implementación…`, `Revisando el veredicto…`.
+- **While the model thinks** — a rotation of playful verbs (`Maquinando…`,
+  `Rumiando…`, `Cocinando…`). Once a `/forge` run is detected the rotation
+  biases toward SDD vocabulary.
+
+It also installs a theme-tinted braille spinner that gently breathes through
+the palette's `dim`/`muted`/`accent` colours. The extension uses only pi's
+public extension API, and every handler is defensive — the indicator can never
+break a session.
+
 Control it with the `ZERO_BANNER` environment variable:
 
 | `ZERO_BANNER` | Effect |
 | ------------- | ------ |
-| _(unset)_ / `shimmer` | Animated shimmer sweep, then settle (default) |
-| `static` | Settled gradient only, no animation |
+| _(unset)_ / `shimmer` | Animated Tetris assembly, then settle (default) |
+| `static` | Completed Tetris banner only, no animation |
 | `off` | Render nothing |
 
 Colour is skipped automatically when `NO_COLOR` is set or the output is not a
 TTY.
 
+### Provider guard (`extensions/provider-guard.ts`)
+
+zero-pi watches model switches and steps in when you move to a metered
+provider. When you switch to a model on the `anthropic` provider — which bills
+per token and draws down your metered extra-usage pool — the guard offers to
+redirect you to the equivalent model on `pi-claude-cli`, the provider backed by
+your subscription's limits.
+
+The redirect is offered through a confirmation dialog, and that dialog is your
+escape hatch: say "yes" and the guard switches you to the subscription-backed
+equivalent; say "no" (or cancel) and you stay on the metered `anthropic`
+provider with no further nagging. When there is no equivalent model on
+`pi-claude-cli`, and when a model is restored on session start rather than
+switched deliberately, the guard skips the modal and just shows a one-line
+warning. Switching to a subscription provider is a complete no-op — no dialog,
+no notification, no noise.
+
+### Conversation resume (`extensions/conversation-resume.ts`)
+
+When pi exits normally, zero-pi writes a local handoff note:
+
+```
+.pi/zero-resume.md
+```
+
+The note includes the exact restore command for the persisted pi session:
+
+```bash
+pi --session '<session-file>'
+```
+
+When a session id is available it also writes the shorter form:
+
+```bash
+pi --session <session-id>
+```
+
+`pi --resume` is listed too for the interactive session picker. The file also
+keeps a concise conversation tail, enough to remember the last user intent and
+assistant progress without replacing pi's real session history.
+
+Generate it manually at any time:
+
+```text
+/zero-resume
+```
+
+The resume lives under `.pi/`, and zero-pi creates `.pi/.gitignore` so local
+conversation context is not accidentally committed.
+
 ## Relationship to `zero`
 
 `zero-pi` is the pi-specific layer of the **[zero](https://github.com/gonzalonicolasr/zero)**

package/extensions/autotune.ts

@@ -12,8 +12,9 @@
 import { readFileSync } from "node:fs";
 
 /** Schema version of one `~/.pi/zero-runs.jsonl` record. A record carrying any
- *  other `v` is dropped by `parseRunLine` rather than mis-aggregated. */
-export const RUN_SCHEMA_VERSION = 1;
+ *  other `v` is dropped by `parseRunLine` rather than mis-aggregated. v2 adds
+ *  the per-round `verdicts` sequence; `parseRunLine` still accepts v1 records. */
+export const RUN_SCHEMA_VERSION = 2;
 
 /** The SDD phases a run record carries a model for, in pipeline order. */
 const RECORD_PHASES = ["explore", "plan", "build", "veredicto"] as const;
@@ -25,6 +26,14 @@ const VERDICTS = ["pasa", "cap-reached"] as const;
 /** A run's terminal verdict. */
 export type RunVerdict = (typeof VERDICTS)[number];
 
+/** Per-round verdicts the `veredicto` phase can return. `corregir` re-runs
+ *  build, `replantear` re-runs plan, `pasa` ends the run. `cap-reached` is a
+ *  run-level terminal state and is deliberately *not* a round verdict. */
+const ROUND_VERDICTS = ["corregir", "replantear", "pasa"] as const;
+
+/** A single round's verdict from the `veredicto` phase. */
+export type RunRoundVerdict = (typeof ROUND_VERDICTS)[number];
+
 /** The model a single phase ran on for a given run. An object (not a bare
  *  string) so the schema can grow additive fields without a version bump. */
 export interface PhaseRun {
@@ -48,6 +57,11 @@ export interface RunRecord {
   verdict: RunVerdict;
   /** Count of build/veredicto rounds — `1` for a clean first-pass run. */
   rounds: number;
+  /** The chronological per-round verdict sequence. Present on `v:2` records
+   *  (`verdicts.length === rounds`); `undefined` on `v:1` records, which carry
+   *  only the run-level verdict and so cannot be phase-attributed. Its
+   *  presence is the single discriminator `aggregate` uses for v2 attribution. */
+  verdicts?: RunRoundVerdict[];
 }
 
 /** How aggressively zero applies a learned profile — stored in `zero.json`.
@@ -60,15 +74,56 @@ function isObject(value: unknown): value is Record<string, unknown> {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 
+/**
+ * Validate a parsed `verdicts` value against the v2 invariants.
+ *
+ * Returns the typed array when the value is a non-empty `RunRoundVerdict[]`
+ * with `length === rounds` and a sequence consistent with the run-level
+ * `verdict`: a `pasa` run ends with exactly one `pasa` (last entry), a
+ * `cap-reached` run contains no `pasa`. Returns `null` for any violation —
+ * the caller drops the whole record rather than mis-attribute.
+ */
+function validateVerdicts(
+  value: unknown,
+  verdict: RunVerdict,
+  rounds: number,
+): RunRoundVerdict[] | null {
+  if (!Array.isArray(value)) return null;
+  if (value.length < 1) return null;
+  if (value.length !== rounds) return null;
+
+  const verdicts: RunRoundVerdict[] = [];
+  for (const entry of value) {
+    if (typeof entry !== "string") return null;
+    if (!(ROUND_VERDICTS as readonly string[]).includes(entry)) return null;
+    verdicts.push(entry as RunRoundVerdict);
+  }
+
+  const passCount = verdicts.filter((e) => e === "pasa").length;
+  if (verdict === "pasa") {
+    // Exactly one `pasa`, and it is the final entry.
+    if (passCount !== 1) return null;
+    if (verdicts[verdicts.length - 1] !== "pasa") return null;
+  } else {
+    // `cap-reached`: the run never passed.
+    if (passCount !== 0) return null;
+  }
+
+  return verdicts;
+}
+
 /**
  * Parse one JSONL line into a `RunRecord`, validating the shape.
  *
- * Returns `null` — never throws — for anything off-shape: invalid JSON, a
- * non-object, an unexpected `v`, a missing/non-string `feature` or `ts`, a
- * non-integer `rounds`, a `verdict` outside the enum, or a `phases` map
- * missing any of the four phases or carrying a non-string model. This is the
- * deliberate defense against malformed LLM-emitted records: a bad emission
- * degrades to "one missing sample", never a crash.
+ * Accepts both `v:1` records (no `verdicts`) and `v:2` records (a fully
+ * validated per-round `verdicts` sequence). Returns `null` — never throws —
+ * for anything off-shape: invalid JSON, a non-object, a `v` outside
+ * `{1, 2}`, a missing/non-string `feature` or `ts`, a non-integer `rounds`, a
+ * `verdict` outside the enum, a `phases` map missing any of the four phases
+ * or carrying a non-string model, or — for `v:2` — a missing/non-array/
+ * inconsistent `verdicts`. This is the deliberate defense against malformed
+ * LLM-emitted records: a bad emission degrades to "one missing sample",
+ * never a crash.
  */
 export function parseRunLine(line: string): RunRecord | null {
   let parsed: unknown;
@@ -80,12 +135,13 @@ export function parseRunLine(line: string): RunRecord | null {
 
   if (!isObject(parsed)) return null;
 
-  if (parsed.v !== RUN_SCHEMA_VERSION) return null;
+  if (parsed.v !== 1 && parsed.v !== 2) return null;
   if (typeof parsed.ts !== "string" || parsed.ts === "") return null;
   if (typeof parsed.feature !== "string" || parsed.feature === "") return null;
   if (typeof parsed.rounds !== "number" || !Number.isInteger(parsed.rounds)) return null;
   if (typeof parsed.verdict !== "string") return null;
   if (!(VERDICTS as readonly string[]).includes(parsed.verdict)) return null;
+  const verdict = parsed.verdict as RunVerdict;
 
   if (!isObject(parsed.phases)) return null;
   const phases = {} as RunRecord["phases"];
@@ -96,13 +152,23 @@ export function parseRunLine(line: string): RunRecord | null {
     phases[phase] = { model: phaseRun.model };
   }
 
+  // v2 records must carry a fully consistent `verdicts` sequence; v1 records
+  // legitimately lack the field (the discriminator is `v`, not its presence).
+  let verdicts: RunRoundVerdict[] | undefined;
+  if (parsed.v === 2) {
+    const validated = validateVerdicts(parsed.verdicts, verdict, parsed.rounds);
+    if (validated === null) return null;
+    verdicts = validated;
+  }
+
   return {
-    v: RUN_SCHEMA_VERSION,
+    v: parsed.v,
     ts: parsed.ts,
     feature: parsed.feature,
     phases,
-    verdict: parsed.verdict as RunVerdict,
+    verdict,
     rounds: parsed.rounds,
+    ...(verdicts !== undefined ? { verdicts } : {}),
   };
 }
 
@@ -149,6 +215,16 @@ export interface PhaseModelStat {
   /** Mean `rounds` averaged ONLY over runs that reached `pasa`; `null` when no
    *  `pasa` run exists for the pair. */
   avgRounds: number | null;
+  // --- v2 phase attribution ---
+  /** Count of `v:2` records contributing to this pair — the dormancy-gate
+   *  denominator. v1 records do not increment this. */
+  v2Samples: number;
+  /** Mean count of `corregir` verdicts per v2 run for this pair — only
+   *  meaningful for `phase === "build"`. `null` when `v2Samples === 0`. */
+  avgCorregir: number | null;
+  /** Mean count of `replantear` verdicts per v2 run for this pair — only
+   *  meaningful for `phase === "plan"`. `null` when `v2Samples === 0`. */
+  avgReplantear: number | null;
 }
 
 /** Map key for a `(phase, model)` bucket. */
@@ -159,12 +235,19 @@ function statKey(phase: string, model: string): string {
 /**
  * Aggregate run records into per-`(phase, model)` statistics.
  *
- * For every record, each of the four phases contributes one sample to the
- * bucket of the model that phase ran on (a phase whose model is missing or
- * non-string is skipped). `avgRounds` is averaged exclusively over runs that
- * reached `pasa`; non-positive `rounds` values (which `parseRunLine` does not
- * reject) are ignored when computing that average so a bad `0`/negative entry
- * never skews or breaks the math. An empty input yields an empty map.
+ * For every record (v1 and v2 alike), each of the four phases contributes one
+ * sample to the bucket of the model that phase ran on (a phase whose model is
+ * missing or non-string is skipped). `avgRounds` is averaged exclusively over
+ * runs that reached `pasa`; non-positive `rounds` values (which `parseRunLine`
+ * does not reject) are ignored when computing that average so a bad
+ * `0`/negative entry never skews or breaks the math.
+ *
+ * Only records carrying a `verdicts` sequence (v2) contribute phase
+ * attribution: each such record increments `v2Samples` for every phase, and
+ * folds its per-run `corregir` count into the `build` model's `avgCorregir`
+ * accumulator and its per-run `replantear` count into the `plan` model's
+ * `avgReplantear` accumulator. `avgCorregir`/`avgReplantear` are `null` when a
+ * pair has no v2 evidence. An empty input yields an empty map.
  */
 export function aggregate(records: RunRecord[]): Map<string, PhaseModelStat> {
   interface Acc {
@@ -172,11 +255,22 @@ export function aggregate(records: RunRecord[]): Map<string, PhaseModelStat> {
     passes: number;
     passRounds: number;
     passRoundCount: number;
+    v2Samples: number;
+    corregirTotal: number;
+    replantearTotal: number;
   }
   const acc = new Map<string, { phase: (typeof RECORD_PHASES)[number]; model: string; data: Acc }>();
 
   for (const record of records) {
     const isPass = record.verdict === "pasa";
+    const isV2 = record.verdicts !== undefined;
+    const corregirCount = isV2
+      ? (record.verdicts as RunRoundVerdict[]).filter((v) => v === "corregir").length
+      : 0;
+    const replantearCount = isV2
+      ? (record.verdicts as RunRoundVerdict[]).filter((v) => v === "replantear").length
+      : 0;
+
     for (const phase of RECORD_PHASES) {
       const phaseRun = record.phases[phase];
       const model = phaseRun?.model;
@@ -185,7 +279,19 @@ export function aggregate(records: RunRecord[]): Map<string, PhaseModelStat> {
       const key = statKey(phase, model);
       let bucket = acc.get(key);
       if (bucket === undefined) {
-        bucket = { phase, model, data: { samples: 0, passes: 0, passRounds: 0, passRoundCount: 0 } };
+        bucket = {
+          phase,
+          model,
+          data: {
+            samples: 0,
+            passes: 0,
+            passRounds: 0,
+            passRoundCount: 0,
+            v2Samples: 0,
+            corregirTotal: 0,
+            replantearTotal: 0,
+          },
+        };
         acc.set(key, bucket);
       }
       bucket.data.samples += 1;
@@ -198,18 +304,29 @@ export function aggregate(records: RunRecord[]): Map<string, PhaseModelStat> {
           bucket.data.passRoundCount += 1;
         }
       }
+      if (isV2) {
+        bucket.data.v2Samples += 1;
+        // `corregir` blames the build phase's model, `replantear` the plan
+        // phase's. The mapping is the pipeline contract, fixed and known.
+        if (phase === "build") bucket.data.corregirTotal += corregirCount;
+        if (phase === "plan") bucket.data.replantearTotal += replantearCount;
+      }
     }
   }
 
   const stats = new Map<string, PhaseModelStat>();
   for (const [key, bucket] of acc) {
-    const { samples, passes, passRounds, passRoundCount } = bucket.data;
+    const { samples, passes, passRounds, passRoundCount, v2Samples, corregirTotal, replantearTotal } =
+      bucket.data;
     stats.set(key, {
       phase: bucket.phase,
       model: bucket.model,
       samples,
       passRate: samples > 0 ? passes / samples : 0,
       avgRounds: passRoundCount > 0 ? passRounds / passRoundCount : null,
+      v2Samples,
+      avgCorregir: v2Samples > 0 ? corregirTotal / v2Samples : null,
+      avgReplantear: v2Samples > 0 ? replantearTotal / v2Samples : null,
     });
   }
   return stats;
@@ -292,6 +409,17 @@ export const HIGH_AVG_ROUNDS = 2.5;
 /** Pass-rate at or over this value marks a phase as reliable — stay put. */
 export const RELIABLE_PASS_RATE = 0.85;
 
+/** Below this many `v:2` records a phase is left dormant — too little
+ *  attributed evidence to act on (Story 7). Reuses v1's `MIN_SAMPLES` value. */
+export const MIN_V2_SAMPLES = 5;
+
+/** Mean `corregir`/run strictly above this value blames the `build` model. */
+export const HIGH_AVG_CORREGIR = 1.0;
+
+/** Mean `replantear`/run strictly above this value blames the `plan` model.
+ *  Lower than `HIGH_AVG_CORREGIR` because a `replantear` is rarer and costlier. */
+export const HIGH_AVG_REPLANTEAR = 0.5;
+
 /**
  * A proposed change of model for one SDD phase. `reason` is a human-readable
  * string used verbatim in notifications.
@@ -307,22 +435,33 @@ export interface Adjustment {
   reason: string;
 }
 
+/** The phases v2 autotune can attribute blame to and adjust. `explore` and
+ *  `veredicto` are structurally excluded — no round verdict ever blames them. */
+const ATTRIBUTABLE_PHASES = ["build", "plan"] as const;
+
 /**
- * Decide model adjustments from aggregated statistics.
+ * Decide model adjustments from aggregated statistics — v2 phase-attributed.
  *
- * For each phase, looks up the `(phase, currentModel)` stat and applies the
- * adjustment rules:
- *   - absent stat or `samples < MIN_SAMPLES` → no decision (too little data);
- *   - under-performing (`passRate <= LOW_PASS_RATE`, or a `pasa`-only
- *     `avgRounds > HIGH_AVG_ROUNDS`) → propose one tier up via `stepUp`;
- *   - reliable (`passRate >= RELIABLE_PASS_RATE` and `avgRounds` not high)
- *     → keep the model;
- *   - otherwise (middling) → no change.
+ * Only the `build` and `plan` phases are considered: a `corregir` verdict
+ * re-runs build and a `replantear` verdict re-runs plan, so those are the only
+ * phases the verdict sequence can blame. `explore` and `veredicto` are
+ * structurally never iterated and so never adjusted (Story 6).
+ *
+ * For each attributable phase, looks up the `(phase, currentModel)` stat and:
+ *   - skips an absent stat;
+ *   - skips a phase with `v2Samples < MIN_V2_SAMPLES` — too little attributed
+ *     evidence (the dormancy gate, Story 7);
+ *   - reads the phase's blame measure (`build` → `avgCorregir` vs
+ *     `HIGH_AVG_CORREGIR`, `plan` → `avgReplantear` vs `HIGH_AVG_REPLANTEAR`)
+ *     and skips when it is `null` or not strictly above its threshold;
+ *   - otherwise proposes one tier up via `stepUp`.
  *
  * Safety caps are baked in: a proposal is emitted only when `stepUp` returns a
  * model (so a phase already at `opus` or on an untierable model is left
  * alone), `stepUp` never jumps more than one tier, and it never returns a
- * model outside `knownModels`-or-the-fixed-representative set.
+ * model outside `knownModels`-or-the-fixed-representative set. v1's
+ * `LOW_PASS_RATE`/`HIGH_AVG_ROUNDS`/`RELIABLE_PASS_RATE` constants remain
+ * exported but no longer drive this function.
  */
 export function decideAdjustments(
   stats: Map<string, PhaseModelStat>,
@@ -331,29 +470,25 @@ export function decideAdjustments(
 ): Adjustment[] {
   const adjustments: Adjustment[] = [];
 
-  for (const phase of RECORD_PHASES) {
+  for (const phase of ATTRIBUTABLE_PHASES) {
     const currentModel = currentModels[phase];
     if (typeof currentModel !== "string" || currentModel === "") continue;
 
     const stat = stats.get(statKey(phase, currentModel));
-    if (stat === undefined || stat.samples < MIN_SAMPLES) continue;
+    if (stat === undefined) continue;
 
-    const highRounds = stat.avgRounds !== null && stat.avgRounds > HIGH_AVG_ROUNDS;
-    const underPerforming = stat.passRate <= LOW_PASS_RATE || highRounds;
-    const reliable =
-      stat.passRate >= RELIABLE_PASS_RATE &&
-      (stat.avgRounds === null || stat.avgRounds <= HIGH_AVG_ROUNDS);
+    // Dormancy gate: too few v2 records to attribute blame.
+    if (stat.v2Samples < MIN_V2_SAMPLES) continue;
 
-    if (reliable) continue;
-    if (!underPerforming) continue;
+    const measure = phase === "build" ? stat.avgCorregir : stat.avgReplantear;
+    const threshold = phase === "build" ? HIGH_AVG_CORREGIR : HIGH_AVG_REPLANTEAR;
+    if (measure === null || !(measure > threshold)) continue;
 
     const to = stepUp(currentModel, knownModels);
     if (to === null) continue; // already at top tier, or untierable
 
-    const reason =
-      stat.passRate <= LOW_PASS_RATE
-        ? `pass-rate ${stat.passRate.toFixed(2)} over ${stat.samples} runs`
-        : `avg ${(stat.avgRounds as number).toFixed(1)} rounds-to-pass over ${stat.samples} runs`;
+    const blame = phase === "build" ? "corregir" : "replantear";
+    const reason = `avg ${measure.toFixed(1)} ${blame}/run over ${stat.v2Samples} v2 runs`;
 
     adjustments.push({ phase, from: currentModel, to, reason });
   }