@rosetears/aili-pi 0.1.0 → 0.1.3

package/README.md

@@ -8,7 +8,7 @@
 - Node.js 22.19.0 or newer
 - Pi 0.81.1 or newer with the Package and Extension APIs used by this release
 
-macOS and native Windows are not supported by this bootstrap and fail before installation mutation. Theme, TUI, and font resources are deferred to a separate change.
+macOS and native Windows are not supported by this bootstrap and fail before installation mutation.
 
 ## Install
 
@@ -35,6 +35,8 @@ pi update npm:@rosetears/aili-pi
 pi remove npm:@rosetears/aili-pi
 ```
 
+During a Pi-managed npm install or update, the package replaces only existing same-name directories in `~/.agents/skills/` with its pinned AILI skill snapshot. It does not create package-only skills, alter differently named skills, retain backups, or load its embedded AILI snapshot as a second Pi skill source. The package remains installed for its Extensions, prompts, theme, and bundled `librarian` skill.
+
 Removal is destructive for this Package. It does not remove Pi and must not be presented as rollback when replacing a pre-existing AILI installation.
 
 ### Explicit global resources
@@ -45,7 +47,13 @@ The package does not write global AILI resources during extension load. After re
 /aili-install-global-resources
 ```
 
-That command creates or updates only the AILI marker block in `~/.pi/agent/APPEND_SYSTEM.md` and installs the 19 packaged profiles at `~/.pi/agent/agents/aili/`. It preserves unrelated prompt content, rejects malformed markers or an unowned profile collision, and reports stale profiles without pruning them.
+That command creates or updates only the AILI marker block in `~/.pi/agent/APPEND_SYSTEM.md` and installs the 19 packaged profiles at `~/.pi/agent/agents/aili/`. The marker block is a Pi-native governance derivation of the pinned `aili-workflows` global AGENTS template: it retains instruction precedence, untrusted-content handling, approval/evidence/verification discipline, bounded delegation, project-rule precedence, and user-language output, while excluding OpenCode-only control planes. It preserves unrelated prompt content, rejects malformed markers or an unowned profile collision, and reports stale profiles without pruning them.
+
+## Rem Cyberdeck
+
+The package supplies the `rem-cyberdeck` theme plus three additional Pi Extensions: a Rem header, matrix animation, and Zentui footer/editor surface. They are derived from `pi-sakura-cyberdeck` at revision `165a1f8011a12a58a6409b56b8a6c0416cd9b589` under MIT; see `THIRD_PARTY_NOTICES.md` and `notices/pi-sakura-cyberdeck-NOTICE.txt`.
+
+Zentui enables its experimental fixed-bottom editor by default when the installed Pi TUI exposes the required private layout capabilities. If capability detection or installation fails, it keeps Pi's native editor and emits a warning. The feature uses the terminal alternate screen; its default mouse scrolling can interfere with terminal text selection and tmux scrollback. Use Zentui's `/zentui` settings to disable the fixed editor or mouse scrolling.
 
 ## Commands and modes
 
