From 7e91338aaf76e4e08f923c2128b6178eda5f4600 Mon Sep 17 00:00:00 2001
From: 4ndreello <4ndreello@users.noreply.github.com>
Date: Mon, 14 Sep 2026 22:28:31 -0300
Subject: [PATCH 1/8] feat(mods): Add arcade function-hooks mod above the
 prompt

Port the cc-arcade pattern into the codedeck plugin as an arcade mod: matcher-based /arcade command, AbovePrompt picker plus 2048 Client board, turn-complete pause banner, counter-only pet feeding from tool calls, and persisted best scores. Manifest declares the hooks module, open defaults CLAUDE_CODE_ENABLE_FUNCTION_HOOKS to 1 with user opt-out preserved, and docs describe enablement plus constraints.

Co-Authored-By: Claude <noreply@anthropic.com>
---
 .gitignore                                 |   2 +
 .specs/features/cc-arcade-mod-port/spec.md |  81 ++++++++++++
 docs/mods.md                               |  64 ++++++++++
 plugin/.claude-plugin/plugin.json          |   2 +-
 plugin/hooks/boards/common.tsx             |  54 ++++++++
 plugin/hooks/boards/twenty48.tsx           |  95 ++++++++++++++
 plugin/hooks/hooks.json                    |   2 +
 plugin/hooks/register.tsx                  | 122 ++++++++++++++++++
 plugin/mods/arcade/games/auto.ts           |  37 ++++++
 plugin/mods/arcade/games/best.ts           |   9 ++
 plugin/mods/arcade/games/pet.ts            | 119 ++++++++++++++++++
 plugin/mods/arcade/games/twenty48.ts       | 136 +++++++++++++++++++++
 plugin/mods/arcade/index.ts                |  13 ++
 src/open/runtime.ts                        |   9 ++
 tests/mods-arcade/auto.test.ts             |  50 ++++++++
 tests/mods-arcade/best.test.ts             |  19 +++
 tests/mods-arcade/pet.test.ts              | 118 ++++++++++++++++++
 tests/mods-arcade/twenty48.test.ts         |  89 ++++++++++++++
 tests/open-args.test.ts                    |  12 +-
 19 files changed, 1031 insertions(+), 2 deletions(-)
 create mode 100644 .specs/features/cc-arcade-mod-port/spec.md
 create mode 100644 docs/mods.md
 create mode 100644 plugin/hooks/boards/common.tsx
 create mode 100644 plugin/hooks/boards/twenty48.tsx
 create mode 100644 plugin/hooks/register.tsx
 create mode 100644 plugin/mods/arcade/games/auto.ts
 create mode 100644 plugin/mods/arcade/games/best.ts
 create mode 100644 plugin/mods/arcade/games/pet.ts
 create mode 100644 plugin/mods/arcade/games/twenty48.ts
 create mode 100644 plugin/mods/arcade/index.ts
 create mode 100644 tests/mods-arcade/auto.test.ts
 create mode 100644 tests/mods-arcade/best.test.ts
 create mode 100644 tests/mods-arcade/pet.test.ts
 create mode 100644 tests/mods-arcade/twenty48.test.ts

diff --git a/.gitignore b/.gitignore
index 8212173..c02b045 100644
--- a/.gitignore
+++ b/.gitignore
@@ -8,3 +8,5 @@ dist
 .DS_Store
 .env
 coverage
