pi-minimal 0.2.2 → 0.3.0

package/CHANGELOG.md

@@ -10,6 +10,51 @@ Releases are cut automatically: when the `version` in `package.json` changes on
 
 ## [Unreleased]
 
+## [0.3.0] - 2026-10-25
+
+### Added
+- `codemode` renders as a tool row: `✓ code  3 calls · plan_tracker ×2, bash … 54 lines · 1.2s`,
+  with one child row per nested call. Built-in tools inside a script read exactly like their
+  top-level rows (`bash` shows its command); other tools show up to three scalar arguments as
+  `key=value` instead of raw JSON. Children update live while the script runs. The script source
+  and output appear only on `ctrl+o`, in plain dim text, so syntax colours no longer compete with
+  status colours. A failed nested call or script error shows its first line under the row, like
+  `bash`. Previously codemode fell through to pi-core's default panel: a background slab with the
+  highlighted script, JSON arguments, an output preview and a `Took …` timer.
+
+### Changed
+- `minimal-dark` contrast: `dim` (verbs, outcomes, tool output) L 48 % → 56 % and `thinkingText`
+  52 % → 58 %, estimated ~3.1:1 → ~4.4:1 and ~3.7:1 → ~4.8:1 on the background. They were within
+  4 % of each other and below WCAG's 4.5:1 text target. `faint` 34 % → 36 %.
+- `minimal-dark` keeps syntax colours off the status hues: `syntaxFunction` was warning-yellow
+  (now lavender) and `syntaxNumber` was success-green (now teal), so code no longer looks like a
+  spinner or a check mark.
+- `minimal-dark` draws no background behind pending/successful tool output (`toolPendingBg`,
+  `toolSuccessBg` → `bg`). Tools pi-minimal does not restyle yet (`subagent`, MCP tools) lose
+  their slab; failures keep `toolErrorBg`.
+
+## [0.2.3] - 2026-10-24
+
+### Added
+- Versioned, session-scoped footer activity contribution API. Companion extensions
+  can publish bounded activity rows after existing hints and tracker summaries
+  without replacing the footer. No visible change without a contributor.
+- Icon-first activity rows with pi-minimal's spinner/check/failure colors,
+  plain/static modes, overflow handling, optional elapsed time/token metrics,
+  and optional task links with independent task-state badges.
+- Snapshot validation, immutable metadata, exclusive slot ownership, stale-update
+  protection, and integration documentation.
+- Independent plan-summary contribution slot with violet slanted progress segments
+  and exact accepted/total counts, rendered below the input. One blank row
+  separates nonempty footer groups; activity rows stay compact. The summary is
+  display-only and does not add task storage or infer acceptance from agent runs.
+- Release checks for matching manifest/lockfile versions and a dated changelog entry.
+
+### Fixed
+- Dispose activity subscriptions and animation timers across footer replacement
+  and shutdown; prevent delayed settle callbacks from reinstalling stale chrome.
+- Synchronize the previously stale lockfile package version with the manifest.
+
 ## [0.2.2] - 2026-10-22
 
 ### Added
@@ -74,7 +119,8 @@ Releases are cut automatically: when the `version` in `package.json` changes on
 - Initial release: header/footer chrome, compact tool activity rows, working
   status line, Herdr sibling status, Gauntlet widget hiding.
 
-[Unreleased]: https://github.com/raviy06/pi-minimal/compare/v0.2.2...HEAD
+[Unreleased]: https://github.com/raviy06/pi-minimal/compare/v0.2.3...HEAD
+[0.2.3]: https://github.com/raviy06/pi-minimal/compare/v0.2.2...v0.2.3
 [0.2.2]: https://github.com/raviy06/pi-minimal/compare/v0.2.1...v0.2.2
 [0.2.1]: https://github.com/raviy06/pi-minimal/compare/v0.2.0...v0.2.1
 [0.2.0]: https://github.com/raviy06/pi-minimal/compare/v0.1.0...v0.2.0

