pi-minimal 0.2.2 → 0.2.3

package/CHANGELOG.md

@@ -10,6 +10,28 @@ Releases are cut automatically: when the `version` in `package.json` changes on
 
 ## [Unreleased]
 
+## [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 +96,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

@@ -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/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(); };
 }

package/dist/index.js

@@ -2,6 +2,8 @@ import { getAgentDir } from "@earendil-works/pi-coding-agent";
 import { loadPiMinimalConfig } from "./config.js";
 import { installHeader } from "./header.js";
 import { installFooter } from "./footer.js";
+import { createFooterContributions } from "./footer-contributions.js";
+import { bindFooterContributionEvents } from "./footer-contribution-events.js";
 import { installCwd } from "./cwd.js";
 import { listSiblings, parseAgentList, parseTabList } from "./herdr.js";
 import { hideGauntletWidgets } from "./tracker.js";
@@ -20,6 +22,10 @@ export default function piMinimalExtension(pi) {
     installToolRenderers(pi);
     installTranscript(pi);
     installCodeBox();
+    const contributions = createFooterContributions();
+    let stopFooter = () => { };
+    let stopContributionEvents = () => { };
+    let sessionActive = false;
     let fastTimer;
     let slowTimer;
     let stealTimer;
@@ -128,11 +134,12 @@ export default function piMinimalExtension(pi) {
         return Math.max(0, Math.min(100, Math.round((usage.tokens / window) * 100)));
     };
     const installChromeFooter = (ctx) => {
-        installFooter(ctx, {
+        stopFooter();
+        stopFooter = installFooter(ctx, {
             busy: () => busy,
             editorText: () => (typeof ctx.ui.getEditorText === "function" ? ctx.ui.getEditorText() : ""),
             contextPct: () => contextPct(ctx),
-        });
+        }, contributions);
     };
     const installStatusLine = (ctx) => {
         installCwd(ctx, {
@@ -149,6 +156,11 @@ export default function piMinimalExtension(pi) {
         installStatusLine(ctx);
     };
     pi.on("session_start", async (_event, ctx) => {
+        stopFooter();
+        stopContributionEvents();
+        sessionActive = true;
+        generation += 1;
+        stopContributionEvents = bindFooterContributionEvents(pi.events, contributions, ctx.sessionManager.getSessionId(), ctx.mode);
         if (ctx.mode !== "tui")
             return;
         const config = loadPiMinimalConfig({
@@ -172,8 +184,13 @@ export default function piMinimalExtension(pi) {
         pinChrome(ctx, "session_start");
         ctx.ui.setHiddenThinkingLabel("◆ Thought");
         ctx.ui.setWorkingIndicator();
-        setTimeout(() => pinChrome(ctx, "session_settle"), 0);
-        setTimeout(() => pinChrome(ctx, "session_settle"), 50);
+        const sessionGeneration = generation;
+        const settle = () => {
+            if (sessionActive && generation === sessionGeneration)
+                pinChrome(ctx, "session_settle");
+        };
+        setTimeout(settle, 0);
+        setTimeout(settle, 50);
         if (!stealTimer) {
             stealTimer = setInterval(() => hideForeignChrome(ctx, "interval"), 200);
         }
@@ -197,6 +214,9 @@ export default function piMinimalExtension(pi) {
         void gitState.refresh();
     });
     pi.on("session_shutdown", async () => {
+        sessionActive = false;
+        stopFooter();
+        stopContributionEvents();
         busy = false;
         stopTimers();
         stopWorkingStatus();

package/doc/footer-contributions.md

@@ -0,0 +1,132 @@
+# Footer activity contributions (v1)
+
+Pi-minimal remains the single footer owner. A trusted companion extension can publish a bounded activity snapshot without replacing the footer or fighting other widgets. With no contributor, existing hints and legacy phase/task summaries are unchanged.
+
+Order: **input → existing hints → plan summary → activity rows last**. When either contribution is visible, a blank row separates the footer from input and separates each nonempty group. Agent rows stay compact, and empty groups leave no extra gaps. Legacy-only output is unchanged.
+
+Two independent slots are supported: `activity` and `summary`, with one owner per slot. An explicit plan summary replaces the legacy tracker projection while present, avoiding duplicate plan bars; clearing it restores the legacy summary. This is display composition, not a task tracker, subagent launcher, or PR/workspace display.
+
+## Events
+
+| Event | Direction | Payload |
+|---|---|---|
+| `pi-minimal:footer:v1:register` | consumer → host | Mutable registration request; host assigns `result` synchronously |
+| `pi-minimal:footer:v1:ready` | host → consumers | `{ version: 1, sessionId, slots: ["activity", "summary"] }` |
+| `pi-minimal:footer:v1:unavailable` | host → consumers | `{ version: 1, sessionId }` |
+
+Use `ctx.sessionManager.getSessionId()`, not a file path. Events are in-process only, not a cross-process API. One consumer owns each slot at a time; a tracker and activity extension can register independently. Names/keys are display identity, not permission or process-control tokens.
+
+Register during `session_start`; also listen for `ready` to tolerate either extension load order. Clear the local handle on `unavailable`. Do not attempt to reinstall the footer if no host responds.
+
+```ts
+const request = {
+  version: 1,
+  sessionId: ctx.sessionManager.getSessionId(),
+  owner: "my-activity-extension",
+  slot: "activity",
+  result: undefined as RegisterRequest["result"],
+};
+pi.events.emit("pi-minimal:footer:v1:register", request);
+if (request.result?.ok) {
+  const registration = request.result.registration;
+  const result = registration.publish({
+    revision: 0,
+    motion: "spinner",
+    format: "icons",
+    omitted: 0,
+    rows: [
+      { key: "child-1", agent: "worker", state: "running", text: "Last: executing tests" },
+      { key: "child-2", agent: "reviewer", state: "completed", text: "Review output available" },
+    ],
+  });
+  // Inspect result.ok; publication is not a task-completion acknowledgement.
+  // On consumer shutdown: registration.dispose().
+}
+```
+
+This snippet assumes the following structural types, copied into the consumer or maintained as a type-only development contract. No runtime import from an independently installed npm package is necessary. `src/footer-contribution-events.ts` and `src/footer-contributions.ts` are the host's canonical definitions.
+
+```ts
+type RegisterRequest = {
+  version: 1;
+  sessionId: string;
+  owner: string;
+  slot: "activity" | "summary";
+  result?:
+    | { ok: true; registration: {
+        publish(snapshot: unknown): { ok: true } | { ok: false; code: string };
+        dispose(): void;
+      } }
+    | { ok: false; code: string };
+};
+```
+
+No result means the host is absent/not ready. Registration errors include `invalid`, `wrong-session`, `occupied`, and `not-tui`. Publish errors include `invalid`, `stale`, and `disposed`.
+
+## Plan summary snapshot (`summary` slot)
+
+```ts
+{
+  revision: 0,
+  format: "icons", // or "plain"
+  plan: { id: "P12", accepted: 3, total: 7, inReview: 1, blocked: 1 }
+}
+```
+
+The plan ID follows row-key bounds. Counts/revision are nonnegative safe integers;
+accepted cannot exceed total; review and blocked counts cannot individually exceed
+remaining tasks. Counts are supplied by the tracker, never inferred from agent
+runs. Omit `plan` on a newer revision to clear the contribution without releasing
+ownership. Snapshot objects are cloned/frozen, and revision/disposal rules match
+the activity slot. Each slot has independent ownership and revision tracking.
+
+The label and filled segments use the semantic `accent` color (violet in
+minimal-dark); empty segments are muted. Up to 12 tasks use one slanted segment
+per task (`▰▰▰▱▱▱▱ 3/7`). Larger plans use ten proportional segments and retain the
+exact count; these represent aggregate progress, not individual task states.
+Plain mode uses `###....`. The strip drops before counts/attention on narrow
+terminals. Zero total displays `No tasks yet`. No animation or task persistence
+is introduced by this display slot.
+
+## Activity snapshot schema (`activity` slot)
+
+- `revision`: nonnegative safe integer, strictly increasing for each successful publish on one registration. Start at zero again after a new registration.
+- `motion`: `spinner` or `static`.
+- `format`: `icons` or `plain` (explicit textual state labels).
+- `omitted`: nonnegative safe integer; extra underlying records not supplied in this snapshot.
+- `rows`: at most 64 records; an empty array clears visible activity without releasing ownership.
+
+Each row:
+- `key`: unique 1–128 character identity, ASCII letters/numbers plus `. _ : @ + -`.
+- `agent`: nonempty label after sanitization, at most 96 input characters.
+- `state`: `queued`, `running`, `waiting`, `paused`, `stopping`, `completed`, `failed`, `stopped`, or `unknown`.
+- `text`: at most 256 input characters; keep it short, safe, and evidence-grounded.
+- Optional `parentKey`: references a key in the same snapshot. Missing references, self-parenting, and cycles are rejected.
+- Optional `metrics`: `{ elapsedMs?: number, tokens?: number }`. Both values must be nonnegative safe integers. An absent object preserves the original compact row; an empty object displays unknown values (`—`, or `-` in plain mode), never invented zeros.
+- Optional `task`: `{ planId: string, id: string, status: "todo" | "in_progress" | "blocked" | "in_review" | "done" | "cancelled" }`. Both IDs use the same bounds as row keys. The link is display context, not permission to read/write a plan.
+
+Metrics are right-aligned only if the full activity text still fits with at least two columns of separation. Drop tokens first, then time, before truncating activity. Elapsed time is supplied by the producer: compute from the run start while active, freeze at the run's end, and do not advance completed/unknown runs by inference. `tokens` means this child's own cumulative reported input + output tokens, excluding separately summed descendants. It is not context-window occupancy; omit unavailable data rather than guessing. The host does not calculate elapsed time from wall-clock time.
+
+Task IDs appear beside activity. In-progress tasks need no extra badge; blocked/review/accepted/cancelled tasks get a distinct badge, and plain mode retains textual status. A completed agent with an `in_review` task shows a green run check plus an accent review diamond. This optional data does not create a tracker or automatically accept a task.
+
+Owner uses the same character/length rules as row keys. Display text has ANSI/OSC, C0/C1, and bidi controls removed, with whitespace collapsed. The host clones and freezes validated snapshots. Invalid/stale publishes preserve the previous valid snapshot. Consumers must handle publish failure and send an explicit unknown/error observation when appropriate; an absent update does not prove a run ended.
+
+## Presentation and responsibility boundaries
+
+The host renders the first four supplied rows and one overflow line, without reordering them. Consumer owns stable ordering, priority, retention, dismissal and source reconciliation. Nesting is indented at most two levels. Terminal-width helpers enforce visible-column limits.
+
+Running uses pi-minimal's yellow `◐`/`◓` frames every 400ms. Completed uses green `✓`; failed uses red `✗`. Attention/stopping is yellow `!`; stopping includes an explicit prefix. Other shapes remain distinct in monochrome. Plain mode retains state words and does not animate. `static` also disables animation. Consumers should choose static/plain according to user accessibility preferences; this terminal contract does not pretend to detect browser reduced-motion settings.
+
+Only visible running rows animate; animation performs no provider queries, model calls, or filesystem reads. Host semantic theme colors are resolved each render. A completed run means only that run completed; it must not be presented as accepted task work without separate evidence.
+
+The host does not validate execution truth. It validates display shape and lifecycle ownership. It does not publish or hide pi-subagents widgets, mutate any other extension's settings, store run history, or expose stop/steer actions.
+
+## Lifecycle and rollback
+
+Footer component reinstalls preserve the session registry, while disposing old redraw/branch listeners and animation timers. Session shutdown/replacement invalidates registration handles even if the next session reuses the same ID. A stale disposer cannot clear a newer owner. Dispose is idempotent.
+
+Consumers dispose their handle and event subscriptions on shutdown, and register again in the new runtime. Use strictly increasing revisions to prevent late responses overwriting fresh data; request/session correlation remains the consumer's responsibility.
+
+Disable the consumer to remove activity rows. No process is stopped and no task state is changed. The host contribution API is inert without a consumer. Test a new consumer in an isolated pi profile before changing live configuration.
+
+This is a trusted extension contract, not a sandbox against malicious code already loaded into the process.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-minimal",
-  "version": "0.2.2",
+  "version": "0.2.3",
   "license": "MIT",
   "type": "module",
   "private": false,