+# plugin-types generates .claude/ slash types here
+.claude/
diff --git a/.specs/features/cc-arcade-mod-port/spec.md b/.specs/features/cc-arcade-mod-port/spec.md
new file mode 100644
index 0000000..817346e
--- /dev/null
+++ b/.specs/features/cc-arcade-mod-port/spec.md
@@ -0,0 +1,81 @@
+# cc-arcade Mod Port (arcade)
+
+## Goal
+
+Port the cc-arcade pattern (sezaakgun cc-arcade v0.2.0 at github.com/sezaakgun/cc-arcade) into the codedeck plugin as a Mod named `arcade`.
+
+Source behavior to port (from session 2bab discovery):
+
+- `hooks/register.tsx` registers the arcade slash command with `immediate: true` on `session.start`.
+- Draws a picker or a board above the prompt on `ui.render` for `AbovePrompt` using `Box`, `Button`, `Client`, `Text` from `$.ui.resolve`.
+- Mounts one `Client` surface module per board from `hooks/boards`.
+- Records turn start time on `turn.start` for the auto picker heuristic.
+- Pauses the open game with a banner on `turn.complete`.
+- Feeds a pet from `tool.call` by matching Bash test runner patterns plus `git commit` plus `Edit`, `Write`, `NotebookEdit`, keeping counters only with no command text stored.
+- Persists pet plus best scores plus colorblind flag with `$.store`.
+- Costs zero tokens because command handling runs locally.
+
+Codedeck baseline (from session e1ed mapping):
+
+- Plugin version 0.2.0.
+- `plugin/hooks/hooks.json` declares only `SessionStart` and `UserPromptSubmit` shell command hooks with no function hooks module.
+- `codedeck open` builds the settings payload at launch with theme plus fullscreen renderer plus spinner verbs plus tips plus statusline.
+- Installed claude is 2.1.270, above the 2.1.269 drawing gate.
+- Root tsconfig includes only `src`, so plugin tsx never breaks `npm run build`.
+- Vitest includes `tests/**/*.test.ts`.
+
+Port deliverables:
+
+1. `arcade` slash command.
+2. `AbovePrompt` board.
+3. Pure pet plus best plus auto logic with unit tests.
+4. Manifest declaring the hooks module.
+5. `open` enabling function hooks.
+6. Docs.
+
+Port constraints carried over from upstream:
+
+- Never declare a local variable named `h` in board files.
+- `Client` module paths must be string literals.
+- The band is about half the terminal height.
+- Redraw is about ten times per second with doom at twenty.
+- The board needs a click for keyboard focus and Esc always returns to the prompt.
+- Terminal only with nothing drawn in `claude -p` headless, desktop, or mobile.
+- A failed hot reload needs a session restart.
+
+Upstream validation reference: `bun test` for pure logic, `oxlint`, `claude plugin validate`, and `/plugin-types` generating git ignored `.claude/types`.
+
+## Acceptance criteria
+
+- Arcade picker renders above the prompt in terminal sessions with function hooks on.
+- One demo board is playable with keyboard after a click and Esc returns to the prompt.
+- `turn.complete` pauses with a visible banner.
+- `tool.call` feeds pet counters only.
+- Best scores persist across sessions.
+- `claude plugin validate` passes on the manifest and on the repo root.
+- The scoped vitest run on the new tests passes.
+- Existing suite expectations stay green.
+
+## Out of scope
+
+- Full nine game catalog parity including doom.
+- Desktop, mobile, and headless support.
+- Cross machine sync.
+- Any dependency install, fetch, or vendor.
+- Any push or destructive git action.
+
+## Verification
+
+Scoped runs only. Do not run the full suite. Do not install or fetch anything.
+
+- `npm run build`
+- `npx vitest run tests/mods-arcade`
+- `claude plugin validate .claude-plugin/plugin.json`
+- `claude plugin validate .`
+
+Each command is run scoped as listed. Quote the output when reporting results.
+
+## Stop conditions
+
+- If `/plugin-types` cannot run noninteractively, specify engine types as stubbed and continue.
+- Never invent engine APIs.
diff --git a/docs/mods.md b/docs/mods.md
new file mode 100644
index 0000000..34fac48
--- /dev/null
+++ b/docs/mods.md
@@ -0,0 +1,64 @@
+# CodeDeck mods (arcade)
+
+Function hooks backing the arcade mod. Boards and game logic live in the MOD
+slice; this file covers integration only: how the hooks get enabled, typed,
+and validated.
+
+## Enablement
+
+`codedeck open` launches claude sessions with `CLAUDE_CODE_ENABLE_FUNCTION_HOOKS=1`
+in the spawn environment (`sanitizeEnv` in `src/open/runtime.ts`, set with
+`??=` so an explicit value of the user's own wins and an opt-out keeps
+working).
+
+The variable is namespaced to Claude Code: the opencode and codex spawns that
+share the helper carry it inertly and behave exactly as before. The
+`--no-bypass`, `--no-theme` and `--no-pty` escape hatches ride in argv, not
+env, so they are untouched.
+
+## Declaration
+
+`plugin/hooks/hooks.json` carries a top-level `modules` array with one entry
+pointing at the register file, plus a description naming the arcade mod and
+its function hooks requirement. The existing `hooks` key (`SessionStart` for
+`session-id.sh`, `UserPromptSubmit` for `session-name.sh`) is unchanged.
+
+The new capability bumps the plugin to 0.3.0 in
+`plugin/.claude-plugin/plugin.json`.
+
+## plugin-types flow
+
+Run the plugin-types flow from the repo root. It writes the generated types
+under `.claude/`, which stays gitignored, so generated output never lands in a
+diff or a review.
+
+## Validation
+
+Validate the manifest path after any manifest edit:
+
+```sh
+claude plugin validate plugin/.claude-plugin/plugin.json
+```
+
+Validate the whole plugin from the repo root:
+
+```sh
+claude plugin validate .
+```
+
+Root-level validation resolves the `modules` entry, so it needs
+`plugin/hooks/register.tsx` from the MOD slice and stays pending until that
+slice lands.
+
+## Board constraints
+
+Board files in the MOD slice hold to these limits:
+
+- Never a local variable named `h`.
+- `Client` module paths are string literals.
+- Board height stays around half the terminal height band.
+- Redraw runs around ten frames per second.
+- Click gives keyboard focus; Esc returns to the prompt.
+- Terminal only: nothing renders in headless desktop or mobile.
+- Version gate: Claude Code 2.1.269 or later (verified against installed
+  2.1.270).
diff --git a/plugin/.claude-plugin/plugin.json b/plugin/.claude-plugin/plugin.json
index 1c2f83b..3d8ff87 100644
--- a/plugin/.claude-plugin/plugin.json
+++ b/plugin/.claude-plugin/plugin.json
@@ -1,6 +1,6 @@
 {
   "name": "codedeck",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "A focused Claude Code workspace for running and reviewing CodeDeck sessions.",
   "author": {
     "name": "CodeDeck"
diff --git a/plugin/hooks/boards/common.tsx b/plugin/hooks/boards/common.tsx
new file mode 100644
index 0000000..3e924f9
--- /dev/null
+++ b/plugin/hooks/boards/common.tsx
@@ -0,0 +1,54 @@
+/** @jsx h */
+import type { ClientElements, ClientSurface } from "claude-code";
+
+import { banner, type SeenDone } from "../../mods/arcade/games/twenty48.js";
+
+export interface ArcadeBoardProps {
+  done: number;
+  colorblind: boolean;
+  best: number;
+}
+
+export interface CommonState {
+  paused: boolean;
+  seenDone: number;
+}
+
+export function initialCommonState(): CommonState {
+  return { paused: false, seenDone: 0 };
+}
+
+export function reportScore(surface: ClientSurface, game: string, score: number, done: number): void {
+  surface.post({ kind: "arcade-score", game, score, done });
+}
+
+export default function CommonBoard(props: ArcadeBoardProps, surface: ClientSurface): ClientElements {
+  const current = (surface.state ?? null) as CommonState | null;
+  const state: CommonState = current ?? initialCommonState();
+  if (current === null) surface.setState(state);
+  const seen: SeenDone = { current: state.seenDone };
+  // banner() owns the transition: it pauses exactly once per new done value.
+  banner(props.done, seen, () => {
+    surface.setState({ ...state, paused: true, seenDone: seen.current });
+  });
+  // The notice is driven by paused state, not by banner()'s transient return,
+  // so it stays visible until the user resumes.
+  const paused = state.paused || seen.current !== state.seenDone;
+  surface.onKey((key) => {
+    void key;
+    if (paused) surface.setState({ ...state, paused: false, seenDone: seen.current });
+  });
+  surface.onPointer((point) => {
+    void point;
+    if (paused) surface.setState({ ...state, paused: false, seenDone: seen.current });
+  });
+  const palette = props.colorblind ? "high-contrast" : "standard";
+  const line = paused
+    ? `Round ${seen.current} finished - board paused. Press any key to resume.`
+    : `Arcade ready (${palette}) - best ${props.best}`;
+  return (
+    <box>
+      <text>{line}</text>
+    </box>
+  ) as unknown as ClientElements;
+}
diff --git a/plugin/hooks/boards/twenty48.tsx b/plugin/hooks/boards/twenty48.tsx
new file mode 100644
index 0000000..631272b
--- /dev/null
+++ b/plugin/hooks/boards/twenty48.tsx
@@ -0,0 +1,95 @@
+/** @jsx h */
+import type { ClientElements, ClientSurface } from "claude-code";
+
+import {
+  banner,
+  directionForKey,
+  initialTwenty48State,
+  isFinished,
+  moveGrid,
+  spawnTile,
+  type SeenDone,
+  type Twenty48State,
+} from "../../mods/arcade/games/twenty48.js";
+
+export interface Twenty48Props {
+  done: number;
+  colorblind: boolean;
+  best: number;
+}
+
+export const BOARD_PATH = "hooks/boards/twenty48.tsx";
+
+export default function Twenty48Board(props: Twenty48Props, surface: ClientSurface): ClientElements {
+  const current = (surface.state ?? null) as Twenty48State | null;
+  const state: Twenty48State = current ?? initialTwenty48State();
+  if (current === null) surface.setState(state);
+  const seen: SeenDone = { current: state.seenDone };
+  // banner() owns the transition: it pauses exactly once per new done value.
+  banner(props.done, seen, () => {
+    surface.setState({ ...state, paused: true, seenDone: seen.current });
+  });
+  // The notice is driven by paused state, not by banner()'s transient return,
+  // so it stays visible until the user resumes and no keypress is eaten blind.
+  const paused = state.paused || seen.current !== state.seenDone;
+
+  const finish = (final: Twenty48State) => {
+    if (!final.posted) {
+      surface.post({ kind: "arcade-score", game: "twenty48", score: final.score, done: props.done });
+      surface.setState({ ...final, posted: true });
+    } else {
+      surface.setState(final);
+    }
+  };
+
+  surface.onKey((key) => {
+    if (paused) {
+      surface.setState({ ...state, paused: false, seenDone: seen.current });
+      return;
+    }
+    if (state.over) return;
+    const direction = directionForKey(key.name);
+    if (direction === null) return;
+    const stepped = moveGrid(state.grid, direction);
+    if (!stepped.moved) return;
+    const grid = spawnTile(stepped.grid, () => Math.floor(Math.random() * 16));
+    const score = state.score + stepped.gained;
+    const won = state.won || grid.some((cell) => cell >= 2048);
+    const over = isFinished(grid);
+    const final: Twenty48State = { ...state, grid, score, won, over };
+    if (over || won) finish(final);
+    else surface.setState(final);
+  });
+
+  surface.onPointer((point) => {
+    void point;
+    if (paused) {
+      surface.setState({ ...state, paused: false, seenDone: seen.current });
+      return;
+    }
+    if (state.over && !state.posted) {
+      surface.post({ kind: "arcade-score", game: "twenty48", score: state.score, done: props.done });
+      surface.setState({ ...state, posted: true });
+    }
+  });
+
+  const palette = props.colorblind ? "high-contrast" : "standard";
+  const rows: string[] = [];
+  for (let rowIdx = 0; rowIdx < 4; rowIdx += 1) {
+    const cells: string[] = [];
+    for (let col = 0; col < 4; col += 1) {
+      const cell = state.grid[rowIdx * 4 + col];
+      cells.push(cell === 0 ? "    ." : String(cell).padStart(5, " "));
+    }
+    rows.push(cells.join(" "));
+  }
+  const status = state.over ? "game over" : state.won ? "you win" : `${palette} - best ${props.best}`;
+  const line = paused
+    ? `Round ${seen.current} finished - board paused. Press any key to resume.`
+    : `2048 score ${state.score} (${status})\n${rows.join("\n")}`;
+  return (
+    <box>
+      <text>{line}</text>
+    </box>
+  ) as unknown as ClientElements;
+}
diff --git a/plugin/hooks/hooks.json b/plugin/hooks/hooks.json
index 8b13bda..276e5e9 100644
--- a/plugin/hooks/hooks.json
+++ b/plugin/hooks/hooks.json
@@ -1,4 +1,6 @@
 {
+  "description": "Codedeck arcade mod: registers function hooks (requires Claude Code with function hooks enabled).",
+  "modules": ["./register.tsx"],
   "hooks": {
     "SessionStart": [
       {
diff --git a/plugin/hooks/register.tsx b/plugin/hooks/register.tsx
new file mode 100644
index 0000000..3f88741
--- /dev/null
+++ b/plugin/hooks/register.tsx
@@ -0,0 +1,122 @@
+/** @jsx h */
+import type { Register } from "claude-code";
+
+import { feed, newPet, petEvent, type Pet } from "../mods/arcade/games/pet.js";
+import { isBetter } from "../mods/arcade/games/best.js";
+import { ARCADE_BOARDS } from "../mods/arcade/index.js";
+
+const PET_KEY = "pet";
+const COLORBLIND_KEY = "colorblind";
+const bestKey = (game: string): string => `best:${game}`;
+
+export const register: Register = (on) => {
+  let pet: Pet = newPet();
+  let best: Record<string, number> = {};
+  let colorblind = false;
+  let turnClock = 0;
+  let lastTurnMs = 0;
+  let openBoard: string | null = null;
+  let done = 0;
+
+  on("session.start", async ($, e, next) => {
+    try {
+      const savedPet = await $.store.get(PET_KEY);
+      if (savedPet) pet = savedPet as Pet;
+      for (const board of ARCADE_BOARDS) {
+        const saved = await $.store.get(bestKey(board));
+        if (typeof saved === "number") best[board] = saved;
+      }
+      const savedColorblind = await $.store.get(COLORBLIND_KEY);
+      if (typeof savedColorblind === "boolean") colorblind = savedColorblind;
+    } catch (err) {
+      $.ui.log(`arcade restore failed: ${String(err)}`);
+    }
+    await $.command.register({ name: "arcade", immediate: true });
+    return next(e);
+  });
+
+  on("command.run", { command: "arcade" }, async ($, e) => {
+    const arg = e.args.trim().toLowerCase();
+    if (arg === "") {
+      openBoard = null;
+      await $.ui.invalidate("ui.render");
+      return { text: "arcade boards: twenty48" };
+    }
+    if (arg === "list") {
+      return { text: "arcade boards: twenty48" };
+    }
+    if (arg === "open" || arg.startsWith("open ")) {
+      const name = arg === "open" ? "twenty48" : arg.slice("open ".length).trim() || "twenty48";
+      if (!(ARCADE_BOARDS as readonly string[]).includes(name)) {
+        return { text: `no game called "${name}"` };
+      }
+      openBoard = name;
+      await $.ui.invalidate("ui.render");
+      return { text: `opened ${name}` };
+    }
+    if (arg === "stop") {
+      openBoard = null;
+      await $.ui.invalidate("ui.render");
+      return { text: "arcade closed" };
+    }
+    return { text: `no game called "${arg}"` };
+  });
+
+  on("turn.start", async ($, e, next) => {
+    turnClock = Date.now();
+    return next(e);
+  });
+
+  on("turn.complete", async ($, e, next) => {
+    lastTurnMs = Date.now() - turnClock;
+    void lastTurnMs;
+    done += 1;
+    await $.ui.invalidate("ui.render");
+    return next(e);
+  });
+
+  on("tool.call", async ($, e, next) => {
+    const r = await next(e);
+    // petEvent already ignores denied calls; only classified events feed the pet.
+    const command = (e as { command?: string }).command ?? undefined;
+    const denied = "deny" in (r as Record<string, unknown>);
+    const ok = denied ? undefined : !(r as { isError?: boolean }).isError;
+    const event = petEvent({ tool: e.tool, command, ok, denied });
+    if (event !== undefined) {
+      pet = feed(pet, event);
+      await $.store.set(PET_KEY, { xp: pet.xp, mood: pet.mood, tests: pet.tests, commits: pet.commits, edits: pet.edits });
+    }
+    return r;
+  });
+
+  on("ui.message", async ($, e, next) => {
+    const posted = e.data as { game?: string; score?: number } | undefined;
+    if (!posted || typeof posted.game !== "string" || typeof posted.score !== "number") {
+      return next(e);
+    }
+    if (isBetter(posted.game, posted.score, best)) {
+      best[posted.game] = posted.score;
+      await $.store.set(bestKey(posted.game), posted.score);
+      $.ui.toast(`New arcade record in ${posted.game}: ${posted.score}`);
+    }
+    return { game: posted.game, score: posted.score };
+  });
+
+  on("ui.render", async ($, e, next) => {
+    if (e.surface !== "terminal") return await next(e);
+    const { Box, Button, Client, Text } = await $.ui.resolve(e, "Box", "Button", "Client", "Text");
+    if (openBoard === null) {
+      return [
+        <Box>
+          <Text>Arcade boards</Text>
+          <Button>twenty48</Button>
+        </Box>,
+        await next(e),
+      ];
+    }
+    return [
+      <Client module="./boards/twenty48.tsx" done={done} colorblind={colorblind} best={best[openBoard] ?? 0} />,
+      await next(e),
+    ];
+  });
+};
diff --git a/plugin/mods/arcade/games/auto.ts b/plugin/mods/arcade/games/auto.ts
new file mode 100644
index 0000000..c302aaa
--- /dev/null
+++ b/plugin/mods/arcade/games/auto.ts
@@ -0,0 +1,37 @@
+export interface AutoInput {
+  lastTurnMs?: number;
+  idle?: boolean;
+}
+
+// One minute (60000 ms) separates quick turns from deep turns.
+export const TURN_THRESHOLD_MS = 60_000;
+
+export const DEEP_GAMES = ["twenty48"];
+export const QUICK_GAMES = ["twenty48"];
+export const DROPIN_GAMES = ["twenty48"];
+
+export type AutoPool = "deep" | "quick" | "dropin";
+
+// Pure pool picker: turns over one minute suggest deep games,
+// turns under one minute suggest quick games, idle suggests drop-in games.
+export function pickPool(input: AutoInput = {}): AutoPool {
+  if (input.idle) return "dropin";
+  if (typeof input.lastTurnMs === "number" && input.lastTurnMs > TURN_THRESHOLD_MS) {
+    return "deep";
+  }
+  return "quick";
+}
+
+// Turn duration heuristic: maps the picked pool to a board.
+export function pickAuto(input: AutoInput = {}): string {
+  const pool = pickPool(input);
+  if (pool === "deep") return DEEP_GAMES[0];
+  if (pool === "dropin") return DROPIN_GAMES[0];
+  return QUICK_GAMES[0];
+}
+
+export function pickRandom(games: string[] = DROPIN_GAMES): string {
+  if (games.length === 0) return DROPIN_GAMES[0];
+  const index = Math.floor(Math.random() * games.length);
+  return games[index];
+}
diff --git a/plugin/mods/arcade/games/best.ts b/plugin/mods/arcade/games/best.ts
new file mode 100644
index 0000000..c3c7174
--- /dev/null
+++ b/plugin/mods/arcade/games/best.ts
@@ -0,0 +1,9 @@
+export type BestTable = Record<string, number>;
+
+// Higher score wins for every arcade game. Returns true when there is no
+// stored best yet for that game, or when the new score beats it.
+export function isBetter(game: string, score: number, best: BestTable): boolean {
+  const prev = best[game];
+  if (prev === undefined) return true;
+  return score > prev;
+}
diff --git a/plugin/mods/arcade/games/pet.ts b/plugin/mods/arcade/games/pet.ts
new file mode 100644
index 0000000..df7833f
--- /dev/null
+++ b/plugin/mods/arcade/games/pet.ts
@@ -0,0 +1,119 @@
+export type PetEventKind = "test-pass" | "test-fail" | "commit" | "edit";
+
+export interface PetToolCall {
+  tool: string;
+  command?: string;
+  text?: string;
+  ok?: boolean;
+  denied?: boolean;
+  exitCode?: number;
+}
+
+export interface PetEvent {
+  kind: PetEventKind;
+  ok: boolean | undefined;
+  xp: number;
+  mood: number;
+}
+
+export interface Pet {
+  xp: number;
+  mood: number;
+  tests: number;
+  commits: number;
+  edits: number;
+}
+
+export const XP: Record<PetEventKind, number> = {
+  "test-pass": 10,
+  "test-fail": 2,
+  commit: 15,
+  edit: 1,
+};
+
+export const MOOD: Record<PetEventKind, number> = {
+  "test-pass": 8,
+  "test-fail": -12,
+  commit: 10,
+  edit: 1,
+};
+
+// Matches common test invocations:
+// bun / npm / pnpm / yarn test, npx jest vitest mocha,
+// pytest jest vitest rspec phpunit mocha at a command start or after a
+// shell separator, go test, cargo test, make test,
+// mvn gradle gradlew sbt test tasks.
+// Bare tool names are anchored so words inside other commands
+// (e.g. "cat vitest.config.ts") do not count as test runs.
+export const TEST_COMMAND =
+  /(?:\b(?:bun|npm|pnpm|yarn)\s+(?:run\s+)?test\b|\bnpx\s+(?:jest|vitest|mocha)\b|(?:^|[;&|]\s*)\b(?:pytest|jest|vitest|rspec|phpunit|mocha)\b(?=\s|$)|\bgo\s+test\b|\bcargo\s+test\b|\bmake\s+test\b|\b(?:mvn|gradle|gradlew|sbt)\b[^\n]*\btest\b)/;
+
+const GIT_COMMIT = /\bgit\s+commit\b/;
+const DRY_RUN = /--dry-run/;
+
+const EDIT_TOOLS = new Set(["Edit", "Write", "NotebookEdit"]);
+
+function commandText(call: PetToolCall): string {
+  return call.command ?? call.text ?? "";
+}
+
+function kindForTest(call: PetToolCall): PetEventKind {
+  if (call.ok === false) return "test-fail";
+  if (typeof call.exitCode === "number" && call.exitCode !== 0) return "test-fail";
+  return "test-pass";
+}
+
+export function petEvent(call: PetToolCall): PetEvent | undefined {
+  // Denied calls carry undefined ok and are ignored.
+  if (call.denied) return undefined;
+
+  if (call.tool === "Bash") {
+    const text = commandText(call);
+    // Commits win over test words: "git commit -m 'fix jest config'"
+    // is a commit, not a test run.
+    if (GIT_COMMIT.test(text) && !DRY_RUN.test(text)) {
+      return { kind: "commit", ok: call.ok, xp: XP.commit, mood: MOOD.commit };
+    }
+    if (TEST_COMMAND.test(text)) {
+      const kind = kindForTest(call);
+      return { kind, ok: call.ok, xp: XP[kind], mood: MOOD[kind] };
+    }
+    return undefined;
+  }
+
+  if (EDIT_TOOLS.has(call.tool)) {
+    return { kind: "edit", ok: call.ok, xp: XP.edit, mood: MOOD.edit };
+  }
+
+  return undefined;
+}
+
+export function newPet(): Pet {
+  return { xp: 0, mood: 0, tests: 0, commits: 0, edits: 0 };
+}
+
+export function feed(pet: Pet, event: PetEvent): Pet {
+  const next: Pet = {
+    xp: pet.xp + event.xp,
+    mood: pet.mood + event.mood,
+    tests: pet.tests,
+    commits: pet.commits,
+    edits: pet.edits,
+  };
+  if (event.kind === "test-pass" || event.kind === "test-fail") next.tests += 1;
+  if (event.kind === "commit") next.commits += 1;
+  if (event.kind === "edit") next.edits += 1;
+  return next;
+}
+
+export function level(pet: Pet): number {
+  return 1 + Math.floor(Math.max(0, pet.xp) / 100);
+}
+
+export function stage(input: Pet | number): string {
+  const lvl = typeof input === "number" ? input : level(input);
+  if (lvl <= 1) return "egg";
+  if (lvl === 2) return "baby";
+  if (lvl === 3) return "teen";
+  return "adult";
+}
diff --git a/plugin/mods/arcade/games/twenty48.ts b/plugin/mods/arcade/games/twenty48.ts
new file mode 100644
index 0000000..58ada5c
--- /dev/null
+++ b/plugin/mods/arcade/games/twenty48.ts
@@ -0,0 +1,136 @@
+// Pure 2048 logic for the arcade demo board. No engine imports so plain
+// vitest runs it. The board components under plugin/hooks/boards/ own the
+// surface wiring (state, keys, pointer, score posts) and import from here.
+
+export interface SeenDone {
+  current: number;
+}
+
+// Banner helper: pauses once per new done value. The caller keeps `seen`
+// across renders; when `done` changes we record it and pause a single time.
+export function banner(done: number, seen: SeenDone, pause: () => void): string | null {
+  if (done === seen.current) return null;
+  seen.current = done;
+  pause();
+  return `Round ${done} finished - board paused. Press any key to resume.`;
+}
+
+export type Direction = "up" | "down" | "left" | "right";
+
+export interface Twenty48State {
+  grid: number[];
+  score: number;
+  over: boolean;
+  won: boolean;
+  posted: boolean;
+  paused: boolean;
+  seenDone: number;
+}
+
+export function emptyGrid(): number[] {
+  return [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0];
+}
+
+export function spawnTile(grid: number[], pick: () => number): number[] {
+  const open: number[] = [];
+  for (let idx = 0; idx < 16; idx += 1) {
+    if (grid[idx] === 0) open.push(idx);
+  }
+  if (open.length === 0) return grid;
+  const slot = open[pick() % open.length];
+  const next = grid.slice();
+  next[slot] = pick() % 10 === 0 ? 4 : 2;
+  return next;
+}
+
+export function slideRow(row: number[]): { row: number[]; gained: number } {
+  const tiles = row.filter((cell) => cell !== 0);
+  const out: number[] = [];
+  let gained = 0;
+  let idx = 0;
+  while (idx < tiles.length) {
+    if (idx + 1 < tiles.length && tiles[idx] === tiles[idx + 1]) {
+      const merged = tiles[idx] * 2;
+      out.push(merged);
+      gained += merged;
+      idx += 2;
+    } else {
+      out.push(tiles[idx]);
+      idx += 1;
+    }
+  }
+  while (out.length < 4) out.push(0);
+  return { row: out, gained };
+}
+
+export function moveGrid(grid: number[], direction: Direction): { grid: number[]; gained: number; moved: boolean } {
+  const next = grid.slice();
+  let gained = 0;
+  let moved = false;
+  const setRow = (rowIdx: number, row: number[]) => {
+    for (let col = 0; col < 4; col += 1) {
+      const at = rowIdx * 4 + col;
+      if (next[at] !== row[col]) moved = true;
+      next[at] = row[col];
+    }
+  };
+  const getRow = (rowIdx: number): number[] => {
+    const row: number[] = [];
+    for (let col = 0; col < 4; col += 1) row.push(grid[rowIdx * 4 + col]);
+    return row;
+  };
+  const getCol = (colIdx: number): number[] => {
+    const col: number[] = [];
+    for (let rowIdx = 0; rowIdx < 4; rowIdx += 1) col.push(grid[rowIdx * 4 + colIdx]);
+    return col;
+  };
+  const setCol = (colIdx: number, col: number[]) => {
+    for (let rowIdx = 0; rowIdx < 4; rowIdx += 1) {
+      const at = rowIdx * 4 + colIdx;
+      if (next[at] !== col[rowIdx]) moved = true;
+      next[at] = col[rowIdx];
+    }
+  };
+  if (direction === "left" || direction === "right") {
+    for (let rowIdx = 0; rowIdx < 4; rowIdx += 1) {
+      let row = getRow(rowIdx);
+      if (direction === "right") row = row.reverse();
+      const slid = slideRow(row);
+      gained += slid.gained;
+      const placed = direction === "right" ? slid.row.reverse() : slid.row;
+      setRow(rowIdx, placed);
+    }
+  } else {
+    for (let colIdx = 0; colIdx < 4; colIdx += 1) {
+      let col = getCol(colIdx);
+      if (direction === "down") col = col.reverse();
+      const slid = slideRow(col);
+      gained += slid.gained;
+      const placed = direction === "down" ? slid.row.reverse() : slid.row;
+      setCol(colIdx, placed);
+    }
+  }
+  return { grid: next, gained, moved };
+}
+
+export function isFinished(grid: number[]): boolean {
+  if (grid.some((cell) => cell === 0)) return false;
+  const probe: Direction[] = ["up", "down", "left", "right"];
+  for (const direction of probe) {
+    if (moveGrid(grid, direction).moved) return false;
+  }
+  return true;
+}
+
+export function initialTwenty48State(pick: () => number = () => Math.floor(Math.random() * 16)): Twenty48State {
+  const seeded = spawnTile(spawnTile(emptyGrid(), pick), pick);
+  return { grid: seeded, score: 0, over: false, won: false, posted: false, paused: false, seenDone: 0 };
+}
+
+export function directionForKey(name: string): Direction | null {
+  if (name === "up" || name === "w") return "up";
+  if (name === "down" || name === "s") return "down";
+  if (name === "left" || name === "a") return "left";
+  if (name === "right" || name === "d") return "right";
+  return null;
+}
diff --git a/plugin/mods/arcade/index.ts b/plugin/mods/arcade/index.ts
new file mode 100644
index 0000000..1ccb34e
--- /dev/null
+++ b/plugin/mods/arcade/index.ts
@@ -0,0 +1,13 @@
+// Arcade mod: a single demo board (twenty48) plus a companion pet that
+// feeds on tool activity. The manifest declaration for this mod lands in a
+// parallel slice; this file only names the mod and its boards.
+
+export const ARCADE_MOD_NAME = "arcade";
+
+export const ARCADE_BOARDS = ["twenty48"] as const;
+
+export type ArcadeBoardName = (typeof ARCADE_BOARDS)[number];
+
+export const ARCADE_BOARD_MODULES: Record<ArcadeBoardName, string> = {
+  twenty48: "hooks/boards/twenty48.tsx",
+};
diff --git a/src/open/runtime.ts b/src/open/runtime.ts
index 5902e68..708f266 100644
--- a/src/open/runtime.ts
+++ b/src/open/runtime.ts
@@ -179,6 +179,15 @@ export function sanitizeEnv(env: NodeJS.ProcessEnv): NodeJS.ProcessEnv {
   // the boot screen. Only the line matters. A setting of the user's own is left
   // alone, since silencing mise everywhere is not this command's call.
   sanitized.MISE_QUIET ??= "1";
+
+  // Function hooks back the codedeck arcade mod, and Claude Code only loads
+  // hook modules when the spawning environment enables them. The variable is
+  // namespaced to Claude Code, so the opencode and codex spawns that share
+  // this helper carry it inertly and behave exactly as before. A value of the
+  // user's own wins, which keeps an explicit opt-out working. The --no-bypass,
+  // --no-theme and --no-pty escape hatches ride in argv, not env, so they are
+  // untouched.
+  sanitized.CLAUDE_CODE_ENABLE_FUNCTION_HOOKS ??= "1";
   return sanitized;
 }
 
diff --git a/tests/mods-arcade/auto.test.ts b/tests/mods-arcade/auto.test.ts
new file mode 100644
index 0000000..9f10e24
--- /dev/null
+++ b/tests/mods-arcade/auto.test.ts
@@ -0,0 +1,50 @@
+import { describe, expect, it } from "vitest";
+
+import { DROPIN_GAMES, pickAuto, pickPool, pickRandom } from "../../plugin/mods/arcade/games/auto";
+
+describe("pickAuto", () => {
+  it("suggests deep games for turns over one minute", () => {
+    expect(pickAuto({ lastTurnMs: 61_000 })).toBe("twenty48");
+    expect(pickAuto({ lastTurnMs: 5 * 60_000 })).toBe("twenty48");
+  });
+
+  it("suggests quick games for turns under one minute", () => {
+    expect(pickAuto({ lastTurnMs: 5_000 })).toBe("twenty48");
+    expect(pickAuto({})).toBe("twenty48");
+  });
+
+  it("suggests drop-in games when idle", () => {
+    expect(DROPIN_GAMES).toContain("twenty48");
+    expect(pickAuto({ idle: true })).toBe("twenty48");
+    expect(pickAuto({ idle: true, lastTurnMs: 10 * 60_000 })).toBe("twenty48");
+  });
+});
+
+describe("pickPool", () => {
+  it("flips from quick to deep across the 60000 ms threshold", () => {
+    expect(pickPool({ lastTurnMs: 59_999 })).toBe("quick");
+    expect(pickPool({ lastTurnMs: 60_000 })).toBe("quick");
+    expect(pickPool({ lastTurnMs: 60_001 })).toBe("deep");
+    expect(pickPool({ lastTurnMs: 61_000 })).toBe("deep");
+  });
+
+  it("maps idle to dropin regardless of turn length", () => {
+    expect(pickPool({ idle: true })).toBe("dropin");
+    expect(pickPool({ idle: true, lastTurnMs: 10 * 60_000 })).toBe("dropin");
+  });
+
+  it("defaults to quick without input", () => {
+    expect(pickPool({})).toBe("quick");
+    expect(pickPool({ lastTurnMs: 5_000 })).toBe("quick");
+  });
+});
+
+describe("pickRandom", () => {
+  it("returns a member of the given list", () => {
+    expect(["a", "b"]).toContain(pickRandom(["a", "b"]));
+  });
+
+  it("falls back to the drop-in list by default", () => {
+    expect(DROPIN_GAMES).toContain(pickRandom());
+  });
+});
diff --git a/tests/mods-arcade/best.test.ts b/tests/mods-arcade/best.test.ts
new file mode 100644
index 0000000..0bc33f6
--- /dev/null
+++ b/tests/mods-arcade/best.test.ts
@@ -0,0 +1,19 @@
+import { describe, expect, it } from "vitest";
+
+import { isBetter } from "../../plugin/mods/arcade/games/best";
+
+describe("isBetter", () => {
+  it("accepts the first score for a game", () => {
+    expect(isBetter("twenty48", 128, {})).toBe(true);
+  });
+
+  it("compares the new score against the stored best per game", () => {
+    expect(isBetter("twenty48", 256, { twenty48: 128 })).toBe(true);
+    expect(isBetter("twenty48", 64, { twenty48: 128 })).toBe(false);
+    expect(isBetter("twenty48", 128, { twenty48: 128 })).toBe(false);
+  });
+
+  it("keeps bests isolated per game", () => {
+    expect(isBetter("other", 10, { twenty48: 9999 })).toBe(true);
+  });
+});
diff --git a/tests/mods-arcade/pet.test.ts b/tests/mods-arcade/pet.test.ts
new file mode 100644
index 0000000..fd09d57
--- /dev/null
+++ b/tests/mods-arcade/pet.test.ts
@@ -0,0 +1,118 @@
+import { describe, expect, it } from "vitest";
+
+import { feed, level, MOOD, newPet, petEvent, stage, TEST_COMMAND, XP } from "../../plugin/mods/arcade/games/pet";
+
+describe("XP table", () => {
+  it("rewards test passes, commits and edits", () => {
+    expect(XP["test-pass"]).toBe(10);
+    expect(XP["test-fail"]).toBe(2);
+    expect(XP.commit).toBe(15);
+    expect(XP.edit).toBe(1);
+  });
+});
+
+describe("MOOD table", () => {
+  it("tracks mood per event kind", () => {
+    expect(MOOD["test-pass"]).toBe(8);
+    expect(MOOD["test-fail"]).toBe(-12);
+    expect(MOOD.commit).toBe(10);
+    expect(MOOD.edit).toBe(1);
+  });
+});
+
+describe("TEST_COMMAND", () => {
+  it.each([
+    "bun test",
+    "npm test",
+    "npm run test",
+    "pnpm test",
+    "yarn test",
+    "npx jest",
+    "npx vitest",
+    "npx mocha",
+    "pytest",
+    "pytest tests/test_pet.py",
+    "jest",
+    "vitest run",
+    "rspec",
+    "phpunit",
+    "mocha",
+    "go test ./...",
+    "cargo test",
+    "make test",
+    "mvn test",
+    "gradle test",
+    "./gradlew test",
+    "sbt test",
+  ])("matches %s", (cmd) => {
+    expect(TEST_COMMAND.test(cmd)).toBe(true);
+  });
+
+  it.each(["git commit -m hi", "go build ./...", "npm run lint"])("does not match %s", (cmd) => {
+    expect(TEST_COMMAND.test(cmd)).toBe(false);
+  });
+
+  it.each([
+    "cat vitest.config.ts",
+    "rm -rf node_modules/.vitest",
+    "git add jest.config.js",
+    "grep -rn mocha docs/",
+    "ls tests/pytest.ini",
+  ])("does not mistake %s for a test run", (cmd) => {
+    expect(TEST_COMMAND.test(cmd)).toBe(false);
+  });
+});
+
+describe("petEvent", () => {
+  it("classifies Bash test runs by command text", () => {
+    expect(petEvent({ tool: "Bash", command: "npm test", ok: true })?.kind).toBe("test-pass");
+    expect(petEvent({ tool: "Bash", command: "go test ./...", ok: false })?.kind).toBe("test-fail");
+  });
+
+  it("classifies git commit without the dry-run flag into commits", () => {
+    expect(petEvent({ tool: "Bash", command: "git commit -m hi", ok: true })?.kind).toBe("commit");
+    expect(petEvent({ tool: "Bash", command: "git commit --dry-run", ok: true })).toBeUndefined();
+  });
+
+  it("prefers commit over test words in the message", () => {
+    expect(petEvent({ tool: "Bash", command: "git commit -m 'fix jest config'", ok: true })?.kind).toBe(
+      "commit",
+    );
+  });
+
+  it.each(["Edit", "Write", "NotebookEdit"])("classifies %s tool names into edits", (tool) => {
+    expect(petEvent({ tool })?.kind).toBe("edit");
+  });
+
+  it("ignores denied calls with undefined ok", () => {
+    expect(petEvent({ tool: "Bash", command: "npm test", denied: true })).toBeUndefined();
+    const denied = petEvent({ tool: "Bash", command: "npm test", denied: true, ok: undefined });
+    expect(denied?.ok).toBeUndefined();
+  });
+
+  it("ignores unrelated tools", () => {
+    expect(petEvent({ tool: "Read" })).toBeUndefined();
+    expect(petEvent({ tool: "Bash", command: "echo hi" })).toBeUndefined();
+  });
+});
+
+describe("feed / level / stage", () => {
+  it("starts from zero with newPet", () => {
+    expect(newPet()).toEqual({ xp: 0, mood: 0, tests: 0, commits: 0, edits: 0 });
+  });
+
+  it("accumulates xp, mood and counters", () => {
+    const start = newPet();
+    const after = feed(start, { kind: "test-pass", ok: true, xp: XP["test-pass"], mood: MOOD["test-pass"] });
+    expect(after.xp).toBe(10);
+    expect(after.mood).toBe(8);
+    expect(after.tests).toBe(1);
+  });
+
+  it("derives level from xp and stage from level", () => {
+    expect(level(newPet())).toBe(1);
+    expect(level({ xp: 250, mood: 0, tests: 0, commits: 0, edits: 0 })).toBe(3);
+    expect(stage(1)).toBe("egg");
+    expect(stage(newPet())).toBe("egg");
+  });
+});
diff --git a/tests/mods-arcade/twenty48.test.ts b/tests/mods-arcade/twenty48.test.ts
new file mode 100644
index 0000000..5269435
--- /dev/null
+++ b/tests/mods-arcade/twenty48.test.ts
@@ -0,0 +1,89 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  banner,
+  directionForKey,
+  initialTwenty48State,
+  isFinished,
+  moveGrid,
+  slideRow,
+} from "../../plugin/mods/arcade/games/twenty48";
+
+describe("slideRow", () => {
+  it("merges pairs once and scores the merge", () => {
+    expect(slideRow([2, 2, 4, 4])).toEqual({ row: [4, 8, 0, 0], gained: 12 });
+  });
+
+  it("slides without merging distinct tiles", () => {
+    expect(slideRow([0, 2, 0, 4])).toEqual({ row: [2, 4, 0, 0], gained: 0 });
+  });
+});
+
+describe("moveGrid", () => {
+  it("reports moved false when nothing changes", () => {
+    const grid = [2, 4, 2, 4, 4, 2, 4, 2, 2, 4, 2, 4, 4, 2, 4, 2];
+    expect(moveGrid(grid, "left").moved).toBe(false);
+  });
+
+  it("moves tiles left with merges", () => {
+    const grid = [2, 2, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0];
+    const stepped = moveGrid(grid, "left");
+    expect(stepped.moved).toBe(true);
+    expect(stepped.grid.slice(0, 4)).toEqual([4, 0, 0, 0]);
+    expect(stepped.gained).toBe(4);
+  });
+});
+
+describe("directionForKey", () => {
+  it.each([
+    ["up", "up"],
+    ["w", "up"],
+    ["down", "down"],
+    ["s", "down"],
+    ["left", "left"],
+    ["a", "left"],
+    ["right", "right"],
+    ["d", "right"],
+  ])("maps %s", (name, expected) => {
+    expect(directionForKey(name)).toBe(expected);
+  });
+
+  it("rejects other keys", () => {
+    expect(directionForKey("q")).toBeNull();
+  });
+});
+
+describe("isFinished", () => {
+  it("is not finished with open cells", () => {
+    expect(isFinished(initialTwenty48State(() => 0).grid)).toBe(false);
+  });
+
+  it("is finished on a full grid with no merges", () => {
+    expect(isFinished([2, 4, 2, 4, 4, 2, 4, 2, 2, 4, 2, 4, 4, 2, 4, 2])).toBe(true);
+  });
+
+  it("is not finished when a merge is still available", () => {
+    expect(isFinished([2, 2, 4, 8, 16, 32, 64, 128, 256, 512, 1024, 2048, 4096, 8192, 16384, 32768])).toBe(
+      false,
+    );
+  });
+});
+
+describe("banner", () => {
+  it("pauses once per new done value", () => {
+    const seen = { current: 0 };
+    let pauses = 0;
+    expect(banner(0, seen, () => (pauses += 1))).toBeNull();
+    expect(banner(1, seen, () => (pauses += 1))).toContain("1");
+    expect(banner(1, seen, () => (pauses += 1))).toBeNull();
+    expect(pauses).toBe(1);
+  });
+});
+
+describe("initialTwenty48State", () => {
+  it("seeds two tiles on an empty board", () => {
+    const state = initialTwenty48State(() => 0);
+    expect(state.grid.filter((cell) => cell !== 0)).toHaveLength(2);
+    expect(state).toMatchObject({ score: 0, over: false, won: false, posted: false, paused: false });
+  });
+});
diff --git a/tests/open-args.test.ts b/tests/open-args.test.ts
index b92390a..1cf2629 100644
--- a/tests/open-args.test.ts
+++ b/tests/open-args.test.ts
@@ -387,7 +387,7 @@ describe("open command pure helpers", () => {
     const env = { PATH: "/bin", CLAUDE_CODE_CHILD_SESSION: "1" };
     const sanitized = sanitizeEnv(env);
 
-    expect(sanitized).toEqual({ PATH: "/bin", MISE_QUIET: "1" });
+    expect(sanitized).toEqual({ PATH: "/bin", MISE_QUIET: "1", CLAUDE_CODE_ENABLE_FUNCTION_HOOKS: "1" });
     expect(env.CLAUDE_CODE_CHILD_SESSION).toBe("1");
     // The caller's own object is never touched, whether a key is dropped or
     // added: it is process.env, and this runs before the launch.
@@ -836,6 +836,16 @@ describe("open command pure helpers", () => {
     expect(sanitizeEnv({ MISE_QUIET: "0" }).MISE_QUIET).toBe("0");
   });
 
+  // Function hooks back the codedeck arcade mod, and Claude Code only loads
+  // hook modules when the spawning environment enables them. A value of the
+  // user's own wins, which keeps an explicit opt-out working.
+  it("enables function hooks without overriding a setting of the user's own", () => {
+    expect(sanitizeEnv({}).CLAUDE_CODE_ENABLE_FUNCTION_HOOKS).toBe("1");
+    expect(
+      sanitizeEnv({ CLAUDE_CODE_ENABLE_FUNCTION_HOOKS: "0" }).CLAUDE_CODE_ENABLE_FUNCTION_HOOKS,
+    ).toBe("0");
+  });
+
   it("resolves a module-relative plugin directory", () => {
     const pluginDir = resolvePluginDir();
 

From 1deae198ea01cf646406db54b14eb1aa2e2762eb Mon Sep 17 00:00:00 2001
From: 4ndreello <4ndreello@users.noreply.github.com>
Date: Tue, 15 Sep 2026 09:38:21 -0300
Subject: [PATCH 2/8] fix(mods): Back arcade randomness with
 crypto.getRandomValues

Math.random draws flagged Sonar rule S2245 as vulnerabilities on new code and sank the Security Rating gate. Tile spawns and game picks now draw from a shared randomInt helper over getRandomValues, with a bounds test covering it.

Co-Authored-By: Claude <noreply@anthropic.com>
---
 plugin/hooks/boards/twenty48.tsx     |  3 ++-
 plugin/mods/arcade/games/auto.ts     |  4 +++-
 plugin/mods/arcade/games/random.ts   | 12 ++++++++++++
 plugin/mods/arcade/games/twenty48.ts |  4 +++-
 tests/mods-arcade/random.test.ts     | 27 +++++++++++++++++++++++++++
 5 files changed, 47 insertions(+), 3 deletions(-)
 create mode 100644 plugin/mods/arcade/games/random.ts
 create mode 100644 tests/mods-arcade/random.test.ts

diff --git a/plugin/hooks/boards/twenty48.tsx b/plugin/hooks/boards/twenty48.tsx
index 631272b..2abb15b 100644
--- a/plugin/hooks/boards/twenty48.tsx
+++ b/plugin/hooks/boards/twenty48.tsx
@@ -11,6 +11,7 @@ import {
   type SeenDone,
   type Twenty48State,
 } from "../../mods/arcade/games/twenty48.js";
+import { randomInt } from "../../mods/arcade/games/random.js";
 
 export interface Twenty48Props {
   done: number;
@@ -52,7 +53,7 @@ export default function Twenty48Board(props: Twenty48Props, surface: ClientSurfa
     if (direction === null) return;
     const stepped = moveGrid(state.grid, direction);
     if (!stepped.moved) return;
-    const grid = spawnTile(stepped.grid, () => Math.floor(Math.random() * 16));
+    const grid = spawnTile(stepped.grid, () => randomInt(16));
     const score = state.score + stepped.gained;
     const won = state.won || grid.some((cell) => cell >= 2048);
     const over = isFinished(grid);
diff --git a/plugin/mods/arcade/games/auto.ts b/plugin/mods/arcade/games/auto.ts
index c302aaa..a6ed9c5 100644
--- a/plugin/mods/arcade/games/auto.ts
+++ b/plugin/mods/arcade/games/auto.ts
@@ -1,3 +1,5 @@
+import { randomInt } from "./random.js";
+
 export interface AutoInput {
   lastTurnMs?: number;
   idle?: boolean;
@@ -32,6 +34,6 @@ export function pickAuto(input: AutoInput = {}): string {
 
 export function pickRandom(games: string[] = DROPIN_GAMES): string {
   if (games.length === 0) return DROPIN_GAMES[0];
-  const index = Math.floor(Math.random() * games.length);
+  const index = randomInt(games.length);
   return games[index];
 }
diff --git a/plugin/mods/arcade/games/random.ts b/plugin/mods/arcade/games/random.ts
new file mode 100644
index 0000000..710cee3
--- /dev/null
+++ b/plugin/mods/arcade/games/random.ts
@@ -0,0 +1,12 @@
+// Game randomness backed by the platform CSPRNG instead of Math.random.
+// Tile spawns and game picks are not secrets, but a predictable generator is
+// one confused refactor away from mattering, and Sonar flags Math.random
+// (typescript:S2245) wherever it appears.
+export function randomInt(bound: number): number {
+  if (!Number.isInteger(bound) || bound <= 0) {
+    throw new RangeError(`randomInt needs a positive integer bound, got ${bound}`);
+  }
+  const sample = new Uint32Array(1);
+  globalThis.crypto.getRandomValues(sample);
+  return sample[0] % bound;
+}
diff --git a/plugin/mods/arcade/games/twenty48.ts b/plugin/mods/arcade/games/twenty48.ts
index 58ada5c..afa0bc9 100644
--- a/plugin/mods/arcade/games/twenty48.ts
+++ b/plugin/mods/arcade/games/twenty48.ts
@@ -2,6 +2,8 @@
 // vitest runs it. The board components under plugin/hooks/boards/ own the
 // surface wiring (state, keys, pointer, score posts) and import from here.
 
+import { randomInt } from "./random.js";
+
 export interface SeenDone {
   current: number;
 }
@@ -122,7 +124,7 @@ export function isFinished(grid: number[]): boolean {
   return true;
 }
 
-export function initialTwenty48State(pick: () => number = () => Math.floor(Math.random() * 16)): Twenty48State {
+export function initialTwenty48State(pick: () => number = () => randomInt(16)): Twenty48State {
   const seeded = spawnTile(spawnTile(emptyGrid(), pick), pick);
   return { grid: seeded, score: 0, over: false, won: false, posted: false, paused: false, seenDone: 0 };
 }
diff --git a/tests/mods-arcade/random.test.ts b/tests/mods-arcade/random.test.ts
new file mode 100644
index 0000000..76bd37e
--- /dev/null
+++ b/tests/mods-arcade/random.test.ts
@@ -0,0 +1,27 @@
+import { describe, expect, it } from "vitest";
+
+import { randomInt } from "../../plugin/mods/arcade/games/random";
+
+describe("randomInt", () => {
+  it("rejects non-positive integer bounds", () => {
+    expect(() => randomInt(0)).toThrow(RangeError);
+    expect(() => randomInt(-4)).toThrow(RangeError);
+    expect(() => randomInt(1.5)).toThrow(RangeError);
+  });
+
+  it("returns 0 for a bound of 1", () => {
+    expect(randomInt(1)).toBe(0);
+  });
+
+  it("stays an integer inside the bound", () => {
+    const seen = new Set<number>();
+    for (let i = 0; i < 100; i += 1) {
+      const value = randomInt(16);
+      expect(Number.isInteger(value)).toBe(true);
+      expect(value).toBeGreaterThanOrEqual(0);
+      expect(value).toBeLessThan(16);
+      seen.add(value);
+    }
+    expect(seen.size).toBeGreaterThan(1);
+  });
+});

From 0f4a78d259ebbd4ee54e46491332071b163972ea Mon Sep 17 00:00:00 2001
From: 4ndreello <4ndreello@users.noreply.github.com>
Date: Tue, 15 Sep 2026 09:38:21 -0300
Subject: [PATCH 3/8] fix(ci): Pin plugin validation to claude 2.1.270

Function hooks events only exist from 2.1.269 on, so the 2.1.258 pin rejects the modules declaration outright. Move the pin to the version this feature was probed against.

Co-Authored-By: Claude <noreply@anthropic.com>
---
 .github/workflows/ci.yml | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 3945cd6..5eb26ba 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -68,6 +68,9 @@ jobs:
         # Pinned on purpose: this is the version every spelling in the plugin
         # contract was probed against, so the job checks the plugin under the
         # CLI the contract describes rather than whatever shipped today.
+        # Bumped to 2.1.270 for the arcade mod: function hooks (and their
+        # events) only exist from 2.1.269 on, so the old pin rejects the
+        # modules declaration outright.
         #
         # The install runs no lifecycle scripts, then invokes the one script
         # this package actually needs, by name. claude ships its real binary
@@ -76,7 +79,7 @@ jobs:
         # keeps that working while nothing else in the tree gets to run code
         # during install.
         run: |
-          npm i -g --ignore-scripts @anthropic-ai/claude-code@2.1.258
+          npm i -g --ignore-scripts @anthropic-ai/claude-code@2.1.270
           node "$(npm root -g)/@anthropic-ai/claude-code/install.cjs"
           claude --version
 

From 3d71f4dc2a209474919c59167782a10dea428ce4 Mon Sep 17 00:00:00 2001
From: 4ndreello <4ndreello@users.noreply.github.com>
Date: Tue, 15 Sep 2026 13:32:49 -0300
Subject: [PATCH 4/8] specs

---
 .../agy-empty-profile-swap/run-notes.md       | 22 ++++++++++
 .../agy-empty-profile-swap/run-report.md      | 42 ++++++++++++++++++
 .../features/cc-arcade-mod-port/run-notes.md  | 32 ++++++++++++++
 .../features/cc-arcade-mod-port/run-report.md | 43 +++++++++++++++++++
 4 files changed, 139 insertions(+)
 create mode 100644 .specs/features/agy-empty-profile-swap/run-notes.md
 create mode 100644 .specs/features/agy-empty-profile-swap/run-report.md
 create mode 100644 .specs/features/cc-arcade-mod-port/run-notes.md
 create mode 100644 .specs/features/cc-arcade-mod-port/run-report.md

diff --git a/.specs/features/agy-empty-profile-swap/run-notes.md b/.specs/features/agy-empty-profile-swap/run-notes.md
new file mode 100644
index 0000000..27f0afb
--- /dev/null
+++ b/.specs/features/agy-empty-profile-swap/run-notes.md
@@ -0,0 +1,22 @@
+# Run notes: agy-empty-profile-swap
+
+> APPEND-ONLY. New entries go at the bottom with a timestamp. Never rewrite or delete earlier entries, correct by appending.
+
+## 2026-09-15 00:33 UTC — bootstrap (bucket 1)
+
+- Created `.specs/features/agy-empty-profile-swap/` with `run-notes.md` and `run-report.md`.
+- Decisions so far:
+  - 2 discovery sessions completed: `2bbf antigravity-empty` and `050c profile-swap`.
+  - Both diffs empty, no code changes landed from discovery.
+- Bucket categories in use:
+  - Bucket 1: reversible file creation (docs, notes, specs). Proceed autonomously.
+  - Bucket 2: needs human confirm (deps, destructive git ops, scope changes).
+  - Bucket 3: never destructive (no force-push, no data loss, no secret exposure).
+- Assumption (logged): this bootstrap is bucket 1, reversible file creation under `.specs/`, no `src/` or `tests/` touched.
+
+## Closing — PR #84 opened (bucket 1 integration, bucket 2 merge deferred)
+
+- Integrated `05fb` (profile, completed exit 0, 129 tests) and `e80c` snapshot (antigravity, 29-43 tests across rounds, 3 reviews success) onto fresh `origin/main` worktree `/tmp/codedeck-pr` as branch `fix/agy-empty-profile-swap`.
+- Verification: 172 scoped tests green, tsc clean, diff-check clean, mutation probe 2 kills / 0 survivors (scratch reverted).
+- Commits `b7efe19` (profile) + `9b3c130` (antigravity); pushed; draft PR https://github.com/4ndreello/codedeck/pull/84.
+- Workers retired: `e80c` + `35c2` stopped, rest completed; pre-existing `7c8b`/`7f0d` left alone. Full detail folded into `run-report.md`.
diff --git a/.specs/features/agy-empty-profile-swap/run-report.md b/.specs/features/agy-empty-profile-swap/run-report.md
new file mode 100644
index 0000000..af1e1f4
--- /dev/null
+++ b/.specs/features/agy-empty-profile-swap/run-report.md
@@ -0,0 +1,42 @@
+# Run report: agy-empty-profile-swap
+
+Autonomous run covering two reported bugs: Antigravity sessions surfacing as an empty string, and setup with --profile showing another profile's content. Both fixed, verified, and proposed as draft PR #84.
+
+## Done
+
+- Branch: [fix/agy-empty-profile-swap](https://github.com/4ndreello/codedeck/tree/fix/agy-empty-profile-swap)
+- Commit: [8772491](https://github.com/4ndreello/codedeck/commit/8772491) (tip; base `07e693f` = origin/main)
+- PR: https://github.com/4ndreello/codedeck/pull/84 (MERGED via merge commit [ba05b32](https://github.com/4ndreello/codedeck/commit/ba05b32fef5003431473a65f827b82a77aedebf0); branch deleted locally and remotely)
+- Commit 1 `b7efe19` fix(profile): 5 files, 187 insertions, 10 deletions. `profile save` resolves the explicit target instead of the active profile, new `--profile` setups start from base with an empty agent map, role pin respects `loaded.defaultAgent`.
+- Commit 2 `9b3c130` fix(antigravity): 3 files, 807 insertions, 6 deletions. Stateful per-session delta accumulation with message reconstruction, `session.failed` on empty/whitespace-only results, lifecycle resets plus bounded replay of consumed output on reattach.
+- Discovery: `2bbf` (reviewer/antigravity, completed) reproduced the empty bug live with `result.response: ""` and zero `text.delta`; `050c` (auditor/antigravity, completed) ranked 4 profile root causes with file:line evidence. Both diffs empty (read-only).
+- Fixes: `05fb` (opencode, completed exit 0, 134 events) delivered the profile fix including a corrective cycle for 3 reviewer regressions; `e80c` (codex, stopped after delivery, 304 events) delivered the antigravity fix through 3 read-only review rounds (`798b`, `6a3a`, `4dab`, all completed success).
+- Verification quoted from the integration worktree: `Test Files 4 passed (4), Tests 172 passed (172)`, `tsc --noEmit` clean, `git diff --check` clean. Mutation probe: M1 (empty branch to completed) killed by 13 tests, M2 (restore root-agent leak) killed by 1 test; 2 kills, 0 survivors; scratch reverted.
+- CI fix after PR: SonarCloud failed the gate on `new_duplicated_lines_density` 16.2% (all 161 lines in `tests/antigravity-driver.test.ts`). Two test-only dedup commits (`2038078` helpers, `8772491` it.each + shared replay helper) brought it to 0.0%; full gate green with no src changes.
+
+## Assumptions I made
+
+- Bucket 1 (reversible, taken): per-session delta accumulation and empty-to-failed semantics; `{ ...baseConfig(loaded), agents: {} }` for new profiles; `loaded.defaultAgent` for the role pin; chunked accumulator with cap plus truncation marker; bounded fd-based replay read; notes/bootstrap files under `.specs/`.
+- Bucket 1 (process): nested `--role reviewer` runs landing on the root Claude binding instead of low-cost Antigravity was treated as lucky routing-around, not as license to use Antigravity for implementation.
+- Fixes were integrated by applying `codedeck diff 05fb` (299 lines) and `codedeck diff e80c` (935 lines) onto a fresh `origin/main` worktree, keeping the arcade agent's uncommitted checkout untouched.
+
+## Deferred / waiting for you
+
+- Merge PR #84 (publishing/sharing is bucket 2; the draft is ready for human review).
+- Decide the `profile save` fork semantics: `use a; save a-copy` no longer forks the active setup (documented in the save description; README line 196 still says "current setup" and was left untouched as outside owned files).
+- Decide what `unset` roles in a partial profile should mean at launch (currently falls back to driver defaults with a visible `general unset` line).
+- Probe why nested `codedeck run --role reviewer --no-worktree` from fix worktrees resolved to root Claude instead of active-profile Antigravity while `run.ts:55` reads correct; sessions `cff7`, `798b`, `6a3a`, `4dab`, `35c2` carry the exact commands.
+
+## Blocked / failed
+
+- `2bbf` delivered no finding text because the Antigravity harness itself returned `""` (299s, 820k input tokens); treated as live reproduction, profile diagnosis `050c` carried the reporting.
+- Fix worktrees ship no `node_modules`, so `pnpm vitest` fails there (`ERR_PNPM_IGNORED_BUILDS` / missing package); both fix workers correctly refused installs (bucket 2) and verification ran in the integration worktree via a temporary `node_modules` symlink (removed before commit).
+- `e80c` entered scope churn on its 4th review cycle (diff 361 to 807 insertions); capped with a complete-now directive and snapshotted. Residual 4dab perf notes (quadratic past-cap append, head-drop marker wording, driver-lifecycle mutation coverage) are partly addressed; anything further is follow-up.
+- Pre-existing, not a regression: `classifyFailure` throws on non-string `result.error` (4dab finding 5); `profile.ts:127` freezing inherited keys on re-save of partial profiles matches HEAD behavior.
+
+## Not covered
+
+- No live `agy` turn was ever spent (model spend, all evidence from parser/runtime/probes); empty-response shape against agy 1.2.2 in the wild stays unverified, as does `--conversation` init-frame behavior gating one stale-text scenario.
+- No full suite (repo batching rule); only `tests/antigravity-driver.test.ts` (43 tests), `tests/profiles.test.ts` (20), `tests/setup-cli-contract.test.ts` (26), `tests/setup-wizard.test.ts` (83).
+- No `dist/` rebuild check, no `gh pr checks` / SonarCloud (uncommitted at review time; CI will run on PR #84).
+- Picker rendering, `doctor`/`open`/`web` profile consumption beyond call-site reads, and empty-response handling in non-antigravity drivers.
diff --git a/.specs/features/cc-arcade-mod-port/run-notes.md b/.specs/features/cc-arcade-mod-port/run-notes.md
new file mode 100644
index 0000000..cfc7fcd
--- /dev/null
+++ b/.specs/features/cc-arcade-mod-port/run-notes.md
@@ -0,0 +1,32 @@
+# Run notes: cc-arcade-mod-port
+
+Autonomous run. Append-only. One line per entry. Time in UTC.
+
+- 2026-09-15T00:33Z | activation | autonomous mode invoked by human in orchestrator session | bucket: n/a | contract: never ask human, bucket1 reversible now with logged assumption, bucket2 irreversible deferred, route around blockers, parallelize for speed
+- 2026-09-15T00:33Z | assumption | slug cc-arcade-mod-port names this work item: port cc-arcade function-hooks Mod pattern into codedeck plugin | bucket: 1 | reason: reversible prose choice, directory created
+- 2026-09-15T00:33Z | assumption | prior swarm findings 2bab and e1ed treated as grounded input, not as delivered code | bucket: 1 | reason: read-only discovery, diffs empty, quoted test output trusted over success messages
+- 2026-09-15T00:33Z | decision | implementation split in 3 parallel slices by file ownership: SPEC owns .specs spec.md, MOD owns plugin hooks register plus boards plus pure logic plus new tests, INTEGRATION owns plugin manifests plus open plus docs | bucket: 1 | reason: avoids two workers in one file, reversible slice plan
+- 2026-09-15T00:33Z | constraint | no installs, fetches, or vendoring by any worker, including bunx remote fetches and npm minus g. scoped local test and build commands only. claude plugin validate allowed, already installed claude 2.1.270 | bucket: 2 deferred by contract | reason: network fetch and transitive code execution are irreversible
+- 2026-09-15T00:33Z | constraint | no pushes, no git clean, no reset hard, no shared state writes. workers leave changes uncommitted in worktrees for codedeck diff review | bucket: 2 deferred by contract | reason: publishing and destructive git actions need human
+- 2026-09-15T00:34Z | dispatch | SPEC worker 3c47 general worktree, MOD worker 6ffe general worktree, INTEGRATION worker 542f general worktree, all parallel | bucket: 1 | reason: implementation slices own disjoint file sets
+- 2026-09-15T00:34Z | registry | 3c47 SPEC owns .specs spec.md, 6ffe MOD owns register plus boards plus mods plus new tests, 542f INTEGRATION owns manifests plus src/open plus docs/mods.md | bucket: 1 | reason: slice ownership record
+- 2026-09-15T00:35Z | finding | SPEC worker 3c47 completed with spec.md verified on disk at .specs/features/cc-arcade-mod-port/spec.md, 3502 bytes, all five headings present. codedeck diff stat was empty because new files are untracked, lesson: verify new-file slices with git status in the worktree, not diff stat alone. SPEC accepted.
+- 2026-09-15T00:35Z | blocked | MOD worker 6ffe and INTEGRATION worker 542f failed, blame harness retryable: opencode sandbox auto-rejects external_directory reads under /tmp/cc-arcade-review referenced by both briefings. No code was written by either. Lesson: keep opencode workers hermetic inside the worktree, inline reference content in briefings.
+- 2026-09-15T00:35Z | finding | reference schema read directly by orchestrator, no worker fetch needed: cc-arcade hooks/hooks.json is exactly description plus modules with value ["./register.tsx"]. register.tsx shape is @jsx h pragma, import type Register from claude-code, export const register assignment, on() handlers for session.start command.run turn.start turn.complete tool.call ui.message ui.render AbovePrompt, Client with string literal module, store get and set with catch, ui resolve invalidate toast log, clock now, command register immediate true. Board shape is @jsx h pragma, ClientElements and ClientSurface type imports, default component export, never a local h.
+- 2026-09-15T00:35Z | dispatch | corrective cycle, one per failed slice: MOD retry and INTEGRATION retry, hermetic briefings with inlined reference, parallel | bucket: 1 | reason: failures are harness sandbox blocks, retryable, no drift to correct
+- 2026-09-15T00:36Z | dispatch | MOD RETRY worker 7125 general worktree, INTEGRATION RETRY worker c2c7 general worktree, parallel | bucket: 1 | reason: single corrective cycle per failed slice, hermetic briefings
+- 2026-09-15T00:53Z | finding | MOD worker 7125 completed exit 0, files verified on disk: register.tsx, boards common.tsx plus twenty48.tsx, mods arcade games pet best auto twenty48 plus index, tests mods-arcade four files. Claims 69 tests pass with empty-config caveat since worktree has no node_modules. Self reviewed via reviewer session 7f9c and acted on findings. Status: delivered, pending validation.
+- 2026-09-15T00:53Z | finding | INTEGRATION worker c2c7 completed exit 0, diff verified: hooks.json gains description plus modules register entry with hooks key intact, plugin.json 0.2.0 to 0.3.0, runtime.ts sanitizeEnv sets CLAUDE_CODE_ENABLE_FUNCTION_HOOKS default 1 with user opt-out preserved, docs/mods.md created. Validator accepts manifest shape, single missing-file error for register.tsx which the MOD slice supplies. Build plus scoped tests BLOCKED in worktree, no node_modules. No test files edited. Status: delivered, pending validation.
+- 2026-09-15T00:53Z | risk | MOD register uses engine call shapes that differ from the reference account: ui.render.invalidate versus ui.invalidate with event string, next with dollar versus next with event, resolve with string args versus resolve with event, namespaced arcade store keys versus upstream pet and best keys. Unresolvable without engine types. Flagged for the review slice to reconcile against discovery evidence.
+- 2026-09-15T00:53Z | dispatch | VALIDATION worker 3cf7 reviewer no-worktree, merged scratch tree plus per worktree checks plus mutation probe | bucket: 1 | reason: independent proof before integration decision
+- 2026-09-15T00:58Z | finding | merged scratch validation by 3cf7: npm run build green, scoped vitest 7 files 117 tests green, claude plugin validate on repo root passed. Manifest-path validate reports 1 error: register.tsx compiled line 32 reads dollar dot name as a value, engine contract requires dollar dot noun dot event at call sites. Reproduced by orchestrator in scratch. MUST FIX in remediation.
+- 2026-09-15T00:58Z | finding | orchestrator mutation probe in scratch, pure logic only, files restored after: XP value flip KILLED with 2 failures, isBetter inversion KILLED with 1 failure, auto threshold direction flip SURVIVED all 69 green. Survivor means the turn duration branch direction is untested. Test gap goes to remediation.
+- 2026-09-15T00:58Z | dispatch | REVIEW worker f8ef reviewer no-worktree read only over both worktrees plus spec | bucket: 1 | reason: final read-only review, findings remediated before delivery
+- 2026-09-15T01:03Z | finding | REVIEW worker f8ef completed: 3 BLOCKER plus 2 MAJOR plus 3 MINOR plus 2 INFO acceptable. Blockers all in register.tsx engine call shapes: dollar dot name read, invalidate shape, ui.render handler signatures. Majors: surface gate placement, upstream store key shape. Minors: callback param naming, .claude missing from gitignore, sanitizeEnv test gap. Sound: pet privacy, Client literals, no local h, banner, manifest shape, version bump, env opt-out, pure logic tests.
+- 2026-09-15T01:03Z | dispatch | FIX-MOD worker 8ac1 general in place in 7125 worktree owns register plus boards plus mods plus new tests, findings 1 to 6 plus auto pool refactor and threshold test. FIX-INT worker 223f general in place in c2c7 worktree owns gitignore plus open-args test, findings 7 and 8. Parallel, disjoint ownership | bucket: 1 | reason: remediate confirmed findings before delivery
+- 2026-09-15T01:12Z | finding | FIX-MOD round 2 plus round 3 done: handlers now positional dollar engine e event next continuation, command.run matcher with string e dot args, invalidate with event string, resolve and next with e, Client module relative ./boards/twenty48.tsx. Manifest validate now lists 7 events plus 7 dollar calls plus 1 surface module and passes. Root validate passes. Build green.
+- 2026-09-15T01:12Z | finding | revalidation in merged scratch after fixes: 8 files 211 tests green, manifest validate passed, root validate passed. Pre-existing open-args exact equality test needed the new env key added to its expectation, one line, done by orchestrator in FIX-INT worktree and recorded as assumption.
+- 2026-09-15T01:12Z | finding | mutation probe closed: threshold flip now KILLED by 2 failures in the new pickPool boundary test, scratch restored to fixed state and green again. Probe total 2 killed before, 1 survived then killed after the new test.
+- 2026-09-15T01:12Z | decision | changes stay uncommitted in worker worktrees 7125 MOD plus fixes and c2c7 INTEGRATION plus fixes for human integration. No merge no push per contract. Scratch at /tmp/opencode/validate-arcade holds the verified merged tree.
+- 2026-09-15T01:20Z | decision | human ordered PR open, bucket 2 publish action explicitly authorized. Branch feat/arcade-mod-port created from main, verified delta applied from 7125 plus c2c7 plus spec, build green, 211 tests green, both validates green. Commit db2207d with Co-Authored-By footer. Pushed and opened draft PR 83. Untracked process notes left out of the branch.
+- 2026-09-15T01:30Z | finding | PR 83 checks red: plugin job pinned claude 2.1.258 predates function hooks so session.start is not an event there, and Sonar gate failed Security Rating on 3x S2245 Math.random in new game code. Fixed on branch: randomInt helper over getRandomValues plus bounds test, CI pin to 2.1.270. Commits 4c888bb and fcb472b. All checks green: sonar pass, plugin pass, test 24 plus 26 pass.
diff --git a/.specs/features/cc-arcade-mod-port/run-report.md b/.specs/features/cc-arcade-mod-port/run-report.md
new file mode 100644
index 0000000..fe909d5
--- /dev/null
+++ b/.specs/features/cc-arcade-mod-port/run-report.md
@@ -0,0 +1,43 @@
+# Run report: cc-arcade-mod-port
+
+Autonomous run 2026-09-15. Goal: port the cc-arcade function-hooks Mod pattern (anthropics claude-code issue 91870, comment 5666255143) into the codedeck plugin as an `arcade` mod: `/arcade` command, AbovePrompt board, pet fed by tool calls, persisted best scores. Swarm of 9 worker sessions plus orchestrator verification. This report is self-contained.
+
+## Done
+
+Branch: [main](https://github.com/4ndreello/codedeck/tree/main). Commit: [07e693f7e0e5ac0a18123e26de1b9a125f31e850](https://github.com/4ndreello/codedeck/commit/07e693f7e0e5ac0a18123e26de1b9a125f31e850). No merge and no push happened in this run. The delivered changes sit uncommitted in two worker worktrees, verified merged in scratch at `/tmp/opencode/validate-arcade`:
+
+- MOD worktree `ra/you-are-implementing-for-coded-7125` (worker 7125, fixes 8ac1): `plugin/hooks/register.tsx` (7 engine events, matcher-based `/arcade`, picker plus 2048 Client board, banner pause, counter-only pet feeding), `plugin/hooks/boards/common.tsx` plus `twenty48.tsx`, `plugin/mods/arcade/` (pet, best, auto with pool picker, 2048 rules, index), `tests/mods-arcade/` (4 files).
+- INTEGRATION worktree `ra/you-are-implementing-for-coded-c2c7` (worker 542f retry c2c7, fixes 223f): `plugin/hooks/hooks.json` gains `modules: ["./register.tsx"]` with shell hooks intact, `plugin.json` 0.2.0 to 0.3.0, `src/open/runtime.ts` defaults `CLAUDE_CODE_ENABLE_FUNCTION_HOOKS` to 1 with user opt-out, `docs/mods.md` created, `.gitignore` gains `.claude/`, `tests/open-args.test.ts` gains env tests plus updated expectation.
+- Spec of record: `.specs/features/cc-arcade-mod-port/spec.md` (worker 3c47).
+
+Verified evidence, quoted from runs I executed or read from worker artifacts: `npm run build` green (tsc plus copy-plugin). Scoped vitest: `Test Files 8 passed (8)`, `Tests 211 passed (211)`. `claude plugin validate` on the manifest: `register.tsx hooks: session.start, command.run{command=arcade}, turn.start, turn.complete, tool.call, ui.message, ui.render`, `calls: $.command.register, $.store.get, $.store.set, $.ui.invalidate, $.ui.log, $.ui.resolve, $.ui.toast`, `surface modules: hooks/boards/twenty48.tsx`, `Validation passed`. Root validate: `Validation passed`. Mutation probe on pure logic: XP flip killed (2 failures), isBetter inversion killed (1 failure), threshold flip survived then killed (2 failures) after the new `pickPool` boundary test. Scratch restored to the fixed state and green afterward.
+
+## Assumptions I made
+
+- Slug `cc-arcade-mod-port` names this work item, and the run splits into SPEC, MOD, INTEGRATION slices owning disjoint file sets so no two workers share a file.
+- Prior read-only discovery (2bab on cc-arcade, e1ed on codedeck, both empty diffs) counts as grounded input, with quoted test output trusted over success messages.
+- Store keys follow the upstream shape (`pet`, `best:<game>`, `colorblind`) per review, not the namespaced draft.
+- One-line expectation update in `tests/open-args.test.ts` for the new env default was done by me directly in the FIX-INT worktree because the worker had finished; it mirrors intended behavior and the full scoped suite passes with it.
+
+## Deferred / waiting for you
+
+- Merge the two worktree branches into main, and any push. Both are retirement-ready: `7125` holds MOD plus fixes, `c2c7` holds INTEGRATION plus fixes.
+- Any dependency install, fetch, or vendor action, including remote `bunx` fetches. All runs used already installed tools (claude 2.1.270, local vitest).
+- Live verification in an interactive Claude Code PTY with `CLAUDE_CODE_ENABLE_FUNCTION_HOOKS=1`: real drawing above the prompt, click for keyboard focus, Esc behavior, frame pacing.
+- Running `/plugin-types` to generate `.claude/types` and the full test suite.
+- Product call: grow beyond the single 2048 demo board toward more games, or keep the mod minimal.
+
+## Blocked / failed
+
+- First MOD (6ffe) and INTEGRATION (542f) attempts failed before writing anything: the opencode harness sandbox auto-rejected reads outside the worktree referenced by their briefings (blame harness, retryable). Recovered with one hermetic corrective cycle each (7125, c2c7), both delivered.
+- Manifest validation failed twice during the run and both were fixed: `$.name` read as a value, then handler parameter order (`$` engine first, `e` event second, `e.args` a string), then the Client module path made relative (`./boards/twenty48.tsx`). Each fix was re-validated to green.
+- Validation worker 3cf7 finished without a readable final summary event, so its verdict was reconstructed from its 89 tool outputs (build, tests, validates, file listings) plus my own reruns. Nothing was taken on trust: every quoted result above was reproduced in scratch.
+- One pre-existing `open-args` exact-equality test broke on the intended new env key and was updated as noted above.
+
+## Not covered
+
+- The other eight games, doom, and the pet board: explicitly out of scope in the spec, one demo board delivered.
+- Desktop, mobile, and headless rendering: terminal only by design and by engine constraint.
+- `oxlint` and upstream `bun test`: remote fetch and out of scope; pure logic is covered by the new vitest files instead.
+- Cross-machine score sync: scores and pet live in the local plugin store.
+- Engine-type strictness beyond what `claude plugin validate` checks: `/plugin-types` output was never generated here.

From db70d2ac09083b82f71b6b7a55f073a6ec3c390e Mon Sep 17 00:00:00 2001
From: 4ndreello <4ndreello@users.noreply.github.com>
Date: Sat, 19 Sep 2026 23:01:13 -0300
Subject: [PATCH 5/8] feat(mods): Replace the arcade with the orchestrator
 agents pane

The arcade drew a game above the prompt. What the run actually needs there is
the `codedeck web` canvas, so this deletes the arcade slice and puts an ASCII
version of that canvas in a docked pane on the right: one card per agent of
the current run, harness glyph, status and age, ordered by last touch, with a
header counting sessions and a footer legend.

The pane opens at session start when CODEDECK_RUN_ID is set, so a plain
`claude --plugin-dir` session gets nothing rather than a permanently empty
dock. It refreshes on turn.complete and on tool.call behind a 1.5s gap, and
redraws only when the snapshot actually changed.

A button above the prompt is the way back in. The pane can be closed by the
engine's own close box, which fires no hook at all, so the module cannot track
whether the pane is open; the button therefore only ever opens, never toggles,
and there is no state to desync. It also re-syncs the flag /band reads.
Removal and replacement land together because the previous register.tsx
imports the arcade modules, so deleting them alone leaves a tree that cannot
build.

The pure layer never throws, because a throw inside a render hook drops the
whole drawing, and it sizes itself from what the pane reports rather than from
an assumed width.

Co-Authored-By: Claude <noreply@anthropic.com>
---
 .github/workflows/ci.yml                      |   6 +-
 .../orchestrator-agents-band/design.md        | 285 ++++++++
 .../reference-register.tsx                    | 131 ++++
 .../features/orchestrator-agents-band/spec.md | 209 ++++++
 .../orchestrator-agents-band/tasks.md         | 354 ++++++++++
 plugin/hooks/boards/common.tsx                |  54 --
 plugin/hooks/boards/twenty48.tsx              |  96 ---
 plugin/hooks/hooks.json                       |   2 +-
 plugin/hooks/register.tsx                     | 311 ++++++---
 plugin/mods/agents/pane.ts                    | 440 +++++++++++++
 plugin/mods/agents/parse.ts                   |  29 +
 plugin/mods/agents/types.ts                   |  43 ++
 plugin/mods/arcade/games/auto.ts              |  39 --
 plugin/mods/arcade/games/best.ts              |   9 -
 plugin/mods/arcade/games/pet.ts               | 119 ----
 plugin/mods/arcade/games/random.ts            |  12 -
 plugin/mods/arcade/games/twenty48.ts          | 138 ----
 plugin/mods/arcade/index.ts                   |  13 -
 scripts/pane-mock.mjs                         | 105 +++
 scripts/pane-probe.sh                         | 178 +++++
 src/open/runtime.ts                           |   2 +-
 tests/mods-agents/pane.test.ts                | 616 ++++++++++++++++++
 tests/mods-agents/parse.test.ts               |  55 ++
 tests/mods-arcade/auto.test.ts                |  50 --
 tests/mods-arcade/best.test.ts                |  19 -
 tests/mods-arcade/pet.test.ts                 | 118 ----
 tests/mods-arcade/random.test.ts              |  27 -
 tests/mods-arcade/twenty48.test.ts            |  89 ---
 tests/open-args.test.ts                       |   2 +-
 29 files changed, 2671 insertions(+), 880 deletions(-)
 create mode 100644 .specs/features/orchestrator-agents-band/design.md
 create mode 100644 .specs/features/orchestrator-agents-band/reference-register.tsx
 create mode 100644 .specs/features/orchestrator-agents-band/spec.md
 create mode 100644 .specs/features/orchestrator-agents-band/tasks.md
 delete mode 100644 plugin/hooks/boards/common.tsx
 delete mode 100644 plugin/hooks/boards/twenty48.tsx
 create mode 100644 plugin/mods/agents/pane.ts
 create mode 100644 plugin/mods/agents/parse.ts
 create mode 100644 plugin/mods/agents/types.ts
 delete mode 100644 plugin/mods/arcade/games/auto.ts
 delete mode 100644 plugin/mods/arcade/games/best.ts
 delete mode 100644 plugin/mods/arcade/games/pet.ts
 delete mode 100644 plugin/mods/arcade/games/random.ts
 delete mode 100644 plugin/mods/arcade/games/twenty48.ts
 delete mode 100644 plugin/mods/arcade/index.ts
 create mode 100644 scripts/pane-mock.mjs
 create mode 100755 scripts/pane-probe.sh
 create mode 100644 tests/mods-agents/pane.test.ts
 create mode 100644 tests/mods-agents/parse.test.ts
 delete mode 100644 tests/mods-arcade/auto.test.ts
 delete mode 100644 tests/mods-arcade/best.test.ts
 delete mode 100644 tests/mods-arcade/pet.test.ts
 delete mode 100644 tests/mods-arcade/random.test.ts
 delete mode 100644 tests/mods-arcade/twenty48.test.ts

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 5eb26ba..b235d9f 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -68,9 +68,9 @@ jobs:
         # Pinned on purpose: this is the version every spelling in the plugin
         # contract was probed against, so the job checks the plugin under the
         # CLI the contract describes rather than whatever shipped today.
-        # Bumped to 2.1.270 for the arcade mod: function hooks (and their
-        # events) only exist from 2.1.269 on, so the old pin rejects the
-        # modules declaration outright.
+        # Bumped to 2.1.270 when the plugin gained a function-hooks module:
+        # function hooks (and their events) only exist from 2.1.269 on, so the
+        # old pin rejects the modules declaration outright.
         #
         # The install runs no lifecycle scripts, then invokes the one script
         # this package actually needs, by name. claude ships its real binary
diff --git a/.specs/features/orchestrator-agents-band/design.md b/.specs/features/orchestrator-agents-band/design.md
new file mode 100644
index 0000000..2438b8e
--- /dev/null
+++ b/.specs/features/orchestrator-agents-band/design.md
@@ -0,0 +1,285 @@
+# Design: orchestrator agents pane
+
+> **Revised.** The first cut drew a table above the prompt. It worked, and it
+> was rejected: the ask is the `codedeck web` canvas, as ASCII, docked on the
+> right. `AbovePrompt` is gone from the plan. What survives is the pure layer
+> and every engine fact below, all of which were paid for.
+
+## Pane contract, verified live
+
+One probe module, one PTY session, dumping the render event:
+
+```
+requestId = "wide"                     // which pane is being drawn, NOT e.id
+viewport  = { columns: 120, rows: 50 }
+props     = { title, isFocused, bodyColumns: 89, placement: "dock", scroll, view }
+```
+
+- `$.ui.open({ id })` opens a docked pane. `{ id, width, side: "right" }` is
+  also accepted. `id` is 1 to 64 of letters, digits, `_` or `-`.
+- `ui.render` then fires with `e.component === "Pane"`, and the module tells
+  panes apart by `e.requestId`, which carries the id passed to open.
+- **`e.props.bodyColumns` is the usable content width.** The pane reports its
+  own size, so the drawing adapts instead of asking. A requested `width` is
+  accepted but is not what comes back.
+- `e.id` is `undefined` on the render event. Reaching for it is the obvious
+  mistake and it fails silently.
+- **`e.props.scroll` is `{ offset, bodyRows }`**, and `bodyRows` is the usable
+  height: 44 in a 50 row terminal. Anything taller is clipped at the bottom
+  with no warning, which eats the footer first. Measured together in one 200
+  by 50 terminal: `bodyColumns` 89, `scroll.bodyRows` 44, `viewport`
+  `{ columns: 110, rows: 50 }`, so `viewport` is the space left over for the
+  rest of the screen, not the terminal and not the pane.
+- A requested `width` is not merely different from what comes back, it is
+  **ignored**: asking for 46 still returned `bodyColumns: 89`. The engine sizes
+  the dock and the module adapts, full stop.
+- **`Box` lays its children out in a row.** A list of `Text` lines needs
+  `<Box flexDirection="column">` or the drawing is shredded into vertical
+  slivers. This cost a day: every validate passed, the module loaded, the hook
+  ran, zero errors were raised, and the pane was garbage. The only instrument
+  that sees it is a screen capture, which is why T5 exists.
+- The pane draws from session start, as soon as one refresh has a snapshot. It
+  does not wait for a turn. An early probe concluded the opposite by reading a
+  PTY byte stream, where a docked pane's repaints interleave and a grep for the
+  header finds nothing even when the pane is perfect. Use `tmux capture-pane`,
+  which returns the settled screen.
+
+## Old design below, kept for the pure layer and the failure posture
+
+
+Source of truth: `spec.md` in this directory. Where the two disagree, the spec
+wins and this file is the one that is wrong.
+
+## Shape
+
+Two layers, split so that everything with logic in it is testable without an
+engine, and everything that needs an engine has no logic in it.
+
+```
+  plugin/mods/agents/           pure, no engine imports, unit tested
+    types.ts      the row shape and the snapshot shape
+    select.ts     filter to this run, drop the orchestrator, order, budget
+    format.ts     one row to one line, truncation, the overflow line
+    parse.ts      raw stdout to a snapshot, or a failure
+
+  plugin/hooks/register.tsx     engine only, no logic worth testing
+    ui.render     gate, resolve, draw the lines the pure layer produced
+    turn.complete start a refresh
+    tool.call     start a refresh, throttled
+    command.run   /agents toggles visibility
+```
+
+The rule that keeps this honest: `register.tsx` may hold state and call the
+engine, but it may not decide anything. Every decision, which rows, which
+order, what a line says, how a fault is handled, lives in `plugin/mods/agents/`
+where a unit test can reach it.
+
+## Why no Client
+
+Proven in a live PTY session: a hooks module drawing `Box`, `Text` and `Button`
+straight from `$.ui.resolve(e, ...)` renders correctly above the prompt, and a
+`Button` carrying `key`, `label` and `onPress` works.
+
+Also proven, in the same way: a `Client` surface module's state does not
+survive across renders in the arcade port, and the engine's guard text blames
+setting state during render. That defect is open and unowned.
+
+The band is read-only and needs no keyboard focus, so it needs no Client. This
+is not a preference, it is the reason the band can ship while the game cannot.
+
+## Data flow
+
+```
+tool.call / turn.complete
+        |
+        v
+  refresh()  --- in flight? --> drop
+        |
+        v
+  $.process.run(["codedeck", "ps", "--all", "--json"])
+        |
+        v
+  parseSnapshot(stdout)  ->  Snapshot | undefined
+        |                        |
+     failure                  success
+        |                        |
+  keep last good          differs from drawn?
+                                 |
+                                yes -> $.ui.invalidate("ui.render")
+```
+
+`$.process.run` is a verified engine capability. Full contract, read out of
+the engine implementation rather than inferred:
+
+- `$.process.run(argv, init?)`. **Both arguments are positional.** `argv` is a
+  string array whose first element is the command. No shell, so no quoting
+  question.
+- `init` is the optional second argument, `{ cwd?, env?, stdin?, timeoutMs? }`.
+  `cwd` resolves against the session cwd, `env` merges over the inherited env,
+  `stdin` is piped only when supplied. `timeoutMs` is a whole number, 1 to
+  600000.
+- default `timeoutMs` 30000, capped by an engine maximum. Each of stdout and
+  stderr is captured and truncated at 4194304 characters. The child runs under
+  cgroup class `plugin`.
+- resolves to `{ exitCode, stdout, stderr }`. `exitCode` falls back to `1` when
+  the process closes without one.
+- **throws** in two cases, both of which the caller must catch: timeout or
+  abort (`$.process.run(codedeck) aborted: still running after 30000ms`) and
+  failure to start (`$.process.run(codedeck) failed to start: <reason>`).
+
+Two rules that only a live session revealed, both of which cost a worker:
+
+- Calling it the way the host-side implementation reads, `$.process.run({ argv:
+  [...] })`, is **refused**: `process.run: takes argv, a non-empty list of
+  strings naming the command first`. The host function does destructure
+  `{ argv, init }`, but the module-side proxy packs the positional arguments
+  into that object first. Reading the implementation and skipping the proxy is
+  how the wrong shape got into this document in the first place.
+- `$` may be passed into a helper function, verified. What is refused is pulling
+  a namespace off it: `const P = $.process` fails to load the module with
+  `$.process is used as a value (a noun...)`. The engine analyses the compiled
+  source statically, so every engine call has to appear literally as
+  `$.<namespace>.<method>(...)` at the call site.
+
+Verified live, in a PTY session, one probe module, four shapes:
+
+```
+$.process.run(["echo","hi"])                        OK, exit 0
+$.process.run(ARGV)  // module-level const          OK, so no literal rule on the array
+$.process.run(["echo","hi"], { timeoutMs: 5000 })   OK, init is positional
+$.process.run(["codedeck","ps","--all","--json"])   OK, exit 0, 73279 chars
+$.process.run({ argv: ["echo","hi"] })              REFUSED
+```
+
+`codedeck ps --json` and `codedeck ps --all --json` return the same 100 rows and
+the same 73685 bytes on this machine: `--all` changes the table, not the JSON.
+`ps` has no run filter, so the band over-fetches and narrows in `select.ts`. Of
+those 100 rows, 18 belonged to the run under test.
+
+The run id comes from `CODEDECK_RUN_ID`, which `codedeck open` already sets and
+which `plugin/statusline.sh` already depends on for its `N agents` field. The
+band reads it the same way.
+
+### Why not the web server
+
+`codedeck web` serves `/api/sessions` and an SSE stream, and `$.http.fetch`
+exists. Rejected: it makes the band depend on a server the user has to remember
+to start, and it would show nothing with no way to say why. `$.process.run`
+against the same CLI the human uses has no such precondition.
+
+## Frozen interface
+
+Both implementation slices are written against exactly this. Neither may change
+it without the other being redispatched.
+
+```ts
+// plugin/mods/agents/types.ts
+export interface SessionRow {
+  id: string;
+  runId?: string;
+  origin?: string | null;
+  name?: string;
+  agent?: string;
+  status?: string;
+  updatedAt?: string;
+}
+
+export interface BandRow {
+  id: string;
+  status: string;
+  agent: string;
+  name: string;
+}
+
+export interface Snapshot {
+  rows: BandRow[];
+  hidden: number;      // rows beyond the budget
+}
+
+// plugin/mods/agents/parse.ts
+// Raw stdout to rows. Returns undefined for anything that is not a JSON array,
+// which is how a failed or truncated command is reported. Never throws.
+export function parseRows(stdout: string): SessionRow[] | undefined;
+
+// plugin/mods/agents/select.ts
+export const ROW_BUDGET = 8;
+// Filter to runId, drop origin "open", order by updatedAt descending,
+// cut to budget. Missing updatedAt sorts last. Never throws.
+export function selectRows(
+  rows: SessionRow[],
+  runId: string,
+  budget?: number,
+): Snapshot;
+
+// plugin/mods/agents/format.ts
+export const NAME_WIDTH = 28;
+// One row to one line. Missing fields render as "-". Never throws.
+export function formatRow(row: BandRow): string;
+// Header plus rows plus the overflow line when hidden > 0. Empty array when
+// the snapshot holds no rows, which is how "draw nothing" is expressed.
+export function formatBand(snapshot: Snapshot): string[];
+```
+
+`register.tsx` consumes those four functions and nothing else from the mod.
+
+## Drawing
+
+One `Box` holding one `Text` per line, returned as a single element with the
+downstream drawing nested as its last child:
+
+```tsx
+return (
+  <Box>
+    {lines.map((line) => <Text key={line}>{line}</Text>)}
+    {await next(e)}
+  </Box>
+);
+```
+
+Contract points this satisfies, each one a bug the arcade port actually hit:
+
+- exactly one tree element returned, never an array
+- drawn only for `e.component === "AbovePrompt"` and `e.surface === "terminal"`
+- capitalized tags, taken from `$.ui.resolve`, because the intrinsic table is
+  `{ Box: 'Box', Text: 'Text' }`
+- no `Client`, so no surface state
+
+## State in the hooks module
+
+Closure state in `register`, which is the path proven to work:
+
+```
+let snapshot: Snapshot | undefined   // last good, undefined until first success
+let inFlight = false
+let lastRefreshEndedAt = 0
+let visible = true                   // /agents toggles
+```
+
+`snapshot` staying `undefined` is how AC18 is met: nothing drawn until a
+refresh has succeeded once.
+
+## Failure posture
+
+Every fault degrades to the last good snapshot and never to a thrown hook. A
+thrown hook is worse than a stale band: the engine drops the whole drawing, and
+that is how the arcade port lost its picker.
+
+| Fault | Behaviour |
+|---|---|
+| command exits non-zero | keep last good, no invalidate |
+| command times out | keep last good, no invalidate |
+| stdout is not a JSON array | keep last good, no invalidate |
+| a row is missing a field | draw the row, field renders as `-` |
+| no refresh has ever succeeded | draw nothing |
+| `CODEDECK_RUN_ID` absent | draw nothing, pass through |
+
+## Open risks
+
+- ~~`$.process.run` may be refused by a permission or capability gate.~~
+  Closed. The extracted implementation contains no permission or capability
+  check: it resolves the command and spawns it directly, with the only guards
+  being the timeout, the output cap and the `plugin` cgroup class. The residual
+  risk is now just first use, which the probe slice covers.
+- The band competes for vertical space with whatever else draws above the
+  prompt. The row budget bounds it, but the right budget is a matter of taste
+  and may need a second look once it is on screen.
diff --git a/.specs/features/orchestrator-agents-band/reference-register.tsx b/.specs/features/orchestrator-agents-band/reference-register.tsx
new file mode 100644
index 0000000..7a33262
--- /dev/null
+++ b/.specs/features/orchestrator-agents-band/reference-register.tsx
@@ -0,0 +1,131 @@
+/** @jsx h */
+import type { Register } from "claude-code";
+
+import { feed, newPet, petEvent, type Pet } from "../mods/arcade/games/pet.js";
+import { isBetter } from "../mods/arcade/games/best.js";
+import { ARCADE_BOARDS } from "../mods/arcade/index.js";
+
+const PET_KEY = "pet";
+const COLORBLIND_KEY = "colorblind";
+const bestKey = (game: string): string => `best:${game}`;
+
+export const register: Register = (on) => {
+  let pet: Pet = newPet();
+  let best: Record<string, number> = {};
+  let colorblind = false;
+  let turnClock = 0;
+  let lastTurnMs = 0;
+  let openBoard: string | null = null;
+  let done = 0;
+
+  on("session.start", async ($, e, next) => {
+    try {
+      const savedPet = await $.store.get(PET_KEY);
+      if (savedPet) pet = savedPet as Pet;
+      for (const board of ARCADE_BOARDS) {
+        const saved = await $.store.get(bestKey(board));
+        if (typeof saved === "number") best[board] = saved;
+      }
+      const savedColorblind = await $.store.get(COLORBLIND_KEY);
+      if (typeof savedColorblind === "boolean") colorblind = savedColorblind;
+    } catch (err) {
+      $.ui.log(`arcade restore failed: ${String(err)}`);
+    }
+    await $.command.register({ name: "arcade", description: "play 2048 above the prompt while Claude works", immediate: true });
+    return next(e);
+  });
+
+  on("command.run", { command: "arcade" }, async ($, e) => {
+    const arg = e.args.trim().toLowerCase();
+    if (arg === "") {
+      openBoard = null;
+      await $.ui.invalidate("ui.render");
+      return { text: "arcade boards: twenty48" };
+    }
+    if (arg === "list") {
+      return { text: "arcade boards: twenty48" };
+    }
+    if (arg === "open" || arg.startsWith("open ")) {
+      const name = arg === "open" ? "twenty48" : arg.slice("open ".length).trim() || "twenty48";
+      if (!(ARCADE_BOARDS as readonly string[]).includes(name)) {
+        return { text: `no game called "${name}"` };
+      }
+      openBoard = name;
+      await $.ui.invalidate("ui.render");
+      return { text: `opened ${name}` };
+    }
+    if (arg === "stop") {
+      openBoard = null;
+      await $.ui.invalidate("ui.render");
+      return { text: "arcade closed" };
+    }
+    return { text: `no game called "${arg}"` };
+  });
+
+  on("turn.start", async ($, e, next) => {
+    turnClock = Date.now();
+    return next(e);
+  });
+
+  on("turn.complete", async ($, e, next) => {
+    lastTurnMs = Date.now() - turnClock;
+    void lastTurnMs;
+    done += 1;
+    await $.ui.invalidate("ui.render");
+    return next(e);
+  });
+
+  on("tool.call", async ($, e, next) => {
+    const r = await next(e);
+    // petEvent already ignores denied calls; only classified events feed the pet.
+    const command = (e as { command?: string }).command ?? undefined;
+    const denied = "deny" in (r as Record<string, unknown>);
+    const ok = denied ? undefined : !(r as { isError?: boolean }).isError;
+    const event = petEvent({ tool: e.tool, command, ok, denied });
+    if (event !== undefined) {
+      pet = feed(pet, event);
+      await $.store.set(PET_KEY, { xp: pet.xp, mood: pet.mood, tests: pet.tests, commits: pet.commits, edits: pet.edits });
+    }
+    return r;
+  });
+
+  on("ui.message", async ($, e, next) => {
+    const posted = e.data as { game?: string; score?: number } | undefined;
+    if (!posted || typeof posted.game !== "string" || typeof posted.score !== "number") {
+      return next(e);
+    }
+    if (isBetter(posted.game, posted.score, best)) {
+      best[posted.game] = posted.score;
+      await $.store.set(bestKey(posted.game), posted.score);
+      $.ui.toast(`New arcade record in ${posted.game}: ${posted.score}`);
+    }
+    return { game: posted.game, score: posted.score };
+  });
+
+  on("ui.render", async ($, e, next) => {
+    if (e.surface !== "terminal" || e.component !== "AbovePrompt") return await next(e);
+    const { Box, Button, Client, Text } = await $.ui.resolve(e, "Box", "Button", "Client", "Text");
+    if (openBoard === null) {
+      return (
+        <Box>
+          <Text>Arcade boards</Text>
+          <Button
+            key="twenty48"
+            label="twenty48"
+            onPress={async () => {
+              openBoard = "twenty48";
+              await $.ui.invalidate("ui.render");
+            }}
+          />
+          {await next(e)}
+        </Box>
+      );
+    }
+    return (
+      <Box>
+        <Client key="twenty48" module="./boards/twenty48.tsx" props={{ done, colorblind, best: best[openBoard] ?? 0 }} />
+        {await next(e)}
+      </Box>
+    );
+  });
+};
diff --git a/.specs/features/orchestrator-agents-band/spec.md b/.specs/features/orchestrator-agents-band/spec.md
new file mode 100644
index 0000000..2e8ce30
--- /dev/null
+++ b/.specs/features/orchestrator-agents-band/spec.md
@@ -0,0 +1,209 @@
+# Orchestrator agents band
+
+## Goal
+
+Draw the orchestrator's own workers as an ASCII panel above the prompt, inside
+the Claude Code session that dispatched them. What `codedeck web --open` shows
+in a browser for every run, scoped to this run alone, in the terminal, for
+free.
+
+The orchestrator dispatches workers and then goes blind: it has to call
+`codedeck ps` and read a 100-row table to learn what its own four workers are
+doing. The band closes that loop without leaving the prompt and without
+spending a token.
+
+## Verified ground
+
+Every fact below was confirmed by running the thing, not by reading docs.
+
+### The run link already exists
+
+- `codedeck open` sets `CODEDECK_RUN_ID` in the session environment. Confirmed
+  live: `CODEDECK_RUN_ID=f5fd` in the orchestrator session that wrote this spec.
+- Every dispatched worker carries `runId` equal to the orchestrator's session
+  id. Confirmed from `codedeck run --bg --json` output: workers `c774`, `1f57`,
+  `2109`, `1c23` all returned `"runId":"f5fd"`.
+- `codedeck ps --all --json` returns a flat array; each row carries `id`,
+  `runId`, `origin`, `name`, `agent`, `model`, `status`, `repository`, `cwd`,
+  `createdAt`, `updatedAt`.
+- Filtering that array on `runId === CODEDECK_RUN_ID` returned exactly the 9
+  sessions of this run: 8 workers plus the orchestrator itself, which is the
+  only row with `origin === "open"`.
+- `plugin/statusline.sh` already uses this exact scoping (`CODEDECK_RUN_ID` plus
+  `codedeck usage <runId> --json`) to print the `N agents` field. The band is
+  the same idea with rows instead of a count.
+
+### The engine can do this
+
+Extracted from the compiled `claude` binary (2.1.273) and, where marked,
+confirmed in a live PTY session:
+
+- `$.process.run(argv, init?)` is a real capability, both arguments positional. Default timeout 30000ms,
+  output capped at 4MB, child spawned under cgroup class `plugin`, stdout and
+  stderr captured. This is the data transport: no web server has to be running.
+- A hooks module can draw directly in `ui.render` with the table
+  `$.ui.resolve(e, ...)` returns: `Box, Text, Button, Input, Select, Link, Code,
+  Client, Raster, Svg`. **Confirmed live**: a `Box` holding a `Text` and a
+  `Button` drew above the prompt and the button rendered as `[ twenty48 ]`.
+- `ui.render` must return exactly one tree element. Engine check, verbatim:
+  `check: (e) => ne(e) && typeof e.type === "string" ? void 0 : "something that
+  is not a tree element"`. An array is rejected and the whole drawing is dropped.
+- `ui.render` fires per component. Known names: `AbovePrompt`, `Pane`,
+  `UserMessage`, `ToolUse`, `ToolResult`. Drawing for all of them paints the
+  panel over every message row.
+- A `Button` must carry `onPress`; the engine names the spelling itself:
+  `<Button key label onPress>`.
+- Intrinsic tag names are capitalized and there are two: `const INTRINSIC =
+  { Box: 'Box', Text: 'Text' }`.
+- `$.command.register` takes `{ name, description, argumentHint?, immediate? }`
+  and rejects a missing description.
+
+### The trap this design walks around
+
+A `Client` surface module is the engine's mechanism for keyboard and pointer
+interactivity, and it owns its own state through `surface.setState`. In the
+arcade port that state never persisted: after 16 keypresses the board still
+drew 2 tiles and score 0, with tile positions changing between frames, which is
+a fresh `initialTwenty48State()` on every render. The engine's own guard text
+points at the cause: *"set its state again after each of N renders, nothing
+heard between; set state on a pointer or key event, a tick, a press or new
+props, and let a render settle"*, and the board seeds its state by calling
+`surface.setState` during render. That bug is unsolved.
+
+**The band therefore mounts no Client.** It is a read-only drawing produced by
+the hooks module, whose state is ordinary closure state in `register.tsx`, which
+is proven to work. The one interactive affordance this spec allows is a
+`Button`, whose `onPress` is a hooks-module closure and which is proven to work.
+
+## Acceptance criteria
+
+### Drawing
+
+- AC1: WHEN a terminal session starts with function hooks enabled and
+  `CODEDECK_RUN_ID` set in its environment, THEN the mod SHALL draw a band above
+  the prompt listing the sessions whose `runId` equals that value.
+- AC2: The band SHALL exclude the row whose `origin` is `open`, which is the
+  orchestrator's own session.
+- AC3: WHERE `CODEDECK_RUN_ID` is absent from the environment, the mod SHALL
+  draw nothing and SHALL return `next(e)` unchanged.
+- AC4: WHEN the run has zero worker rows, THEN the mod SHALL draw nothing rather
+  than an empty frame.
+- AC5: The mod SHALL draw only when `e.component` is `AbovePrompt` and
+  `e.surface` is `terminal`, and SHALL return `next(e)` unchanged for every
+  other event.
+- AC6: The `ui.render` handler SHALL return exactly one tree element, never an
+  array.
+- AC7: The mod SHALL NOT mount a `Client` surface module.
+
+### Rows
+
+- AC8: Each worker row SHALL carry the session id, the status, the harness, and
+  the slice name.
+- AC9: A row SHALL occupy exactly one terminal line, with the slice name
+  truncated rather than wrapped.
+- AC10: Rows SHALL be ordered by `updatedAt`, most recent first.
+- AC11: WHEN the run holds more worker rows than the row budget, THEN the band
+  SHALL draw the first rows up to the budget and SHALL end with a line stating
+  how many rows were left out.
+- AC12: The band SHALL never exceed its row budget in drawn lines, header and
+  overflow line included.
+
+### Refresh
+
+- AC13: WHEN a turn completes, THEN the mod SHALL start a data refresh.
+- AC13a: WHEN a tool call completes, THEN the mod SHALL start a data refresh,
+  subject to the throttle in AC16a.
+- AC16a: The mod SHALL NOT start a refresh within the throttle interval of the
+  previous refresh returning. A `turn.complete` refresh SHALL ignore the
+  throttle, since a finished turn is the moment the band is read.
+- AC14: WHEN a refresh returns data that differs from the drawn snapshot, THEN
+  the mod SHALL call `$.ui.invalidate("ui.render")` exactly once for that
+  refresh.
+- AC15: WHILE a refresh is in flight, the band SHALL keep drawing the last good
+  snapshot.
+- AC16: The mod SHALL NOT start a refresh while one is already in flight.
+
+### Faults
+
+- AC17: IF the data command exits non-zero, times out, or returns output that
+  does not parse as an array, THEN the mod SHALL keep the last good snapshot and
+  SHALL NOT throw.
+- AC18: IF no refresh has ever succeeded, THEN the mod SHALL draw nothing.
+- AC19: IF a row is missing a field the band draws, THEN that field SHALL render
+  as a placeholder and the row SHALL still draw.
+
+### Cost and isolation
+
+- AC20: The mod SHALL add nothing to the model's prompt and SHALL consume zero
+  model tokens.
+- AC21: The mod SHALL read session metadata only. It SHALL NOT read worker
+  transcripts, diffs, or prompts.
+
+## Decisions, settled
+
+1. **The arcade does not ship.** Decided by the human, option B. The 93 line
+   plumbing stays (the `CLAUDE_CODE_ENABLE_FUNCTION_HOOKS` default, the
+   `modules` declaration, the CI pin to 2.1.270, the version bump, the docs
+   page). The 783 line game goes: `plugin/mods/arcade/`,
+   `plugin/hooks/boards/`, `tests/mods-arcade/`. The game is removed because it
+   does not work, not because the plumbing is wrong, and it stays recoverable
+   from the branch history.
+2. **Always on**, whenever the run has worker rows, with `/agents` toggling it
+   off and on. Assumed from the recommendation, cheap to reverse.
+3. **Row budget: 8**, then the overflow line. Assumed, cheap to reverse.
+4. **Columns: `id  status  agent  name`.** Deliberately not model, cwd, or
+   token counts: the statusline already carries those. Assumed, cheap to
+   reverse.
+5. **Refresh on `turn.complete` and on `tool.call`, throttled, no timer.**
+   This overrides the earlier `turn.complete` only recommendation. The band's
+   whole value is watching workers *while* the orchestrator works, and
+   `turn.complete` fires only after that window closes, so the band would be
+   stale exactly when it matters. `tool.call` fires throughout a working turn
+   and needs no timer, which keeps the subprocess count tied to real activity
+   instead of to the clock. The throttle in AC16a bounds the cost.
+6. **Monochrome ASCII** for the first cut. Colour is additive and can follow
+   once the band earns its place.
+
+## Out of scope
+
+- Any interactive control of workers from the band: no stop, no send, no
+  resume. Read-only.
+- Worker output, diffs, logs, or transcripts in the band.
+- Any run other than the current one.
+- Desktop, mobile, and headless rendering. Terminal only, by engine constraint.
+- Replacing or changing `codedeck web`, `codedeck ps`, or the statusline.
+- Fixing the `Client` surface state bug. The band avoids Clients entirely;
+  the bug stays open and unowned by this work.
+- Any dependency install, fetch, or vendoring.
+
+## Verification
+
+Scoped runs only. Never the full suite.
+
+- `npm run build`
+- `npx vitest run tests/mods-agents`
+- `claude plugin validate plugin/.claude-plugin/plugin.json`
+- `claude plugin validate .`
+- The PTY probe, which is the only check that proves drawing. It reproduced
+  every arcade defect and is known to discriminate:
+
+```sh
+CLAUDE_CODE_ENABLE_FUNCTION_HOOKS=1 timeout 40 \
+  script -qec "claude --plugin-dir <repo>/dist/plugin" /dev/null > probe.txt 2>&1
+sed 's/\x1b\[[0-9;?]*[a-zA-Z]//g' probe.txt | tr -d '\r' > probe-clean.txt
+grep -c "hook skipped\|is not an element" probe-clean.txt   # must be 0
+```
+
+A PASS needs the error count at zero AND the band's own text present in the
+capture. Zero errors alone is not a pass: a hook that draws nothing also scores
+zero errors.
+
+## Stop conditions
+
+- Never invent an engine API. Every `$` call and every element prop used must
+  trace to a contract quoted in this spec or extracted from the binary the same
+  way.
+- If the band cannot be drawn without a `Client`, stop and report. Do not mount
+  one: its state path is a known open bug.
+- If `$.process.run` is refused at runtime, stop and report the exact message.
+  Do not fall back to requiring `codedeck web`.
diff --git a/.specs/features/orchestrator-agents-band/tasks.md b/.specs/features/orchestrator-agents-band/tasks.md
new file mode 100644
index 0000000..bed159d
--- /dev/null
+++ b/.specs/features/orchestrator-agents-band/tasks.md
@@ -0,0 +1,354 @@
+# Tasks: orchestrator agents band
+
+Source of truth: `spec.md`. Interface: the frozen block in `design.md`.
+
+## Coverage matrix
+
+Confirm this before Execute. It is the authority for what counts as covered.
+
+| Layer | Test type | Lives in | Command |
+|---|---|---|---|
+| `plugin/mods/agents/parse.ts` | unit | `tests/mods-agents/parse.test.ts` | `npx vitest run tests/mods-agents` |
+| `plugin/mods/agents/select.ts` | unit | `tests/mods-agents/select.test.ts` | `npx vitest run tests/mods-agents` |
+| `plugin/mods/agents/format.ts` | unit | `tests/mods-agents/format.test.ts` | `npx vitest run tests/mods-agents` |
+| `plugin/hooks/register.tsx` | none | n/a | PTY probe, below |
+| manifest | contract | n/a | `claude plugin validate .` |
+| drawing, end to end | probe | `scripts/band-probe.sh` | `bash scripts/band-probe.sh` |
+
+`register.tsx` carries test type **none** on purpose: it runs only inside the
+engine sandbox, it holds no decisions by design, and a unit test of it would
+test a mock rather than the engine. Its proof is the probe. This is the one
+row in the matrix that may be `none`, and the rule that keeps it honest is the
+design rule: any logic that appears in `register.tsx` is a design violation and
+belongs in the pure layer where it is covered.
+
+The probe is the only check that can distinguish "draws correctly" from "draws
+nothing". A PASS requires zero engine errors **and** the band's text present in
+the capture. Zero errors alone is not a pass.
+
+## T0. Strip the arcade
+
+- Requirement: spec decision 1.
+- Delete `plugin/mods/arcade/`, `plugin/hooks/boards/`, `tests/mods-arcade/`.
+  Reduce `plugin/hooks/register.tsx` to a valid passthrough module. Trim the
+  arcade text out of `docs/mods.md`.
+- Keeps untouched: `src/open/runtime.ts`, `plugin/hooks/hooks.json`,
+  `plugin/.claude-plugin/plugin.json`, `.github/workflows/ci.yml`,
+  `.gitignore`, `tests/open-args.test.ts`.
+- Tests: none new. `npx vitest run tests/open-args` must stay green, which is
+  what proves the plumbing survived the deletion.
+- Gate: build green, both validates pass, PTY probe reports zero matches for
+  `hook skipped`, `is not an element` and `arcade`.
+- Status: dispatched as worker `adde`.
+
+## T1. Pure layer: parse
+
+- Requirement: AC17, AC18, AC19.
+- Write `plugin/mods/agents/types.ts` and `plugin/mods/agents/parse.ts` to the
+  frozen interface.
+- Tests: `tests/mods-agents/parse.test.ts`, in this same task. Cases: a well
+  formed array; an empty array; `stdout` that is not JSON; JSON that is an
+  object rather than an array; truncated JSON; an array holding a non-object.
+  Each returns rows or `undefined`, never throws.
+- Gate: `npx vitest run tests/mods-agents` green.
+- Status: worker `a0a9`, completed. 10 tests green.
+
+## T2. Pure layer: select
+
+- Requirement: AC1, AC2, AC10, AC11, AC12.
+- Write `plugin/mods/agents/select.ts` to the frozen interface.
+- Tests: `tests/mods-agents/select.test.ts`, in this same task. Cases: rows of
+  another run are excluded; the `origin: "open"` row is excluded; ordering is
+  `updatedAt` descending; a row with no `updatedAt` sorts last; exactly budget
+  rows yields `hidden: 0`; budget plus three yields `hidden: 3`; an empty input
+  yields no rows and `hidden: 0`.
+- Gate: `npx vitest run tests/mods-agents` green.
+- Status: worker `e343`, completed. 15 tests green.
+
+## T3. Pure layer: format
+
+- Requirement: AC8, AC9, AC11, AC19, and AC4 through the empty-array contract.
+- Write `plugin/mods/agents/format.ts` to the frozen interface.
+- Tests: `tests/mods-agents/format.test.ts`, in this same task. Cases: a row
+  renders id, status, agent and name; a name longer than `NAME_WIDTH` is
+  truncated, not wrapped; every produced line is free of `\n`; a missing field
+  renders `-`; `hidden: 0` produces no overflow line; `hidden: 3` produces one
+  naming three; a snapshot with no rows produces an empty array.
+- Gate: `npx vitest run tests/mods-agents` green.
+- Status: worker `b83f`, stopped once its artifact was green. 26 tests green,
+  no drift outside `format.ts` and `format.test.ts`.
+
+## T4. Wire the band into the hooks module
+
+- Requirement: AC3, AC5, AC6, AC7, AC13, AC13a, AC14, AC15, AC16, AC16a, AC20,
+  AC21, plus decision 2 for `/agents`.
+- Owns `plugin/hooks/register.tsx` alone. Consumes T1 through T3 through the
+  frozen interface and adds no logic of its own.
+- Tests: none, per the coverage matrix. Its proof is T5.
+- Gate: build green, both validates pass.
+- Depends on: T0, T1, T2, T3.
+- Also owns the `description` string in `plugin/hooks/hooks.json`, which still
+  named the arcade after T0.
+- Status: worker `c96f` **rejected, empty delivery**. It reported `completed
+  exit 0` and wrote nothing: `git diff` on `register.tsx` was still T0's strip.
+  Its log shows it spent the whole budget investigating, and died reaching for
+  the claude binary to find the return shape of `$.process.run`. The briefing
+  gave the call shape but not the result shape, so the gap was mine.
+- Redispatched as worker `a3f7` with the full `$.process.run` contract inlined
+  (`{ exitCode, stdout, stderr }` on success, throws on timeout and on failure
+  to start), an explicit ban on opening the binary, and an instruction to write
+  the file before investigating anything.
+- `a3f7` was superseded when the design changed from a band above the prompt to
+  a pane on the right. Worker `308a` rewrote the file against the pane contract:
+  **accepted**, gates right, reads `e.requestId` and `e.props.bodyColumns`, and
+  carries no logic of its own.
+- Two defects found after acceptance, by screen capture, and fixed in place:
+  1. the drawing came out shredded into vertical slivers. `Box` defaults to
+     `flexDirection: "row"`, so the 51 `Text` children were laid side by side.
+     Fixed with `<Box flexDirection="column">`. No error was raised anywhere:
+     the module loaded, the hook ran, every validate passed, and the pane was
+     garbage on screen. Nothing but a capture would have caught this
+  2. the drawing was clipped at the bottom, eating the hidden count, the legend
+     and the closing border. The pane reports its height as
+     `props.scroll.bodyRows` (44 in a 50 row terminal) and `formatPane` was
+     never told. Fixed by passing it through; making it fit is T7
+
+## T5. The probe, written down
+
+- Requirement: the spec's Verification section.
+- Write `scripts/pane-probe.sh`: start a real session under tmux with the
+  plugin, capture the screen, assert the frame is present, assert the drawing
+  is column shaped rather than shredded, assert the closing border is on
+  screen, assert no engine complaint, exit non-zero when any of them fails.
+  Never sends a prompt: the pane draws at session start, so the probe costs no
+  tokens.
+- The PTY capture through `script` was the first approach and it reads badly:
+  a docked pane repaints in place, so the byte stream interleaves and a grep
+  for a header finds nothing even when the pane is correct. `tmux
+  capture-pane` returns the settled screen and is what the assertions run on.
+- Tests: the script is the test. It must be shown to discriminate: run it once
+  against a deliberately broken band and show it failing, then against the real
+  one and show it passing.
+- Gate: the script passes on the real pane and fails on the broken one. Today
+  it is expected to fail the closing border assertion, because the drawing does
+  not fit yet. A probe that goes green against a known broken state is worth
+  nothing.
+- Depends on: T4.
+- Status: **accepted**, after two failed workers and one hand finish.
+  - `8555` died reading `~/.claude`, which the harness auto-rejects. It wrote
+    nothing. Briefing gap: no repo boundary was stated
+  - `5a23` delivered the script with the tmux driver, the polling, the trap and
+    all four assertions
+  - `86c2` was dispatched to fix the `shape` assertion and reported
+    `completed exit 0` having changed nothing: its attempt to copy the plugin
+    into `/tmp` was blocked, and it stopped there. Second false success of the
+    run from the same shape of gap, a briefing that sends a worker somewhere it
+    cannot write
+  - the `shape` fix was finished by hand. It mattered: the assertion written to
+    catch a shredded drawing reported **PASS on a shredded drawing**, because
+    counting dock lines of equal width measures the dock rail, not the content.
+    It now counts dock lines holding a run of 20 or more `─`, which is 8 on the
+    real drawing and 0 when shredded, with the threshold at 5 because the floor
+    of a legitimate drawing is 6
+- Verified by hand, both directions: `VERDICT: PASS` against `dist/plugin`,
+  `VERDICT: FAIL (3 assertions)` against a copy with `flexDirection` removed.
+
+## T6. Document the engine contract
+
+- Requirement: none in the spec. This is debt repayment, not a feature.
+- Add to `docs/mods.md` the function-hooks contract extracted from the engine
+  binary: the single tree element rule, the per-component `ui.render` gate, the
+  `<Button key label onPress>` rule, the `<Client>` six-prop rule and its
+  silent discard of anything else, the `{ Box: 'Box', Text: 'Text' }` intrinsic
+  table, and `$.command.register`'s required description. Each with the engine's
+  own wording quoted.
+- Tests: none. It is prose.
+- Gate: a reader who has never seen this run can spell a correct hooks module
+  from the page alone.
+- Status: dispatched as worker `55e9`.
+- Note: this is the most valuable artifact of the arcade detour. None of it is
+  in public documentation. Do not let it die with the game.
+
+## Mutation probe, before delivery
+
+Per the run contract, after T1 through T3 are green, inject one behavior fault
+per pure module in a scratch copy and confirm the tests catch it:
+
+- `select.ts`: invert the `updatedAt` comparison.
+- `format.ts`: change the truncation width by one.
+- `parse.ts`: return `[]` instead of `undefined` on a parse failure.
+
+Kills and survivors both go in the closing report. A survivor becomes a fix
+slice, not a footnote.
+
+### Result: 5 injected, 5 killed, 0 survivors
+
+Run in a scratch copy at `scratchpad/mut` holding only the four mod files, the
+three test files and a minimal vitest config, with `node_modules` symlinked.
+Baseline there was 51 passed, matching the repo. Scratch discarded after.
+
+| Mutant | Fault | Outcome |
+|---|---|---|
+| M1 | `select.ts`, `return tb - ta` becomes `ta - tb` | killed, 2 tests |
+| M2 | `format.ts`, `clip(value, NAME_WIDTH - 1)` becomes `NAME_WIDTH` | killed, 3 tests |
+| M3 | `parse.ts`, failure returns `[]` instead of `undefined` | killed, 3 tests |
+| M4 | `select.ts`, drop `row.origin !== "open"` | killed, 1 test |
+| M5 | `format.ts`, drop the empty-rows early return | killed, 2 tests |
+
+M4 and M5 are extra, beyond the three the plan required. They were added
+because they hit the two acceptance criteria that carry the feature: AC2, the
+orchestrator must not list itself, and AC4, an empty snapshot draws nothing.
+Both were caught by a named test, so the suite discriminates on the behaviour
+the feature is about, not only on the shape of its output.
+
+## T7. Make the drawing fit the height it is given
+
+- Requirement: new. The pane reports `props.scroll.bodyRows`, measured at 44 in
+  a 50 row terminal, and `formatPane` returned 51 lines. The bottom 7 were
+  clipped: the hidden count, the legend and the closing border all fell off.
+- Owns `plugin/mods/agents/pane.ts` and `tests/mods-agents/pane.test.ts`.
+- `formatPane(snapshot, columns, rows?)`, additive. With `rows` given the
+  result never exceeds it, the frame and footer are never what gets cut, rows
+  in a live status keep full cards, finished rows collapse to one line, and
+  everything dropped counts into the hidden total.
+- Deletes the `CARD_BUDGET` export. It is a real hole: a mutation from 6 to 7
+  survived the whole suite, because the tests read their expectations off the
+  exported constant instead of pinning a number. The fit decision belongs where
+  the height is known, and the replacement tests pin literals.
+- Tests: in the same task, one per rule, two of them with literal line counts.
+- Gate: `npx vitest run tests/mods-agents` green, `npm run build` green, and
+  the drawing fits on screen under T5's probe.
+- Depends on: T4.
+- Status: **accepted**, worker `d9f1`.
+- Verified by hand, not by report: 46 tests green scoped to `tests/mods-agents`,
+  and an independent mutation probe of 4 faults with 4 kills (fit loop off by
+  one, minimum height ignored, eviction order inverted, `MAX_CARD_COLUMNS`
+  56 to 60). The last one is the one that matters: the same mutation against
+  the old `CARD_BUDGET` survived, and it dies now because the tests pin
+  literals instead of reading the exported constant.
+- `d9f1` raised its own reviewer, `bdaa`, which fuzzed the layer independently
+  (36300 checks, its own mutants) and found no blocking defect. Two edges on
+  the record, neither fixed:
+  1. the orchestrator counts into `+N agentes ocultos` when it is itself
+     evacuated, while the rest of the frame uses "agentes" for workers only.
+     Reachable only in a pane of 12 to 15 lines with no drawable worker
+  2. two `origin: "open"` rows in one run keep the second in `total` alone.
+     Unreachable with real data, since `codedeck open` exports its own session
+     id as the run id and ids are unique
+
+## Final review over the finished scope
+
+Worker `3216`, reviewer role, read only, over the whole uncommitted tree except
+`pane.ts` and `pane.test.ts`, which `bdaa` had already fuzzed. It left the tree
+byte identical, verified by `git status` before and after.
+
+No blocking defect. It re-ran every gate itself rather than trusting the
+reports: 46 pane tests, 10 setup tests, the pinned regression trio at 123, the
+manifest suite at 15, `npm run build`, `claude plugin validate --strict`, and
+the live pane probe at `VERDICT: PASS`. It also reverted `resolveSetupTarget`
+in a scratch copy and showed 7 of the 10 setup tests failing against the old
+behaviour, so those tests can actually fail.
+
+Seven findings, all non blocking, all remediated:
+
+1. `refresh` reads its single flight guard at line 55 and sets the flag at line
+   62, with an await in between, so two interleaved firings both spawn
+   `codedeck ps`. `$.env.get` also sat outside the try, so a rejection escaped
+   as an unhandled rejection of a voided promise. Dispatched as `d68e`
+2. `session.start` opened the dock unconditionally, so a session loading the
+   plugin without `CODEDECK_RUN_ID` got a permanently empty 90 column dock,
+   reproduced live by the reviewer. Dispatched as `d68e`
+3. `BandRow` and `Snapshot` in `types.ts` had no importer, left over from the
+   rejected band design. Deleted
+4. `src/open/runtime.ts:183` and `tests/open-args.test.ts:839` still said the
+   function hooks back the arcade mod, in the present tense. Renamed, and the
+   CI pin comment reworded to name the module rather than the dead game
+5. `scripts/pane-probe.sh` tested `${dock:0:1}` against a box character set
+   right after building `dock` with a leading box character, so the guard
+   could never reject anything. Deleted, along with the now orphaned constant
+6. `scripts/band-mock.mjs` held a ternary with two identical branches. It was
+   the three variant mock that settled the design, and the design is settled.
+   File deleted
+7. `docs/mods.md` told the reader to "run the plugin-types flow" with no
+   command behind it: no such script exists in `package.json`. Section deleted
+
+## T8. The connectors, and the rows they wasted
+
+- Requirement: new, from reading a real capture. Two defects the tests could
+  not see because no test looked at the shape of the tree.
+- A stem hung above the orchestrator card, a connector to nothing, since the
+  orchestrator is the root. And every collapsed one liner carried its own stem,
+  so a finished agent cost two rows to say one line's worth: 11 rows of
+  connector in a 44 row pane while 12 agents were reported hidden.
+- Owns `plugin/mods/agents/pane.ts` and `tests/mods-agents/pane.test.ts`.
+- Rule now: no stem above the first block ever, cards keep stems between them
+  because that is what reads as a tree, and a run of collapsed lines draws with
+  one stem where the run begins and none between the entries.
+- Status: **accepted**, worker `8ee0`, with two test gaps closed on a second
+  pass after its reviewer `e16e` found them.
+- Result on screen, same pane, same 44 rows: 22 agents drawn instead of 11,
+  hidden down from 12 to 3.
+- Verified by hand: 52 tests green, and three injected faults all killed. The
+  stem above the first block (7 failures), the stem between collapsed entries
+  (6 failures), and the orchestrator losing its place as the last card to be
+  evicted (2 failures). The last one only dies because `e16e` spotted that
+  nothing pinned it and `8ee0` added the pin.
+
+## T9. The way back in
+
+- Requirement: new, from the user asking "se eu fechar como abre dnv?". The
+  pane could be closed three ways (the `/band` toggle, the dock's own `✕`, or a
+  desynced flag) and only one of them had a way back, a command nobody would
+  guess.
+- Probed first, because the design depended on facts nobody had: closing the
+  pane by its `✕` fires no hook at all, so the module cannot track open state;
+  a `Button`'s `onPress` is handed the press event, not `$`, so it cannot call
+  the engine; a `hotkey` is swallowed by the prompt; `$.ui.open` on an open pane
+  is a no-op. All four verified live under tmux with synthetic SGR clicks, and
+  written into `docs/mods.md`.
+- Shape that survives those facts: one button above the prompt that only ever
+  opens, never toggles, so there is no state to desync. `paneButtonLabel` in the
+  pure layer draws the count, the `ui.press` hook does the work and re-syncs
+  `paneOpen` so a later `/band` still toggles the right way.
+- Owns `plugin/mods/agents/pane.ts`, `plugin/hooks/register.tsx`,
+  `tests/mods-agents/pane.test.ts`, `docs/mods.md`.
+- Gated on `CODEDECK_RUN_ID`, same as the pane: verified that a plain
+  `claude --plugin-dir` session with the variable unset draws neither.
+- Verified live end to end in a real `codedeck open orchestrator` session:
+  button renders as `[ 1 agente ]`, the `✕` closes the pane, one click brings it
+  back with the drawing intact. `pane-probe.sh` still grades PASS on all four
+  assertions.
+- Tests 48 in `tests/mods-agents/pane.test.ts`, six of them new. Four injected
+  faults, four killed: the singular collapsed into the plural, the working half
+  dropped, `starting` no longer counted as working, and the defensive read of a
+  mangled snapshot removed.
+
+## Delivery state
+
+Landed as three commits, not the four this section first planned. The arcade
+removal cannot stand alone: `register.tsx` at the previous HEAD imports
+`../mods/arcade/games/pet.js`, `best.js` and `../mods/arcade/index.js`, so a
+commit that deletes those modules without rewriting the hooks module leaves a
+tree that cannot build. Removal and replacement are one change.
+
+1. `fix(setup)`: `src/cli/commands/setup.ts`, `tests/setup-profile-target.test.ts`,
+   `.specs/fixes/`. Independent of the pane, and carried onto its own branch off
+   main so the urgent fix is reviewable without the feature.
+2. `feat(mods)`: the arcade deleted, the pane added. `plugin/`, `tests/mods-arcade/`
+   deleted, `tests/mods-agents/`, `scripts/pane-mock.mjs`, `scripts/pane-probe.sh`,
+   `.specs/features/`, plus the stale "arcade mod" comments renamed in
+   `src/open/runtime.ts`, `tests/open-args.test.ts` and `.github/workflows/ci.yml`,
+   which are stale the moment the arcade is gone.
+3. `docs(mods)`: `docs/mods.md`, the engine contract this feature had to learn.
+
+Gates run on the tree that was committed: `npm run build` ok,
+`claude plugin validate --strict plugin/` passed, 73 tests across
+`tests/mods-agents/` and `tests/plugin-manifest.test.ts`, 224 across the setup,
+profile and open-args files.
+
+## Order
+
+T0 alone, because everything else builds on the stripped tree.
+Then T1, T2, T3 in parallel: disjoint files, same frozen interface.
+Then T4, then T5.
+T6 any time after T0, it touches only docs.
diff --git a/plugin/hooks/boards/common.tsx b/plugin/hooks/boards/common.tsx
deleted file mode 100644
index 3e924f9..0000000
--- a/plugin/hooks/boards/common.tsx
+++ /dev/null
@@ -1,54 +0,0 @@
-/** @jsx h */
-import type { ClientElements, ClientSurface } from "claude-code";
-
-import { banner, type SeenDone } from "../../mods/arcade/games/twenty48.js";
-
-export interface ArcadeBoardProps {
-  done: number;
-  colorblind: boolean;
-  best: number;
-}
-
-export interface CommonState {
-  paused: boolean;
-  seenDone: number;
-}
-
-export function initialCommonState(): CommonState {
-  return { paused: false, seenDone: 0 };
-}
-
-export function reportScore(surface: ClientSurface, game: string, score: number, done: number): void {
-  surface.post({ kind: "arcade-score", game, score, done });
-}
-
-export default function CommonBoard(props: ArcadeBoardProps, surface: ClientSurface): ClientElements {
-  const current = (surface.state ?? null) as CommonState | null;
-  const state: CommonState = current ?? initialCommonState();
-  if (current === null) surface.setState(state);
-  const seen: SeenDone = { current: state.seenDone };
-  // banner() owns the transition: it pauses exactly once per new done value.
-  banner(props.done, seen, () => {
-    surface.setState({ ...state, paused: true, seenDone: seen.current });
-  });
-  // The notice is driven by paused state, not by banner()'s transient return,
-  // so it stays visible until the user resumes.
-  const paused = state.paused || seen.current !== state.seenDone;
-  surface.onKey((key) => {
-    void key;
-    if (paused) surface.setState({ ...state, paused: false, seenDone: seen.current });
-  });
-  surface.onPointer((point) => {
-    void point;
-    if (paused) surface.setState({ ...state, paused: false, seenDone: seen.current });
-  });
-  const palette = props.colorblind ? "high-contrast" : "standard";
-  const line = paused
-    ? `Round ${seen.current} finished - board paused. Press any key to resume.`
-    : `Arcade ready (${palette}) - best ${props.best}`;
-  return (
-    <box>
-      <text>{line}</text>
-    </box>
-  ) as unknown as ClientElements;
-}
diff --git a/plugin/hooks/boards/twenty48.tsx b/plugin/hooks/boards/twenty48.tsx
deleted file mode 100644
index 2abb15b..0000000
--- a/plugin/hooks/boards/twenty48.tsx
+++ /dev/null
@@ -1,96 +0,0 @@
-/** @jsx h */
-import type { ClientElements, ClientSurface } from "claude-code";
-
-import {
-  banner,
-  directionForKey,
-  initialTwenty48State,
-  isFinished,
-  moveGrid,
-  spawnTile,
-  type SeenDone,
-  type Twenty48State,
-} from "../../mods/arcade/games/twenty48.js";
-import { randomInt } from "../../mods/arcade/games/random.js";
-
-export interface Twenty48Props {
-  done: number;
-  colorblind: boolean;
-  best: number;
-}
-
-export const BOARD_PATH = "hooks/boards/twenty48.tsx";
-
-export default function Twenty48Board(props: Twenty48Props, surface: ClientSurface): ClientElements {
-  const current = (surface.state ?? null) as Twenty48State | null;
-  const state: Twenty48State = current ?? initialTwenty48State();
-  if (current === null) surface.setState(state);
-  const seen: SeenDone = { current: state.seenDone };
-  // banner() owns the transition: it pauses exactly once per new done value.
-  banner(props.done, seen, () => {
-    surface.setState({ ...state, paused: true, seenDone: seen.current });
-  });
-  // The notice is driven by paused state, not by banner()'s transient return,
-  // so it stays visible until the user resumes and no keypress is eaten blind.
-  const paused = state.paused || seen.current !== state.seenDone;
-
-  const finish = (final: Twenty48State) => {
-    if (!final.posted) {
-      surface.post({ kind: "arcade-score", game: "twenty48", score: final.score, done: props.done });
-      surface.setState({ ...final, posted: true });
-    } else {
-      surface.setState(final);
-    }
-  };
-
-  surface.onKey((key) => {
-    if (paused) {
-      surface.setState({ ...state, paused: false, seenDone: seen.current });
-      return;
-    }
-    if (state.over) return;
-    const direction = directionForKey(key.name);
-    if (direction === null) return;
-    const stepped = moveGrid(state.grid, direction);
-    if (!stepped.moved) return;
-    const grid = spawnTile(stepped.grid, () => randomInt(16));
-    const score = state.score + stepped.gained;
-    const won = state.won || grid.some((cell) => cell >= 2048);
-    const over = isFinished(grid);
-    const final: Twenty48State = { ...state, grid, score, won, over };
-    if (over || won) finish(final);
-    else surface.setState(final);
-  });
-
-  surface.onPointer((point) => {
-    void point;
-    if (paused) {
-      surface.setState({ ...state, paused: false, seenDone: seen.current });
-      return;
-    }
-    if (state.over && !state.posted) {
-      surface.post({ kind: "arcade-score", game: "twenty48", score: state.score, done: props.done });
-      surface.setState({ ...state, posted: true });
-    }
-  });
-
-  const palette = props.colorblind ? "high-contrast" : "standard";
-  const rows: string[] = [];
-  for (let rowIdx = 0; rowIdx < 4; rowIdx += 1) {
-    const cells: string[] = [];
-    for (let col = 0; col < 4; col += 1) {
-      const cell = state.grid[rowIdx * 4 + col];
-      cells.push(cell === 0 ? "    ." : String(cell).padStart(5, " "));
-    }
-    rows.push(cells.join(" "));
-  }
-  const status = state.over ? "game over" : state.won ? "you win" : `${palette} - best ${props.best}`;
-  const line = paused
-    ? `Round ${seen.current} finished - board paused. Press any key to resume.`
-    : `2048 score ${state.score} (${status})\n${rows.join("\n")}`;
-  return (
-    <box>
-      <text>{line}</text>
-    </box>
-  ) as unknown as ClientElements;
-}
diff --git a/plugin/hooks/hooks.json b/plugin/hooks/hooks.json
index 276e5e9..e4f491d 100644
--- a/plugin/hooks/hooks.json
+++ b/plugin/hooks/hooks.json
@@ -1,5 +1,5 @@
 {
-  "description": "Codedeck arcade mod: registers function hooks (requires Claude Code with function hooks enabled).",
+  "description": "Codedeck agents pane: draws this session's dispatched workers as ASCII in a pane docked on the right (requires Claude Code with function hooks enabled).",
   "modules": ["./register.tsx"],
   "hooks": {
     "SessionStart": [
diff --git a/plugin/hooks/register.tsx b/plugin/hooks/register.tsx
index 3f88741..885c07a 100644
--- a/plugin/hooks/register.tsx
+++ b/plugin/hooks/register.tsx
@@ -1,122 +1,251 @@
 /** @jsx h */
 import type { Register } from "claude-code";
 
-import { feed, newPet, petEvent, type Pet } from "../mods/arcade/games/pet.js";
-import { isBetter } from "../mods/arcade/games/best.js";
-import { ARCADE_BOARDS } from "../mods/arcade/index.js";
+// The .js extension on a .ts source is the proven import form here:
+// `npm run build:plugin` copies plugin/ verbatim and the engine loads the .ts
+// file directly, so what resolves is what the engine's loader accepts.
+import { formatPane, paneButtonLabel, selectPane } from "../mods/agents/pane.js";
+import { parseRows } from "../mods/agents/parse.js";
+import type { PaneSnapshot } from "../mods/agents/types.js";
 
-const PET_KEY = "pet";
-const COLORBLIND_KEY = "colorblind";
-const bestKey = (game: string): string => `best:${game}`;
+// Stable pane id: 1 to 64 letters, digits, "_" or "-". open carries it into
+// e.requestId on the render event, which is how this module tells its own pane
+// from any other: e.id is undefined on that event. Verified live.
+const PANE_ID = "codedeck-agents";
+
+// Key of the button drawn above the prompt. It comes back as e.element on the
+// press event, which is how this module tells its own button from every other
+// plugin's. Verified live.
+const BUTTON_KEY = "codedeck-agents-open";
+
+// The engine ships no type package for $, so this mirrors only the
+// capabilities the refresh helper calls. Both arguments of process.run are
+// positional: the host implementation destructures { argv, init }, but the
+// module-side proxy packs the positional arguments into that object first, and
+// calling it with the object shape is refused at runtime with "process.run:
+// takes argv, a non-empty list of strings naming the command first". Verified
+// in a live PTY session, see docs/mods.md.
+type Engine$ = {
+  env: {
+    get(name: string): Promise<string | undefined>;
+  };
+  process: {
+    run(
+      argv: string[],
+      init?: { cwd?: string; env?: Record<string, string>; stdin?: string; timeoutMs?: number },
+    ): Promise<{ exitCode: number; stdout: string; stderr: string }>;
+  };
+  ui: {
+    open(pane: { id: string; width?: number; side?: "right" }): Promise<unknown>;
+    close(pane: { id: string }): Promise<unknown>;
+    invalidate(target: string): Promise<unknown>;
+  };
+};
+
+// Passing $ into a helper is allowed, verified. What the engine refuses is
+// pulling a namespace off it: `const P = $.process` fails to load the module.
+// So refresh takes $ as a parameter and the state register owns travels beside
+// it in this object. paneOpen never leaves register, so it stays a bare let.
+type PaneState = {
+  // Last good snapshot; undefined until one refresh has fully succeeded, which
+  // is how the pane draws nothing rather than a guess.
+  snapshot: PaneSnapshot | undefined;
+  inFlight: boolean;
+  lastRefreshEndedAt: number;
+  // True once session.start saw a CODEDECK_RUN_ID. Cached because ui.render
+  // fires on every drawing pass and must not await an env read to decide
+  // whether to draw one button.
+  hasRun: boolean;
+};
+
+const TOOL_REFRESH_GAP_MS = 1500;
+
+const refresh = async ($: Engine$, state: PaneState): Promise<void> => {
+  // Claim the slot before the first await. Guard and set must not straddle a
+  // yield point: with the `$.env.get` read in between, two tool.call firings
+  // that interleave in that window both pass the guard and both spawn
+  // `codedeck ps`. Nothing between these two lines can yield.
+  if (state.inFlight) return;
+  state.inFlight = true;
+  try {
+    // Not process.env: a hooks module runs in a realm with no `process`
+    // global at all, and reading it throws
+    // `ReferenceError: process is not defined`. The engine's own $.env.get is
+    // the door, and it takes a literal name. Verified live: this returns the
+    // run id that `codedeck open` exports. The await sits inside the try
+    // because the call sites use `void refresh(...)`: a rejection here must
+    // land in the catch, not surface as an unhandled rejection.
+    const runId = await $.env.get("CODEDECK_RUN_ID");
+    if (!runId) return;
+    const { exitCode, stdout } = await $.process.run(["codedeck", "ps", "--all", "--json"]);
+    if (exitCode !== 0) return;
+    const rows = parseRows(stdout);
+    if (!rows) return;
+    const nextSnapshot = selectPane(rows, runId);
+    // Cheap compare: an unchanged list must not invalidate, or the tool.call
+    // cadence turns into a redraw storm.
+    const drawn = JSON.stringify(state.snapshot);
+    state.snapshot = nextSnapshot;
+    if (JSON.stringify(nextSnapshot) !== drawn) {
+      await $.ui.invalidate("ui.render");
+    }
+  } catch {
+    // $.process.run throws on timeout and on start failure. A thrown hook
+    // makes the engine drop the whole drawing, so nothing escapes here: the
+    // pane keeps the last good snapshot.
+  } finally {
+    state.inFlight = false;
+    state.lastRefreshEndedAt = Date.now();
+  }
+};
 
 export const register: Register = (on) => {
-  let pet: Pet = newPet();
-  let best: Record<string, number> = {};
-  let colorblind = false;
-  let turnClock = 0;
-  let lastTurnMs = 0;
-  let openBoard: string | null = null;
-  let done = 0;
+  const state: PaneState = {
+    snapshot: undefined,
+    inFlight: false,
+    lastRefreshEndedAt: 0,
+    hasRun: false,
+  };
+  let paneOpen = false;
 
   on("session.start", async ($, e, next) => {
-    try {
-      const savedPet = await $.store.get(PET_KEY);
-      if (savedPet) pet = savedPet as Pet;
-      for (const board of ARCADE_BOARDS) {
-        const saved = await $.store.get(bestKey(board));
-        if (typeof saved === "number") best[board] = saved;
-      }
-      const savedColorblind = await $.store.get(COLORBLIND_KEY);
-      if (typeof savedColorblind === "boolean") colorblind = savedColorblind;
-    } catch (err) {
-      $.ui.log(`arcade restore failed: ${String(err)}`);
+    // Not "agents": the engine refuses it with `$.command.register: "/agents"
+    // refused: it is the built-in /agents`. "band", "deck" and
+    // "codedeck-agents" were each verified free. The description is load
+    // bearing: without it the whole session.start hook dies.
+    await $.command.register({
+      name: "band",
+      description: "toggle the codedeck agents pane",
+      immediate: true,
+    });
+    // Only open when there is actually a run behind the pane. A session that
+    // loads this plugin by manual --plugin-dir or a global install has no
+    // CODEDECK_RUN_ID, and the dock there is permanently empty while eating
+    // most of the screen for the whole session. /band stays the escape hatch
+    // for anyone who wants the pane anyway.
+    const runId = await $.env.get("CODEDECK_RUN_ID");
+    state.hasRun = Boolean(runId);
+    if (runId) {
+      // No width is requested: the engine sizes the dock itself and reports
+      // the usable content back as e.props.bodyColumns on every render.
+      await $.ui.open({ id: PANE_ID, side: "right" });
+      paneOpen = true;
+      // Populate before the first turn, or the pane stays blank through the
+      // whole opening exchange, which is exactly when the run is dispatched.
+      void refresh($, state);
     }
-    await $.command.register({ name: "arcade", immediate: true });
     return next(e);
   });
 
-  on("command.run", { command: "arcade" }, async ($, e) => {
-    const arg = e.args.trim().toLowerCase();
-    if (arg === "") {
-      openBoard = null;
-      await $.ui.invalidate("ui.render");
-      return { text: "arcade boards: twenty48" };
-    }
-    if (arg === "list") {
-      return { text: "arcade boards: twenty48" };
+  on("command.run", { command: "band" }, async ($) => {
+    // The action derives from the current state and the flag flips only after
+    // the engine call resolves: if $.ui.close ever rejects, its argument shape
+    // is the one call here not yet verified in a PTY session, paneOpen stays
+    // true and the next /band retries the close, instead of the flag and the
+    // pane desyncing for the rest of the session.
+    if (paneOpen) {
+      await $.ui.close({ id: PANE_ID });
+      paneOpen = false;
+    } else {
+      await $.ui.open({ id: PANE_ID, side: "right" });
+      paneOpen = true;
     }
-    if (arg === "open" || arg.startsWith("open ")) {
-      const name = arg === "open" ? "twenty48" : arg.slice("open ".length).trim() || "twenty48";
-      if (!(ARCADE_BOARDS as readonly string[]).includes(name)) {
-        return { text: `no game called "${name}"` };
-      }
-      openBoard = name;
-      await $.ui.invalidate("ui.render");
-      return { text: `opened ${name}` };
-    }
-    if (arg === "stop") {
-      openBoard = null;
-      await $.ui.invalidate("ui.render");
-      return { text: "arcade closed" };
-    }
-    return { text: `no game called "${arg}"` };
-  });
-
-  on("turn.start", async ($, e, next) => {
-    turnClock = Date.now();
-    return next(e);
+    await $.ui.invalidate("ui.render");
+    return { text: paneOpen ? "agents pane open" : "agents pane closed" };
   });
 
   on("turn.complete", async ($, e, next) => {
-    lastTurnMs = Date.now() - turnClock;
-    void lastTurnMs;
-    done += 1;
-    await $.ui.invalidate("ui.render");
+    void refresh($, state);
     return next(e);
   });
 
   on("tool.call", async ($, e, next) => {
-    const r = await next(e);
-    // petEvent already ignores denied calls; only classified events feed the pet.
-    const command = (e as { command?: string }).command ?? undefined;
-    const denied = "deny" in (r as Record<string, unknown>);
-    const ok = denied ? undefined : !(r as { isError?: boolean }).isError;
-    const event = petEvent({ tool: e.tool, command, ok, denied });
-    if (event !== undefined) {
-      pet = feed(pet, event);
-      await $.store.set(PET_KEY, { xp: pet.xp, mood: pet.mood, tests: pet.tests, commits: pet.commits, edits: pet.edits });
+    if (Date.now() - state.lastRefreshEndedAt >= TOOL_REFRESH_GAP_MS) {
+      void refresh($, state);
     }
-    return r;
+    // The downstream result goes back unchanged: the pane must never alter a
+    // tool result.
+    return await next(e);
   });
 
-  on("ui.message", async ($, e, next) => {
-    const posted = e.data as { game?: string; score?: number } | undefined;
-    if (!posted || typeof posted.game !== "string" || typeof posted.score !== "number") {
-      return next(e);
-    }
-    if (isBetter(posted.game, posted.score, best)) {
-      best[posted.game] = posted.score;
-      await $.store.set(bestKey(posted.game), posted.score);
-      $.ui.toast(`New arcade record in ${posted.game}: ${posted.score}`);
+  on("ui.press", async ($, e, next) => {
+    // e.element is the key of the pressed button, so everything else on screen
+    // belongs to somebody else. The work sits here rather than in the button's
+    // own onPress because this $ is the one the engine hands the press event.
+    // A $ captured from a past render does work, verified, but it outlives the
+    // event it came from and nothing promises how long.
+    if ((e as { element?: string }).element === BUTTON_KEY) {
+      await $.ui.open({ id: PANE_ID, side: "right" });
+      // Opening an already open pane is a no-op, verified live, so the button
+      // never has to know the truth. Re-syncing the flag is the point: the
+      // pane's own close box closes it without firing a single hook, and after
+      // that one /band would toggle the wrong way.
+      paneOpen = true;
+      await $.ui.invalidate("ui.render");
+      void refresh($, state);
     }
-    return { game: posted.game, score: posted.score };
+    return await next(e);
   });
 
+  // Both drawings. The pane carries the canvas; above the prompt there is one
+  // button and nothing else, which is all that is left of the rejected design's
+  // flat table. ui.render fires once per component, so every gate here is load
+  // bearing, and each branch returns exactly one tree element, never an array,
+  // or the engine drops the drawing with "ui.render hook skipped: returned the
+  // wrong shape".
   on("ui.render", async ($, e, next) => {
     if (e.surface !== "terminal") return await next(e);
-    const { Box, Button, Client, Text } = await $.ui.resolve(e, "Box", "Button", "Client", "Text");
-    if (openBoard === null) {
-      return [
-        <Box>
-          <Text>Arcade boards</Text>
-          <Button>twenty48</Button>
-        </Box>,
-        await next(e),
-      ];
+    // The way back in. The pane can be closed from its own close box, which
+    // fires no hook, so without a visible affordance the only recovery is
+    // knowing that /band exists. One button above the prompt, only when there
+    // is a run behind it.
+    if (e.component === "AbovePrompt") {
+      if (!state.hasRun) return await next(e);
+      const { Box, Button } = await $.ui.resolve(e, "Box", "Button");
+      return (
+        <Box flexDirection="column">
+          <Button
+            key={BUTTON_KEY}
+            label={paneButtonLabel(state.snapshot)}
+            // Mandatory, and empty on purpose: a Button without onPress makes
+            // the engine drop the whole drawing with "returned a Button without
+            // an onPress function". Its own argument is the press event, not $,
+            // so `async ($) => $.ui.open(...)` here throws. The ui.press hook
+            // above does the work.
+            onPress={() => {}}
+          />
+          {await next(e)}
+        </Box>
+      );
     }
-    return [
-      <Client module="./boards/twenty48.tsx" done={done} colorblind={colorblind} best={best[openBoard] ?? 0} />,
-      await next(e),
-    ];
+    if (e.component !== "Pane") return await next(e);
+    if (e.requestId !== PANE_ID) return await next(e);
+    if (state.snapshot === undefined) return await next(e);
+    // The usable content size is what the pane reports, never an assumed
+    // number. Width comes as props.bodyColumns and height as
+    // props.scroll.bodyRows: measured live as 89 and 44 in a 200 column,
+    // 50 row terminal. A requested width on $.ui.open is ignored, the engine
+    // sizes the dock itself, so reading both off the event is the only way to
+    // fit. Without the width there is no safe number to hand formatPane; the
+    // height is optional and only caps the drawing.
+    const props = (e as { props?: { bodyColumns?: number; scroll?: { bodyRows?: number } } }).props;
+    const columns = props?.bodyColumns;
+    if (typeof columns !== "number") return await next(e);
+    const lines = formatPane(state.snapshot, columns, props?.scroll?.bodyRows);
+    if (lines.length === 0) return await next(e);
+    // Capitalized tags from the resolve table; a lowercase <text> is refused
+    // as "JSX element <text> is not an element".
+    const { Box, Text } = await $.ui.resolve(e, "Box", "Text");
+    // flexDirection is load bearing: Box lays children out in a row by default,
+    // so without it the 51 lines are drawn side by side as narrow columns and
+    // the pane comes out as shredded box characters. Verified on screen.
+    return (
+      <Box flexDirection="column">
+        {lines.map((line) => (
+          <Text key={line}>{line}</Text>
+        ))}
+        {await next(e)}
+      </Box>
+    );
   });
 };
diff --git a/plugin/mods/agents/pane.ts b/plugin/mods/agents/pane.ts
new file mode 100644
index 0000000..58d88f9
--- /dev/null
+++ b/plugin/mods/agents/pane.ts
@@ -0,0 +1,440 @@
+// Canvas layer of the orchestrator agents pane.
+//
+// The `codedeck web` canvas, drawn as ASCII boxes for a docked terminal pane.
+// Two pure functions behind one frozen interface: selectPane narrows the
+// daemon's full session list to one run, formatPane turns that snapshot into
+// the lines of the drawing and fits them to the height the pane was given.
+// The engine draws them inside a render hook, where a throw drops the whole
+// pane, so nothing here throws and nothing here reaches for the engine.
+//
+// Every line comes out exactly `columns` code units wide so the frame never
+// looks ragged, and no line ever carries a line break, a tab or a control
+// character: everything the daemon supplied is sanitised and clipped first.
+// The filtering and ordering rules are carried across from the deleted
+// select.ts; the sanitising and surrogate-safe clipping from format.ts.
+
+import type { PaneRow, PaneSnapshot, SessionRow } from "./types.js";
+
+/** Cards never stretch past this, however wide the dock is. */
+export const MAX_CARD_COLUMNS = 56;
+
+/** Below this many usable columns the pane draws nothing rather than garbage. */
+export const MIN_COLUMNS = 24;
+
+/** Placeholder for a cell the daemon did not supply. Rule 13. */
+const EMPTY_CELL = "-";
+
+// Control characters and the line-terminator separators would break the frame,
+// so they become spaces before anything is drawn. Carried across verbatim from
+// format.ts: the C0 block (which holds \n, \r, \t, \v, \f and the ESC CSI
+// sequences), DEL, the C1 block, and U+2028 / U+2029.
+const CONTROL = /[\u0000-\u001f\u007f-\u009f\u2028\u2029]/g;
+
+// Status buckets, matching the web canvas. working and starting are "working";
+// needs_input is "waiting for you"; everything else is finished.
+const LIVE = new Set(["working", "starting"]);
+const WAIT = new Set(["needs_input"]);
+
+// Vocabulary for the drawing. Unknown statuses and harnesses fall back to the
+// raw value or a generic glyph, never to undefined. These maps are keyed by
+// daemon-supplied strings, so they get a null prototype: a plain `{}` would
+// resolve an agent or status of "constructor" through Object.prototype and draw
+// a function's source into the card, where the `??` fallback never fires.
+function vocab(entries: Record<string, string>): Record<string, string> {
+  return Object.assign(Object.create(null) as Record<string, string>, entries);
+}
+
+const STATUS_DOT = vocab({
+  working: "●",
+  starting: "●",
+  needs_input: "◉",
+});
+const STATUS_WORD = vocab({
+  working: "Trabalhando agora",
+  starting: "Subindo",
+  needs_input: "Esperando voce",
+  completed: "Concluida",
+  stopped: "Em pausa",
+  failed: "Falhou",
+});
+const HARNESS_GLYPH = vocab({
+  claude: "▲",
+  opencode: "■",
+  codex: "◆",
+  omp: "⬟",
+});
+const HARNESS_LABEL = vocab({
+  claude: "Claude",
+  opencode: "OpenCode",
+  codex: "Codex",
+  omp: "OMP",
+});
+
+function timestamp(row: SessionRow): number {
+  return typeof row.updatedAt === "string" ? Date.parse(row.updatedAt) : Number.NaN;
+}
+
+// Newest first; a row with no parseable updatedAt sorts last; ties break by id
+// so the order is total and the pane does not flicker between refreshes.
+function compareRows(a: SessionRow, b: SessionRow): number {
+  const ta = timestamp(a);
+  const tb = timestamp(b);
+  const hasA = !Number.isNaN(ta);
+  const hasB = !Number.isNaN(tb);
+  if (hasA !== hasB) return hasA ? -1 : 1;
+  if (hasA && ta !== tb) return tb - ta;
+  if (a.id !== b.id) return a.id < b.id ? -1 : 1;
+  return 0;
+}
+
+// An omitted or non-finite budget means "keep everything": the default cut is
+// formatPane's job now, because only it knows the pane height.
+function budgetLimit(budget: number | undefined): number {
+  if (typeof budget !== "number" || !Number.isFinite(budget)) return Number.POSITIVE_INFINITY;
+  return Math.max(0, Math.trunc(budget));
+}
+
+function text(value: unknown): string {
+  if (typeof value !== "string") return "";
+  return value;
+}
+
+function toPaneRow(row: SessionRow): PaneRow {
+  const iso = typeof row.updatedAt === "string" ? row.updatedAt : undefined;
+  return {
+    id: row.id,
+    status: row.status || EMPTY_CELL,
+    agent: row.agent || EMPTY_CELL,
+    name: row.name || EMPTY_CELL,
+    updatedAt: iso,
+  };
+}
+
+/**
+ * Narrow the daemon's full session list to one run. Never throws.
+ *
+ * Filters to `runId`, lifts the single `origin === "open"` row out as the
+ * orchestrator, orders the rest by `updatedAt` descending with a total order,
+ * and cuts to `budget`. With no explicit budget every matched row is kept and
+ * `hidden` is 0; dropping rows to fit the pane is formatPane's decision.
+ */
+export function selectPane(rows: SessionRow[], runId: string, budget?: number): PaneSnapshot {
+  try {
+    const limit = budgetLimit(budget);
+    const source = Array.isArray(rows) ? rows : [];
+    const matching = source.filter(
+      (row) => row != null && typeof row === "object" && (row as SessionRow).runId === runId,
+    );
+    const orchestratorRow = matching.find((row) => row.origin === "open");
+    const orchestrator = orchestratorRow
+      ? { agent: text(orchestratorRow.agent) || EMPTY_CELL }
+      : undefined;
+    const workers = matching.filter((row) => row.origin !== "open");
+    const ordered = [...workers].sort(compareRows);
+    const kept = ordered.slice(0, limit);
+    return {
+      runId: text(runId),
+      orchestrator,
+      rows: kept.map(toPaneRow),
+      hidden: ordered.length - kept.length,
+      total: matching.length,
+    };
+  } catch {
+    return { runId: "", orchestrator: undefined, rows: [], hidden: 0, total: 0 };
+  }
+}
+
+// A cell the daemon supplied: control and separator characters become spaces,
+// the ends are trimmed, and an empty result is a placeholder. Rule 7.
+function cell(value: unknown): string {
+  const clean = text(value).replace(CONTROL, " ").trim();
+  return clean === "" ? EMPTY_CELL : clean;
+}
+
+// Cut to `width` code units, never wrap, and never strand half of a surrogate
+// pair. Carried across from format.ts, with a marker so a clipped value reads
+// as clipped. The result is always exactly `width` units after the padEnd.
+function fit(value: string, width: number, fill = " "): string {
+  if (width <= 0) return "";
+  if (value.length <= width) return value.padEnd(width, fill);
+  let cut = value.slice(0, width - 1);
+  const tail = cut.charCodeAt(cut.length - 1);
+  if (tail >= 0xd800 && tail <= 0xdbff) cut = cut.slice(0, -1);
+  return (cut + "…").padEnd(width, fill);
+}
+
+function glyph(agent: unknown): string {
+  const key = text(agent);
+  return HARNESS_GLYPH[key] ?? "□";
+}
+
+function harnessLabel(agent: unknown): string {
+  const key = text(agent);
+  return HARNESS_LABEL[key] ?? cell(agent);
+}
+
+function dot(status: unknown): string {
+  return STATUS_DOT[text(status)] ?? "○";
+}
+
+function statusWord(status: unknown): string {
+  return STATUS_WORD[text(status)] ?? cell(status);
+}
+
+function age(iso: unknown, now: number): string {
+  if (typeof iso !== "string") return "";
+  const then = Date.parse(iso);
+  if (Number.isNaN(then)) return "";
+  const minutes = Math.floor((now - then) / 60000);
+  if (minutes < 1) return "agora";
+  if (minutes < 60) return `${minutes}m`;
+  return `${Math.floor(minutes / 60)}h`;
+}
+
+function count(value: unknown): number {
+  return typeof value === "number" && Number.isFinite(value) ? Math.max(0, Math.trunc(value)) : 0;
+}
+
+// How old a row looks for eviction: an unparseable timestamp is the oldest
+// possible age, matching how compareRows parks such rows at the end of the
+// display. The orchestrator pins itself to +Infinity so it is the very last
+// card to leave when the pane shrinks.
+function rowAge(iso: unknown): number {
+  const then = typeof iso === "string" ? Date.parse(iso) : Number.NaN;
+  return Number.isNaN(then) ? Number.NEGATIVE_INFINITY : then;
+}
+
+// One drawable piece of the pane: an orchestrator card, a worker card, or a
+// collapsed finished row. `size` counts the block's own lines and never the
+// connector above it: only the assembled order knows where a stem hangs, so
+// `build` receives `connects`, whether the bottom edge grows the stem
+// junction, and `lead`, whether a stem is drawn above the block.
+type Block = {
+  kind: "card" | "line";
+  size: number;
+  age: number;
+  id: string;
+  build: (connects: boolean, lead: boolean) => string[];
+};
+
+// One drawing pass, with the widths derived from the column budget. Kept inside
+// its own function so formatPane can wrap the whole thing in one guard.
+// `limit` is the usable body height in rows, or undefined for unbounded.
+function draw(snapshot: PaneSnapshot, columns: number, limit: number | undefined): string[] {
+  const source = (snapshot ?? {}) as Partial<PaneSnapshot>;
+  const rows = (Array.isArray(source.rows) ? source.rows : []).map(
+    (row) => (row ?? {}) as Partial<PaneRow>,
+  );
+  const orchestrator =
+    source.orchestrator && typeof source.orchestrator === "object"
+      ? (source.orchestrator as Partial<{ agent: string }>)
+      : undefined;
+  const hidden = count(source.hidden);
+  const total = count(source.total);
+
+  // Rule 10: nothing to draw when there is neither a card nor an orchestrator.
+  if (rows.length === 0 && orchestrator === undefined) return [];
+
+  const workerTotal = rows.length + hidden;
+  const working = rows.filter((row) => LIVE.has(row.status ?? "")).length;
+  const waiting = rows.filter((row) => WAIT.has(row.status ?? "")).length;
+  // The overflow is reported by count only, its statuses are not in the
+  // snapshot, so it is folded into "finished": the most recently touched
+  // sessions are the live ones and stay inside the budget.
+  const finished = Math.max(0, workerTotal - working - waiting);
+
+  const W = Math.trunc(columns);
+  const IN = W - 2;
+  // Rule 8: the card box caps at MAX_CARD_COLUMNS no matter how wide the dock
+  // gets; the outer frame still spans the full width. The two-space inset the
+  // cards have always sat at inside the frame is kept.
+  const CARD = Math.min(IN - 4, MAX_CARD_COLUMNS);
+  const INNER = Math.max(0, CARD - 2);
+  const now = Date.now();
+
+  // Everything routed through frame* is exactly W wide.
+  const frameRow = (s: string) => "│" + fit(s, IN) + "│";
+  const frameSep = () => "├" + "─".repeat(IN) + "┤";
+  const frameBot = () => "└" + "─".repeat(IN) + "┘";
+  const frameTop = (label: string) =>
+    "┌" + fit(("─ " + label + " ").replace(CONTROL, " "), IN, "─") + "┐";
+
+  // A node card, indented inside the frame. The stem that joins it to whatever
+  // sits above is drawn by the assembly, not by the block: the first block is
+  // the root and never has one.
+  const stem = () => frameRow("  " + " ".repeat(Math.floor(INNER / 2) + 1) + "│");
+  const cardTop = () => frameRow("  ┌" + "─".repeat(INNER) + "┐");
+  const cardRow = (s: string) => frameRow("  │" + fit(s, INNER) + "│");
+  const stemAt = Math.floor(INNER / 2);
+  const cardBottom = (connects: boolean) =>
+    connects
+      ? frameRow("  └" + "─".repeat(stemAt) + "┬" + "─".repeat(INNER - stemAt - 1) + "┘")
+      : frameRow("  └" + "─".repeat(INNER) + "┘");
+
+  const cardBlock = (ageValue: number, id: string, body: string[]): Block => ({
+    kind: "card",
+    size: body.length + 2,
+    age: ageValue,
+    id,
+    build: (connects, lead) => [
+      ...(lead ? [stem()] : []),
+      cardTop(),
+      ...body.map(cardRow),
+      cardBottom(connects),
+    ],
+  });
+
+  const blocks: Block[] = [];
+
+  if (orchestrator !== undefined) {
+    blocks.push(
+      cardBlock(Number.POSITIVE_INFINITY, "", [
+        ` ${glyph(orchestrator.agent)} ● Orquestrador`,
+        `   ${harnessLabel(orchestrator.agent)} · ${workerTotal} agentes`,
+      ]),
+    );
+  }
+
+  for (const row of rows) {
+    const status = row.status ?? "";
+    // Rule 4: live rows draw as full cards; everything else collapses to one
+    // line naming its glyph, dot, id, name and age.
+    if (LIVE.has(status) || WAIT.has(status)) {
+      const when = age(row.updatedAt, now);
+      const word = statusWord(status);
+      blocks.push(
+        cardBlock(rowAge(row.updatedAt), cell(row.id), [
+          ` ${glyph(row.agent)} ${dot(row.status)} ${cell(row.id)}  ${harnessLabel(row.agent)}`,
+          `   ${cell(row.name)}`,
+          when === "" ? `   ${word}` : `   ${word} · ${when}`,
+        ]),
+      );
+    } else {
+      const when = age(row.updatedAt, now);
+      const line = ` ${glyph(row.agent)} ${dot(row.status)} ${cell(row.id)}  ${cell(row.name)}${
+        when === "" ? "" : ` · ${when}`
+      }`;
+      blocks.push({
+        kind: "line",
+        size: 1,
+        age: rowAge(row.updatedAt),
+        id: cell(row.id),
+        build: (_connects, lead) => [...(lead ? [stem()] : []), frameRow(line)],
+      });
+    }
+  }
+
+  // Whether the block at index i hangs from the one above it by a stem. The
+  // first block is the root and never leads with one. A card is always joined
+  // to what sits above it; a collapsed line only when it opens a run, so a
+  // run of one liners costs a single row per entry.
+  const stemAbove = (list: Block[], i: number): boolean =>
+    i > 0 && (list[i].kind === "card" || list[i - 1].kind === "card");
+
+  // Rule 3: these ten lines are the frame. Whenever anything is drawn at all
+  // they are drawn, and they are never the lines that the fit cuts.
+  const head = [
+    frameTop(`Canvas do run ${cell(source.runId)}`),
+    frameRow(` ${total} sessoes · ${working} trabalhando`),
+    frameRow(` ${waiting} esperando voce · ${finished} prontas`),
+    frameSep(),
+    frameRow(""),
+  ];
+  const tail = [
+    frameRow(""),
+    frameSep(),
+    frameRow(" ● trabalha  ◉ te espera  ○ pronta"),
+    frameRow(" ▲ Claude    ■ OpenCode    ◆ Codex    ⬟ OMP"),
+    frameBot(),
+  ];
+  const fixed = head.length + tail.length;
+  // The hidden line keeps its own stem only when it hangs off a full card;
+  // after a run of one liners it extends the list and costs a single row.
+  const hiddenSize = (list: Block[]): number =>
+    list.length > 0 && list[list.length - 1].kind === "card" ? 2 : 1;
+
+  let kept = blocks;
+  let dropped = 0;
+  if (limit !== undefined) {
+    // Rule 7: the frame alone does not fit, so nothing is drawn at all.
+    if (limit < fixed) return [];
+    // Rule 5: collapsed lines leave first, oldest first; then full cards,
+    // oldest first. The hidden count grows with every row that leaves (rule 6).
+    const victims = [...blocks].sort(
+      (a, b) =>
+        Number(a.kind === "card") - Number(b.kind === "card") ||
+        a.age - b.age ||
+        (a.id < b.id ? -1 : a.id > b.id ? 1 : 0),
+    );
+    const sizeOf = (list: Block[]) =>
+      list.reduce((sum, block, i) => sum + block.size + (stemAbove(list, i) ? 1 : 0), 0);
+    const needed = () => fixed + sizeOf(kept) + (hidden + dropped > 0 ? hiddenSize(kept) : 0);
+    for (let vi = 0; needed() > limit && vi < victims.length; vi += 1) {
+      kept = kept.filter((block) => block !== victims[vi]);
+      dropped += 1;
+    }
+    // Rule 6 outranks one more agent, but the height itself outranks
+    // everything: every block has left and the hidden line still does not
+    // fit, so the frame stands alone. kept is empty by here: the loop only
+    // runs out of victims once every block is gone.
+    if (needed() > limit && kept.length === 0 && hidden + dropped > 0) {
+      return [...head, ...tail];
+    }
+  }
+
+  const hiddenTotal = hidden + dropped;
+  const hiddenRow = frameRow(`  +${hiddenTotal} agentes ocultos`);
+  const out: string[] = [...head];
+  for (let i = 0; i < kept.length; i += 1) {
+    const connects = i < kept.length - 1 || hiddenTotal > 0;
+    out.push(...kept[i].build(connects, stemAbove(kept, i)));
+  }
+  if (hiddenTotal > 0) {
+    if (kept.length > 0 && kept[kept.length - 1].kind === "card") out.push(stem(), hiddenRow);
+    else out.push(hiddenRow);
+  }
+  out.push(...tail);
+  return out;
+}
+
+/**
+ * The whole drawing, one string per line, every line exactly `columns` wide.
+ * `rows` is the usable body height. When given, the result never exceeds it.
+ * Returns [] when there is nothing to draw, the pane is too narrow, or the
+ * height cannot hold even the frame. Never throws.
+ */
+export function formatPane(
+  snapshot: PaneSnapshot,
+  columns: number,
+  rows?: number,
+): string[] {
+  if (typeof columns !== "number" || !Number.isFinite(columns)) return [];
+  if (Math.trunc(columns) < MIN_COLUMNS) return [];
+  const limit =
+    typeof rows === "number" && Number.isFinite(rows) ? Math.trunc(rows) : undefined;
+  try {
+    return draw(snapshot, columns, limit);
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Label for the button drawn above the prompt, the one affordance that brings
+ * the pane back after the engine's own close box took it away. That close is
+ * invisible to this module (verified live: clicking the pane's X fires no hook
+ * at all), so the label never claims to know whether the pane is open and the
+ * button only ever opens. Never throws: it is read inside a render hook.
+ */
+export function paneButtonLabel(snapshot: PaneSnapshot | undefined): string {
+  if (!snapshot || typeof snapshot !== "object") return "agentes";
+  try {
+    const total = count((snapshot as Partial<PaneSnapshot>).total);
+    const rows = Array.isArray(snapshot.rows) ? snapshot.rows : [];
+    const working = rows.filter((row) => LIVE.has(row?.status ?? "")).length;
+    const head = `${total} ${total === 1 ? "agente" : "agentes"}`;
+    return working > 0 ? `${head} · ${working} trabalhando` : head;
+  } catch {
+    return "agentes";
+  }
+}
diff --git a/plugin/mods/agents/parse.ts b/plugin/mods/agents/parse.ts
new file mode 100644
index 0000000..fb94925
--- /dev/null
+++ b/plugin/mods/agents/parse.ts
@@ -0,0 +1,29 @@
+// Parse layer of the orchestrator agents band.
+//
+// Turns the raw stdout of `codedeck ps --all --json` into rows the band can
+// render. The engine draws the whole band in one pass, so a throw here would
+// take the band down with it: every failure path returns undefined instead.
+
+import type { SessionRow } from "./types.js";
+
+// Raw stdout to rows. Returns undefined for anything that is not a JSON array,
+// which is how a failed or truncated command is reported. Never throws.
+export function parseRows(stdout: string): SessionRow[] | undefined {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(stdout);
+  } catch {
+    return undefined;
+  }
+  if (!Array.isArray(parsed)) return undefined;
+  const rows: SessionRow[] = [];
+  for (const entry of parsed) {
+    if (typeof entry !== "object" || entry === null) continue;
+    // id is the one field the band cannot render without, so an entry without
+    // a non-empty string id is dropped rather than passed through.
+    const id = (entry as { id?: unknown }).id;
+    if (typeof id !== "string" || id === "") continue;
+    rows.push(entry as SessionRow);
+  }
+  return rows;
+}
diff --git a/plugin/mods/agents/types.ts b/plugin/mods/agents/types.ts
new file mode 100644
index 0000000..762e3a0
--- /dev/null
+++ b/plugin/mods/agents/types.ts
@@ -0,0 +1,43 @@
+// Shared shapes for the orchestrator agents band.
+//
+// Owned by the interface, not by any one slice: parse, select and format are
+// written against this file and none of them may change it.
+//
+// SessionRow mirrors one element of `codedeck ps --all --json`. Every field
+// past `id` is optional on purpose: the band reads a CLI it does not version
+// with, so a missing field degrades one cell rather than the whole row.
+
+export interface SessionRow {
+  id: string;
+  runId?: string;
+  origin?: string | null;
+  name?: string;
+  agent?: string;
+  status?: string;
+  updatedAt?: string;
+}
+
+/**
+ * One agent card in the pane. The canvas draws a glyph per harness and an age,
+ * so the raw harness id and the timestamp survive here rather than being
+ * flattened into a label.
+ */
+export interface PaneRow {
+  id: string;
+  status: string;
+  agent: string;
+  name: string;
+  updatedAt?: string;
+}
+
+/** Everything one drawing of the pane needs, already narrowed to one run. */
+export interface PaneSnapshot {
+  runId: string;
+  /** The orchestrator's own row, the only one whose origin is "open". */
+  orchestrator: { agent: string } | undefined;
+  rows: PaneRow[];
+  /** Rows that matched the run but fell outside the budget. */
+  hidden: number;
+  /** Every row of the run, including the orchestrator and the hidden ones. */
+  total: number;
+}
diff --git a/plugin/mods/arcade/games/auto.ts b/plugin/mods/arcade/games/auto.ts
deleted file mode 100644
index a6ed9c5..0000000
--- a/plugin/mods/arcade/games/auto.ts
+++ /dev/null
@@ -1,39 +0,0 @@
-import { randomInt } from "./random.js";
-
-export interface AutoInput {
-  lastTurnMs?: number;
-  idle?: boolean;
-}
-
-// One minute (60000 ms) separates quick turns from deep turns.
-export const TURN_THRESHOLD_MS = 60_000;
-
-export const DEEP_GAMES = ["twenty48"];
-export const QUICK_GAMES = ["twenty48"];
-export const DROPIN_GAMES = ["twenty48"];
-
-export type AutoPool = "deep" | "quick" | "dropin";
-
-// Pure pool picker: turns over one minute suggest deep games,
-// turns under one minute suggest quick games, idle suggests drop-in games.
-export function pickPool(input: AutoInput = {}): AutoPool {
-  if (input.idle) return "dropin";
-  if (typeof input.lastTurnMs === "number" && input.lastTurnMs > TURN_THRESHOLD_MS) {
-    return "deep";
-  }
-  return "quick";
-}
-
-// Turn duration heuristic: maps the picked pool to a board.
-export function pickAuto(input: AutoInput = {}): string {
-  const pool = pickPool(input);
-  if (pool === "deep") return DEEP_GAMES[0];
-  if (pool === "dropin") return DROPIN_GAMES[0];
-  return QUICK_GAMES[0];
-}
-
-export function pickRandom(games: string[] = DROPIN_GAMES): string {
-  if (games.length === 0) return DROPIN_GAMES[0];
-  const index = randomInt(games.length);
-  return games[index];
-}
diff --git a/plugin/mods/arcade/games/best.ts b/plugin/mods/arcade/games/best.ts
deleted file mode 100644
index c3c7174..0000000
--- a/plugin/mods/arcade/games/best.ts
+++ /dev/null
@@ -1,9 +0,0 @@
-export type BestTable = Record<string, number>;
-
-// Higher score wins for every arcade game. Returns true when there is no
-// stored best yet for that game, or when the new score beats it.
-export function isBetter(game: string, score: number, best: BestTable): boolean {
-  const prev = best[game];
-  if (prev === undefined) return true;
-  return score > prev;
-}
diff --git a/plugin/mods/arcade/games/pet.ts b/plugin/mods/arcade/games/pet.ts
deleted file mode 100644
index df7833f..0000000
--- a/plugin/mods/arcade/games/pet.ts
+++ /dev/null
@@ -1,119 +0,0 @@
-export type PetEventKind = "test-pass" | "test-fail" | "commit" | "edit";
-
-export interface PetToolCall {
-  tool: string;
-  command?: string;
-  text?: string;
-  ok?: boolean;
-  denied?: boolean;
-  exitCode?: number;
-}
-
-export interface PetEvent {
-  kind: PetEventKind;
-  ok: boolean | undefined;
-  xp: number;
-  mood: number;
-}
-
-export interface Pet {
-  xp: number;
-  mood: number;
-  tests: number;
-  commits: number;
-  edits: number;
-}
-
-export const XP: Record<PetEventKind, number> = {
-  "test-pass": 10,
-  "test-fail": 2,
-  commit: 15,
-  edit: 1,
-};
-
-export const MOOD: Record<PetEventKind, number> = {
-  "test-pass": 8,
-  "test-fail": -12,
-  commit: 10,
-  edit: 1,
-};
-
-// Matches common test invocations:
-// bun / npm / pnpm / yarn test, npx jest vitest mocha,
-// pytest jest vitest rspec phpunit mocha at a command start or after a
-// shell separator, go test, cargo test, make test,
-// mvn gradle gradlew sbt test tasks.
-// Bare tool names are anchored so words inside other commands
-// (e.g. "cat vitest.config.ts") do not count as test runs.
-export const TEST_COMMAND =
-  /(?:\b(?:bun|npm|pnpm|yarn)\s+(?:run\s+)?test\b|\bnpx\s+(?:jest|vitest|mocha)\b|(?:^|[;&|]\s*)\b(?:pytest|jest|vitest|rspec|phpunit|mocha)\b(?=\s|$)|\bgo\s+test\b|\bcargo\s+test\b|\bmake\s+test\b|\b(?:mvn|gradle|gradlew|sbt)\b[^\n]*\btest\b)/;
-
-const GIT_COMMIT = /\bgit\s+commit\b/;
-const DRY_RUN = /--dry-run/;
-
-const EDIT_TOOLS = new Set(["Edit", "Write", "NotebookEdit"]);
-
-function commandText(call: PetToolCall): string {
-  return call.command ?? call.text ?? "";
-}
-
-function kindForTest(call: PetToolCall): PetEventKind {
-  if (call.ok === false) return "test-fail";
-  if (typeof call.exitCode === "number" && call.exitCode !== 0) return "test-fail";
-  return "test-pass";
-}
-
-export function petEvent(call: PetToolCall): PetEvent | undefined {
-  // Denied calls carry undefined ok and are ignored.
-  if (call.denied) return undefined;
-
-  if (call.tool === "Bash") {
-    const text = commandText(call);
-    // Commits win over test words: "git commit -m 'fix jest config'"
-    // is a commit, not a test run.
-    if (GIT_COMMIT.test(text) && !DRY_RUN.test(text)) {
-      return { kind: "commit", ok: call.ok, xp: XP.commit, mood: MOOD.commit };
-    }
-    if (TEST_COMMAND.test(text)) {
-      const kind = kindForTest(call);
-      return { kind, ok: call.ok, xp: XP[kind], mood: MOOD[kind] };
-    }
-    return undefined;
-  }
-
-  if (EDIT_TOOLS.has(call.tool)) {
-    return { kind: "edit", ok: call.ok, xp: XP.edit, mood: MOOD.edit };
-  }
-
-  return undefined;
-}
-
-export function newPet(): Pet {
-  return { xp: 0, mood: 0, tests: 0, commits: 0, edits: 0 };
-}
-
-export function feed(pet: Pet, event: PetEvent): Pet {
-  const next: Pet = {
-    xp: pet.xp + event.xp,
-    mood: pet.mood + event.mood,
-    tests: pet.tests,
-    commits: pet.commits,
-    edits: pet.edits,
-  };
-  if (event.kind === "test-pass" || event.kind === "test-fail") next.tests += 1;
-  if (event.kind === "commit") next.commits += 1;
-  if (event.kind === "edit") next.edits += 1;
-  return next;
-}
-
-export function level(pet: Pet): number {
-  return 1 + Math.floor(Math.max(0, pet.xp) / 100);
-}
-
-export function stage(input: Pet | number): string {
-  const lvl = typeof input === "number" ? input : level(input);
-  if (lvl <= 1) return "egg";
-  if (lvl === 2) return "baby";
-  if (lvl === 3) return "teen";
-  return "adult";
-}
diff --git a/plugin/mods/arcade/games/random.ts b/plugin/mods/arcade/games/random.ts
deleted file mode 100644
index 710cee3..0000000
--- a/plugin/mods/arcade/games/random.ts
+++ /dev/null
@@ -1,12 +0,0 @@
-// Game randomness backed by the platform CSPRNG instead of Math.random.
-// Tile spawns and game picks are not secrets, but a predictable generator is
-// one confused refactor away from mattering, and Sonar flags Math.random
-// (typescript:S2245) wherever it appears.
-export function randomInt(bound: number): number {
-  if (!Number.isInteger(bound) || bound <= 0) {
-    throw new RangeError(`randomInt needs a positive integer bound, got ${bound}`);
-  }
-  const sample = new Uint32Array(1);
-  globalThis.crypto.getRandomValues(sample);
-  return sample[0] % bound;
-}
diff --git a/plugin/mods/arcade/games/twenty48.ts b/plugin/mods/arcade/games/twenty48.ts
deleted file mode 100644
index afa0bc9..0000000
--- a/plugin/mods/arcade/games/twenty48.ts
+++ /dev/null
@@ -1,138 +0,0 @@
-// Pure 2048 logic for the arcade demo board. No engine imports so plain
-// vitest runs it. The board components under plugin/hooks/boards/ own the
-// surface wiring (state, keys, pointer, score posts) and import from here.
-
-import { randomInt } from "./random.js";
-
-export interface SeenDone {
-  current: number;
-}
-
-// Banner helper: pauses once per new done value. The caller keeps `seen`
-// across renders; when `done` changes we record it and pause a single time.
-export function banner(done: number, seen: SeenDone, pause: () => void): string | null {
-  if (done === seen.current) return null;
-  seen.current = done;
-  pause();
-  return `Round ${done} finished - board paused. Press any key to resume.`;
-}
-
-export type Direction = "up" | "down" | "left" | "right";
-
-export interface Twenty48State {
-  grid: number[];
-  score: number;
-  over: boolean;
-  won: boolean;
-  posted: boolean;
-  paused: boolean;
-  seenDone: number;
-}
-
-export function emptyGrid(): number[] {
-  return [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0];
-}
-
-export function spawnTile(grid: number[], pick: () => number): number[] {
-  const open: number[] = [];
-  for (let idx = 0; idx < 16; idx += 1) {
-    if (grid[idx] === 0) open.push(idx);
-  }
-  if (open.length === 0) return grid;
-  const slot = open[pick() % open.length];
-  const next = grid.slice();
-  next[slot] = pick() % 10 === 0 ? 4 : 2;
-  return next;
-}
-
-export function slideRow(row: number[]): { row: number[]; gained: number } {
-  const tiles = row.filter((cell) => cell !== 0);
-  const out: number[] = [];
-  let gained = 0;
-  let idx = 0;
-  while (idx < tiles.length) {
-    if (idx + 1 < tiles.length && tiles[idx] === tiles[idx + 1]) {
-      const merged = tiles[idx] * 2;
-      out.push(merged);
-      gained += merged;
-      idx += 2;
-    } else {
-      out.push(tiles[idx]);
-      idx += 1;
-    }
-  }
-  while (out.length < 4) out.push(0);
-  return { row: out, gained };
-}
-
-export function moveGrid(grid: number[], direction: Direction): { grid: number[]; gained: number; moved: boolean } {
-  const next = grid.slice();
-  let gained = 0;
-  let moved = false;
-  const setRow = (rowIdx: number, row: number[]) => {
-    for (let col = 0; col < 4; col += 1) {
-      const at = rowIdx * 4 + col;
-      if (next[at] !== row[col]) moved = true;
-      next[at] = row[col];
-    }
-  };
-  const getRow = (rowIdx: number): number[] => {
-    const row: number[] = [];
-    for (let col = 0; col < 4; col += 1) row.push(grid[rowIdx * 4 + col]);
-    return row;
-  };
-  const getCol = (colIdx: number): number[] => {
-    const col: number[] = [];
-    for (let rowIdx = 0; rowIdx < 4; rowIdx += 1) col.push(grid[rowIdx * 4 + colIdx]);
-    return col;
-  };
-  const setCol = (colIdx: number, col: number[]) => {
-    for (let rowIdx = 0; rowIdx < 4; rowIdx += 1) {
-      const at = rowIdx * 4 + colIdx;
-      if (next[at] !== col[rowIdx]) moved = true;
-      next[at] = col[rowIdx];
-    }
-  };
-  if (direction === "left" || direction === "right") {
-    for (let rowIdx = 0; rowIdx < 4; rowIdx += 1) {
-      let row = getRow(rowIdx);
-      if (direction === "right") row = row.reverse();
-      const slid = slideRow(row);
-      gained += slid.gained;
-      const placed = direction === "right" ? slid.row.reverse() : slid.row;
-      setRow(rowIdx, placed);
-    }
-  } else {
-    for (let colIdx = 0; colIdx < 4; colIdx += 1) {
-      let col = getCol(colIdx);
-      if (direction === "down") col = col.reverse();
-      const slid = slideRow(col);
-      gained += slid.gained;
-      const placed = direction === "down" ? slid.row.reverse() : slid.row;
-      setCol(colIdx, placed);
-    }
-  }
-  return { grid: next, gained, moved };
-}
-
-export function isFinished(grid: number[]): boolean {
-  if (grid.some((cell) => cell === 0)) return false;
-  const probe: Direction[] = ["up", "down", "left", "right"];
-  for (const direction of probe) {
-    if (moveGrid(grid, direction).moved) return false;
-  }
-  return true;
-}
-
-export function initialTwenty48State(pick: () => number = () => randomInt(16)): Twenty48State {
-  const seeded = spawnTile(spawnTile(emptyGrid(), pick), pick);
-  return { grid: seeded, score: 0, over: false, won: false, posted: false, paused: false, seenDone: 0 };
-}
-
-export function directionForKey(name: string): Direction | null {
-  if (name === "up" || name === "w") return "up";
-  if (name === "down" || name === "s") return "down";
-  if (name === "left" || name === "a") return "left";
-  if (name === "right" || name === "d") return "right";
-  return null;
-}
diff --git a/plugin/mods/arcade/index.ts b/plugin/mods/arcade/index.ts
deleted file mode 100644
index 1ccb34e..0000000
--- a/plugin/mods/arcade/index.ts
+++ /dev/null
@@ -1,13 +0,0 @@
-// Arcade mod: a single demo board (twenty48) plus a companion pet that
-// feeds on tool activity. The manifest declaration for this mod lands in a
-// parallel slice; this file only names the mod and its boards.
-
-export const ARCADE_MOD_NAME = "arcade";
-
-export const ARCADE_BOARDS = ["twenty48"] as const;
-
-export type ArcadeBoardName = (typeof ARCADE_BOARDS)[number];
-
-export const ARCADE_BOARD_MODULES: Record<ArcadeBoardName, string> = {
-  twenty48: "hooks/boards/twenty48.tsx",
-};
diff --git a/scripts/pane-mock.mjs b/scripts/pane-mock.mjs
new file mode 100644
index 0000000..08029f9
--- /dev/null
+++ b/scripts/pane-mock.mjs
@@ -0,0 +1,105 @@
+// Mock of the right-side agents pane: the web canvas, drawn as ASCII.
+// Throwaway, exists to settle the shape before any engine work.
+// Run: node scripts/pane-mock.mjs [runId] [width]
+
+import { execFileSync } from "node:child_process";
+
+const runId = process.argv[2] ?? process.env.CODEDECK_RUN_ID ?? "f5fd";
+const W = Number(process.argv[3] ?? 40);
+
+const all = JSON.parse(
+  execFileSync("codedeck", ["ps", "--all", "--json"], { encoding: "utf8", maxBuffer: 33554432 }),
+);
+const mine = all.filter((r) => r && r.runId === runId);
+const boss = mine.find((r) => r.origin === "open");
+const kids = mine
+  .filter((r) => r.origin !== "open")
+  .sort((a, b) => Date.parse(b.updatedAt ?? 0) - Date.parse(a.updatedAt ?? 0));
+
+const LIVE = new Set(["working", "starting"]);
+const WAIT = new Set(["needs_input"]);
+const count = {
+  live: kids.filter((k) => LIVE.has(k.status)).length,
+  wait: kids.filter((k) => WAIT.has(k.status)).length,
+  done: kids.filter((k) => !LIVE.has(k.status) && !WAIT.has(k.status)).length,
+};
+
+const dot = (s) => (LIVE.has(s) ? "●" : WAIT.has(s) ? "◉" : "○");
+const word = (s) =>
+  ({
+    working: "Trabalhando agora",
+    starting: "Subindo",
+    needs_input: "Esperando voce",
+    completed: "Concluida",
+    stopped: "Em pausa",
+    failed: "Falhou",
+  })[s] ?? s;
+const glyph = (a) => ({ claude: "▲", opencode: "■", codex: "◆", omp: "⬟" })[a] ?? "□";
+const nameOf = (a) => ({ claude: "Claude", opencode: "OpenCode", codex: "Codex", omp: "OMP" })[a] ?? a;
+
+function age(iso) {
+  const ms = Date.now() - Date.parse(iso ?? 0);
+  if (!Number.isFinite(ms)) return "";
+  const m = Math.floor(ms / 60000);
+  return m < 1 ? "agora" : m < 60 ? `${m}m` : `${Math.floor(m / 60)}h`;
+}
+const clip = (s, n) => (String(s).length <= n ? String(s) : String(s).slice(0, n - 1) + "…");
+const pad = (s, n) => clip(s, n).padEnd(n);
+
+// Outer frame helpers. Everything inside is exactly W-2 wide.
+const IN = W - 2;
+const out = [];
+const frameTop = (label) => out.push("┌" + ("─ " + label + " ").padEnd(IN, "─") + "┐");
+const frameRow = (s) => out.push("│" + pad(s, IN) + "│");
+const frameSep = () => out.push("├" + "─".repeat(IN) + "┤");
+const frameBot = () => out.push("└" + "─".repeat(IN) + "┘");
+
+// A node card, indented inside the frame, with an optional stem below it.
+const CARD = IN - 4; // two spaces of margin each side
+const cardTop = () => frameRow("  ┌" + "─".repeat(CARD - 2) + "┐");
+const cardRow = (s) => frameRow("  │" + pad(s, CARD - 2) + "│");
+const cardBotStem = () => {
+  const left = Math.floor((CARD - 2) / 2);
+  frameRow("  └" + "─".repeat(left) + "┬" + "─".repeat(CARD - 3 - left) + "┘");
+};
+const cardBotPlain = () => frameRow("  └" + "─".repeat(CARD - 2) + "┘");
+const stem = () => {
+  const left = Math.floor((CARD - 2) / 2);
+  frameRow("  " + " ".repeat(left + 1) + "│");
+};
+
+frameTop("Canvas do run " + runId);
+frameRow(` ${mine.length} sessoes · ${count.live} trabalhando`);
+frameRow(` ${count.wait} esperando voce · ${count.done} prontas`);
+frameSep();
+frameRow("");
+
+// orchestrator
+cardTop();
+cardRow(` ${glyph(boss?.agent ?? "claude")} ● Orquestrador`);
+cardRow(`   ${nameOf(boss?.agent ?? "claude")} · ${kids.length} agentes`);
+cardBotStem();
+
+const SHOW = 5;
+kids.slice(0, SHOW).forEach((k, i) => {
+  stem();
+  cardTop();
+  cardRow(` ${glyph(k.agent)} ${dot(k.status)} ${k.id}  ${nameOf(k.agent)}`);
+  cardRow(`   ${clip(k.name ?? "-", CARD - 5)}`);
+  cardRow(`   ${word(k.status)} · ${age(k.updatedAt)}`);
+  const last = i === Math.min(SHOW, kids.length) - 1;
+  if (last && kids.length <= SHOW) cardBotPlain();
+  else cardBotStem();
+});
+if (kids.length > SHOW) {
+  stem();
+  frameRow(`  +${kids.length - SHOW} agentes ocultos`);
+}
+frameRow("");
+frameSep();
+frameRow(" ● trabalha  ◉ te espera  ○ pronta");
+frameBot();
+
+console.log("");
+for (const l of out) console.log("  " + l);
+console.log("");
diff --git a/scripts/pane-probe.sh b/scripts/pane-probe.sh
new file mode 100755
index 0000000..5f282bf
--- /dev/null
+++ b/scripts/pane-probe.sh
@@ -0,0 +1,178 @@
+#!/usr/bin/env bash
+# Proves the codedeck agents pane actually draws on screen.
+#
+# `npm run build` never type checks plugin/ and `claude plugin validate` only
+# checks manifest shape, so both pass against a module that draws nothing or
+# draws garbage. That gap cost a day once: the pane looked broken while the
+# module was fine, and the real defect was <Box> defaulting to a row layout,
+# which shredded 51 lines into vertical slivers of box characters with zero
+# errors raised. Only a screen capture showed it.
+#
+# This probe starts a disposable tmux session running the real CLI against a
+# plugin dir, polls the capture until the canvas frame appears, then grades
+# the screen. It never sends a prompt to the model: the pane draws at session
+# start, and a probe that spends tokens is a probe nobody runs.
+#
+# Usage: pane-probe.sh [run-id] [plugin-dir]
+# Defaults: $CODEDECK_RUN_ID or f5fd, and $PWD/dist/plugin.
+# Exit 0 only when every assertion passed.
+set -euo pipefail
+
+# Widths are counted in characters, and the dock is made of three-byte box
+# drawing glyphs, so a UTF-8 locale is not optional here. Re-exec once under
+# C.UTF-8 rather than trust whatever the caller exported.
+if [[ ${_PANE_PROBE_UTF8:-} != 1 ]]; then
+  export _PANE_PROBE_UTF8=1 LC_ALL=C.UTF-8
+  exec "$0" "$@"
+fi
+
+RUN_ID="${1:-${CODEDECK_RUN_ID:-f5fd}}"
+PLUGIN_DIR="${2:-$PWD/dist/plugin}"
+SESSION="pane-probe-$$-${RANDOM}"
+COLS=200
+ROWS=50
+TIMEOUT=45
+FRAME_TEXT="Canvas do run $RUN_ID"
+
+probe_char=$'\xc3\xa9'
+if [[ ${#probe_char} -ne 1 ]]; then
+  echo "pane-probe: no UTF-8 locale available, cannot count box drawing widths" >&2
+  exit 2
+fi
+for tool in tmux claude; do
+  command -v "$tool" >/dev/null || { echo "pane-probe: $tool is not installed" >&2; exit 2; }
+done
+[[ -d $PLUGIN_DIR ]] || { echo "pane-probe: plugin dir not found: $PLUGIN_DIR" >&2; exit 2; }
+
+cleanup() { tmux kill-session -t "$SESSION" 2>/dev/null || true; }
+trap cleanup EXIT
+trap 'exit 130' INT
+trap 'exit 143' TERM
+
+echo "pane-probe: session=$SESSION run=$RUN_ID plugin=$PLUGIN_DIR" >&2
+
+# exec inside the session keeps death detection honest: when claude quits the
+# tmux session goes with it and the poll below stops early instead of waiting
+# out the timeout on a corpse.
+tmux new-session -d -s "$SESSION" -x "$COLS" -y "$ROWS" \
+  "CLAUDE_CODE_ENABLE_FUNCTION_HOOKS=1 CODEDECK_RUN_ID=$RUN_ID exec claude --plugin-dir '$PLUGIN_DIR'"
+
+capture=""
+deadline=$((SECONDS + TIMEOUT))
+while ((SECONDS < deadline)); do
+  if ! tmux has-session -t "$SESSION" 2>/dev/null; then
+    echo "pane-probe: session died before the pane drew" >&2
+    capture=""
+    break
+  fi
+  capture="$(tmux capture-pane -t "$SESSION" -p 2>/dev/null || true)"
+  [[ $capture == *"$FRAME_TEXT"* ]] && break
+  sleep 1
+done
+if tmux has-session -t "$SESSION" 2>/dev/null; then
+  capture="$(tmux capture-pane -t "$SESSION" -p 2>/dev/null || true)"
+fi
+
+failures=0
+result() { # <name> <PASS|FAIL> [detail]
+  printf '%-5s %-7s%s\n' "$2" "$1" "${3:+  ($3)}"
+  [[ $2 == PASS ]] || failures=$((failures + 1))
+}
+
+echo
+echo "== captured screen =="
+printf '%s\n' "$capture"
+echo
+echo "== assertions =="
+
+if grep -qF -- "$FRAME_TEXT" <<<"$capture"; then
+  result frame PASS
+else
+  result frame FAIL "no line holds \"$FRAME_TEXT\""
+fi
+
+# Counting dock lines that share a width does not work: the dock rail alone
+# satisfies it, so a shredded drawing scores the same as a canvas. Measured,
+# that check reported PASS on a screen full of confetti.
+#
+# What does separate them is the horizontal rules. A real drawing is built out
+# of long runs of ─, the frame top, the separators, every card edge. Shredding
+# chops each of those into two and three character fragments, so the long runs
+# vanish. Measured on both captures: 23 such lines when correct, 0 inside the
+# dock when shredded. The only long runs left on a shredded screen are the
+# prompt separators, which span the terminal and sit outside the dock, so
+# restricting the count to the dock region is load bearing.
+#
+# The threshold is 5 because the floor of a legitimate drawing is 6: the frame
+# top, two separators and the closing border, plus the two edges of the
+# orchestrator card, which is always drawn. Everything else, the worker cards
+# and their edges, comes and goes with what the run is doing. A screen with one
+# working agent counts 8. Shredded counts 0. Five sits clear of both.
+rule_lines=0
+while IFS= read -r line; do
+  [[ $line == *│* ]] || continue
+  # the dock region starts at the rail, so everything from the first │ on
+  dock="│${line#*│}"
+  longest=0
+  run=0
+  rest="$dock"
+  while [[ -n $rest ]]; do
+    if [[ ${rest:0:1} == ─ ]]; then
+      run=$((run + 1))
+      ((run > longest)) && longest=$run
+    else
+      run=0
+    fi
+    rest="${rest:1}"
+  done
+  ((longest >= 20)) && rule_lines=$((rule_lines + 1))
+done <<<"$capture"
+
+if ((rule_lines >= 5)); then
+  result shape PASS "$rule_lines dock lines hold a rule of 20 or more"
+else
+  result shape FAIL "only $rule_lines dock lines hold a rule of 20 or more, drawing is shredded"
+fi
+
+# The closing border of the canvas frame is the widest └…┘ on screen. Its
+# width is measured from the frame top line, corner to last visible
+# character, because the top-right corner carries the close glyph instead of
+# a ┐. An inner card bottom is always narrower, so it cannot match by
+# accident.
+bottom=""
+width=0
+frame_line="$(grep -F -- "$FRAME_TEXT" <<<"$capture" | head -n 1)" || true
+frame_line="${frame_line%"${frame_line##*[![:space:]]}"}"
+if [[ $frame_line == *┌* ]]; then
+  span="${frame_line#*┌}"
+  width=$(( ${#span} + 1 ))
+  dashes=""
+  while (( ${#dashes} < width - 2 )); do dashes+="─"; done
+  bottom="└${dashes}┘"
+fi
+if [[ -z $bottom ]]; then
+  result footer FAIL "frame top line absent, cannot measure the closing border"
+elif grep -qF -- "$bottom" <<<"$capture"; then
+  result footer PASS "closing border present at width $width"
+else
+  result footer FAIL "closing border (width $width) not on screen, drawing is clipped"
+fi
+
+offenders=""
+for phrase in "hook skipped" "did not load" "refused"; do
+  grep -qF -- "$phrase" <<<"$capture" && offenders+="'$phrase' "
+done
+if [[ -z $offenders ]]; then
+  result clean PASS
+else
+  result clean FAIL "capture holds $offenders"
+fi
+
+echo
+if ((failures == 0)); then
+  echo "VERDICT: PASS"
+  exit 0
+else
+  echo "VERDICT: FAIL ($failures assertion(s))"
+  exit 1
+fi
diff --git a/src/open/runtime.ts b/src/open/runtime.ts
index 708f266..3e9e40b 100644
--- a/src/open/runtime.ts
+++ b/src/open/runtime.ts
@@ -180,7 +180,7 @@ export function sanitizeEnv(env: NodeJS.ProcessEnv): NodeJS.ProcessEnv {
   // alone, since silencing mise everywhere is not this command's call.
   sanitized.MISE_QUIET ??= "1";
 
-  // Function hooks back the codedeck arcade mod, and Claude Code only loads
+  // Function hooks back the codedeck agents pane, and Claude Code only loads
   // hook modules when the spawning environment enables them. The variable is
   // namespaced to Claude Code, so the opencode and codex spawns that share
   // this helper carry it inertly and behave exactly as before. A value of the
diff --git a/tests/mods-agents/pane.test.ts b/tests/mods-agents/pane.test.ts
new file mode 100644
index 0000000..07a63bb
--- /dev/null
+++ b/tests/mods-agents/pane.test.ts
@@ -0,0 +1,616 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  MAX_CARD_COLUMNS,
+  MIN_COLUMNS,
+  formatPane,
+  paneButtonLabel,
+  selectPane,
+} from "../../plugin/mods/agents/pane.js";
+import type { PaneRow, PaneSnapshot, SessionRow } from "../../plugin/mods/agents/types.js";
+
+const RUN = "f5fd";
+
+const session = (overrides: Partial<SessionRow> = {}): SessionRow => ({
+  id: "seed",
+  runId: RUN,
+  origin: "run",
+  status: "completed",
+  agent: "opencode",
+  name: "task",
+  updatedAt: "2026-09-19T12:00:00.000Z",
+  ...overrides,
+});
+
+// A ready-made snapshot for the drawing rules, independent of selectPane.
+const snapshot = (overrides: Partial<PaneSnapshot> = {}): PaneSnapshot => ({
+  runId: RUN,
+  orchestrator: { agent: "claude" },
+  rows: [
+    { id: "a1", status: "working", agent: "opencode", name: "alpha" },
+    { id: "b2", status: "completed", agent: "claude", name: "beta" },
+  ],
+  hidden: 0,
+  total: 3,
+  ...overrides,
+});
+
+const ids = (snap: PaneSnapshot) => snap.rows.map((row) => row.id);
+
+// The stem connector line at 89 columns: the card box caps at 56, so the
+// stem sits at column 31 inside a frame row padded to the full width. Exact
+// literal, so a stray or duplicated stem is caught by string identity.
+const STEM89 = "│" + " ".repeat(30) + "│" + " ".repeat(56) + "│";
+
+// Assert every line is exactly `columns` code units (the frozen contract is
+// code units, matching fit()'s .length and the mock) and carries no newline,
+// carriage return or tab. Reused by the width and hygiene rules.
+function expectCleanWidth(lines: string[], columns: number): void {
+  expect(lines.length).toBeGreaterThan(0);
+  for (const line of lines) {
+    expect(line.length).toBe(columns);
+    expect(line).not.toMatch(/[\n\r\t]/);
+  }
+}
+
+// The real-screen fixture from the bug report: a run of 19 workers, one
+// working and 18 finished, in a pane 89 columns wide and 44 rows tall. Built
+// through selectPane so the snapshot is what the daemon pipeline produces.
+function workerFixture(): PaneSnapshot {
+  const base = Date.parse("2026-09-19T12:00:00.000Z");
+  const finished = Array.from({ length: 18 }, (_, i) =>
+    session({
+      id: `a${String(i + 1).padStart(2, "0")}`,
+      name: `task-${String(i + 1).padStart(2, "0")}`,
+      updatedAt: new Date(base - i * 60000).toISOString(),
+    }),
+  );
+  return selectPane(
+    [session({ id: "w1", status: "working", name: "live", updatedAt: new Date(base + 30 * 60000).toISOString() }), ...finished],
+    RUN,
+  );
+}
+
+describe("selectPane", () => {
+  it("keeps only the rows whose runId matches (rule 1)", () => {
+    const snap = selectPane(
+      [session({ id: "mine" }), session({ id: "theirs", runId: "other" }), session({ id: "bare", runId: undefined })],
+      RUN,
+    );
+    expect(ids(snap)).toEqual(["mine"]);
+  });
+
+  it("lifts the origin open row as the orchestrator, never a card (rule 2)", () => {
+    const snap = selectPane(
+      [session({ id: "boss", origin: "open", agent: "claude" }), session({ id: "kid", origin: "run" })],
+      RUN,
+    );
+    expect(snap.orchestrator).toEqual({ agent: "claude" });
+    expect(ids(snap)).toEqual(["kid"]);
+  });
+
+  it("orders workers by updatedAt descending, unparseable last, ties by id (rule 3)", () => {
+    const snap = selectPane(
+      [
+        session({ id: "z-old", updatedAt: "2026-09-19T10:00:00.000Z" }),
+        session({ id: "new", updatedAt: "2026-09-19T14:00:00.000Z" }),
+        session({ id: "alpha", updatedAt: "2026-09-19T12:00:00.000Z" }),
+        session({ id: "zeta", updatedAt: "2026-09-19T12:00:00.000Z" }),
+        session({ id: "no-date", updatedAt: undefined }),
+        session({ id: "garbage", updatedAt: "yesterday-ish" }),
+      ],
+      RUN,
+    );
+    expect(ids(snap)).toEqual(["new", "alpha", "zeta", "z-old", "garbage", "no-date"]);
+  });
+
+  it("gives a total order, so input order does not change the pane (rule 3)", () => {
+    const tied = [
+      session({ id: "b", updatedAt: "2026-09-19T12:00:00.000Z" }),
+      session({ id: "a", updatedAt: "2026-09-19T12:00:00.000Z" }),
+      session({ id: "c", updatedAt: "2026-09-19T12:00:00.000Z" }),
+    ];
+    expect(ids(selectPane(tied, RUN))).toEqual(["a", "b", "c"]);
+    expect(ids(selectPane([...tied].reverse(), RUN))).toEqual(["a", "b", "c"]);
+  });
+
+  it("cuts to an explicit budget and counts the rest as hidden", () => {
+    const workers = Array.from({ length: 4 }, (_, i) =>
+      session({ id: `s${i}`, updatedAt: `2026-09-19T10:0${i}:00.000Z` }),
+    );
+    const snap = selectPane([session({ id: "boss", origin: "open" }), ...workers], RUN, 2);
+    expect(ids(snap)).toEqual(["s3", "s2"]);
+    expect(snap.hidden).toBe(2);
+    expect(snap.total).toBe(5);
+  });
+
+  it("keeps every matched row and reports no hidden when the budget is omitted", () => {
+    const workers = Array.from({ length: 19 }, (_, i) =>
+      session({ id: `s${String(i).padStart(2, "0")}`, updatedAt: `2026-09-19T10:${String(i).padStart(2, "0")}:00.000Z` }),
+    );
+    const snap = selectPane(workers, RUN);
+    expect(snap.rows).toHaveLength(19);
+    expect(snap.hidden).toBe(0);
+    expect(snap.total).toBe(19);
+  });
+
+  it("treats a non-finite budget as no budget, and zero as cut everything", () => {
+    const workers = [session({ id: "s1" }), session({ id: "s2", updatedAt: "2026-09-19T10:00:00.000Z" })];
+    expect(selectPane(workers, RUN, Number.NaN).rows).toHaveLength(2);
+    expect(selectPane(workers, RUN, Number.POSITIVE_INFINITY).hidden).toBe(0);
+    const none = selectPane(workers, RUN, 0);
+    expect(none.rows).toHaveLength(0);
+    expect(none.hidden).toBe(2);
+  });
+
+  it("resolves a missing agent, name or status to a placeholder (rule 13)", () => {
+    const snap = selectPane(
+      [session({ id: "bare", status: undefined, agent: "", name: undefined })],
+      RUN,
+    );
+    expect(snap.rows[0]).toMatchObject({ status: "-", agent: "-" });
+    expect(snap.rows[0].name).toBe("-");
+  });
+
+  it("never throws on a degenerate row list (rule 14)", () => {
+    expect(selectPane(null as unknown as SessionRow[], RUN)).toMatchObject({ rows: [], hidden: 0, total: 0 });
+    expect(selectPane([null, undefined] as unknown as SessionRow[], RUN).rows).toEqual([]);
+  });
+});
+
+describe("formatPane", () => {
+  it("never exceeds the given rows, at every width and every input (rule 1)", () => {
+    const snaps = [snapshot(), workerFixture(), snapshot({ rows: [], hidden: 7, total: 7 })];
+    for (const snap of snaps) {
+      for (const columns of [MIN_COLUMNS, 40, 89, 120]) {
+        for (const rows of [0, 9, 10, 11, 12, 15, 20, 44, 45, 200]) {
+          const lines = formatPane(snap, columns, rows);
+          expect(lines.length).toBeLessThanOrEqual(rows);
+          for (const line of lines) expect(line.length).toBe(columns);
+        }
+      }
+    }
+  });
+
+  it("cuts nothing and keeps every row when rows is not a usable number (rule 2)", () => {
+    const snap = workerFixture();
+    const wide = formatPane(snap, 89);
+    // 10 frame + the card at 5, the 18 collapsed lines at 1 each, and the
+    // single stem opening their run: 24 body lines once stems stop padding
+    // every one liner.
+    expect(wide).toHaveLength(34);
+    expect(wide.some((l) => l.includes("agentes ocultos"))).toBe(false);
+    expect(wide.join("\n")).toContain("a18");
+    expect(formatPane(snap, 89, undefined)).toEqual(wide);
+    expect(formatPane(snap, 89, Number.NaN)).toEqual(wide);
+    expect(formatPane(snap, 89, Number.POSITIVE_INFINITY)).toEqual(wide);
+    expect(formatPane(snap, 89, "44" as unknown as number)).toEqual(wide);
+    // The same snapshot under a height that cannot hold it does cut.
+    expect(formatPane(snap, 89, 30)).toHaveLength(30);
+  });
+
+  it("survives as a frame at every height that draws anything (rule 3)", () => {
+    const snap = workerFixture();
+    for (const rows of [10, 11, 12, 15, 20, 30, 44, 50, 400]) {
+      const lines = formatPane(snap, 89, rows);
+      expect(lines.length).toBeGreaterThan(0);
+      expect(lines[0]).toMatch(/^┌─ Canvas do run/);
+      expect(lines[1]).toContain("sessoes");
+      expect(lines[2]).toContain("prontas");
+      expect(lines[3]).toMatch(/^├─/);
+      expect(lines[lines.length - 1]).toMatch(/^└─/);
+      expect(lines[lines.length - 3]).toContain("● trabalha");
+      expect(lines[lines.length - 2]).toContain("▲ Claude");
+      expect(lines[lines.length - 4]).toMatch(/^├─/);
+    }
+  });
+
+  it("draws live rows as cards and everything else as one collapsed line (rule 4)", () => {
+    const rows: PaneRow[] = [
+      { id: "k1", status: "working", agent: "opencode", name: "k-live" },
+      { id: "k2", status: "needs_input", agent: "claude", name: "k-wait" },
+      { id: "k3", status: "starting", agent: "codex", name: "k-boot" },
+      { id: "k4", status: "completed", agent: "claude", name: "k-done" },
+      { id: "k5", status: "stopped", agent: "omp", name: "k-stop" },
+      { id: "k6", status: "weird", agent: "opencode", name: "k-odd" },
+    ];
+    const joined = formatPane(snapshot({ rows, hidden: 0, total: 7 }), 89).join("\n");
+    expect(joined).toContain("Trabalhando agora");
+    expect(joined).toContain("Esperando voce");
+    expect(joined).toContain("Subindo");
+    expect(joined).not.toContain("Concluida");
+    expect(joined).not.toContain("Em pausa");
+    expect(joined).toContain("▲ ○ k4  k-done");
+    expect(joined).toContain("⬟ ○ k5  k-stop");
+    expect(joined).toContain("■ ○ k6  k-odd");
+  });
+
+  it("drops collapsed lines oldest first before any full card (rule 5)", () => {
+    const rows: PaneRow[] = [
+      { id: "wNew", status: "working", agent: "claude", name: "wn", updatedAt: "2026-09-19T12:00:00.000Z" },
+      { id: "cNew", status: "completed", agent: "claude", name: "cn", updatedAt: "2026-09-19T11:00:00.000Z" },
+      { id: "wOld", status: "working", agent: "claude", name: "wo", updatedAt: "2026-09-19T09:00:00.000Z" },
+      { id: "cOld", status: "completed", agent: "claude", name: "co", updatedAt: "2026-09-19T08:00:00.000Z" },
+    ];
+    const snap = snapshot({ rows, orchestrator: undefined, hidden: 0, total: 4 });
+    // Full drawing is 10 + 5 + 2 + 6 + 2 = 25: the first card costs no stem,
+    // the line after the other card costs one. At 24 exactly the two collapsed
+    // lines leave; the older card stays though the collapsed rows are newer.
+    const at24 = formatPane(snap, 40, 24);
+    expect(at24).toHaveLength(23);
+    expect(at24.join("\n")).toContain("wOld");
+    expect(at24.join("\n")).not.toContain("cOld");
+    expect(at24.join("\n")).not.toContain("cNew");
+    expect(at24.join("\n")).toContain("+2 agentes ocultos");
+    // At 21 the next victim is the older card, not the newer one.
+    const at21 = formatPane(snap, 40, 21);
+    expect(at21).toHaveLength(17);
+    expect(at21.join("\n")).toContain("wNew");
+    expect(at21.join("\n")).not.toContain("wOld");
+    expect(at21.join("\n")).toContain("+3 agentes ocultos");
+  });
+
+  it("counts everything it dropped into the hidden line, and the line outranks one agent (rule 6)", () => {
+    const snap = snapshot({ hidden: 2, total: 6 });
+    const unbounded = formatPane(snap, 40);
+    const hiddenLine = unbounded.filter((l) => l.includes("agentes ocultos"));
+    expect(hiddenLine).toHaveLength(1);
+    expect(hiddenLine[0]).toContain("+2 agentes ocultos");
+
+    // Force fifteen row drops on top of the snapshot's own hidden zero.
+    const fitted = formatPane(workerFixture(), 89, 20);
+    expect(fitted.filter((l) => l.includes("agentes ocultos"))).toHaveLength(1);
+    expect(fitted.join("\n")).toContain("+15 agentes ocultos");
+
+    // At 12 rows drawing any agent would crowd out the hidden line; the
+    // hidden line wins and no agent is drawn.
+    const tight = formatPane(workerFixture(), 89, 12);
+    expect(tight.join("\n")).toContain("+19 agentes ocultos");
+    expect(tight.join("\n")).not.toContain("w1");
+  });
+
+  it("returns nothing when the height cannot hold the frame alone (rule 7)", () => {
+    const snap = workerFixture();
+    expect(formatPane(snap, 89, 9)).toEqual([]);
+    expect(formatPane(snap, 89, 0)).toEqual([]);
+    expect(formatPane(snap, 89, -5)).toEqual([]);
+    expect(formatPane(snap, 89, 10)).toHaveLength(10);
+  });
+
+  it("caps cards at MAX_CARD_COLUMNS while the frame spans the pane (rule 8)", () => {
+    expect(MAX_CARD_COLUMNS).toBe(56);
+    const lines = formatPane(workerFixture(), 100);
+    expectCleanWidth(lines, 100);
+    const cardTops = lines.filter((l) => l.startsWith("│  ┌─"));
+    expect(cardTops.length).toBeGreaterThan(0);
+    for (const top of cardTops) {
+      const open = top.indexOf("┌", 2);
+      const close = top.indexOf("┐");
+      expect(close - open - 1).toBeLessThanOrEqual(MAX_CARD_COLUMNS - 2);
+      expect(close - open - 1).toBe(54);
+    }
+    expect(lines[0]).toMatch(/^┌─ Canvas do run .*─┐$/);
+    expect(lines[0]).toHaveLength(100);
+  });
+
+  it("returns lines all exactly the requested width across three widths (rule 9)", () => {
+    const snap = snapshot();
+    for (const columns of [MIN_COLUMNS, 40, 60]) {
+      expectCleanWidth(formatPane(snap, columns), columns);
+      expectCleanWidth(formatPane(snap, columns, 100), columns);
+    }
+  });
+
+  it("keeps exact code-unit width when astral content is clipped (rule 9)", () => {
+    const snap = snapshot({
+      rows: [{ id: "🚀🚀🚀", status: "completed", agent: "claude", name: "🚀 a🚀b🚀 café" }],
+    });
+    for (const columns of [24, 40, 60]) {
+      const lines = formatPane(snap, columns);
+      expectCleanWidth(lines, columns);
+    }
+  });
+
+  it("draws the agreed shape at 40 columns (rule 9)", () => {
+    const lines = formatPane(snapshot({
+      rows: [{ id: "12a4", status: "completed", agent: "opencode", name: "fix-setup-active-profile", updatedAt: "2026-09-19T12:00:00.000Z" }],
+      hidden: 12,
+      total: 14,
+    }), 40);
+    expect(lines[0]).toBe("┌─ Canvas do run f5fd ─────────────────┐");
+    expect(lines[0]).toHaveLength(40);
+    expect(lines.some((l) => l.includes("Orquestrador"))).toBe(true);
+    expect(lines.some((l) => l.includes("12a4"))).toBe(true);
+    expect(lines.some((l) => l.includes("+12 agentes ocultos"))).toBe(true);
+  });
+
+  it("returns no line carrying a newline, carriage return or tab (rule 9)", () => {
+    const snap = snapshot({
+      rows: [{ id: "x", status: "work\ting", agent: "cla\rude", name: "line\nbreak" }],
+    });
+    for (const line of formatPane(snap, 40)) {
+      expect(line).not.toMatch(/[\n\r\t]/);
+    }
+  });
+
+  it("turns control and separator characters into spaces before drawing (rule 9)", () => {
+    const snap = snapshot({
+      rows: [{ id: "esc", status: "completed", agent: "opencode", name: "ref\u001b[2J\u001b[Hx\u2028docs\u2029y" }],
+    });
+    const lines = formatPane(snap, 40);
+    expectCleanWidth(lines, 40);
+    for (const line of lines) {
+      expect(line).not.toMatch(/[\u0000-\u001f\u007f-\u009f\u2028\u2029]/);
+    }
+    expect(lines.join("\n")).toContain("ref");
+  });
+
+  it("clips an over-long name to the cell without wrapping it (rule 9)", () => {
+    const snap = snapshot({
+      rows: [{ id: "c", status: "completed", agent: "claude", name: "n".repeat(200) }],
+    });
+    const lines = formatPane(snap, 40);
+    expectCleanWidth(lines, 40);
+    expect(lines.join("\n")).not.toMatch(/n{40}/);
+  });
+
+  it("never strands half of a surrogate pair when clipping (rule 9)", () => {
+    const snap = snapshot({
+      rows: [{ id: "s", status: "completed", agent: "claude", name: "🚀".repeat(60) }],
+    });
+    for (const line of formatPane(snap, 40)) {
+      // Walk the line as code units, consuming a valid pair together. A high
+      // not followed by a low, or a low not preceded by a high, is a strand.
+      for (let i = 0; i < line.length; i += 1) {
+        const code = line.charCodeAt(i);
+        if (code >= 0xd800 && code <= 0xdbff) {
+          const next = line.charCodeAt(i + 1);
+          expect(next >= 0xdc00 && next <= 0xdfff).toBe(true);
+          i += 1;
+        } else {
+          expect(code >= 0xdc00 && code <= 0xdfff).toBe(false);
+        }
+      }
+    }
+  });
+
+  it("returns an empty array when columns is below MIN_COLUMNS (rule 9)", () => {
+    expect(MIN_COLUMNS).toBe(24);
+    expect(formatPane(snapshot(), 23)).toEqual([]);
+    expect(formatPane(snapshot(), 0)).toEqual([]);
+  });
+
+  it("returns an empty array when there are no rows and no orchestrator (rule 10)", () => {
+    expect(formatPane(snapshot({ rows: [], orchestrator: undefined, hidden: 0 }), 40)).toEqual([]);
+    expect(formatPane(snapshot({ rows: [], orchestrator: undefined, hidden: 4 }), 40)).toEqual([]);
+  });
+
+  it("draws an orchestrator-only run as a single node (rule 10)", () => {
+    const lines = formatPane(snapshot({ rows: [], hidden: 0, total: 1 }), 40);
+    expectCleanWidth(lines, 40);
+    expect(lines.some((l) => l.includes("Orquestrador"))).toBe(true);
+    expect(lines.some((l) => l.includes("ocultos"))).toBe(false);
+  });
+
+  it("adds exactly one hidden line naming the count, and none when hidden is 0 (rule 6)", () => {
+    const withHidden = formatPane(snapshot({ hidden: 3, total: 6 }), 40);
+    const hiddenLines = withHidden.filter((l) => l.includes("agentes ocultos"));
+    expect(hiddenLines).toHaveLength(1);
+    expect(hiddenLines[0]).toContain("+3 agentes ocultos");
+
+    const withoutHidden = formatPane(snapshot({ hidden: 0 }), 40);
+    expect(withoutHidden.some((l) => l.includes("agentes ocultos"))).toBe(false);
+  });
+
+  it("counts working, waiting and finished separately in the header (rule 3)", () => {
+    const rows: PaneRow[] = [
+      { id: "w", status: "working", agent: "claude", name: "w" },
+      { id: "s", status: "starting", agent: "claude", name: "s" },
+      { id: "n", status: "needs_input", agent: "claude", name: "n" },
+      { id: "c", status: "completed", agent: "claude", name: "c" },
+      { id: "f", status: "failed", agent: "claude", name: "f" },
+    ];
+    const header = formatPane(snapshot({ rows, orchestrator: { agent: "claude" }, hidden: 0, total: 6 }), 40);
+    expect(header.some((l) => l.includes("2 trabalhando"))).toBe(true);
+    expect(header.some((l) => l.includes("1 esperando voce"))).toBe(true);
+    expect(header.some((l) => l.includes("2 prontas"))).toBe(true);
+  });
+
+  it("folds the hidden overflow into the finished count (rule 6)", () => {
+    const rows: PaneRow[] = [{ id: "w", status: "working", agent: "claude", name: "w" }];
+    const lines = formatPane(snapshot({ rows, hidden: 3, total: 5 }), 40);
+    expect(lines.some((l) => l.includes("1 trabalhando"))).toBe(true);
+    expect(lines.some((l) => l.includes("3 prontas"))).toBe(true);
+    expect(lines.some((l) => l.includes("5 sessoes"))).toBe(true);
+  });
+
+  it("renders missing fields as a placeholder, never undefined (rule 10)", () => {
+    const snap = snapshot({
+      orchestrator: undefined,
+      rows: [{ status: "completed" } as unknown as PaneRow],
+    });
+    const lines = formatPane(snap, 40);
+    expectCleanWidth(lines, 40);
+    expect(lines.join("\n")).not.toContain("undefined");
+    expect(lines.some((l) => l.includes("-"))).toBe(true);
+  });
+
+  it("renders a prototype-key agent or status as a placeholder, not a function (rule 10)", () => {
+    for (const key of ["constructor", "toString", "valueOf", "__proto__", "hasOwnProperty"]) {
+      const snap = snapshot({
+        orchestrator: { agent: key },
+        rows: [{ id: "x", status: key, agent: key, name: key }],
+      });
+      const lines = formatPane(snap, 40);
+      expectCleanWidth(lines, 40);
+      const joined = lines.join("\n");
+      expect(joined).not.toMatch(/function|native code|\[object/);
+      expect(joined).not.toContain("undefined");
+    }
+  });
+
+  it("never throws on a snapshot that is not the shape it claims (rule 10)", () => {
+    const junk = [
+      null,
+      undefined,
+      {},
+      { rows: null },
+      { rows: [null, undefined], orchestrator: "open" },
+      { rows: [{ id: 7, name: {}, status: null }], hidden: Number.NaN, total: -5 },
+    ];
+    for (const bad of junk) {
+      for (const rows of [undefined, 0, 9, 10, 12, 44]) {
+        const lines = formatPane(bad as unknown as PaneSnapshot, 40, rows);
+        expect(Array.isArray(lines)).toBe(true);
+        if (typeof rows === "number") expect(lines.length).toBeLessThanOrEqual(Math.max(rows, 0));
+        for (const line of lines) expect(line).toHaveLength(40);
+      }
+    }
+  });
+
+  it("keeps a hostile name with a newline and an escape clean and correctly wide (mandatory)", () => {
+    const snap = snapshot({
+      rows: [
+        { id: "h", status: "working", agent: "opencode", name: "evil\nname\rwith\ttabs\u001b[31mred\u2028next" },
+      ],
+    });
+    const lines = formatPane(snap, 40);
+    expectCleanWidth(lines, 40);
+    expect(lines.some((l) => l.includes("evil name with tabs"))).toBe(true);
+    for (const line of lines) {
+      expect(line).not.toMatch(/[\u0000-\u001f\u007f-\u009f\u2028\u2029]/);
+    }
+  });
+
+  it("renders 19 workers at 89x44 as 34 stemless-run lines (mandatory)", () => {
+    const lines = formatPane(workerFixture(), 89, 44);
+    expect(lines).toHaveLength(34);
+    expect(lines[33]).toBe("└" + "─".repeat(87) + "┘");
+    expect(lines[31]).toContain("● trabalha");
+    expect(lines[32]).toContain("▲ Claude");
+    expect(lines.some((l) => l.includes("19 sessoes"))).toBe(true);
+    expect(lines.some((l) => l.includes("1 trabalhando"))).toBe(true);
+    expect(lines.some((l) => l.includes("0 esperando voce"))).toBe(true);
+    expect(lines.some((l) => l.includes("18 prontas"))).toBe(true);
+    // Everything fits at 44 rows now: 10 frame + a 5-line card with no stem
+    // above it + one stem opening the collapsed run + 18 one-liners.
+    expect(lines.filter((l) => l.includes("agentes ocultos"))).toHaveLength(0);
+    const joined = lines.join("\n");
+    for (const worker of ["w1", "a01", "a18"]) expect(joined).toContain(worker);
+  });
+
+  it("draws strictly more of the 19 workers at 89x44 than the stemmed layout did (mandatory)", () => {
+    const lines = formatPane(workerFixture(), 89, 44);
+    const joined = lines.join("\n");
+    const workerIds = ["w1", ...Array.from({ length: 18 }, (_, i) => `a${String(i + 1).padStart(2, "0")}`)];
+    const drawn = workerIds.filter((id) => joined.includes(id)).length;
+    // The old drawing fitted 14 of these 19 entries into the same 44 rows and
+    // reported the other 5 as ocultos; the stemless run fits every one.
+    expect(drawn).toBe(19);
+  });
+
+  it("renders 19 workers at 89x20 cutting to exactly 20 lines (mandatory)", () => {
+    const lines = formatPane(workerFixture(), 89, 20);
+    expect(lines).toHaveLength(20);
+    expect(lines[19]).toBe("└" + "─".repeat(87) + "┘");
+    const joined = lines.join("\n");
+    expect(joined).toContain("w1");
+    expect(joined).toContain("a03");
+    expect(joined).toContain("+15 agentes ocultos");
+    for (const gone of ["a04", "a05", "a14", "a18"]) expect(joined).not.toContain(gone);
+  });
+
+  it("draws the first line after the header separator and its blank as a card top (mandatory)", () => {
+    for (const snap of [workerFixture(), snapshot()]) {
+      const lines = formatPane(snap, 89, 44);
+      expect(lines[5].startsWith("│  ┌─")).toBe(true);
+    }
+  });
+
+  it("holds no two stem lines in a row when every entry is collapsed (mandatory)", () => {
+    const rows: PaneRow[] = [
+      { id: "c1", status: "completed", agent: "claude", name: "one" },
+      { id: "c2", status: "completed", agent: "opencode", name: "two" },
+      { id: "c3", status: "stopped", agent: "codex", name: "three" },
+    ];
+    const lines = formatPane(snapshot({ rows, hidden: 0, total: 4 }), 89);
+    expect(lines.filter((l) => l === STEM89)).toHaveLength(1);
+    expect(lines.join("\n")).not.toContain(STEM89 + "\n" + STEM89);
+  });
+
+  it("draws a collapsed run that is the first block with no stem at all (mandatory)", () => {
+    const rows: PaneRow[] = [
+      { id: "c1", status: "completed", agent: "claude", name: "one" },
+      { id: "c2", status: "completed", agent: "opencode", name: "two" },
+      { id: "c3", status: "stopped", agent: "codex", name: "three" },
+    ];
+    const lines = formatPane(snapshot({ orchestrator: undefined, rows, hidden: 0, total: 3 }), 89);
+    // 10 frame + three one-liners, not even the run opener: the first block
+    // is the root, so there is nothing above it to hang a stem from.
+    expect(lines).toHaveLength(13);
+    expect(lines.filter((l) => l === STEM89)).toHaveLength(0);
+    expect(lines[5].startsWith("│ ▲ ○ c1")).toBe(true);
+  });
+
+  it("evicts the orchestrator only after every worker card and line is gone (mandatory)", () => {
+    // snapshot(): orchestrator + working a1 + finished b2; full drawing 22.
+    const at16 = formatPane(snapshot(), 40, 16);
+    expect(at16).toHaveLength(16);
+    const joined16 = at16.join("\n");
+    expect(joined16).toContain("Orquestrador");
+    expect(joined16).toContain("+2 agentes ocultos");
+    expect(joined16).not.toContain("a1");
+    expect(joined16).not.toContain("b2");
+    // One row tighter and the root itself leaves, counted into the hidden.
+    const at15 = formatPane(snapshot(), 40, 15);
+    expect(at15).toHaveLength(11);
+    const joined15 = at15.join("\n");
+    expect(joined15).not.toContain("Orquestrador");
+    expect(joined15).toContain("+3 agentes ocultos");
+  });
+
+  it("renders the same 19 workers at 12 rows as header, footer and hidden line (mandatory)", () => {
+    const lines = formatPane(workerFixture(), 89, 12);
+    expect(lines).toHaveLength(11);
+    expect(lines[10]).toBe("└" + "─".repeat(87) + "┘");
+    expect(lines.some((l) => l.includes("19 sessoes"))).toBe(true);
+    expect(lines.some((l) => l.includes("● trabalha"))).toBe(true);
+    expect(lines.some((l) => l.includes("+19 agentes ocultos"))).toBe(true);
+    for (const worker of ["w1", "a01", "a18"]) expect(lines.join("\n")).not.toContain(worker);
+  });
+});
+
+describe("paneButtonLabel", () => {
+  it("counts every session of the run, orchestrator included", () => {
+    expect(paneButtonLabel(snapshot({ total: 3 }))).toBe("3 agentes · 1 trabalhando");
+  });
+
+  it("drops the working half when nobody is working", () => {
+    const idle = snapshot({
+      rows: [{ id: "b2", status: "completed", agent: "claude", name: "beta" }],
+      total: 2,
+    });
+    expect(paneButtonLabel(idle)).toBe("2 agentes");
+  });
+
+  it("counts starting as working, matching the pane header", () => {
+    const booting = snapshot({
+      rows: [{ id: "a1", status: "starting", agent: "codex", name: "alpha" }],
+      total: 2,
+    });
+    expect(paneButtonLabel(booting)).toBe("2 agentes · 1 trabalhando");
+  });
+
+  it("says agente in the singular", () => {
+    expect(paneButtonLabel(snapshot({ rows: [], hidden: 0, total: 1 }))).toBe("1 agente");
+  });
+
+  it("falls back to a bare word before the first refresh lands", () => {
+    expect(paneButtonLabel(undefined)).toBe("agentes");
+  });
+
+  it("survives a snapshot the daemon mangled, because a throw drops the drawing", () => {
+    const broken = { rows: "nope", total: "many" } as unknown as PaneSnapshot;
+    expect(paneButtonLabel(broken)).toBe("0 agentes");
+  });
+});
diff --git a/tests/mods-agents/parse.test.ts b/tests/mods-agents/parse.test.ts
new file mode 100644
index 0000000..9882477
--- /dev/null
+++ b/tests/mods-agents/parse.test.ts
@@ -0,0 +1,55 @@
+import { describe, expect, it } from "vitest";
+import { parseRows } from "../../plugin/mods/agents/parse.js";
+
+describe("parseRows", () => {
+  it("returns the rows of a well formed array of two objects", () => {
+    const stdout = JSON.stringify([
+      { id: "a83f", name: "power", agent: "claude", status: "running" },
+      { id: "b94e", runId: "r-1", origin: null, status: "idle" },
+    ]);
+    expect(parseRows(stdout)).toEqual([
+      { id: "a83f", name: "power", agent: "claude", status: "running" },
+      { id: "b94e", runId: "r-1", origin: null, status: "idle" },
+    ]);
+  });
+
+  it("returns an empty array (not undefined) for an empty JSON array", () => {
+    const result = parseRows("[]");
+    expect(result).not.toBeUndefined();
+    expect(result).toEqual([]);
+  });
+
+  it("returns undefined for a string that is not JSON at all", () => {
+    expect(parseRows("codedeck: command not found")).toBeUndefined();
+  });
+
+  it("returns undefined for truncated JSON cut mid object", () => {
+    expect(parseRows('[{"id": "a83f", "na')).toBeUndefined();
+  });
+
+  it("returns undefined for JSON that is an object rather than an array", () => {
+    expect(parseRows('{"id": "a83f"}')).toBeUndefined();
+  });
+
+  it("returns undefined for JSON null", () => {
+    expect(parseRows("null")).toBeUndefined();
+  });
+
+  it("drops non-object entries and keeps the object ones", () => {
+    expect(parseRows('[42, {"id": "a83f"}, "nope", null]')).toEqual([{ id: "a83f" }]);
+  });
+
+  it("returns an empty array when every entry is a non-object", () => {
+    expect(parseRows("[1, 2, 3]")).toEqual([]);
+  });
+
+  it("drops an object entry with no usable string id", () => {
+    expect(parseRows('[{"name": "power"}, {"id": 7}, {"id": ""}, {"id": "b94e"}]')).toEqual([
+      { id: "b94e" },
+    ]);
+  });
+
+  it("returns undefined for the empty string", () => {
+    expect(parseRows("")).toBeUndefined();
+  });
+});
diff --git a/tests/mods-arcade/auto.test.ts b/tests/mods-arcade/auto.test.ts
deleted file mode 100644
index 9f10e24..0000000
--- a/tests/mods-arcade/auto.test.ts
+++ /dev/null
@@ -1,50 +0,0 @@
-import { describe, expect, it } from "vitest";
-
-import { DROPIN_GAMES, pickAuto, pickPool, pickRandom } from "../../plugin/mods/arcade/games/auto";
-
-describe("pickAuto", () => {
-  it("suggests deep games for turns over one minute", () => {
-    expect(pickAuto({ lastTurnMs: 61_000 })).toBe("twenty48");
-    expect(pickAuto({ lastTurnMs: 5 * 60_000 })).toBe("twenty48");
-  });
-
-  it("suggests quick games for turns under one minute", () => {
-    expect(pickAuto({ lastTurnMs: 5_000 })).toBe("twenty48");
-    expect(pickAuto({})).toBe("twenty48");
-  });
-
-  it("suggests drop-in games when idle", () => {
-    expect(DROPIN_GAMES).toContain("twenty48");
-    expect(pickAuto({ idle: true })).toBe("twenty48");
-    expect(pickAuto({ idle: true, lastTurnMs: 10 * 60_000 })).toBe("twenty48");
-  });
-});
-
-describe("pickPool", () => {
-  it("flips from quick to deep across the 60000 ms threshold", () => {
-    expect(pickPool({ lastTurnMs: 59_999 })).toBe("quick");
-    expect(pickPool({ lastTurnMs: 60_000 })).toBe("quick");
-    expect(pickPool({ lastTurnMs: 60_001 })).toBe("deep");
-    expect(pickPool({ lastTurnMs: 61_000 })).toBe("deep");
-  });
-
-  it("maps idle to dropin regardless of turn length", () => {
-    expect(pickPool({ idle: true })).toBe("dropin");
-    expect(pickPool({ idle: true, lastTurnMs: 10 * 60_000 })).toBe("dropin");
-  });
-
-  it("defaults to quick without input", () => {
-    expect(pickPool({})).toBe("quick");
-    expect(pickPool({ lastTurnMs: 5_000 })).toBe("quick");
-  });
-});
-
-describe("pickRandom", () => {
-  it("returns a member of the given list", () => {
-    expect(["a", "b"]).toContain(pickRandom(["a", "b"]));
-  });
-
-  it("falls back to the drop-in list by default", () => {
-    expect(DROPIN_GAMES).toContain(pickRandom());
-  });
-});
diff --git a/tests/mods-arcade/best.test.ts b/tests/mods-arcade/best.test.ts
deleted file mode 100644
index 0bc33f6..0000000
--- a/tests/mods-arcade/best.test.ts
+++ /dev/null
@@ -1,19 +0,0 @@
-import { describe, expect, it } from "vitest";
-
-import { isBetter } from "../../plugin/mods/arcade/games/best";
-
-describe("isBetter", () => {
-  it("accepts the first score for a game", () => {
-    expect(isBetter("twenty48", 128, {})).toBe(true);
-  });
-
-  it("compares the new score against the stored best per game", () => {
-    expect(isBetter("twenty48", 256, { twenty48: 128 })).toBe(true);
-    expect(isBetter("twenty48", 64, { twenty48: 128 })).toBe(false);
-    expect(isBetter("twenty48", 128, { twenty48: 128 })).toBe(false);
-  });
-
-  it("keeps bests isolated per game", () => {
-    expect(isBetter("other", 10, { twenty48: 9999 })).toBe(true);
-  });
-});
diff --git a/tests/mods-arcade/pet.test.ts b/tests/mods-arcade/pet.test.ts
deleted file mode 100644
index fd09d57..0000000
--- a/tests/mods-arcade/pet.test.ts
+++ /dev/null
@@ -1,118 +0,0 @@
-import { describe, expect, it } from "vitest";
-
-import { feed, level, MOOD, newPet, petEvent, stage, TEST_COMMAND, XP } from "../../plugin/mods/arcade/games/pet";
-
-describe("XP table", () => {
-  it("rewards test passes, commits and edits", () => {
-    expect(XP["test-pass"]).toBe(10);
-    expect(XP["test-fail"]).toBe(2);
-    expect(XP.commit).toBe(15);
-    expect(XP.edit).toBe(1);
-  });
-});
-
-describe("MOOD table", () => {
-  it("tracks mood per event kind", () => {
-    expect(MOOD["test-pass"]).toBe(8);
-    expect(MOOD["test-fail"]).toBe(-12);
-    expect(MOOD.commit).toBe(10);
-    expect(MOOD.edit).toBe(1);
-  });
-});
-
-describe("TEST_COMMAND", () => {
-  it.each([
-    "bun test",
-    "npm test",
-    "npm run test",
-    "pnpm test",
-    "yarn test",
-    "npx jest",
-    "npx vitest",
-    "npx mocha",
-    "pytest",
-    "pytest tests/test_pet.py",
-    "jest",
-    "vitest run",
-    "rspec",
-    "phpunit",
-    "mocha",
-    "go test ./...",
-    "cargo test",
-    "make test",
-    "mvn test",
-    "gradle test",
-    "./gradlew test",
-    "sbt test",
-  ])("matches %s", (cmd) => {
-    expect(TEST_COMMAND.test(cmd)).toBe(true);
-  });
-
-  it.each(["git commit -m hi", "go build ./...", "npm run lint"])("does not match %s", (cmd) => {
-    expect(TEST_COMMAND.test(cmd)).toBe(false);
-  });
-
-  it.each([
-    "cat vitest.config.ts",
-    "rm -rf node_modules/.vitest",
-    "git add jest.config.js",
-    "grep -rn mocha docs/",
-    "ls tests/pytest.ini",
-  ])("does not mistake %s for a test run", (cmd) => {
-    expect(TEST_COMMAND.test(cmd)).toBe(false);
-  });
-});
-
-describe("petEvent", () => {
-  it("classifies Bash test runs by command text", () => {
-    expect(petEvent({ tool: "Bash", command: "npm test", ok: true })?.kind).toBe("test-pass");
-    expect(petEvent({ tool: "Bash", command: "go test ./...", ok: false })?.kind).toBe("test-fail");
-  });
-
-  it("classifies git commit without the dry-run flag into commits", () => {
-    expect(petEvent({ tool: "Bash", command: "git commit -m hi", ok: true })?.kind).toBe("commit");
-    expect(petEvent({ tool: "Bash", command: "git commit --dry-run", ok: true })).toBeUndefined();
-  });
-
-  it("prefers commit over test words in the message", () => {
-    expect(petEvent({ tool: "Bash", command: "git commit -m 'fix jest config'", ok: true })?.kind).toBe(
-      "commit",
-    );
-  });
-
-  it.each(["Edit", "Write", "NotebookEdit"])("classifies %s tool names into edits", (tool) => {
-    expect(petEvent({ tool })?.kind).toBe("edit");
-  });
-
-  it("ignores denied calls with undefined ok", () => {
-    expect(petEvent({ tool: "Bash", command: "npm test", denied: true })).toBeUndefined();
-    const denied = petEvent({ tool: "Bash", command: "npm test", denied: true, ok: undefined });
-    expect(denied?.ok).toBeUndefined();
-  });
-
-  it("ignores unrelated tools", () => {
-    expect(petEvent({ tool: "Read" })).toBeUndefined();
-    expect(petEvent({ tool: "Bash", command: "echo hi" })).toBeUndefined();
-  });
-});
-
-describe("feed / level / stage", () => {
-  it("starts from zero with newPet", () => {
-    expect(newPet()).toEqual({ xp: 0, mood: 0, tests: 0, commits: 0, edits: 0 });
-  });
-
-  it("accumulates xp, mood and counters", () => {
-    const start = newPet();
-    const after = feed(start, { kind: "test-pass", ok: true, xp: XP["test-pass"], mood: MOOD["test-pass"] });
-    expect(after.xp).toBe(10);
-    expect(after.mood).toBe(8);
-    expect(after.tests).toBe(1);
-  });
-
-  it("derives level from xp and stage from level", () => {
-    expect(level(newPet())).toBe(1);
-    expect(level({ xp: 250, mood: 0, tests: 0, commits: 0, edits: 0 })).toBe(3);
-    expect(stage(1)).toBe("egg");
-    expect(stage(newPet())).toBe("egg");
-  });
-});
diff --git a/tests/mods-arcade/random.test.ts b/tests/mods-arcade/random.test.ts
deleted file mode 100644
index 76bd37e..0000000
--- a/tests/mods-arcade/random.test.ts
+++ /dev/null
@@ -1,27 +0,0 @@
-import { describe, expect, it } from "vitest";
-
-import { randomInt } from "../../plugin/mods/arcade/games/random";
-
-describe("randomInt", () => {
-  it("rejects non-positive integer bounds", () => {
-    expect(() => randomInt(0)).toThrow(RangeError);
-    expect(() => randomInt(-4)).toThrow(RangeError);
-    expect(() => randomInt(1.5)).toThrow(RangeError);
-  });
-
-  it("returns 0 for a bound of 1", () => {
-    expect(randomInt(1)).toBe(0);
-  });
-
-  it("stays an integer inside the bound", () => {
-    const seen = new Set<number>();
-    for (let i = 0; i < 100; i += 1) {
-      const value = randomInt(16);
-      expect(Number.isInteger(value)).toBe(true);
-      expect(value).toBeGreaterThanOrEqual(0);
-      expect(value).toBeLessThan(16);
-      seen.add(value);
-    }
-    expect(seen.size).toBeGreaterThan(1);
-  });
-});
diff --git a/tests/mods-arcade/twenty48.test.ts b/tests/mods-arcade/twenty48.test.ts
deleted file mode 100644
index 5269435..0000000
--- a/tests/mods-arcade/twenty48.test.ts
+++ /dev/null
@@ -1,89 +0,0 @@
-import { describe, expect, it } from "vitest";
-
-import {
-  banner,
-  directionForKey,
-  initialTwenty48State,
-  isFinished,
-  moveGrid,
-  slideRow,
-} from "../../plugin/mods/arcade/games/twenty48";
-
-describe("slideRow", () => {
-  it("merges pairs once and scores the merge", () => {
-    expect(slideRow([2, 2, 4, 4])).toEqual({ row: [4, 8, 0, 0], gained: 12 });
-  });
-
-  it("slides without merging distinct tiles", () => {
-    expect(slideRow([0, 2, 0, 4])).toEqual({ row: [2, 4, 0, 0], gained: 0 });
-  });
-});
-
-describe("moveGrid", () => {
-  it("reports moved false when nothing changes", () => {
-    const grid = [2, 4, 2, 4, 4, 2, 4, 2, 2, 4, 2, 4, 4, 2, 4, 2];
-    expect(moveGrid(grid, "left").moved).toBe(false);
-  });
-
-  it("moves tiles left with merges", () => {
-    const grid = [2, 2, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0];
-    const stepped = moveGrid(grid, "left");
-    expect(stepped.moved).toBe(true);
-    expect(stepped.grid.slice(0, 4)).toEqual([4, 0, 0, 0]);
-    expect(stepped.gained).toBe(4);
-  });
-});
-
-describe("directionForKey", () => {
-  it.each([
-    ["up", "up"],
-    ["w", "up"],
-    ["down", "down"],
-    ["s", "down"],
-    ["left", "left"],
-    ["a", "left"],
-    ["right", "right"],
-    ["d", "right"],
-  ])("maps %s", (name, expected) => {
-    expect(directionForKey(name)).toBe(expected);
-  });
-
-  it("rejects other keys", () => {
-    expect(directionForKey("q")).toBeNull();
-  });
-});
-
-describe("isFinished", () => {
-  it("is not finished with open cells", () => {
-    expect(isFinished(initialTwenty48State(() => 0).grid)).toBe(false);
-  });
-
-  it("is finished on a full grid with no merges", () => {
-    expect(isFinished([2, 4, 2, 4, 4, 2, 4, 2, 2, 4, 2, 4, 4, 2, 4, 2])).toBe(true);
-  });
-
-  it("is not finished when a merge is still available", () => {
-    expect(isFinished([2, 2, 4, 8, 16, 32, 64, 128, 256, 512, 1024, 2048, 4096, 8192, 16384, 32768])).toBe(
-      false,
-    );
-  });
-});
-
-describe("banner", () => {
-  it("pauses once per new done value", () => {
-    const seen = { current: 0 };
-    let pauses = 0;
-    expect(banner(0, seen, () => (pauses += 1))).toBeNull();
-    expect(banner(1, seen, () => (pauses += 1))).toContain("1");
-    expect(banner(1, seen, () => (pauses += 1))).toBeNull();
-    expect(pauses).toBe(1);
-  });
-});
-
-describe("initialTwenty48State", () => {
-  it("seeds two tiles on an empty board", () => {
-    const state = initialTwenty48State(() => 0);
-    expect(state.grid.filter((cell) => cell !== 0)).toHaveLength(2);
-    expect(state).toMatchObject({ score: 0, over: false, won: false, posted: false, paused: false });
-  });
-});
diff --git a/tests/open-args.test.ts b/tests/open-args.test.ts
index 1cf2629..fe318d6 100644
--- a/tests/open-args.test.ts
+++ b/tests/open-args.test.ts
@@ -836,7 +836,7 @@ describe("open command pure helpers", () => {
     expect(sanitizeEnv({ MISE_QUIET: "0" }).MISE_QUIET).toBe("0");
   });
 
-  // Function hooks back the codedeck arcade mod, and Claude Code only loads
+  // Function hooks back the codedeck agents pane, and Claude Code only loads
   // hook modules when the spawning environment enables them. A value of the
   // user's own wins, which keeps an explicit opt-out working.
   it("enables function hooks without overriding a setting of the user's own", () => {

From 010a6ceab252230f1f4c76b1adf651842e6df9f0 Mon Sep 17 00:00:00 2001
From: 4ndreello <4ndreello@users.noreply.github.com>
Date: Sat, 19 Sep 2026 23:01:21 -0300
Subject: [PATCH 6/8] docs(mods): Record the engine contract the pane had to
 learn

Every rule here cost a live probe, and each one had already produced a wrong
conclusion before it was pinned down. Box lays children out in a row, so a
column of lines comes out shredded. A docked pane ignores the width you ask
for and reports its own size back on every render. A Button's onPress is
handed the press event, not the engine handle, though a handle captured from
the render hook does work. A hotkey is swallowed by the prompt. A pane closed
by its own close box fires no hook, so a module cannot track its open state.

Also written down: how to click a button from a test, since the client turns
on SGR mouse tracking and tmux can deliver a synthetic press and release.

Co-Authored-By: Claude <noreply@anthropic.com>
---
 docs/mods.md | 323 ++++++++++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 305 insertions(+), 18 deletions(-)

diff --git a/docs/mods.md b/docs/mods.md
index 34fac48..5b24f35 100644
--- a/docs/mods.md
+++ b/docs/mods.md
@@ -1,8 +1,8 @@
-# CodeDeck mods (arcade)
+# CodeDeck mods
 
-Function hooks backing the arcade mod. Boards and game logic live in the MOD
-slice; this file covers integration only: how the hooks get enabled, typed,
-and validated.
+Function hooks backing codedeck plugin mods. This file covers integration:
+how the hooks get enabled, typed, and validated, and the engine contract a
+module has to satisfy.
 
 ## Enablement
 
@@ -19,18 +19,296 @@ env, so they are untouched.
 ## Declaration
 
 `plugin/hooks/hooks.json` carries a top-level `modules` array with one entry
-pointing at the register file, plus a description naming the arcade mod and
-its function hooks requirement. The existing `hooks` key (`SessionStart` for
-`session-id.sh`, `UserPromptSubmit` for `session-name.sh`) is unchanged.
+pointing at the register file, plus a description stating what the plugin
+provides and its function hooks requirement. The existing `hooks` key
+(`SessionStart` for `session-id.sh`, `UserPromptSubmit` for `session-name.sh`)
+is unchanged.
 
 The new capability bumps the plugin to 0.3.0 in
 `plugin/.claude-plugin/plugin.json`.
 
-## plugin-types flow
+## Runtime contract
 
-Run the plugin-types flow from the repo root. It writes the generated types
-under `.claude/`, which stays gitignored, so generated output never lands in a
-diff or a review.
+The rules below are what the engine actually enforces on a hooks module. They
+were recovered from error strings in the Claude Code binary while porting a
+game into this module, and none of them appear in public Claude Code docs. The
+exact wording is quoted in backticks because it is what shows up in your
+terminal when a hook is refused, so you can grep for it.
+
+### One tree element
+
+A `ui.render` handler returns exactly one tree element, never an array. The
+validator rejects anything else with `something that is not a tree element`,
+surfaced as:
+
+```
+codedeck: ui.render hook skipped: returned the wrong shape (something that is not a tree element)
+```
+
+To keep the rest of the UI drawing, nest the downstream result as the last
+child of your single element: `{await next(e)}`.
+
+### ui.render fires per drawn component
+
+The event runs once for each of `AbovePrompt`, `Pane`, `UserMessage`,
+`ToolUse`, and `ToolResult`. A handler that does not gate draws in all of
+them. The gate:
+
+```tsx
+if (e.surface !== "terminal" || e.component !== "AbovePrompt") return await next(e);
+```
+
+The engine also refuses some components outright, with wording of the form
+`<component> is drawn by the engine alone`.
+
+### Box lays children out in a row
+
+`Box` defaults to `flexDirection: "row"`, so a list of `Text` children is
+drawn side by side, not stacked. A 51 line drawing came out as vertical
+slivers of box characters, one per column, with no error anywhere: the module
+loaded, the hook ran, the engine was happy. Only a screen capture showed it.
+Any multi line drawing needs the direction spelled out:
+
+```tsx
+<Box flexDirection="column">
+  {lines.map((line) => <Text key={line}>{line}</Text>)}
+  {await next(e)}
+</Box>
+```
+
+### A docked pane reports its own size, and ignores the one you ask for
+
+`$.ui.open({ id, side: "right" })` opens the dock. `width` is accepted and
+then ignored: the engine sizes the dock. What comes back on every `ui.render`
+is the truth, and a module that assumes a number instead of reading these
+draws off the edge:
+
+- `e.requestId` carries the id from `open`. `e.id` is `undefined` on the
+  render event, so it is the only way to tell one pane from another
+- `e.props.bodyColumns` is the usable width
+- `e.props.scroll` is `{ offset, bodyRows }`, and `bodyRows` is the usable
+  height. Anything taller is clipped at the bottom with no warning, which
+  silently eats a footer
+- `e.viewport` is the space left over for everything else, not the terminal
+  and not the pane
+
+Measured together in one 200 by 50 terminal: `bodyColumns` 89,
+`scroll.bodyRows` 44, `viewport` `{ columns: 110, rows: 50 }`.
+
+The pane draws from session start, as soon as one refresh has a snapshot. It
+does not wait for a turn.
+
+### Capitalized tags, resolved from the event
+
+With `/** @jsx h */`, a lowercase tag compiles to a string literal and a
+capitalized tag to an identifier. The intrinsic table in a hooks module is
+exactly `{ Box: 'Box', Text: 'Text' }`, so `<text>` fails. The refusal
+arrives whole, and its tail names every tag that does resolve:
+
+```
+JSX element <text> is not an element: a render hook draws with the table $.ui.resolve(e) returns (Box, Text, Button, Input, Select, Link, Code, Client, Svg) and what next(e) returned
+```
+
+Take the components from the event:
+
+```tsx
+const { Box, Text } = await $.ui.resolve(e, "Box", "Text");
+```
+
+A surface module is different. It gets its element set from
+`surface.elements`: on the terminal that is `Box, Text, Button, Input,
+Select, Link, Code` and `Client`. `Svg` completes the table and belongs to
+the desktop surface.
+
+### Button needs a key, a label and an onPress
+
+Three refusals:
+
+```
+JSX element <Button> needs a key: its address, what e.element carries at ui.press (the label when absent)
+JSX element <Button> needs a label: the label prop, or one string child
+JSX element <Button key="..."> needs an onPress function
+```
+
+A button missing any of them throws out of the render hook, and the whole
+drawing is dropped. The `onPress` refusal is a runtime one too, not only a
+validator rule: a live session answers
+
+```
+ui.render hook skipped: threw <plugin>: returned a Button without an onPress
+function; a render hook draws one with <Button key label onPress>
+```
+
+### onPress is handed the press event, not the engine handle
+
+The callback's first argument is the press event:
+
+```json
+{ "plugin": "…", "element": "…", "component": "AbovePrompt", "requestId": "above-prompt", "surface": "terminal" }
+```
+
+So `onPress={async ($) => { await $.ui.open(…) }}` throws
+`undefined is not an object (evaluating '$.ui.open')`. The failure is quiet in
+the worst way: everything the callback did before the first `await` has already
+happened, so a flag flipped at the top makes the button look like it worked.
+
+A `$` captured from the enclosing render hook does work. Verified: a button
+whose `onPress` closes over the render hook's `$` opened a docked pane and the
+pane drew. What does not exist is a handle delivered to the callback.
+
+Both spellings are live. The agents pane uses a third: an empty `onPress` and
+the work in a `ui.press` hook, where `e.element` is the key of the button that
+was pressed and `$` is the one the engine hands that event, rather than one
+captured from a render that has already finished.
+
+A `hotkey` prop does not help at the top-level prompt: the key is typed into
+the input instead of firing the button. Verified with `hotkey="a"` on an empty
+prompt.
+
+### A pane closed by its own close box tells the module nothing
+
+The dock draws an `✕` in its top-right corner. Clicking it closes the pane and
+fires no hook at all: no `ui.press`, no render, nothing. A module that tracks
+open state in a flag will desync there, and the next toggle goes the wrong way.
+
+`$.ui.open` on an already open pane is a no-op, no error and no second dock, so
+the safe shape for a reopen affordance is a button that only ever opens.
+
+### Clicking a button from a test
+
+The client turns on SGR mouse tracking, so a synthetic click is deliverable.
+Confirm the flags, then send press and release at a cell:
+
+```sh
+tmux display -t <session> -p 'any=#{mouse_any_flag} sgr=#{mouse_sgr_flag}'  # any=1 sgr=1
+tmux send-keys -t <session> -l $'\033[<0;<col>;<row>M'
+tmux send-keys -t <session> -l $'\033[<0;<col>;<row>m'
+```
+
+Column and row are 1-based and come straight from `tmux capture-pane -p`.
+
+### Client reads six props and silently discards the rest
+
+`<Client>` takes `module`, `key`, `props`, `width`, `height`, and `flexGrow`.
+Anything else passed at the top level is dropped with no error at all, which is
+the worst failure mode here because nothing tells you. Application data goes
+inside `props={{ ... }}`.
+
+`module` must be a string literal path relative to the declaring file, and
+`key` is required:
+
+```
+JSX element <Client module="..."> needs a key: its address, what e.element carries at ui.message
+```
+
+`<Client>` is a leaf and takes no children.
+
+### command.register requires a description
+
+```
+$.command.register takes { name, description, argumentHint?, immediate? }; name is letters, digits, _ or - (up to 64)
+```
+
+Omitting the description throws
+`$.command.register: <name> needs a description (what the menu shows)`, which
+kills the entire `session.start` hook, not just the command.
+
+### Do not seed surface state during render
+
+The engine's guard reads:
+
+```
+set its state again after each of {N} renders, nothing heard between; set state on a pointer or key event, a tick, a press or new props, and let a render settle
+```
+
+This is an open defect observed in this repo, not settled theory. In a live
+PTY session, a `Client` surface that seeded its state during render did not
+keep state across renders. That was observed. Why is a grounded hypothesis,
+the render-time seeding, not a proven fact.
+
+### process.run
+
+`$.process.run(argv, init?)`. **Both arguments are positional**, and this is
+the one contract on this page where reading the engine implementation gives you
+the wrong answer. The host function destructures `{ argv, init }`, so the
+obvious call is `$.process.run({ argv: [...] })`, and that call is refused:
+
+```
+process.run: takes argv, a non-empty list of strings naming the command first
+```
+
+The module-side proxy packs positional arguments into that object before the
+host sees them. Verified in a live session:
+
+```ts
+await $.process.run(["codedeck", "ps", "--all", "--json"])            // works
+await $.process.run(["echo", "hi"], { timeoutMs: 5000 })              // works
+await $.process.run({ argv: ["echo", "hi"] })                         // refused
+```
+
+`argv[0]` is the command and an array means no shell, so no quoting question.
+`init` is `{ cwd?, env?, stdin?, timeoutMs? }`, with `timeoutMs` a whole number
+from 1 to 600000 and a default of 30000. Each of stdout and stderr is captured
+and truncated at 4194304 characters. The child runs under cgroup class
+`plugin`. It resolves to `{ exitCode, stdout, stderr }`, with `exitCode`
+falling back to `1` when the process closes without one, and it throws on
+timeout or abort and on failure to start. Both throws must be caught: an
+uncaught one takes the whole drawing down.
+
+### $ is analysed statically, so never alias it
+
+`$` can be passed into a helper function. Pulling a namespace off it cannot:
+
+```ts
+const P = $.process;   // module fails to load
+```
+
+```
+$.process is used as a value (a noun...)
+```
+
+Every engine call has to appear literally as `$.<namespace>.<method>(...)` at
+the call site. The engine reads the compiled source, and it names the compiled
+line in the error, not the line you wrote.
+
+## Worked example
+
+`.specs/features/orchestrator-agents-band/reference-register.tsx` is the
+arcade register after all five fixes, kept on purpose. What is verified is
+its shape: the `ui.render` handler below drew correctly in a live PTY
+session, and it carries the gate, the resolve, the single returned element, a
+`Button` with a key, a label and `onPress`, and the nested `{await next(e)}`.
+The register will not load as it stands. Its imports, and its `Client`
+module path, point at the arcade slice that was deleted.
+
+```tsx
+on("ui.render", async ($, e, next) => {
+  if (e.surface !== "terminal" || e.component !== "AbovePrompt") return await next(e);
+  const { Box, Button, Client, Text } = await $.ui.resolve(e, "Box", "Button", "Client", "Text");
+  if (openBoard === null) {
+    return (
+      <Box>
+        <Text>Arcade boards</Text>
+        <Button
+          key="twenty48"
+          label="twenty48"
+          onPress={async () => {
+            openBoard = "twenty48";
+            await $.ui.invalidate("ui.render");
+          }}
+        />
+        {await next(e)}
+      </Box>
+    );
+  }
+  return (
+    <Box>
+      <Client key="twenty48" module="./boards/twenty48.tsx" props={{ done, colorblind, best: best[openBoard] ?? 0 }} />
+      {await next(e)}
+    </Box>
+  );
+});
+```
 
 ## Validation
 
@@ -47,18 +325,27 @@ claude plugin validate .
 ```
 
 Root-level validation resolves the `modules` entry, so it needs
-`plugin/hooks/register.tsx` from the MOD slice and stays pending until that
-slice lands.
+`plugin/hooks/register.tsx`.
+
+## What validation does not prove
+
+Two traps, both reached for during that port and both useless here.
+
+`claude plugin validate .` proves manifest shape only. It passes cleanly
+against a module that throws on every render. Never read a green validate as
+evidence that anything draws.
+
+A headless `claude -p` run is not a probe for this either. It was tried, it
+reported no errors, and a control built by restoring known-broken code also
+reported no errors, even with `--debug`. Only a PTY session shows these
+failures. Nobody should repeat that experiment.
 
-## Board constraints
+## Module constraints
 
-Board files in the MOD slice hold to these limits:
+Modules loaded through the `modules` declaration hold to these limits:
 
 - Never a local variable named `h`.
 - `Client` module paths are string literals.
-- Board height stays around half the terminal height band.
-- Redraw runs around ten frames per second.
-- Click gives keyboard focus; Esc returns to the prompt.
 - Terminal only: nothing renders in headless desktop or mobile.
 - Version gate: Claude Code 2.1.269 or later (verified against installed
   2.1.270).

From 44b83cb855a9b1a63e7eee5a8c83537c059b2af0 Mon Sep 17 00:00:00 2001
From: 4ndreello <4ndreello@users.noreply.github.com>
Date: Sat, 19 Sep 2026 23:03:51 -0300
Subject: [PATCH 7/8] docs(specs): Drop the arcade spec along with the arcade

The spec and run record for the arcade mod describe a feature the previous
commit deletes. Leaving them beside the pane's own spec, which already records
what replaced the arcade and why, gives the next reader two specs and only one
implementation.

Co-Authored-By: Claude <noreply@anthropic.com>
---
 .../features/cc-arcade-mod-port/run-notes.md  | 32 --------
 .../features/cc-arcade-mod-port/run-report.md | 43 ----------
 .specs/features/cc-arcade-mod-port/spec.md    | 81 -------------------
 3 files changed, 156 deletions(-)
 delete mode 100644 .specs/features/cc-arcade-mod-port/run-notes.md
 delete mode 100644 .specs/features/cc-arcade-mod-port/run-report.md
 delete mode 100644 .specs/features/cc-arcade-mod-port/spec.md

diff --git a/.specs/features/cc-arcade-mod-port/run-notes.md b/.specs/features/cc-arcade-mod-port/run-notes.md
deleted file mode 100644
index cfc7fcd..0000000
--- a/.specs/features/cc-arcade-mod-port/run-notes.md
+++ /dev/null
@@ -1,32 +0,0 @@
-# Run notes: cc-arcade-mod-port
-
-Autonomous run. Append-only. One line per entry. Time in UTC.
-
-- 2026-09-15T00:33Z | activation | autonomous mode invoked by human in orchestrator session | bucket: n/a | contract: never ask human, bucket1 reversible now with logged assumption, bucket2 irreversible deferred, route around blockers, parallelize for speed
-- 2026-09-15T00:33Z | assumption | slug cc-arcade-mod-port names this work item: port cc-arcade function-hooks Mod pattern into codedeck plugin | bucket: 1 | reason: reversible prose choice, directory created
-- 2026-09-15T00:33Z | assumption | prior swarm findings 2bab and e1ed treated as grounded input, not as delivered code | bucket: 1 | reason: read-only discovery, diffs empty, quoted test output trusted over success messages
-- 2026-09-15T00:33Z | decision | implementation split in 3 parallel slices by file ownership: SPEC owns .specs spec.md, MOD owns plugin hooks register plus boards plus pure logic plus new tests, INTEGRATION owns plugin manifests plus open plus docs | bucket: 1 | reason: avoids two workers in one file, reversible slice plan
-- 2026-09-15T00:33Z | constraint | no installs, fetches, or vendoring by any worker, including bunx remote fetches and npm minus g. scoped local test and build commands only. claude plugin validate allowed, already installed claude 2.1.270 | bucket: 2 deferred by contract | reason: network fetch and transitive code execution are irreversible
-- 2026-09-15T00:33Z | constraint | no pushes, no git clean, no reset hard, no shared state writes. workers leave changes uncommitted in worktrees for codedeck diff review | bucket: 2 deferred by contract | reason: publishing and destructive git actions need human
-- 2026-09-15T00:34Z | dispatch | SPEC worker 3c47 general worktree, MOD worker 6ffe general worktree, INTEGRATION worker 542f general worktree, all parallel | bucket: 1 | reason: implementation slices own disjoint file sets
-- 2026-09-15T00:34Z | registry | 3c47 SPEC owns .specs spec.md, 6ffe MOD owns register plus boards plus mods plus new tests, 542f INTEGRATION owns manifests plus src/open plus docs/mods.md | bucket: 1 | reason: slice ownership record
-- 2026-09-15T00:35Z | finding | SPEC worker 3c47 completed with spec.md verified on disk at .specs/features/cc-arcade-mod-port/spec.md, 3502 bytes, all five headings present. codedeck diff stat was empty because new files are untracked, lesson: verify new-file slices with git status in the worktree, not diff stat alone. SPEC accepted.
-- 2026-09-15T00:35Z | blocked | MOD worker 6ffe and INTEGRATION worker 542f failed, blame harness retryable: opencode sandbox auto-rejects external_directory reads under /tmp/cc-arcade-review referenced by both briefings. No code was written by either. Lesson: keep opencode workers hermetic inside the worktree, inline reference content in briefings.
-- 2026-09-15T00:35Z | finding | reference schema read directly by orchestrator, no worker fetch needed: cc-arcade hooks/hooks.json is exactly description plus modules with value ["./register.tsx"]. register.tsx shape is @jsx h pragma, import type Register from claude-code, export const register assignment, on() handlers for session.start command.run turn.start turn.complete tool.call ui.message ui.render AbovePrompt, Client with string literal module, store get and set with catch, ui resolve invalidate toast log, clock now, command register immediate true. Board shape is @jsx h pragma, ClientElements and ClientSurface type imports, default component export, never a local h.
-- 2026-09-15T00:35Z | dispatch | corrective cycle, one per failed slice: MOD retry and INTEGRATION retry, hermetic briefings with inlined reference, parallel | bucket: 1 | reason: failures are harness sandbox blocks, retryable, no drift to correct
-- 2026-09-15T00:36Z | dispatch | MOD RETRY worker 7125 general worktree, INTEGRATION RETRY worker c2c7 general worktree, parallel | bucket: 1 | reason: single corrective cycle per failed slice, hermetic briefings
-- 2026-09-15T00:53Z | finding | MOD worker 7125 completed exit 0, files verified on disk: register.tsx, boards common.tsx plus twenty48.tsx, mods arcade games pet best auto twenty48 plus index, tests mods-arcade four files. Claims 69 tests pass with empty-config caveat since worktree has no node_modules. Self reviewed via reviewer session 7f9c and acted on findings. Status: delivered, pending validation.
-- 2026-09-15T00:53Z | finding | INTEGRATION worker c2c7 completed exit 0, diff verified: hooks.json gains description plus modules register entry with hooks key intact, plugin.json 0.2.0 to 0.3.0, runtime.ts sanitizeEnv sets CLAUDE_CODE_ENABLE_FUNCTION_HOOKS default 1 with user opt-out preserved, docs/mods.md created. Validator accepts manifest shape, single missing-file error for register.tsx which the MOD slice supplies. Build plus scoped tests BLOCKED in worktree, no node_modules. No test files edited. Status: delivered, pending validation.
-- 2026-09-15T00:53Z | risk | MOD register uses engine call shapes that differ from the reference account: ui.render.invalidate versus ui.invalidate with event string, next with dollar versus next with event, resolve with string args versus resolve with event, namespaced arcade store keys versus upstream pet and best keys. Unresolvable without engine types. Flagged for the review slice to reconcile against discovery evidence.
-- 2026-09-15T00:53Z | dispatch | VALIDATION worker 3cf7 reviewer no-worktree, merged scratch tree plus per worktree checks plus mutation probe | bucket: 1 | reason: independent proof before integration decision
-- 2026-09-15T00:58Z | finding | merged scratch validation by 3cf7: npm run build green, scoped vitest 7 files 117 tests green, claude plugin validate on repo root passed. Manifest-path validate reports 1 error: register.tsx compiled line 32 reads dollar dot name as a value, engine contract requires dollar dot noun dot event at call sites. Reproduced by orchestrator in scratch. MUST FIX in remediation.
-- 2026-09-15T00:58Z | finding | orchestrator mutation probe in scratch, pure logic only, files restored after: XP value flip KILLED with 2 failures, isBetter inversion KILLED with 1 failure, auto threshold direction flip SURVIVED all 69 green. Survivor means the turn duration branch direction is untested. Test gap goes to remediation.
-- 2026-09-15T00:58Z | dispatch | REVIEW worker f8ef reviewer no-worktree read only over both worktrees plus spec | bucket: 1 | reason: final read-only review, findings remediated before delivery
-- 2026-09-15T01:03Z | finding | REVIEW worker f8ef completed: 3 BLOCKER plus 2 MAJOR plus 3 MINOR plus 2 INFO acceptable. Blockers all in register.tsx engine call shapes: dollar dot name read, invalidate shape, ui.render handler signatures. Majors: surface gate placement, upstream store key shape. Minors: callback param naming, .claude missing from gitignore, sanitizeEnv test gap. Sound: pet privacy, Client literals, no local h, banner, manifest shape, version bump, env opt-out, pure logic tests.
-- 2026-09-15T01:03Z | dispatch | FIX-MOD worker 8ac1 general in place in 7125 worktree owns register plus boards plus mods plus new tests, findings 1 to 6 plus auto pool refactor and threshold test. FIX-INT worker 223f general in place in c2c7 worktree owns gitignore plus open-args test, findings 7 and 8. Parallel, disjoint ownership | bucket: 1 | reason: remediate confirmed findings before delivery
-- 2026-09-15T01:12Z | finding | FIX-MOD round 2 plus round 3 done: handlers now positional dollar engine e event next continuation, command.run matcher with string e dot args, invalidate with event string, resolve and next with e, Client module relative ./boards/twenty48.tsx. Manifest validate now lists 7 events plus 7 dollar calls plus 1 surface module and passes. Root validate passes. Build green.
-- 2026-09-15T01:12Z | finding | revalidation in merged scratch after fixes: 8 files 211 tests green, manifest validate passed, root validate passed. Pre-existing open-args exact equality test needed the new env key added to its expectation, one line, done by orchestrator in FIX-INT worktree and recorded as assumption.
-- 2026-09-15T01:12Z | finding | mutation probe closed: threshold flip now KILLED by 2 failures in the new pickPool boundary test, scratch restored to fixed state and green again. Probe total 2 killed before, 1 survived then killed after the new test.
-- 2026-09-15T01:12Z | decision | changes stay uncommitted in worker worktrees 7125 MOD plus fixes and c2c7 INTEGRATION plus fixes for human integration. No merge no push per contract. Scratch at /tmp/opencode/validate-arcade holds the verified merged tree.
-- 2026-09-15T01:20Z | decision | human ordered PR open, bucket 2 publish action explicitly authorized. Branch feat/arcade-mod-port created from main, verified delta applied from 7125 plus c2c7 plus spec, build green, 211 tests green, both validates green. Commit db2207d with Co-Authored-By footer. Pushed and opened draft PR 83. Untracked process notes left out of the branch.
-- 2026-09-15T01:30Z | finding | PR 83 checks red: plugin job pinned claude 2.1.258 predates function hooks so session.start is not an event there, and Sonar gate failed Security Rating on 3x S2245 Math.random in new game code. Fixed on branch: randomInt helper over getRandomValues plus bounds test, CI pin to 2.1.270. Commits 4c888bb and fcb472b. All checks green: sonar pass, plugin pass, test 24 plus 26 pass.
diff --git a/.specs/features/cc-arcade-mod-port/run-report.md b/.specs/features/cc-arcade-mod-port/run-report.md
deleted file mode 100644
index fe909d5..0000000
--- a/.specs/features/cc-arcade-mod-port/run-report.md
+++ /dev/null
@@ -1,43 +0,0 @@
-# Run report: cc-arcade-mod-port
-
-Autonomous run 2026-09-15. Goal: port the cc-arcade function-hooks Mod pattern (anthropics claude-code issue 91870, comment 5666255143) into the codedeck plugin as an `arcade` mod: `/arcade` command, AbovePrompt board, pet fed by tool calls, persisted best scores. Swarm of 9 worker sessions plus orchestrator verification. This report is self-contained.
-
-## Done
-
-Branch: [main](https://github.com/4ndreello/codedeck/tree/main). Commit: [07e693f7e0e5ac0a18123e26de1b9a125f31e850](https://github.com/4ndreello/codedeck/commit/07e693f7e0e5ac0a18123e26de1b9a125f31e850). No merge and no push happened in this run. The delivered changes sit uncommitted in two worker worktrees, verified merged in scratch at `/tmp/opencode/validate-arcade`:
-
-- MOD worktree `ra/you-are-implementing-for-coded-7125` (worker 7125, fixes 8ac1): `plugin/hooks/register.tsx` (7 engine events, matcher-based `/arcade`, picker plus 2048 Client board, banner pause, counter-only pet feeding), `plugin/hooks/boards/common.tsx` plus `twenty48.tsx`, `plugin/mods/arcade/` (pet, best, auto with pool picker, 2048 rules, index), `tests/mods-arcade/` (4 files).
-- INTEGRATION worktree `ra/you-are-implementing-for-coded-c2c7` (worker 542f retry c2c7, fixes 223f): `plugin/hooks/hooks.json` gains `modules: ["./register.tsx"]` with shell hooks intact, `plugin.json` 0.2.0 to 0.3.0, `src/open/runtime.ts` defaults `CLAUDE_CODE_ENABLE_FUNCTION_HOOKS` to 1 with user opt-out, `docs/mods.md` created, `.gitignore` gains `.claude/`, `tests/open-args.test.ts` gains env tests plus updated expectation.
-- Spec of record: `.specs/features/cc-arcade-mod-port/spec.md` (worker 3c47).
-
-Verified evidence, quoted from runs I executed or read from worker artifacts: `npm run build` green (tsc plus copy-plugin). Scoped vitest: `Test Files 8 passed (8)`, `Tests 211 passed (211)`. `claude plugin validate` on the manifest: `register.tsx hooks: session.start, command.run{command=arcade}, turn.start, turn.complete, tool.call, ui.message, ui.render`, `calls: $.command.register, $.store.get, $.store.set, $.ui.invalidate, $.ui.log, $.ui.resolve, $.ui.toast`, `surface modules: hooks/boards/twenty48.tsx`, `Validation passed`. Root validate: `Validation passed`. Mutation probe on pure logic: XP flip killed (2 failures), isBetter inversion killed (1 failure), threshold flip survived then killed (2 failures) after the new `pickPool` boundary test. Scratch restored to the fixed state and green afterward.
-
-## Assumptions I made
-
-- Slug `cc-arcade-mod-port` names this work item, and the run splits into SPEC, MOD, INTEGRATION slices owning disjoint file sets so no two workers share a file.
-- Prior read-only discovery (2bab on cc-arcade, e1ed on codedeck, both empty diffs) counts as grounded input, with quoted test output trusted over success messages.
-- Store keys follow the upstream shape (`pet`, `best:<game>`, `colorblind`) per review, not the namespaced draft.
-- One-line expectation update in `tests/open-args.test.ts` for the new env default was done by me directly in the FIX-INT worktree because the worker had finished; it mirrors intended behavior and the full scoped suite passes with it.
-
-## Deferred / waiting for you
-
-- Merge the two worktree branches into main, and any push. Both are retirement-ready: `7125` holds MOD plus fixes, `c2c7` holds INTEGRATION plus fixes.
-- Any dependency install, fetch, or vendor action, including remote `bunx` fetches. All runs used already installed tools (claude 2.1.270, local vitest).
-- Live verification in an interactive Claude Code PTY with `CLAUDE_CODE_ENABLE_FUNCTION_HOOKS=1`: real drawing above the prompt, click for keyboard focus, Esc behavior, frame pacing.
-- Running `/plugin-types` to generate `.claude/types` and the full test suite.
-- Product call: grow beyond the single 2048 demo board toward more games, or keep the mod minimal.
-
-## Blocked / failed
-
-- First MOD (6ffe) and INTEGRATION (542f) attempts failed before writing anything: the opencode harness sandbox auto-rejected reads outside the worktree referenced by their briefings (blame harness, retryable). Recovered with one hermetic corrective cycle each (7125, c2c7), both delivered.
-- Manifest validation failed twice during the run and both were fixed: `$.name` read as a value, then handler parameter order (`$` engine first, `e` event second, `e.args` a string), then the Client module path made relative (`./boards/twenty48.tsx`). Each fix was re-validated to green.
-- Validation worker 3cf7 finished without a readable final summary event, so its verdict was reconstructed from its 89 tool outputs (build, tests, validates, file listings) plus my own reruns. Nothing was taken on trust: every quoted result above was reproduced in scratch.
-- One pre-existing `open-args` exact-equality test broke on the intended new env key and was updated as noted above.
-
-## Not covered
-
-- The other eight games, doom, and the pet board: explicitly out of scope in the spec, one demo board delivered.
-- Desktop, mobile, and headless rendering: terminal only by design and by engine constraint.
-- `oxlint` and upstream `bun test`: remote fetch and out of scope; pure logic is covered by the new vitest files instead.
-- Cross-machine score sync: scores and pet live in the local plugin store.
-- Engine-type strictness beyond what `claude plugin validate` checks: `/plugin-types` output was never generated here.
diff --git a/.specs/features/cc-arcade-mod-port/spec.md b/.specs/features/cc-arcade-mod-port/spec.md
deleted file mode 100644
index 817346e..0000000
--- a/.specs/features/cc-arcade-mod-port/spec.md
+++ /dev/null
@@ -1,81 +0,0 @@
-# cc-arcade Mod Port (arcade)
-
-## Goal
-
-Port the cc-arcade pattern (sezaakgun cc-arcade v0.2.0 at github.com/sezaakgun/cc-arcade) into the codedeck plugin as a Mod named `arcade`.
-
-Source behavior to port (from session 2bab discovery):
-
-- `hooks/register.tsx` registers the arcade slash command with `immediate: true` on `session.start`.
-- Draws a picker or a board above the prompt on `ui.render` for `AbovePrompt` using `Box`, `Button`, `Client`, `Text` from `$.ui.resolve`.
-- Mounts one `Client` surface module per board from `hooks/boards`.
-- Records turn start time on `turn.start` for the auto picker heuristic.
-- Pauses the open game with a banner on `turn.complete`.
-- Feeds a pet from `tool.call` by matching Bash test runner patterns plus `git commit` plus `Edit`, `Write`, `NotebookEdit`, keeping counters only with no command text stored.
-- Persists pet plus best scores plus colorblind flag with `$.store`.
-- Costs zero tokens because command handling runs locally.
-
-Codedeck baseline (from session e1ed mapping):
-
-- Plugin version 0.2.0.
-- `plugin/hooks/hooks.json` declares only `SessionStart` and `UserPromptSubmit` shell command hooks with no function hooks module.
-- `codedeck open` builds the settings payload at launch with theme plus fullscreen renderer plus spinner verbs plus tips plus statusline.
-- Installed claude is 2.1.270, above the 2.1.269 drawing gate.
-- Root tsconfig includes only `src`, so plugin tsx never breaks `npm run build`.
-- Vitest includes `tests/**/*.test.ts`.
-
-Port deliverables:
-
-1. `arcade` slash command.
-2. `AbovePrompt` board.
-3. Pure pet plus best plus auto logic with unit tests.
-4. Manifest declaring the hooks module.
-5. `open` enabling function hooks.
-6. Docs.
-
-Port constraints carried over from upstream:
-
-- Never declare a local variable named `h` in board files.
-- `Client` module paths must be string literals.
-- The band is about half the terminal height.
-- Redraw is about ten times per second with doom at twenty.
-- The board needs a click for keyboard focus and Esc always returns to the prompt.
-- Terminal only with nothing drawn in `claude -p` headless, desktop, or mobile.
-- A failed hot reload needs a session restart.
-
-Upstream validation reference: `bun test` for pure logic, `oxlint`, `claude plugin validate`, and `/plugin-types` generating git ignored `.claude/types`.
-
-## Acceptance criteria
-
-- Arcade picker renders above the prompt in terminal sessions with function hooks on.
-- One demo board is playable with keyboard after a click and Esc returns to the prompt.
-- `turn.complete` pauses with a visible banner.
-- `tool.call` feeds pet counters only.
-- Best scores persist across sessions.
-- `claude plugin validate` passes on the manifest and on the repo root.
-- The scoped vitest run on the new tests passes.
-- Existing suite expectations stay green.
-
-## Out of scope
-
-- Full nine game catalog parity including doom.
-- Desktop, mobile, and headless support.
-- Cross machine sync.
-- Any dependency install, fetch, or vendor.
-- Any push or destructive git action.
-
-## Verification
-
-Scoped runs only. Do not run the full suite. Do not install or fetch anything.
-
-- `npm run build`
-- `npx vitest run tests/mods-arcade`
-- `claude plugin validate .claude-plugin/plugin.json`
-- `claude plugin validate .`
-
-Each command is run scoped as listed. Quote the output when reporting results.
-
-## Stop conditions
-
-- If `/plugin-types` cannot run noninteractively, specify engine types as stubbed and continue.
-- Never invent engine APIs.

From f078dc79e4770048f57a2e24bcbcdf9ad8925646 Mon Sep 17 00:00:00 2001
From: 4ndreello <4ndreello@users.noreply.github.com>
Date: Sat, 19 Sep 2026 23:08:08 -0300
Subject: [PATCH 8/8] chore(scripts): Drop the throwaway pane mock

The mock existed to settle the pane's shape before any engine work, and the
pane it was drawing is now implemented, tested and verified on screen. It also
resolved the codedeck binary through PATH, which the security gate flags, and
hardening a script with no remaining purpose is the wrong trade.

Co-Authored-By: Claude <noreply@anthropic.com>
---
 .../orchestrator-agents-band/tasks.md         |   2 +-
 scripts/pane-mock.mjs                         | 105 ------------------
 2 files changed, 1 insertion(+), 106 deletions(-)
 delete mode 100644 scripts/pane-mock.mjs

diff --git a/.specs/features/orchestrator-agents-band/tasks.md b/.specs/features/orchestrator-agents-band/tasks.md
index bed159d..fd471a6 100644
--- a/.specs/features/orchestrator-agents-band/tasks.md
+++ b/.specs/features/orchestrator-agents-band/tasks.md
@@ -335,7 +335,7 @@ tree that cannot build. Removal and replacement are one change.
    `.specs/fixes/`. Independent of the pane, and carried onto its own branch off
    main so the urgent fix is reviewable without the feature.
 2. `feat(mods)`: the arcade deleted, the pane added. `plugin/`, `tests/mods-arcade/`
-   deleted, `tests/mods-agents/`, `scripts/pane-mock.mjs`, `scripts/pane-probe.sh`,
+   deleted, `tests/mods-agents/`, `scripts/pane-probe.sh`,
    `.specs/features/`, plus the stale "arcade mod" comments renamed in
    `src/open/runtime.ts`, `tests/open-args.test.ts` and `.github/workflows/ci.yml`,
    which are stale the moment the arcade is gone.
diff --git a/scripts/pane-mock.mjs b/scripts/pane-mock.mjs
deleted file mode 100644
index 08029f9..0000000
--- a/scripts/pane-mock.mjs
+++ /dev/null
@@ -1,105 +0,0 @@
-// Mock of the right-side agents pane: the web canvas, drawn as ASCII.
-// Throwaway, exists to settle the shape before any engine work.
-// Run: node scripts/pane-mock.mjs [runId] [width]
-
-import { execFileSync } from "node:child_process";
-
-const runId = process.argv[2] ?? process.env.CODEDECK_RUN_ID ?? "f5fd";
-const W = Number(process.argv[3] ?? 40);
-
-const all = JSON.parse(
-  execFileSync("codedeck", ["ps", "--all", "--json"], { encoding: "utf8", maxBuffer: 33554432 }),
-);
-const mine = all.filter((r) => r && r.runId === runId);
-const boss = mine.find((r) => r.origin === "open");
-const kids = mine
-  .filter((r) => r.origin !== "open")
-  .sort((a, b) => Date.parse(b.updatedAt ?? 0) - Date.parse(a.updatedAt ?? 0));
-
-const LIVE = new Set(["working", "starting"]);
-const WAIT = new Set(["needs_input"]);
-const count = {
-  live: kids.filter((k) => LIVE.has(k.status)).length,
-  wait: kids.filter((k) => WAIT.has(k.status)).length,
-  done: kids.filter((k) => !LIVE.has(k.status) && !WAIT.has(k.status)).length,
-};
-
-const dot = (s) => (LIVE.has(s) ? "●" : WAIT.has(s) ? "◉" : "○");
-const word = (s) =>
-  ({
-    working: "Trabalhando agora",
-    starting: "Subindo",
-    needs_input: "Esperando voce",
-    completed: "Concluida",
-    stopped: "Em pausa",
-    failed: "Falhou",
-  })[s] ?? s;
-const glyph = (a) => ({ claude: "▲", opencode: "■", codex: "◆", omp: "⬟" })[a] ?? "□";
-const nameOf = (a) => ({ claude: "Claude", opencode: "OpenCode", codex: "Codex", omp: "OMP" })[a] ?? a;
-
-function age(iso) {
-  const ms = Date.now() - Date.parse(iso ?? 0);
-  if (!Number.isFinite(ms)) return "";
-  const m = Math.floor(ms / 60000);
-  return m < 1 ? "agora" : m < 60 ? `${m}m` : `${Math.floor(m / 60)}h`;
-}
-const clip = (s, n) => (String(s).length <= n ? String(s) : String(s).slice(0, n - 1) + "…");
-const pad = (s, n) => clip(s, n).padEnd(n);
-
-// Outer frame helpers. Everything inside is exactly W-2 wide.
-const IN = W - 2;
-const out = [];
-const frameTop = (label) => out.push("┌" + ("─ " + label + " ").padEnd(IN, "─") + "┐");
-const frameRow = (s) => out.push("│" + pad(s, IN) + "│");
-const frameSep = () => out.push("├" + "─".repeat(IN) + "┤");
-const frameBot = () => out.push("└" + "─".repeat(IN) + "┘");
-
-// A node card, indented inside the frame, with an optional stem below it.
-const CARD = IN - 4; // two spaces of margin each side
-const cardTop = () => frameRow("  ┌" + "─".repeat(CARD - 2) + "┐");
-const cardRow = (s) => frameRow("  │" + pad(s, CARD - 2) + "│");
-const cardBotStem = () => {
-  const left = Math.floor((CARD - 2) / 2);
-  frameRow("  └" + "─".repeat(left) + "┬" + "─".repeat(CARD - 3 - left) + "┘");
-};
-const cardBotPlain = () => frameRow("  └" + "─".repeat(CARD - 2) + "┘");
-const stem = () => {
-  const left = Math.floor((CARD - 2) / 2);
-  frameRow("  " + " ".repeat(left + 1) + "│");
-};
-
-frameTop("Canvas do run " + runId);
-frameRow(` ${mine.length} sessoes · ${count.live} trabalhando`);
-frameRow(` ${count.wait} esperando voce · ${count.done} prontas`);
-frameSep();
-frameRow("");
-
-// orchestrator
-cardTop();
-cardRow(` ${glyph(boss?.agent ?? "claude")} ● Orquestrador`);
-cardRow(`   ${nameOf(boss?.agent ?? "claude")} · ${kids.length} agentes`);
-cardBotStem();
-
-const SHOW = 5;
-kids.slice(0, SHOW).forEach((k, i) => {
-  stem();
-  cardTop();
-  cardRow(` ${glyph(k.agent)} ${dot(k.status)} ${k.id}  ${nameOf(k.agent)}`);
-  cardRow(`   ${clip(k.name ?? "-", CARD - 5)}`);
-  cardRow(`   ${word(k.status)} · ${age(k.updatedAt)}`);
-  const last = i === Math.min(SHOW, kids.length) - 1;
-  if (last && kids.length <= SHOW) cardBotPlain();
-  else cardBotStem();
-});
-if (kids.length > SHOW) {
-  stem();
-  frameRow(`  +${kids.length - SHOW} agentes ocultos`);
-}
-frameRow("");
-frameSep();
-frameRow(" ● trabalha  ◉ te espera  ○ pronta");
-frameBot();
-
-console.log("");
-for (const l of out) console.log("  " + l);
-console.log("");