package/README.md

@@ -30,14 +30,14 @@ Do not load this package beside the live `grok-chrome` extension. Disable or rem
 
 ## What it changes
 
-- **Tool rows** – every built-in tool call (`bash`, `read`, `edit`, `write`, `grep`, `find`, `ls`) renders as one line: status glyph (`◐` running, `✓` ok, `✗` failed), verb, item, and a right-aligned outcome (`34 lines · 1.0s`, `exit 1`, `+3 −1`, `4 matches`). Failed rows show the first line of output underneath; `ctrl+o` expands full output in a `│`-ruled block.
+- **Tool rows** – every built-in tool call (`bash`, `read`, `edit`, `write`, `grep`, `find`, `ls`) renders as one line: status glyph (`◐` running, `✓` ok, `✗` failed), verb, item, and a right-aligned outcome (`34 lines · 1.0s`, `exit 1`, `+3 −1`, `4 matches`). Failed rows show the first line of output underneath; `ctrl+o` expands full output in a `│`-ruled block. `codemode` renders the same way, as a `code` row with one child row per nested tool call; `ctrl+o` shows the script and its output.
 - **Turn rule** – after each agent run a dim `── 15:51 · 12s · 4 tools ──` separator is appended (stored as a custom entry; never sent to the model).
 - **Thinking gutter** – thinking paragraphs are prefixed with `┊` so they read as secondary.
 - **Status line** – one line above the editor: model · thinking level · context meter (amber at 70 %, red at 90 %) · cwd · `⎇ branch ±dirty` · Herdr siblings.
 - **Footer** – key hints appear only when the agent is idle and the editor is empty; `/compact` is suggested under context pressure.
 - **Code blocks** – fenced code renders as a closed box with the language as its title, keeping syntax highlighting, instead of literal ``` lines; long lines wrap inside the box.
 - **Alignment** – chrome follows pi's `outputPad` setting. Pi's editor uses the separate `editorPaddingX` setting (default `0`); set `"editorPaddingX": 1` for a flush left edge with the transcript.
-- **Theme** – ships `minimal-dark`: neutral tool backgrounds, visible user-message tint, dimmer thinking text, violet headings (yellow is reserved for warnings), and faint code-block frames. Select it in `/settings` → Theme, or set `"theme": "minimal-dark"`.
+- **Theme** – ships `minimal-dark`: no background behind tool rows (failures excepted), a grey ladder whose readable tiers stay near 4.5:1, syntax colours kept off the status hues, visible user-message tint, dimmer thinking text, violet headings (yellow is reserved for warnings), and faint code-block frames. Select it in `/settings` → Theme, or set `"theme": "minimal-dark"`.
 
 ## Configuration
 
@@ -55,8 +55,30 @@ The only supported key is `hideGauntletWidgets`. It defaults to `true`.
 { "hideGauntletWidgets": true }
 ```
 
+## Optional footer activity API
+
+Companion extensions can publish session-scoped activity rows through the versioned
+in-process footer contribution API. Pi-minimal keeps ownership of the footer and
+renders activity **after** existing hints and tracker summaries. An independent
+`summary` slot supplies a violet segmented plan bar below the input. Nonempty
+groups are separated by one blank row; agent rows remain compact. The API adds no
+visible content without a contributor and changes no other extension's settings.
+
+Rows use pi-minimal's yellow running spinner, green completion check, and red
+failure glyph. Plain-text and static modes are supported. See
+[Footer activity contributions](doc/footer-contributions.md) for the protocol,
+validation limits, lifecycle, and integration example.
+
+This is a display integration seam, not a subagent runtime or task tracker.
+
 ## Releasing
 
+Every new extension PR must include a version bump before it is opened, so merging
+it can trigger publication and users can update. Keep `package.json`, both root
+version fields in `package-lock.json`, the package test expectation, and the dated
+changelog entry synchronized. Before merging concurrent PRs, verify that the
+selected version is still newer than `main` and has not already been published.
+
 Releases are automatic. To ship a version:
 
 1. Add a `## [x.y.z] - YYYY-MM-DD` section to `CHANGELOG.md`.