@@ -63,7 +71,7 @@ That command creates or updates only the AILI marker block in `~/.pi/agent/APPEN
 - `pi-web-access@0.13.0` provides its complete upstream web-search, content-fetch, curator, clone/PDF/video, and bundled-skill surface. Its provider fallback, network traffic, config/credential paths, clone cache, temporary curator service, downloads, and optional browser-cookie access are upstream behavior; inspect its tool requests and configuration before use.
 - `pi-quota-status@0.3.0` is enabled by default. It may maintain `~/.pi/agent/pi-quota-status/state.json`; `/quota config` creates its configuration template.
 - `pi-permission-modes@2.2.0` provides the permission UI and sandbox degradation behavior above. AILI does not retain `/aili-mode` or `Ctrl+Shift+Alt+A` as competing controls.
-- `@agwab/pi-subagent@0.4.8` owns child spawn, cancellation, JSONL handling, and artifacts. AILI adds only role/tool/path policy projection, a two-child ceiling, and structured-result normalization. AILI children do not expose resume, worktree, background, recursive dispatch, or automatic retry.
+- `@agwab/pi-subagent@0.4.8` owns the generic `subagent` tool, child spawn, cancellation, durable run/artifact lifecycle, bounded parallel fan-out, async actions, worktrees, external `cwd`, and sandbox options. The 19 `aili.<role>` profiles are optional named agents; generic or agentless runs do not use an AILI-only result schema. AILI injects an immutable credential-path guard; child Pi processes load the ambient AILI `pi-permission-modes` registration exactly once. The upstream runner excludes recursive `subagent` exposure inside workers.
 
 ## Optional capability packs
 
@@ -78,13 +86,14 @@ When unavailable, runtime and doctor output use explicit `SKIP`/`WARN` results a
 
 ## Security boundary
 
-AILI adds role/tool/path projection and structured-result redaction around the native integrations. Vendor permission and sandbox behavior remains vendor-owned. Neither AILI nor Pi provides a universal OS sandbox: trusted extensions, user-authority processes, ambient network access, and filesystem races remain in the user trust domain. Inspect exact approval targets and do not put credentials in task text.
+AILI injects a non-removable guard that denies standard Pi file-tool and parsed-bash access to credential, authentication, and private-key paths, including from an external `cwd`, a YOLO permission mode, or a caller-supplied child extension list. Child Pi processes load the ambient AILI `pi-permission-modes` registration exactly once, so vendor permission prompts and sandbox behavior remain active; headless confirmation requests fail closed. The guard does not make arbitrary third-party extension code safe: extensions remain trusted code and may have direct process authority. Neither AILI nor Pi provides a universal OS sandbox or containment: trusted extensions, user-authority processes, ambient network access, and filesystem races remain in the user trust domain. Inspect exact approval targets and do not put credentials in task text.
 
-Child roles are fresh, single-use processes with no resume, chaining, background continuation, recursive delegation, or automatic retry. At most two child processes run concurrently. Output and diagnostics are bounded and redacted; provider/model behavior still depends on the configured Pi environment.
+Use `subagent` lifecycle actions (`status`, `logs`, `wait`, `interrupt`, `mark-background`, and `reconcile`) to inspect durable async work. Upstream fan-out is version-bounded rather than capped by AILI at two; background completion is not evidence until inspected. Provider/model behavior still depends on the configured Pi environment.
 
 ## Provenance and reproducibility
 
 - `upstream/aili-workflows.lock.json` pins the exact canonical 64-skill/471-file snapshot.
+- `upstream/opencode-global-agents.lock.json` pins the global AGENTS source revision/hash and documents its Pi-native derivation.
 - `manifests/skill-compatibility.json` records one compatibility state per skill.
 - `manifests/roles.json` records the 19 generated Pi role profiles.
 - `manifests/provenance.json`, `manifests/sbom.json`, and `THIRD_PARTY_NOTICES.md` record adapted/reference sources and the exact npm lock inventory.
@@ -104,6 +113,6 @@ npm run validate:release
 - **Doctor is non-pass:** inspect the exact `ERROR`, `WARN`, `SKIP`, or `UNVERIFIED` component. Missing optional packs are not core execution success.
 - **Permission shortcut does nothing:** use `/perm`; terminal multiplexers may consume `Alt+M`.
 - **Global resources are non-pass:** run `/aili-install-global-resources` only after reviewing the exact `~/.pi/agent/` targets. A malformed marker or an unowned role collision intentionally leaves files unchanged.
-- **Offline use:** the installed Package embeds the pinned skills and does not fetch `aili-workflows` at runtime. First-time Pi/package installation still requires the relevant package sources.
+- **Offline use:** the installed Package embeds the pinned skills and does not fetch `aili-workflows` at runtime. Its Pi-managed npm lifecycle synchronizes only pre-existing same-name global skills from that embedded fixed snapshot. First-time Pi/package installation still requires the relevant package sources.
 
 See `THIRD_PARTY_NOTICES.md` for source and license details. No official endorsement by the Pi maintainers is claimed.

package/THIRD_PARTY_NOTICES.md

@@ -9,9 +9,9 @@ This distribution is MIT-licensed. The following adapted sources and locked deve
 - Revision: 7eb35f357ad489f5841ee10dac1e44549c1bdb76
 - Version: 0.2.7
 - License: MIT
-- Source files: upstream/aili-workflows.lock.json#files (471 exact skill files), manifests/roles.json#records[].sourcePath (19 exact role source files)
+- Source files: upstream/aili-workflows.lock.json#files (471 exact skill files), manifests/roles.json#records[].sourcePath (19 exact role source files), upstream/opencode-global-agents.lock.json (pinned source template revision/hash)
 - Reused symbols/patterns: 64 canonical skill bodies and owned assets, 19 child-role prompt bodies
-- Local changes: skills/** is an exact byte-for-byte snapshot with no semantic overlay; role prompts are generated as Pi frontmatter with explicit tool/capability ceilings and structured output
+- Local changes: skills/** is an exact byte-for-byte snapshot with no semantic overlay; role prompts are generated as Pi frontmatter with explicit tool/capability ceilings and structured output; templates/APPEND_SYSTEM.md is a Pi-native governance derivation of the pinned global AGENTS template, with OpenCode-only control planes excluded
 
 ## @agwab/pi-subagent
 
@@ -22,7 +22,7 @@ This distribution is MIT-licensed. The following adapted sources and locked deve
 - License: MIT
 - Source files: src/api.ts, src/runners/headless-model.ts, src/artifacts/result.ts
 - Reused symbols/patterns: runSubagent API, headless lifecycle, artifact envelope
-- Local changes: AILI calls the pinned API through a thin role/path/tool policy adapter; no upstream source is copied
+- Local changes: AILI registers the full pinned upstream subagent tool schema, injects a non-removable credential guard, and relies on the ambient AILI pi-permission-modes registration exactly once in each child; no upstream source is copied
 
 ## pi-permission-modes
 
@@ -57,6 +57,17 @@ This distribution is MIT-licensed. The following adapted sources and locked deve
 - Reused symbols/patterns: web_search, fetch_content, get_search_content, curator and bundled librarian skill
 - Local changes: AILI initializes the complete pinned upstream surface through its sole Extension entry; no upstream source is copied
 
+## pi-sakura-cyberdeck
+
+- Status: adapted
+- Source: https://github.com/beautifulrem/pi-sakura-cyberdeck.git
+- Revision: 165a1f8011a12a58a6409b56b8a6c0416cd9b589
+- Version: undefined
+- License: MIT
+- Source files: extensions/header/index.ts, extensions/matrix/index.ts, extensions/zentui/**
+- Reused symbols/patterns: header, matrix animation, Zentui footer, fixed editor compositor
+- Local changes: registered as three additional Pi Package Extensions; header avatar loads the supplied Rem asset; Sakura palette values are replaced with the Rem palette; relative import specifiers and session lifecycle event are adapted for this package's NodeNext TypeScript contract
+
 ## npm dependency inventory
 
 The exact 350-entry package-lock inventory, versions, integrity values, dependency scope, and declared licenses is recorded in `manifests/sbom.json`.

package/extensions/header/index.ts

@@ -0,0 +1,92 @@
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+const RESET = "\x1b[0m";
+const BOLD = "\x1b[1m";
+
+type RGB = readonly [number, number, number];
+
+function rgb([r, g, b]: RGB, text: string, bold = false): string {
+  return `${bold ? BOLD : ""}\x1b[38;2;${r};${g};${b}m${text}${RESET}`;
+}
+
+function gradient(text: string, from: RGB, to: RGB, bold = false): string {
+  const chars = [...text];
+  const span = Math.max(1, chars.length - 1);
+  return chars.map((char, index) => {
+    if (char === " ") return char;
+    const t = index / span;
+    const color: RGB = [
+      Math.round(from[0] + (to[0] - from[0]) * t),
+      Math.round(from[1] + (to[1] - from[1]) * t),
+      Math.round(from[2] + (to[2] - from[2]) * t),
+    ];
+    return rgb(color, char, bold);
+  }).join("");
+}
+
+const ANIME_ART = readFileSync(fileURLToPath(new URL("../../src/runtime/rem-head.txt", import.meta.url)), "utf8").trimEnd().split("\n") as readonly string[];
+
+function getAvailableRows(tui: unknown): number {
+  try {
+    const terminal = (tui as { terminal?: { rows?: unknown } }).terminal;
+    const rows = terminal?.rows;
+    return typeof rows === "number" && Number.isFinite(rows) ? Math.max(0, Math.floor(rows)) : 0;
+  } catch {
+    return 0;
+  }
+}
+
+function renderHeader(width: number, availableRows = 0): string[] {
+  if (width <= 0) return [];
+
+  const sakura: RGB = [136, 184, 255];
+  const peach: RGB = [125, 228, 255];
+  const lavender: RGB = [188, 167, 255];
+  const sky: RGB = [214, 244, 255];
+  const telemetry = "◈  REM CYBERDECK  ◈";
+  const artWidth = Math.max(...ANIME_ART.map((line) => [...line].length));
+  const visibleArtWidth = Math.min(width, artWidth);
+  const artPad = " ".repeat(Math.max(0, Math.floor((width - visibleArtWidth) / 2) - 2));
+  // Keep the divider visually subordinate: inset it symmetrically from the artwork.
+  const railInset = visibleArtWidth >= 8 ? Math.max(2, Math.round(visibleArtWidth * 0.15)) : 0;
+  const railWidth = Math.max(1, visibleArtWidth - railInset * 2);
+  const rail = "━".repeat(railWidth);
+  const railPad = " ".repeat(Math.max(0, Math.min(width - railWidth, Math.floor((width - railWidth) / 2) + 1)));
+  const visibleTelemetry = [...telemetry].slice(0, width).join("");
+  const telemetryWidth = [...visibleTelemetry].length;
+  const telemetryPad = " ".repeat(Math.max(0, Math.min(width - telemetryWidth, Math.floor((width - telemetryWidth) / 2) + 1)));
+
+  const art = ANIME_ART.map((line) => {
+    const clipped = [...line].slice(0, visibleArtWidth).join("");
+    return `${artPad}${gradient(clipped, sakura, sky)}`;
+  });
+
+  const visualHeight = ANIME_ART.length + 3; // artwork + gap + divider + label
+  const extraTopPadding = Math.max(0, Math.floor((availableRows - visualHeight) / 2) - 1);
+
+  return [
+    ...Array(extraTopPadding).fill(""),
+    "",
+    ...art,
+    "",
+    `${railPad}${gradient(rail, sakura, sky)}`,
+    `${telemetryPad}${gradient(visibleTelemetry, lavender, peach, true)}`,
+    "",
+  ];
+}
+
+export default function sakuraCyberdeckHeader(pi: ExtensionAPI): void {
+  pi.on("session_start", (_event, ctx) => {
+    if (!ctx.hasUI) return;
+    ctx.ui.setHeader((tui) => ({
+      render: (width) => renderHeader(width, getAvailableRows(tui)),
+      invalidate() {},
+    }));
+  });
+
+  pi.on("session_shutdown", (_event, ctx) => {
+    if (ctx.hasUI) ctx.ui.setHeader(undefined);
+  });
+}

package/extensions/matrix/index.ts

@@ -0,0 +1,375 @@
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+const WIDGET_KEY = "sakura-matrix-engine";
+const CONFIG_PATH = join(homedir(), ".pi", "agent", "sakura-cyberdeck-matrix.json");
+const RESET = "\x1b[0m";
+const GLYPHS = [..."0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZｱｲｳｴｵｶｷｸｹｺｻｼｽｾｿﾀﾁﾂﾃﾄﾅﾆﾇﾈﾉﾊﾋﾌﾍﾎﾏﾐﾑﾒﾓﾗﾘﾙﾚﾛﾜﾝ"];
+// Matrix glyphs use foreground colors only. Blend trails into the user's
+// white terminal background to simulate transparency without terminal alpha.
+const BG: RGB = [255, 255, 255];
+const TEXT: RGB = [255, 255, 255];
+const CANDY: readonly RGB[] = [
+  [136, 184, 255], // sakura
+  [125, 228, 255], // sakura-iro
+  [188, 167, 255], // petal
+  [188, 167, 255], // lavender
+  [125, 228, 255], // sky
+  [140, 230, 194], // mint
+];
+const WORKING_INDICATOR = "◆";
+const PHASE_MESSAGES: Record<Phase, string> = {
+  thinking: "Weaving the next move…",
+  working: "Composing the response…",
+  tool: "Running tools…",
+};
+
+type RGB = readonly [number, number, number];
+type Phase = "thinking" | "working" | "tool";
+type Timer = ReturnType<typeof setTimeout>;
+
+interface MatrixConfig {
+  enabled: boolean;
+  fps: number;
+  density: number;
+  height: number;
+}
+
+interface Drop {
+  x: number;
+  offset: number;
+  speed: number;
+  length: number;
+  gap: number;
+  seed: number;
+  color: RGB;
+}
+
+const DEFAULT_CONFIG: MatrixConfig = {
+  enabled: true,
+  fps: 10,
+  density: 0.65,
+  height: 4,
+};
+
+function clamp(value: number, min: number, max: number): number {
+  return Math.min(max, Math.max(min, value));
+}
+
+function loadConfig(): MatrixConfig {
+  try {
+    if (!existsSync(CONFIG_PATH)) return { ...DEFAULT_CONFIG };
+    const parsed = JSON.parse(readFileSync(CONFIG_PATH, "utf8")) as Partial<MatrixConfig>;
+    return {
+      enabled: typeof parsed.enabled === "boolean" ? parsed.enabled : DEFAULT_CONFIG.enabled,
+      fps: clamp(Number(parsed.fps) || DEFAULT_CONFIG.fps, 8, 18),
+      density: clamp(Number(parsed.density) || DEFAULT_CONFIG.density, 0.45, 0.95),
+      height: clamp(Math.round(Number(parsed.height) || DEFAULT_CONFIG.height), 3, 6),
+    };
+  } catch {
+    return { ...DEFAULT_CONFIG };
+  }
+}
+
+function saveConfig(config: MatrixConfig): void {
+  writeFileSync(CONFIG_PATH, `${JSON.stringify(config, null, 2)}\n`, "utf8");
+}
+
+function mulberry32(seed: number): () => number {
+  let value = seed >>> 0;
+  return () => {
+    value += 0x6d2b79f5;
+    let n = value;
+    n = Math.imul(n ^ (n >>> 15), n | 1);
+    n ^= n + Math.imul(n ^ (n >>> 7), n | 61);
+    return ((n ^ (n >>> 14)) >>> 0) / 4294967296;
+  };
+}
+
+function mix(from: RGB, to: RGB, amount: number): RGB {
+  return [
+    Math.round(from[0] + (to[0] - from[0]) * amount),
+    Math.round(from[1] + (to[1] - from[1]) * amount),
+    Math.round(from[2] + (to[2] - from[2]) * amount),
+  ];
+}
+
+function colorize(char: string, color: RGB, bold = false): string {
+  return `\x1b[${bold ? "1;" : ""}38;2;${color[0]};${color[1]};${color[2]}m${char}${RESET}`;
+}
+
+function workingIndicatorFrame(): string {
+  return colorize(WORKING_INDICATOR, CANDY[0] ?? [136, 184, 255], true);
+}
+
+function stableGlyph(seed: number, row: number, timeSlice: number): string {
+  let hash = Math.imul(seed ^ (row + 17), 0x45d9f3b);
+  hash = Math.imul(hash ^ timeSlice, 0x45d9f3b);
+  hash ^= hash >>> 16;
+  return GLYPHS[Math.abs(hash) % GLYPHS.length] ?? "0";
+}
+
+export function createDrops(width: number, density: number, height: number): Drop[] {
+  const random = mulberry32((width * 2654435761) ^ 0x53414b55);
+  const columns = Array.from({ length: Math.ceil(width / 2) }, (_, index) => index * 2);
+  const active = columns.filter(() => random() < density);
+  const selected = active.length >= 8 ? active : columns.slice(0, Math.min(columns.length, 8));
+  return selected.slice(0, 96).map((x, index) => {
+    const length = 3 + Math.floor(random() * 5);
+    const gap = 1 + Math.floor(random() * 5);
+    const cycle = height + length + gap;
+    return {
+      x,
+      offset: random() * cycle,
+      speed: 5.5 + random() * 7.5,
+      length,
+      gap,
+      seed: Math.floor(random() * 0x7fffffff) ^ (index * 7919),
+      color: CANDY[index % CANDY.length] ?? [136, 184, 255],
+    };
+  });
+}
+
+export function renderSakuraMatrix(
+  width: number,
+  height: number,
+  elapsedSeconds: number,
+  phase: Phase,
+  drops: readonly Drop[],
+): string[] {
+  const safeWidth = Math.max(1, width);
+  const safeHeight = clamp(height, 3, 6);
+  const grid: string[][] = Array.from({ length: safeHeight }, () => Array(safeWidth).fill(" "));
+  const timeSlice = Math.floor(elapsedSeconds * 8);
+  const phaseSpeed = phase === "tool" ? 1.12 : phase === "thinking" ? 1.06 : 1;
+
+  for (const drop of drops) {
+    const cycle = safeHeight + drop.length + drop.gap;
+    const head = ((drop.offset + elapsedSeconds * drop.speed * phaseSpeed) % cycle) - drop.gap;
+    for (let trail = 0; trail < drop.length; trail++) {
+      const row = Math.floor(head - trail);
+      if (row < 0 || row >= safeHeight || drop.x >= safeWidth) continue;
+      const glyph = stableGlyph(drop.seed + trail * 97, row, timeSlice);
+      const color = trail === 0
+        ? mix(drop.color, TEXT, 0.58)
+        : trail === 1
+          ? drop.color
+          : mix(drop.color, BG, clamp((trail - 1) * 0.16, 0, 0.72));
+      const gridRow = grid[row];
+      if (gridRow) gridRow[drop.x] = colorize(glyph, color, trail <= 1);
+    }
+  }
+
+  return grid.map((row) => `${row.join("")}${RESET}`);
+}
+
+export default function sakuraMatrixExtension(pi: ExtensionAPI): void {
+  const config = loadConfig();
+  let activeContext: ExtensionContext | undefined;
+  let phase: Phase = "working";
+  let active = false;
+  let timer: Timer | undefined;
+  let startedAt = 0;
+  let nextDeadline = 0;
+  let lastHostUpdateAt = 0;
+  let frame = 0;
+  let generation = 0;
+  let requestRender: (() => void) | undefined;
+  let cachedKey = "";
+  let cachedLines: string[] = [];
+  const dropsByWidth = new Map<number, Drop[]>();
+
+  const invalidate = () => {
+    cachedKey = "";
+    cachedLines = [];
+  };
+
+  const component = {
+    render(width: number): string[] {
+      const safeWidth = Math.max(1, width);
+      const key = `${safeWidth}:${config.height}:${frame}:${phase}`;
+      if (key === cachedKey) return cachedLines;
+      let drops = dropsByWidth.get(safeWidth);
+      if (!drops) {
+        drops = createDrops(safeWidth, config.density, config.height);
+        if (dropsByWidth.size >= 4) {
+          dropsByWidth.delete(dropsByWidth.keys().next().value ?? safeWidth);
+        }
+        dropsByWidth.set(safeWidth, drops);
+      }
+      cachedLines = renderSakuraMatrix(
+        safeWidth,
+        config.height,
+        Math.max(0, performance.now() - startedAt) / 1000,
+        phase,
+        drops,
+      );
+      cachedKey = key;
+      return cachedLines;
+    },
+    invalidate(): void {
+      dropsByWidth.clear();
+      invalidate();
+    },
+  };
+
+  const clearTimer = () => {
+    if (timer) clearTimeout(timer);
+    timer = undefined;
+  };
+
+  const schedule = (token: number) => {
+    if (!active || token !== generation) return;
+    const frameMs = 1000 / config.fps;
+    const now = performance.now();
+    if (now - nextDeadline > frameMs * 3) nextDeadline = now;
+    nextDeadline += frameMs;
+    timer = setTimeout(() => {
+      if (!active || token !== generation) return;
+      frame += 1;
+      invalidate();
+      // Streaming and tool updates already schedule a host render. Avoid adding
+      // a second full TUI pass when one occurred within this frame window.
+      if (performance.now() - lastHostUpdateAt >= frameMs) requestRender?.();
+      schedule(token);
+    }, Math.max(16, nextDeadline - performance.now()));
+    timer.unref?.();
+  };
+
+  const stop = () => {
+    generation += 1;
+    active = false;
+    clearTimer();
+    const ctx = activeContext;
+    activeContext = undefined;
+    requestRender = undefined;
+    lastHostUpdateAt = 0;
+    invalidate();
+    if (!ctx) return;
+    try {
+      ctx.ui.setWidget(WIDGET_KEY, undefined);
+      ctx.ui.setWorkingMessage();
+      ctx.ui.setWorkingIndicator();
+      ctx.ui.setWorkingVisible(true);
+    } catch {
+      // UI may already be disposed during shutdown; cleanup remains idempotent.
+    }
+  };
+
+  const start = (ctx: ExtensionContext, initialPhase: Phase = "working") => {
+    stop();
+    if (!config.enabled || ctx.mode !== "tui") return;
+    activeContext = ctx;
+    active = true;
+    phase = initialPhase;
+    frame = 0;
+    startedAt = performance.now();
+    nextDeadline = startedAt;
+    lastHostUpdateAt = 0;
+    dropsByWidth.clear();
+    invalidate();
+    const token = generation;
+    ctx.ui.setWorkingVisible(true);
+    // The matrix owns the only animation clock; a static indicator prevents a
+    // second independent timer from forcing redundant full-screen renders.
+    ctx.ui.setWorkingIndicator({ frames: [workingIndicatorFrame()] });
+    ctx.ui.setWorkingMessage(PHASE_MESSAGES[phase]);
+    ctx.ui.setWidget(WIDGET_KEY, (tui) => {
+      requestRender = () => tui.requestRender();
+      return component;
+    });
+    schedule(token);
+  };
+
+  const noteHostUpdate = () => {
+    lastHostUpdateAt = performance.now();
+  };
+
+  const setPhase = (next: Phase) => {
+    noteHostUpdate();
+    if (!active || phase === next) return;
+    phase = next;
+    activeContext?.ui.setWorkingMessage(PHASE_MESSAGES[phase]);
+    frame += 1;
+    invalidate();
+  };
+
+  pi.on("agent_start", (_event, ctx) => start(ctx));
+  pi.on("agent_end", () => stop());
+  pi.on("session_before_switch", () => stop());
+  pi.on("session_shutdown", () => stop());
+
+  pi.on("message_update", (event) => {
+    noteHostUpdate();
+    const streamEvent = event.assistantMessageEvent as { type?: string } | undefined;
+    if (!streamEvent?.type) return;
+    if (streamEvent.type === "thinking_start" || streamEvent.type === "thinking_delta") {
+      setPhase("thinking");
+    } else if (streamEvent.type === "thinking_end" || streamEvent.type === "text_delta") {
+      setPhase("working");
+    }
+  });
+
+  pi.on("tool_execution_start", () => setPhase("tool"));
+  pi.on("tool_execution_update", () => noteHostUpdate());
+  pi.on("tool_execution_end", () => setPhase("working"));
+
+  pi.registerCommand("sakura-matrix", {
+    description: "Sakura Matrix animation: status, on, off, preview, fps <8-18>, density <0.45-0.95>",
+    handler: async (args, ctx) => {
+      const [command = "status", value] = args.trim().toLowerCase().split(/\s+/);
+      if (command === "on") {
+        config.enabled = true;
+        saveConfig(config);
+        ctx.ui.notify("Sakura Matrix enabled", "info");
+        return;
+      }
+      if (command === "off") {
+        config.enabled = false;
+        saveConfig(config);
+        stop();
+        ctx.ui.notify("Sakura Matrix disabled", "info");
+        return;
+      }
+      if (command === "preview") {
+        start(ctx, "thinking");
+        const previewToken = generation;
+        const previewTimer = setTimeout(() => {
+          if (generation === previewToken) stop();
+        }, 5000);
+        previewTimer.unref?.();
+        ctx.ui.notify("Sakura Matrix preview: 5 seconds", "info");
+        return;
+      }
+      if (command === "fps") {
+        const fps = Number(value);
+        if (!Number.isFinite(fps) || fps < 8 || fps > 18) {
+          ctx.ui.notify("Usage: /sakura-matrix fps <8-18>", "error");
+          return;
+        }
+        config.fps = Math.round(fps);
+        saveConfig(config);
+        ctx.ui.notify(`Sakura Matrix FPS: ${config.fps}`, "info");
+        return;
+      }
+      if (command === "density") {
+        const density = Number(value);
+        if (!Number.isFinite(density) || density < 0.45 || density > 0.95) {
+          ctx.ui.notify("Usage: /sakura-matrix density <0.45-0.95>", "error");
+          return;
+        }
+        config.density = Math.round(density * 100) / 100;
+        dropsByWidth.clear();
+        saveConfig(config);
+        ctx.ui.notify(`Sakura Matrix density: ${config.density}`, "info");
+        return;
+      }
+      ctx.ui.notify(
+        `Sakura Matrix: ${config.enabled ? "on" : "off"} · ${config.fps} FPS · ${config.height} lines · density ${config.density}`,
+        "info",
+      );
+    },
+  });
+}