@gonrocca/zero-pi 0.1.26 → 0.1.28

package/README.md

@@ -13,294 +13,89 @@
 
 **The zero spec-driven development workflow, packaged for [pi](https://pi.dev).**
 
-[![npm](https://img.shields.io/npm/v/@gonrocca/zero-pi?color=af8aff&label=npm)](https://www.npmjs.com/package/@gonrocca/zero-pi)
-[![repo](https://img.shields.io/badge/repo-github-7497ff?logo=github&logoColor=white)](https://github.com/gonzalonicolasr/zero-pi)
-[![license](https://img.shields.io/npm/l/@gonrocca/zero-pi?color=eebe5c)](./LICENSE)
-[![node](https://img.shields.io/node/v/@gonrocca/zero-pi?color=4fddab&label=node)](https://nodejs.org)
-
-**Repositorio:** [github.com/gonzalonicolasr/zero-pi](https://github.com/gonzalonicolasr/zero-pi)
+[![npm](https://img.shields.io/npm/v/@gonrocca/zero-pi?color=af8aff&label=npm)](https://www.npmjs.com/package/@gonrocca/zero-pi) [![repo](https://img.shields.io/badge/repo-github-7497ff?logo=github&logoColor=white)](https://github.com/gonzalonicolasr/zero-pi) [![license](https://img.shields.io/npm/l/@gonrocca/zero-pi?color=eebe5c)](./LICENSE) [![node](https://img.shields.io/node/v/@gonrocca/zero-pi?color=4fddab&label=node)](https://nodejs.org)
 
 </div>
 
 ---
 
-zero-pi adds the **`/forge`** SDD pipeline, skill auto-learning, adaptive
-per-phase models, a metered-billing guard, and an animated `ZERO` banner —
-**without modifying pi itself**. Same idea as `gentle-pi`: pi stays untouched;
-zero-pi is a package pi loads. Every prompt, skill, extension and theme below
-ships inside this one package.
-
-## Contents
-
-- [Install](#-install)
-- [The SDD workflow](#-the-sdd-workflow)
-- [Quality-of-life extensions](#-quality-of-life-extensions)
-- [Commands](#-commands)
-- [Environment variables](#-environment-variables)
-- [Files it reads & writes](#-files-it-reads--writes)
-- [Relationship to `zero`](#-relationship-to-zero)
-- [Development](#-development)
-
----
+zero-pi is an installable **[pi](https://pi.dev)** package that adds a
+disciplined spec-driven development pipeline — plus a handful of quality-of-life
+extensions — **without modifying pi**. Same idea as `gentle-pi`: pi stays
+untouched; zero-pi is a package it loads.
 
 ## 📦 Install
 
 ```
 pi install npm:@gonrocca/zero-pi
+pi install npm:pi-subagents      # required — the pipeline delegates to sub-agents
 ```
 
-That registers zero-pi in `~/.pi/agent/settings.json` and makes its prompts,
-skills, theme, and extensions available in every pi session.
-
-| Requirement | Detail |
-| ----------- | ------ |
-| `pi-subagents` | **Required** — the SDD pipeline delegates each phase to a sub-agent. Install with `pi install npm:pi-subagents`. |
-| Node | ≥ 20.6 — pi loads the TypeScript extensions directly. |
-| After upgrade | Restart pi for the new version to take effect. |
-
-Remove it with `pi remove npm:@gonrocca/zero-pi`.
-
----
+Needs Node ≥ 20.6. Restart pi after an upgrade.
 
-## 🛠 The SDD workflow
+## 🛠 `/forge` — the SDD pipeline
 
-### `/forge` — the four-phase pipeline
-
-A spec-driven development run, driven through four phases in order:
+The core of zero-pi. Run **`/forge <feature>`** and the orchestrator drives the
+work through four phases, each delegated to its own sub-agent:
 
 | Phase | Does |
 | ----- | ---- |
 | **explore** | Investigate the codebase read-only; produce findings. |
 | **plan** | Write requirements, design, and an ordered task list. |
 | **build** | Implement the plan. |
-| **veredicto** | Review the build adversarially and record a verdict. |
-
-Start it with `/forge <feature>`. The orchestrator drives phase order and
-enforces a hard build/veredicto iteration cap — a `corregir` verdict re-runs
-`build`, a `replantear` re-runs `plan`, and when the cap is reached without a
-`pasa` the run stops and reports the result as **not verified**.
-`/forge --continue [slug]` resumes an interrupted run from its `.sdd/<slug>/`
-artifacts.
-
-A run can also start from natural language: describe the work and signal SDD
-intent — "hacelo con sdd", "usá el pipeline" — and the `sdd-routing` skill
-routes it into `/forge`. It triggers only on a clear signal phrase; `/forge`
-stays the primary, explicit entry point.
-
-### Language & output
-
-A `/forge` run reads as a short, calm progress stream, in Spanish:
-
-- **Language Boundary** — every user-facing message is in Spanish (Rioplatense
-  voseo); sub-agent briefs stay in English for token efficiency; identifiers
-  (verdicts, slugs, paths, model ids, commands) are kept verbatim.
-- **Output Contract** — each phase reports a bounded summary
-  (`Estado` / `Resumen` / `Artefactos` / `Siguiente`), never free-form prose.
-  No raw tool output, file dumps, sub-agent listings, or triple-backtick code
-  fences reach the chat. The phase-start line names the model and provider the
-  phase runs on plus a brief gloss of what it does — so a slow phase reads as
-  working, not frozen. The run ends stating `verificado` or `no verificado`.
-
-### Review Workload Forecast
-
-The `plan` phase keeps tasks reviewable. Every planned task carries a
-`review: ~N changed lines` estimate, and `tasks.md` gains a `## Review Workload`
-section with a bold run total. Tasks are sized against a fixed budget of
-**400 changed lines per task** (borrowed from gentle-ai). A task over budget is
-split; one that genuinely cannot be split stays whole and is recorded as an
-over-budget exception with a reason.
-
-### SDD sub-agents — `sdd-agents.ts`
-
-`pi-subagents` discovers agents from `~/.pi/agent/agents/**/*.md`, but a
-`pi install` ships only the phase *prompts*. This extension closes the gap: on
-every load it generates the four `zero-<phase>` agent files under
-`~/.pi/agent/agents/zero/` from the package's phase prompts and the per-phase
-models in `~/.pi/zero.json`, so they stay in sync with the prompts and with
-`/zero-models`.
-
-### Per-phase models — `/zero-models`
-
-A real pi command — a code handler, not an LLM prompt — for the SDD models. Run
-it with no argument for the **provider-aware** interactive picker
-(**phase → provider → model**, sourced from pi's model registry), or set one
-directly:
-
-```
-/zero-models                          interactive picker
-/zero-models build=claude-opus-4-7     set one phase
-/zero-models build=codex/gpt-5-codex   set one phase with an explicit provider
-```
-
-It reads and writes `~/.pi/zero.json` — a `models` map and a parallel
-`providers` map. The orchestrator picks the change up on the next `/forge` run.
-
-### Run memory — Cortex
-
-Every run reads from and writes to Cortex, the persistent-memory MCP server.
-Before exploring, the orchestrator recalls prior `zero-run/*` traces; when the
-run ends it saves a run-trace — verdict, correction rounds, gotchas — under
-`topic_key: zero-run/<slug>`. The next run starts from what the last one
-learned. With `--no-mcp`, or when Cortex is unreachable, the loop degrades
-silently and never blocks a run.
-
-### Canonical specs & `/zero-sync`
-
-zero keeps a **canonical, project-wide spec store** that accumulates accepted
-requirements across runs, so each `/forge` run builds on the last.
-
-- **The store** — `.sdd/specs/requirements.md`: a `# ` title followed by
-  `### REQ: <name>` blocks. The `plan` phase reads it as the baseline.
-- **The plan artifacts** — every run's `plan` phase writes `proposal.md`,
-  `spec.md` (the **delta**: `## ADDED` / `## MODIFIED` / `## REMOVED`),
-  `design.md`, and `tasks.md` into `.sdd/<slug>/`.
-- **`/zero-sync <slug>`** — a deterministic, unit-tested merge that folds the
-  delta into the store atomically. Guardrails reject a bad delta before
-  anything is written. The orchestrator invokes it automatically after a `pasa`
-  verdict — never on `corregir`, `replantear`, or a cap-reached run.
-- **The archive** — `.sdd/archive/<YYYY-MM-DD>-<slug>/`: an append-only audit
-  trail of every sync.
-
-### Adaptive model profiles — autotune
-
-zero learns which model fits each SDD phase from your own run history.
-
-- **The metrics log** — `~/.pi/zero-runs.jsonl`: every completed run appends one
-  JSON line (slug, per-phase models, verdict, round count, per-round verdict
-  sequence). Append-only.
-- **Phase attribution** — a `corregir` round blames `build`, a `replantear`
-  blames `plan`. Autotune upgrades **only the phase at fault**, one tier at a
-  time. `explore` and `veredicto` are never tuned.
-- **Cross-machine sync** — each run pushes its metrics to Cortex; `/forge`
-  pulls the shared log back, so autotune sees runs from other machines too.
+| **veredicto** | Review it adversarially and record a verdict. |
 
-The `autotune` mode in `~/.pi/zero.json` controls what happens:
+The verdict is `pasa` (done), `corregir` (re-run build), or `replantear`
+(re-run plan). A hard iteration cap bounds the build↔veredicto loop — reached
+without a `pasa`, the run stops and is reported as **not verified**.
+`/forge --continue [slug]` resumes an interrupted run.
 
-| Mode | Behaviour |
-| ---- | --------- |
-| `auto` _(default)_ | Applies the adjustment to `~/.pi/zero.json` and notifies you what changed. |
-| `ask` | Records the recommendation; you apply it from `/zero-models`. |
-| `off` | Records run metrics, but never changes or recommends anything. |
+The run speaks **Spanish**, in a bounded, low-noise format — one short summary
+per phase, naming the model that phase runs on, no raw tool output. Or just
+describe the work and say "hacelo con sdd": the `sdd-routing` skill routes it
+into `/forge` for you.
 
-Set it with `/zero-models autotune=<auto\|ask\|off>`. In `ask` mode a waiting
-recommendation shows as a leading `★ aplicar sugerencia` entry in `/zero-models`.
+## ✨ What else it adds
 
-### Skill auto-learning — `skill-loop`
-
-Gives the agent a closed learning loop — distill a reusable skill from a
-substantial task, store it, surface relevant skills on a new task, refine an
-existing skill instead of duplicating it — so solutions are reused, not
-re-derived.
-
----
-
-## ✨ Quality-of-life extensions
-
-### Provider guard — `provider-guard.ts`
-
-The `anthropic` provider runs two ways: a Claude Pro/Max **subscription** login
-(OAuth, via `/login` — `pi-claude-oauth-adapter` smooths this path) or an **API
-key**, which bills per token from your metered extra-usage pool. Same provider
-id, different billing. The guard watches model switches and reads pi's auth mode
-(`modelRegistry.isUsingOAuth`): when a model runs on `anthropic` with an API key
-it emits a single non-blocking warning suggesting `/login`. On OAuth, or on any
-other provider, it stays silent.
-
-### Startup banner — `startup-banner.ts`
-
-Renders the `ZERO` wordmark as ASCII-safe Tetris cells in pure ANSI 24-bit
-colour, no runtime dependencies. The cells assemble from the bottom up, settle,
-then run a short **sparkle pass** — a few cells glint bright for about a second.
-The render runs synchronously before pi draws its UI.
-
-| `ZERO_BANNER` | Effect |
-| ------------- | ------ |
-| _(unset)_ / `shimmer` | Animated assembly + sparkle, then settle (default) |
-| `static` | Completed banner only, no animation |
-| `off` | Render nothing |
-
-Colour is skipped automatically when `NO_COLOR` is set or output is not a TTY.
-
-### Working-phrase ticker — `working-phrases.ts`
-
-Replaces pi's static `Working...` line with a context-aware, rotating Spanish
-phrase — tool-specific while a tool runs (`Leyendo archivos…`), the SDD phase
-while a sub-agent runs (`Planeando la solución…`), playful verbs while the model
-thinks (`Maquinando…`) — plus a theme-tinted braille spinner.
-
-### Conversation resume — `conversation-resume.ts`
-
-When pi exits normally, writes a local handoff note at `.pi/zero-resume.md` —
-the exact restore command for the persisted session plus a concise conversation
-tail. Generate it any time with `/zero-resume`. zero-pi creates `.pi/.gitignore`
-so conversation context is never committed. Set `ZERO_RESUME=off` to disable the
-automatic write.
-
-### Windows process-tree kill — `win-tree-kill.ts`
-
-On Windows, `kill()` terminates only the target process — so aborting a turn can
-leave an orphaned `claude` process streaming (Esc appears to do nothing). This
-extension patches `child_process.spawn` so every later subprocess tree-kills via
-`taskkill /T /F`. No-op on non-Windows. **Keep it enabled on Windows.**
-
-### ZERO terminal theme — `themes/zero-sdd.json`
-
-A dark, high-contrast pi theme with cyan, amber, mint, rose, and violet accents
-tuned for SDD work. Select it from `/settings`, or set `"theme": "zero-sdd"`.
-
----
-
-## ⌨️ Commands
-
-| Command | What it does |
+| Feature | What it does |
 | ------- | ------------ |
-| `/forge <feature>` | Run the four-phase SDD pipeline for a feature. |
-| `/forge --continue [slug]` | Resume an interrupted SDD run. |
-| `/zero-models [<phase>=[<provider>/]<model>]` | Show or set the per-phase SDD models. |
-| `/zero-models autotune=<auto\|ask\|off>` | Set the autotune mode. |
-| `/zero-sync <slug>` | Fold a run's delta `spec.md` into the canonical store. |
-| `/zero-resume` | Write `.pi/zero-resume.md` now. |
+| **`/zero-models`** | Pick the model + provider for each SDD phase — interactive or direct. |
+| **Autotune** | Learns which model fits each phase from your run history and re-tunes itself. |
+| **`/zero-sync`** | Folds each run's spec delta into a canonical, project-wide spec store. |
+| **Run memory** | Every run recalls and saves traces to Cortex, so runs learn from each other. |
+| **Provider guard** | Warns when the `anthropic` provider runs on a metered API key instead of your subscription. |
+| **Working-phrase ticker** | Swaps pi's `Working...` for a context-aware Spanish phrase + spinner. |
+| **Conversation resume** | Writes `.pi/zero-resume.md` on exit — the restore command + a conversation tail. |
+| **Windows tree-kill** | Aborting a turn kills the whole process tree — no orphaned `claude`. |
+| **Skill auto-learning** | Distills reusable skills from substantial tasks and surfaces them later. |
+| **`zero-sdd` theme** | A dark, high-contrast pi theme tuned for SDD work. |
 
-## 🔧 Environment variables
+## ⌨️ Commands
 
-| Variable | Effect |
-| -------- | ------ |
-| `ZERO_BANNER` | `shimmer` (default) · `static` · `off` — startup-banner mode. |
-| `ZERO_RESUME` | `off` / `0` disables the automatic conversation-resume write. |
-| `NO_COLOR` | Standard — disables banner colour. |
+| Command | Does |
+| ------- | ---- |
+| `/forge <feature>` | Run the SDD pipeline — `--continue [slug]` resumes. |
+| `/zero-models [<phase>=[<provider>/]<model>]` | Show or set per-phase models — `autotune=auto\|ask\|off`. |
+| `/zero-sync <slug>` | Fold a run's delta into the canonical spec store. |
+| `/zero-resume` | Write the session handoff note now. |
 
-## 📂 Files it reads & writes
+## 🔧 Configuration
 
-| Path | Role |
-| ---- | ---- |
-| `~/.pi/zero.json` | Per-phase `models` / `providers` and the `autotune` mode. |
-| `~/.pi/zero-runs.jsonl` | Append-only run-metrics log autotune learns from. |
-| `~/.pi/agent/agents/zero/` | Generated `zero-<phase>` sub-agent files. |
-| `.sdd/<slug>/` | Per-run plan artifacts. |
-| `.sdd/specs/requirements.md` | The canonical, project-wide spec store. |
-| `.sdd/archive/` | Append-only audit trail of every `/zero-sync`. |
-| `.pi/zero-resume.md` | Local session handoff note. |
+zero-pi keeps its state in `~/.pi/zero.json` (per-phase models + autotune mode)
+and `~/.pi/zero-runs.jsonl` (the run-metrics log); per-project artifacts live
+under `.sdd/`. Set `ZERO_RESUME=off` to disable the conversation-resume note.
 
 ## 🔗 Relationship to `zero`
 
-`zero-pi` is the pi-specific layer of the **zero** integrator. The `zero` CLI
-installs this layer onto pi (bootstrapping pi.dev itself when missing) and
-writes the per-phase model configuration. You can also install `zero-pi`
-directly with `pi install npm:@gonrocca/zero-pi` if you only want the pi layer.
+zero-pi is the pi layer of the **zero** integrator. The `zero` CLI installs it
+onto pi and writes the per-phase model config; you can also install zero-pi on
+its own with the command above.
 
-## 🧪 Development
+## Development
 
 Dependency-free, no build step — pi loads the TypeScript extensions directly.
-Run the test suite with:
+Run the test suite with `npm test`.
 
-```
-npm test
-```
-
----
+## License
 
-<div align="center">
-
-MIT © Gonzalo Rocca
-
-</div>
+MIT © Gonzalo Rocca · [github.com/gonzalonicolasr/zero-pi](https://github.com/gonzalonicolasr/zero-pi)

package/extensions/autotune-extension.ts

@@ -15,8 +15,8 @@
 //
 // All decisions live in `autotune.ts`; this file only reads files, calls those
 // functions, and applies/notifies. The whole handler is wrapped in a swallowing
-// `try/catch` — exactly like `startup-banner.ts`, a failure must never break a
-// pi session. The package stays dependency-free: `node:fs`/`node:os`/`node:path`
+// `try/catch` — a failure must never break a pi session. The package stays
+// dependency-free: `node:fs`/`node:os`/`node:path`
 // only, plus minimal local interfaces for the pi API.
 
 import { readFileSync, writeFileSync } from "node:fs";

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@gonrocca/zero-pi",
-  "version": "0.1.26",
-  "description": "zero-pi — an installable layer for pi (pi.dev): the zero spec-driven development workflow, skill auto-learning, and an animated ZERO startup banner. Adds capability to pi without modifying pi.",
+  "version": "0.1.28",
+  "description": "zero-pi — an installable layer for pi (pi.dev): the zero spec-driven development workflow, per-phase model autotune, and skill auto-learning. Adds capability to pi without modifying pi.",
   "type": "module",
   "keywords": [
     "pi",
@@ -23,7 +23,6 @@
       "./themes"
     ],
     "extensions": [
-      "./extensions/startup-banner.ts",
       "./extensions/working-phrases.ts",
       "./extensions/win-tree-kill.ts",
       "./extensions/sdd-agents.ts",
@@ -38,7 +37,6 @@
     "prompts",
     "skills",
     "themes",
-    "extensions/startup-banner.ts",
     "extensions/working-phrases.ts",
     "extensions/win-tree-kill.ts",
     "extensions/sdd-agents.ts",

package/extensions/startup-banner.ts

@@ -1,280 +0,0 @@
-// zero-pi - animated startup banner.
-//
-// A pi extension that renders the ZERO wordmark as ASCII-safe Tetris cells.
-// The animated mode progressively assembles the wordmark from the bottom up,
-// then settles into the complete banner. The extension stays dependency-free
-// and keeps the historical ZERO_BANNER controls.
-
-type RGB = [number, number, number];
-
-const COLORS: Record<string, RGB> = {
-  cyan: [80, 210, 255],
-  blue: [116, 151, 255],
-  mint: [79, 221, 171],
-  amber: [238, 190, 92],
-  rose: [255, 106, 122],
-  violet: [175, 138, 255],
-  peak: [255, 245, 218],
-};
-
-/** Number of rows in every glyph. */
-const ROWS = 6;
-
-// Five-cell-wide glyphs. Non-space characters become visible Tetris cells.
-const FONT: Record<string, string[]> = {
-  Z: ["ZZZZZ", "   ZZ", "  ZZ ", " ZZ  ", "ZZ   ", "ZZZZZ"],
-  E: ["EEEEE", "EE   ", "EEEE ", "EE   ", "EE   ", "EEEEE"],
-  R: ["RRRR ", "RR RR", "RRRR ", "RR RR", "RR  R", "RR  R"],
-  O: [" OOO ", "OO OO", "OO OO", "OO OO", "OO OO", " OOO "],
-  P: ["PPPP ", "PP PP", "PP PP", "PPPP ", "PP   ", "PP   "],
-  I: ["IIIII", "  II ", "  II ", "  II ", "  II ", "IIIII"],
-  "-": ["     ", "     ", "-----", "     ", "     ", "     "],
-  " ": ["     ", "     ", "     ", "     ", "     ", "     "],
-};
-
-const PIECE_COLORS: Record<string, RGB> = {
-  Z: COLORS.cyan,
-  E: COLORS.amber,
-  R: COLORS.mint,
-  O: COLORS.rose,
-  P: COLORS.violet,
-  I: COLORS.blue,
-  "-": COLORS.amber,
-};
-
-interface Matrix {
-  rows: string[];
-  width: number;
-  totalCells: number;
-  ranks: Map<string, number>;
-}
-
-function glyphFor(ch: string): string[] {
-  return FONT[ch.toUpperCase()] ?? FONT[" "];
-}
-
-function matrixForText(text: string): Matrix {
-  const rows = Array.from({ length: ROWS }, () => "");
-  for (const [index, raw] of Array.from(text).entries()) {
-    const glyph = glyphFor(raw);
-    for (let r = 0; r < ROWS; r++) {
-      rows[r] += (index === 0 ? "" : " ") + glyph[r];
-    }
-  }
-
-  const cells: Array<{ row: number; col: number }> = [];
-  for (let row = 0; row < ROWS; row++) {
-    for (let col = 0; col < rows[row].length; col++) {
-      if (rows[row][col] !== " ") cells.push({ row, col });
-    }
-  }
-
-  // Tetris reads as a pile building upward: bottom rows settle first.
-  cells.sort((a, b) => b.row - a.row || a.col - b.col);
-
-  const ranks = new Map<string, number>();
-  for (const [rank, cell] of cells.entries()) {
-    ranks.set(`${cell.row}:${cell.col}`, rank);
-  }
-
-  return {
-    rows,
-    width: rows[0]?.length ?? 0,
-    totalCells: cells.length,
-    ranks,
-  };
-}
-
-/** Lay a word out as six rows of ASCII-safe Tetris cells. */
-export function bannerLines(text = "ZERO"): string[] {
-  return matrixForText(text).rows.map((row) =>
-    Array.from(row)
-      .map((cell) => (cell === " " ? "  " : "[]"))
-      .join(""),
-  );
-}
-
-function lerp(a: number, b: number, t: number): number {
-  return a + (b - a) * t;
-}
-
-function lerpColor(c1: RGB, c2: RGB, t: number): RGB {
-  const k = Math.max(0, Math.min(1, t));
-  return [
-    Math.round(lerp(c1[0], c2[0], k)),
-    Math.round(lerp(c1[1], c2[1], k)),
-    Math.round(lerp(c1[2], c2[2], k)),
-  ];
-}
-
-function ansiFg([r, g, b]: RGB, text: string): string {
-  return `\x1b[38;2;${r};${g};${b}m${text}\x1b[0m`;
-}
-
-function colorForPiece(piece: string, row: number, rank: number, active: boolean): RGB {
-  if (active) return COLORS.peak;
-  const base = PIECE_COLORS[piece] ?? COLORS.blue;
-  const heightWarmth = (ROWS - 1 - row) / Math.max(1, ROWS - 1);
-  const rankPulse = (rank % 7) / 18;
-  return lerpColor(base, COLORS.peak, heightWarmth * 0.18 + rankPulse);
-}
-
-function paintMatrixLine(
-  matrix: Matrix,
-  row: number,
-  visibleCells: number,
-  sparkles?: ReadonlySet<string>,
-): string {
-  let out = "";
-  const line = matrix.rows[row] ?? "";
-  for (let col = 0; col < matrix.width; col++) {
-    const piece = line[col] ?? " ";
-    if (piece === " ") {
-      out += "  ";
-      continue;
-    }
-    const key = `${row}:${col}`;
-    const rank = matrix.ranks.get(key) ?? Number.POSITIVE_INFINITY;
-    if (rank >= visibleCells) {
-      out += "  ";
-      continue;
-    }
-    // A cell glints when it is the assembly's leading cell or when this
-    // sparkle frame picked it.
-    const glint = rank === visibleCells - 1 || (sparkles?.has(key) ?? false);
-    out += ansiFg(colorForPiece(piece, row, rank, glint), "[]");
-  }
-  return out;
-}
-
-/** Pick a handful of distinct settled cells to glint for one sparkle frame. */
-function pickSparkles(matrix: Matrix, count: number, rand: () => number): Set<string> {
-  const keys = Array.from(matrix.ranks.keys());
-  const chosen = new Set<string>();
-  const target = Math.min(Math.max(0, count), keys.length);
-  for (let guard = 0; chosen.size < target && guard < target * 8; guard++) {
-    chosen.add(keys[Math.floor(rand() * keys.length)]);
-  }
-  return chosen;
-}
-
-interface OutStream {
-  write(chunk: string): unknown;
-  isTTY?: boolean;
-}
-
-/** Whether colour output is appropriate for the given stream. */
-function shouldColor(stream: OutStream): boolean {
-  if (process.env.NO_COLOR) return false;
-  if (process.env.FORCE_COLOR) return true;
-  return Boolean(stream && stream.isTTY);
-}
-
-/** The three banner modes, resolved from the ZERO_BANNER environment variable. */
-export type BannerMode = "off" | "static" | "shimmer";
-
-/** Resolve the banner mode from an environment-variable value. */
-export function resolveBannerMode(raw: string | undefined): BannerMode {
-  const value = (raw ?? "").trim().toLowerCase();
-  if (value === "off" || value === "0" || value === "false" || value === "none") return "off";
-  if (value === "static" || value === "plain" || value === "no-animate") return "static";
-  return "shimmer";
-}
-
-// Atomics.wait gives us a synchronous sleep without adding a dependency. The
-// banner renders before Pi's TUI takes over, so blocking briefly is intentional.
-const SLEEP_SLOT = new Int32Array(new SharedArrayBuffer(4));
-function sleepSync(ms: number): void {
-  if (ms > 0) Atomics.wait(SLEEP_SLOT, 0, 0, ms);
-}
-
-function easeOutCubic(t: number): number {
-  return 1 - Math.pow(1 - t, 3);
-}
-
-/** Options for {@link renderBanner}. */
-export interface RenderOptions {
-  mode?: BannerMode;
-  text?: string;
-  frames?: number;
-  frameMs?: number;
-  /** Number of post-settle sparkle frames (shimmer mode). `0` disables it. */
-  sparkleFrames?: number;
-  /** Delay between sparkle frames, in milliseconds. */
-  sparkleMs?: number;
-  stream?: OutStream;
-}
-
-/**
- * Render the ZERO banner synchronously.
- *
- * On a non-colour stream the banner is printed plain. Otherwise the animated
- * mode assembles cells frame by frame, then settles on the completed wordmark.
- */
-export function renderBanner(options: RenderOptions = {}): void {
-  const mode = options.mode ?? resolveBannerMode(process.env.ZERO_BANNER);
-  if (mode === "off") return;
-
-  const stream: OutStream = options.stream ?? process.stdout;
-  const matrix = matrixForText(options.text ?? "ZERO");
-
-  if (!shouldColor(stream)) {
-    stream.write("\n" + bannerLines(options.text ?? "ZERO").join("\n") + "\n\n");
-    return;
-  }
-
-  stream.write("\n" + Array.from({ length: ROWS }, () => "").join("\n") + "\n");
-
-  // Repaint the six rows in place; optionally with this frame's sparkle set.
-  const paintRows = (sparkles?: ReadonlySet<string>): void => {
-    stream.write(`\x1b[${ROWS}A\r`);
-    for (let r = 0; r < ROWS; r++) {
-      stream.write("\x1b[2K" + paintMatrixLine(matrix, r, matrix.totalCells, sparkles) + "\n");
-    }
-  };
-
-  if (mode === "shimmer") {
-    const frames = Math.max(2, options.frames ?? 42);
-    const frameMs = Math.max(1, options.frameMs ?? 18);
-    for (let f = 0; f < frames; f++) {
-      const t = easeOutCubic(f / (frames - 1));
-      const visibleCells = Math.max(1, Math.ceil(matrix.totalCells * t));
-      stream.write(`\x1b[${ROWS}A\r`);
-      for (let r = 0; r < ROWS; r++) {
-        stream.write("\x1b[2K" + paintMatrixLine(matrix, r, visibleCells) + "\n");
-      }
-      sleepSync(frameMs);
-    }
-  }
-
-  // Settle on the completed wordmark.
-  paintRows();
-
-  // Sparkle pass — a few settled cells glint bright each frame, then a clean
-  // final settle. Shimmer only; `sparkleFrames: 0` disables it.
-  if (mode === "shimmer") {
-    const sparkleFrames = Math.max(0, options.sparkleFrames ?? 22);
-    const sparkleMs = Math.max(1, options.sparkleMs ?? 36);
-    for (let f = 0; f < sparkleFrames; f++) {
-      paintRows(pickSparkles(matrix, 3 + (f % 4), Math.random));
-      sleepSync(sparkleMs);
-    }
-    if (sparkleFrames > 0) paintRows();
-  }
-
-  stream.write("\n");
-}
-
-/**
- * The pi extension entry point.
- *
- * The pi argument is accepted for API compatibility. The banner is rendered
- * defensively: visual sugar should never break an interactive session.
- */
-export default function register(_pi?: unknown): void {
-  try {
-    renderBanner();
-  } catch {
-    // A banner failure must never break a pi session.
-  }
-}