package/dist/codemode-rows.js

@@ -0,0 +1,109 @@
+import { firstLine, formatDuration, resultText, toolItem } from "./tool-rows.js";
+const KINDS = new Set(["bash", "read", "edit", "write", "grep", "find", "ls"]);
+const SCRIPT_HEADER = /^Script (?:completed|failed)\nWall time [\d.]+ seconds\nOutput:\n?/;
+/** Argument keys toolItem() reads, in the order it prefers them. */
+const ITEM_KEYS = ["command", "path", "file_path", "target_directory", "pattern"];
+export function nestedCalls(result) {
+    const calls = result?.details?.calls;
+    if (!Array.isArray(calls))
+        return [];
+    return calls.filter((call) => Boolean(call) && typeof call === "object");
+}
+/** Script output without pi-core's "Script completed / Wall time / Output:" header. */
+export function scriptOutput(result) {
+    return resultText(result).replace(SCRIPT_HEADER, "").trim();
+}
+/**
+ * Parse the host's argument preview. Complete JSON parses directly; a preview cut at 200 chars
+ * still yields the first string value of each known key, which is all a one-line row needs.
+ */
+export function parseArgs(args) {
+    if (!args)
+        return {};
+    try {
+        const value = JSON.parse(args);
+        return value && typeof value === "object" && !Array.isArray(value) ? value : {};
+    }
+    catch {
+        const out = {};
+        const pair = /"([A-Za-z_$][\w$]*)":(?:"((?:[^"\\]|\\.)*)"?|(-?\d+(?:\.\d+)?|true|false|null))/g;
+        for (const m of args.matchAll(pair)) {
+            if (m[1] in out)
+                continue;
+            if (m[2] !== undefined)
+                out[m[1]] = unescape(m[2]);
+            else if (m[3] !== undefined)
+                out[m[1]] = JSON.parse(m[3]);
+        }
+        return out;
+    }
+}
+function unescape(raw) {
+    // A cut can land inside an escape; drop a dangling backslash so JSON.parse accepts the rest.
+    const safe = raw.replace(/\\(u[0-9a-fA-F]{0,3})?$/, "");
+    try {
+        return JSON.parse(`"${safe}"`);
+    }
+    catch {
+        return safe;
+    }
+}
+function scalar(value) {
+    if (typeof value === "string")
+        return value.split("\n")[0]?.trim();
+    if (typeof value === "number" || typeof value === "boolean")
+        return String(value);
+    return undefined;
+}
+/**
+ * The item column of a nested call. Built-in tools read exactly like their top-level rows
+ * (`bash` shows its command, `read` a short path). Other tools show up to three scalar
+ * arguments as `key=value`, strings unquoted, instead of raw JSON.
+ */
+export function nestedItem(call) {
+    const name = call.name ?? "tool";
+    const args = parseArgs(call.args);
+    if (KINDS.has(name)) {
+        const picked = {};
+        for (const key of ITEM_KEYS)
+            if (key in args)
+                picked[key] = args[key];
+        return toolItem(name, picked);
+    }
+    const parts = [];
+    for (const [key, value] of Object.entries(args)) {
+        const shown = scalar(value);
+        if (shown === undefined || shown === "")
+            continue;
+        parts.push(`${key}=${shown}`);
+        if (parts.length === 3)
+            break;
+    }
+    return parts.join(" ");
+}
+/** `3 calls · plan_tracker ×2, bash` — names in first-call order with repeat counts. */
+export function callSummary(calls) {
+    if (calls.length === 0)
+        return "script";
+    const counts = new Map();
+    for (const call of calls)
+        counts.set(call.name ?? "tool", (counts.get(call.name ?? "tool") ?? 0) + 1);
+    const names = [...counts].map(([name, n]) => (n > 1 ? `${name} ×${n}` : name)).join(", ");
+    return `${calls.length} call${calls.length === 1 ? "" : "s"} · ${names}`;
+}
+/** Right-hand outcome of the parent row, and the line shown under it when something failed. */
+export function codemodeOutcome(result, isError, durationMs) {
+    const calls = nestedCalls(result);
+    const output = scriptOutput(result);
+    const failedCalls = calls.filter((call) => call.status === "error");
+    const dur = formatDuration(durationMs);
+    const join = (...parts) => parts.filter(Boolean).join(" · ");
+    if (isError || failedCalls.length > 0) {
+        const label = failedCalls.length > 0 ? `${failedCalls.length} failed` : "failed";
+        const scriptError = /Script error:\s*(.*)/.exec(output)?.[1];
+        const errorLine = firstLine(failedCalls[0]?.error ?? "") ?? scriptError ?? firstLine(output);
+        return { text: join(label, dur), failed: true, errorLine };
+    }
+    const lines = output ? output.split("\n").filter((line) => line.length > 0).length : 0;
+    return { text: join(lines === 0 ? "ok" : `${lines} line${lines === 1 ? "" : "s"}`, dur), failed: false };
+}

package/dist/footer-activity-details.js

@@ -0,0 +1,45 @@
+import { truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+export function taskPrefix(task, plain, theme) {
+    if (!task)
+        return "";
+    if (plain)
+        return `[${task.status}] ${task.id} / `;
+    const badges = {
+        blocked: ["!", "warning"], in_review: ["◇", "accent"], done: ["✓", "success"], cancelled: ["⊘", "muted"],
+    };
+    const badge = badges[task.status];
+    return `${badge ? theme.fg(badge[1], badge[0]) + " " : ""}${task.id} · `;
+}
+function elapsed(ms, missing) {
+    if (ms === undefined)
+        return missing;
+    const seconds = Math.floor(ms / 1000);
+    if (seconds >= 3600)
+        return `${Math.floor(seconds / 3600)}h ${String(Math.floor(seconds / 60) % 60).padStart(2, "0")}m`;
+    if (seconds >= 60)
+        return `${Math.floor(seconds / 60)}m ${String(seconds % 60).padStart(2, "0")}s`;
+    return `${seconds}s`;
+}
+function tokens(value, missing) {
+    if (value === undefined)
+        return missing;
+    if (value >= 999950)
+        return `${(value / 1000000).toFixed(1)}m`;
+    if (value >= 1000)
+        return `${(value / 1000).toFixed(1)}k`;
+    return String(value);
+}
+/** Metrics never displace activity text: first drop tokens, then elapsed time. */
+export function alignActivityMetrics(left, metrics, width, plain, theme) {
+    if (metrics) {
+        const missing = plain ? "-" : "—";
+        const time = elapsed(metrics.elapsedMs, missing);
+        const full = `${time}${plain ? " / " : " · "}${tokens(metrics.tokens, missing)} tok`;
+        for (const right of [full, time]) {
+            const gap = width - visibleWidth(left) - visibleWidth(right);
+            if (gap >= 2)
+                return left + " ".repeat(gap) + theme.fg("muted", right);
+        }
+    }
+    return truncateToWidth(left, width);
+}

package/dist/footer-activity.js

@@ -0,0 +1,36 @@
+import { truncateToWidth } from "@earendil-works/pi-tui";
+import { cleanActivityText } from "./footer-contributions.js";
+import { rowGlyph } from "./tool-rows.js";
+import { alignActivityMetrics, taskPrefix } from "./footer-activity-details.js";
+const MAX_ROWS = 4;
+const indicators = {
+    queued: ["○", "muted"], running: ["◐", "warning"], waiting: ["!", "warning"], paused: ["Ⅱ", "muted"],
+    stopping: ["!", "warning"], completed: ["✓", "success"], failed: ["✗", "error"], stopped: ["⊘", "muted"], unknown: ["?", "muted"],
+};
+export function activityNeedsAnimation(snapshot) {
+    return snapshot?.motion === "spinner" && snapshot.format === "icons" && snapshot.rows.slice(0, MAX_ROWS).some(row => row.state === "running");
+}
+export function renderFooterActivity(snapshot, width, theme, frame = 0) {
+    if (!snapshot || width <= 0)
+        return [];
+    const parents = new Map(snapshot.rows.map(row => [row.key, row.parentKey]));
+    const lines = snapshot.rows.slice(0, MAX_ROWS).map(row => {
+        const [fallback, tone] = indicators[row.state];
+        const glyph = row.state === "running" ? rowGlyph("running", snapshot.motion === "spinner" ? frame : 0)
+            : row.state === "completed" ? rowGlyph("ok", 0) : row.state === "failed" ? rowGlyph("error", 0) : fallback;
+        const marker = snapshot.format === "plain" ? `[${row.state}]` : glyph;
+        let depth = 0, parent = row.parentKey;
+        while (parent && depth < 2) {
+            depth++;
+            parent = parents.get(parent);
+        }
+        const reason = row.state === "stopping" && snapshot.format === "icons" ? "Stopping: " : "";
+        const task = taskPrefix(row.task, snapshot.format === "plain", theme);
+        const text = `${"  ".repeat(depth)}${theme.fg(tone, marker)} ${cleanActivityText(row.agent)}  ${task}${reason}${cleanActivityText(row.text)}`.trimEnd();
+        return alignActivityMetrics(text, row.metrics, width, snapshot.format === "plain", theme);
+    });
+    const omitted = Math.min(Number.MAX_SAFE_INTEGER, snapshot.omitted + Math.max(0, snapshot.rows.length - MAX_ROWS));
+    if (omitted > 0)
+        lines.push(truncateToWidth(theme.fg("muted", `+ ${omitted} more`), width));
+    return lines;
+}

package/dist/footer-contribution-events.js

@@ -0,0 +1,35 @@
+export const FOOTER_EVENTS = {
+    register: "pi-minimal:footer:v1:register",
+    ready: "pi-minimal:footer:v1:ready",
+    unavailable: "pi-minimal:footer:v1:unavailable",
+};
+/** Bind once per session, not once per footer mount. Trusted in-process protocol. */
+export function bindFooterContributionEvents(events, registry, sessionId, mode) {
+    registry.reset(mode === "tui" ? sessionId : null);
+    const unsubscribe = events.on(FOOTER_EVENTS.register, (value) => {
+        if (typeof value !== "object" || value === null || Array.isArray(value))
+            return;
+        const request = value;
+        // A different host may have answered first. Never overwrite its result.
+        if (request.result !== undefined)
+            return;
+        if (request.version !== 1 || (request.slot !== "activity" && request.slot !== "summary"))
+            request.result = { ok: false, code: "invalid" };
+        else if (mode !== "tui")
+            request.result = { ok: false, code: "not-tui" };
+        else
+            request.result = request.slot === "summary" ? registry.registerPlan(request) : registry.register(request);
+    });
+    if (mode === "tui")
+        events.emit(FOOTER_EVENTS.ready, { version: 1, sessionId, slots: ["activity", "summary"] });
+    let disposed = false;
+    return () => {
+        if (disposed)
+            return;
+        disposed = true;
+        unsubscribe();
+        registry.reset(null);
+        if (mode === "tui")
+            events.emit(FOOTER_EVENTS.unavailable, { version: 1, sessionId });
+    };
+}

package/dist/footer-contributions.js

@@ -0,0 +1,130 @@
+import { stripVTControlCharacters } from "node:util";
+import { normalizePlanSnapshot } from "./footer-plan.js";
+export const ACTIVITY_STATES = ["queued", "running", "waiting", "paused", "stopping", "completed", "failed", "stopped", "unknown"];
+export const TASK_STATUSES = ["todo", "in_progress", "blocked", "in_review", "done", "cancelled"];
+function record(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function identity(value) {
+    return typeof value === "string" && /^[a-zA-Z0-9._:@+-]{1,128}$/.test(value);
+}
+export function cleanActivityText(value) {
+    return stripVTControlCharacters(value)
+        // Also remove bare C0/C1 and bidi controls; no terminal commands from labels.
+        // eslint-disable-next-line no-control-regex
+        .replace(/[\u0000-\u001f\u007f-\u009f\u202a-\u202e\u2066-\u2069]/g, " ")
+        .replace(/\s+/gu, " ").trim();
+}
+function validMetrics(value) {
+    return record(value) && [value.elapsedMs, value.tokens].every(n => n === undefined || (Number.isSafeInteger(n) && n >= 0));
+}
+function validTask(value) {
+    return record(value) && identity(value.planId) && identity(value.id) && TASK_STATUSES.includes(value.status);
+}
+function normalizeSnapshot(input) {
+    if (!record(input) || !Number.isSafeInteger(input.revision) || input.revision < 0 ||
+        !Number.isSafeInteger(input.omitted) || input.omitted < 0 ||
+        !["spinner", "static"].includes(input.motion) || !["icons", "plain"].includes(input.format) ||
+        !Array.isArray(input.rows) || input.rows.length > 64)
+        return;
+    const rows = [];
+    const parents = new Map();
+    for (const item of input.rows) {
+        if (!record(item) || !identity(item.key) || parents.has(item.key) ||
+            typeof item.agent !== "string" || item.agent.length > 96 || !cleanActivityText(item.agent) ||
+            typeof item.text !== "string" || item.text.length > 256 ||
+            !ACTIVITY_STATES.includes(item.state) ||
+            (item.parentKey !== undefined && !identity(item.parentKey)) ||
+            (item.metrics !== undefined && !validMetrics(item.metrics)) ||
+            (item.task !== undefined && !validTask(item.task)))
+            return;
+        parents.set(item.key, item.parentKey);
+        rows.push(Object.freeze({ key: item.key, agent: cleanActivityText(item.agent), state: item.state,
+            text: cleanActivityText(item.text), ...(item.parentKey === undefined ? {} : { parentKey: item.parentKey }),
+            ...(item.metrics === undefined ? {} : { metrics: Object.freeze({ elapsedMs: item.metrics.elapsedMs, tokens: item.metrics.tokens }) }),
+            ...(item.task === undefined ? {} : { task: Object.freeze({ planId: item.task.planId, id: item.task.id, status: item.task.status }) }),
+        }));
+    }
+    for (const row of rows) {
+        const seen = new Set([row.key]);
+        let parent = row.parentKey;
+        while (parent !== undefined) {
+            if (!parents.has(parent) || seen.has(parent))
+                return;
+            seen.add(parent);
+            parent = parents.get(parent);
+        }
+    }
+    return Object.freeze({ revision: input.revision, rows: Object.freeze(rows), omitted: input.omitted,
+        motion: input.motion, format: input.format });
+}
+function createFooterSlot(normalize, initialSessionId) {
+    let sessionId = initialSessionId;
+    let owner;
+    let snapshot;
+    const observers = new Set();
+    const notify = () => {
+        for (const observer of [...observers]) {
+            try {
+                observer();
+            }
+            catch { /* A disposed UI must not invalidate a successful publish. */ }
+        }
+    };
+    return {
+        read: () => snapshot,
+        subscribe(observer) { observers.add(observer); return () => { observers.delete(observer); }; },
+        reset(nextSessionId) {
+            sessionId = nextSessionId;
+            owner = undefined;
+            snapshot = undefined;
+            notify();
+        },
+        register(input) {
+            if (!record(input) || !identity(input.owner) || typeof input.sessionId !== "string" || !input.sessionId)
+                return { ok: false, code: "invalid" };
+            if (sessionId === null || input.sessionId !== sessionId)
+                return { ok: false, code: "wrong-session" };
+            if (owner)
+                return { ok: false, code: "occupied" };
+            const token = Symbol(input.owner);
+            owner = token;
+            return { ok: true, registration: {
+                    publish(input) {
+                        if (owner !== token)
+                            return { ok: false, code: "disposed" };
+                        const next = normalize(input);
+                        if (!next)
+                            return { ok: false, code: "invalid" };
+                        if (snapshot && next.revision <= snapshot.revision)
+                            return { ok: false, code: "stale" };
+                        snapshot = next;
+                        notify();
+                        return { ok: true };
+                    },
+                    dispose() {
+                        if (owner !== token)
+                            return;
+                        owner = undefined;
+                        snapshot = undefined;
+                        notify();
+                    },
+                } };
+        },
+    };
+}
+export function createFooterContributions(initialSessionId = null) {
+    const activity = createFooterSlot(normalizeSnapshot, initialSessionId);
+    const summary = createFooterSlot(normalizePlanSnapshot, initialSessionId);
+    return {
+        read: activity.read,
+        readPlan: summary.read,
+        register: activity.register,
+        registerPlan: summary.register,
+        subscribe(observer) {
+            const offActivity = activity.subscribe(observer), offSummary = summary.subscribe(observer);
+            return () => { offActivity(); offSummary(); };
+        },
+        reset(sessionId) { activity.reset(sessionId); summary.reset(sessionId); },
+    };
+}

package/dist/footer-plan.js

@@ -0,0 +1,41 @@
+import { truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+function record(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+const count = (value) => Number.isSafeInteger(value) && value >= 0;
+export function normalizePlanSnapshot(value) {
+    if (!record(value) || !count(value.revision) || (value.format !== "icons" && value.format !== "plain"))
+        return;
+    if (value.plan === undefined)
+        return Object.freeze({ revision: value.revision, format: value.format });
+    const plan = value.plan;
+    if (!record(plan) || typeof plan.id !== "string" || !/^[a-zA-Z0-9._:@+-]{1,128}$/.test(plan.id) ||
+        !count(plan.accepted) || !count(plan.total) || !count(plan.inReview) || !count(plan.blocked) ||
+        plan.accepted > plan.total || plan.inReview > plan.total - plan.accepted || plan.blocked > plan.total - plan.accepted)
+        return;
+    return Object.freeze({ revision: value.revision, format: value.format,
+        plan: Object.freeze({ id: plan.id, accepted: plan.accepted, total: plan.total, inReview: plan.inReview, blocked: plan.blocked }) });
+}
+/** Display-only accepted-task counts, never inferred from agent execution. */
+export function renderFooterPlan(snapshot, width, theme) {
+    if (!snapshot?.plan || width <= 0)
+        return [];
+    const { id, accepted, total, inReview, blocked } = snapshot.plan;
+    const plain = snapshot.format === "plain", separator = plain ? " / " : " · ";
+    const label = theme.fg("accent", `Plan ${id}`);
+    if (!total)
+        return [truncateToWidth(`${label}${separator}No tasks yet`, width)];
+    const slots = total <= 12 ? total : 10;
+    const filled = total <= 12 ? accepted : Math.floor(accepted / total * slots);
+    const bar = theme.fg("accent", (plain ? "#" : "▰").repeat(filled)) + theme.fg("muted", (plain ? "." : "▱").repeat(slots - filled));
+    const counts = `${accepted}/${total}`;
+    const attention = [inReview ? `${plain ? "" : "◇ "}${inReview} review` : "", blocked ? `! ${blocked} blocked` : ""].filter(Boolean);
+    const suffix = attention.length ? separator + attention.join(separator) : "";
+    for (const text of [`${label}${separator}${bar} ${counts}${suffix}`, `${label}${separator}${counts}${suffix}`, `${label}${separator}${counts}`]) {
+        if (visibleWidth(text) <= width)
+            return [text];
+    }
+    // Exact counts outrank a long plan label on extremely narrow terminals.
+    const room = width - visibleWidth(counts) - 1;
+    return [room > 0 ? `${truncateToWidth(label, room)} ${counts}` : truncateToWidth(counts, width)];
+}

package/dist/footer.js

@@ -2,6 +2,9 @@ import { keyHint } from "@earendil-works/pi-coding-agent";
 import { truncateToWidth } from "@earendil-works/pi-tui";
 import * as chrome from "./chrome.js";
 import { formatTrackerLines } from "./tracker.js";
+import { activityNeedsAnimation, renderFooterActivity } from "./footer-activity.js";
+import { createLiveWatch } from "./live-watch.js";
+import { renderFooterPlan } from "./footer-plan.js";
 /** Tolerates a stale chrome module after /reload, where only CHROME_MARGIN may exist. */
 const margin = () => (typeof chrome.chromeMargin === "function" ? chrome.chromeMargin() : (chrome.CHROME_MARGIN ?? 1));
 /**
@@ -19,11 +22,40 @@ export function footerHints(sources, hints) {
         out.push("/compact");
     return out;
 }
-export function installFooter(ctx, sources) {
+export function installFooter(ctx, sources, contributions) {
+    let stopMount = () => { };
+    let stopped = false;
     ctx.ui.setFooter((tui, theme, footerData) => {
-        const unsub = footerData.onBranchChange(() => tui.requestRender());
+        stopMount();
+        if (stopped)
+            return { render: () => [], invalidate() { } };
+        const live = createLiveWatch(400);
+        let disposed = false;
+        let activityHasSpace = true;
+        const redraw = () => { if (!disposed)
+            tui.requestRender(); };
+        const syncAnimation = () => {
+            if (disposed)
+                return;
+            if (activityHasSpace && activityNeedsAnimation(contributions?.read()))
+                live.watch("footer", redraw);
+            else
+                live.unwatch("footer");
+        };
+        const update = () => { syncAnimation(); redraw(); };
+        const unsub = footerData.onBranchChange(redraw);
+        const unsubscribeActivity = contributions?.subscribe(update);
+        stopMount = () => {
+            if (disposed)
+                return;
+            disposed = true;
+            unsub();
+            unsubscribeActivity?.();
+            live.stop();
+        };
+        update();
         return {
-            dispose: unsub,
+            dispose: stopMount,
             invalidate() { },
             render(width) {
                 const inner = Math.max(8, width - margin() * 2);
@@ -37,11 +69,21 @@ export function installFooter(ctx, sources) {
                     const line = theme.fg("dim", hints.join("  ·  "));
                     out.push(`${" ".repeat(margin())}${truncateToWidth(line, inner, "")}`);
                 }
-                for (const extra of formatTrackerLines(ctx, theme)) {
-                    out.push(`${" ".repeat(margin())}${truncateToWidth(extra, inner, "")}`);
-                }
-                return out;
+                const activityWidth = Math.max(0, width - margin() * 2);
+                const plan = renderFooterPlan(contributions?.readPlan(), activityWidth, theme);
+                const summary = (plan.length ? plan : formatTrackerLines(ctx, theme))
+                    .map(line => `${" ".repeat(margin())}${truncateToWidth(line, plan.length ? activityWidth : inner, "")}`);
+                activityHasSpace = activityWidth > 0;
+                syncAnimation();
+                const activity = renderFooterActivity(contributions?.read(), activityWidth, theme, live.frame)
+                    .map(line => `${" ".repeat(margin())}${line}`);
+                // Preserve legacy-only layout; contributions opt into the spaced layout.
+                if (!plan.length && !activity.length)
+                    return [...out, ...summary];
+                const groups = [out, summary, activity].filter(group => group.length > 0);
+                return ["", ...groups.flatMap((group, index) => index === 0 ? group : ["", ...group])];
             },
         };
     });
+    return () => { stopped = true; stopMount(); };
 }