pi-minimal 0.3.1 → 0.5.0

package/CHANGELOG.md

@@ -10,6 +10,66 @@ Releases are cut automatically: when the `version` in `package.json` changes on
 
 ## [Unreleased]
 
+## [0.5.0] - 2026-10-27
+
+Session lifecycle, one tool-row lifecycle, and a domain glossary. `hideGauntletWidgets`
+is now opt-in and the 200 ms chrome steal interval is gone.
+
+### Added
+
+- `write` rows show the written content (first 400 lines) when expanded with `ctrl+o`.
+- With `editDiff: "expanded"` (the default), diffs of up to 8 lines are shown inline;
+  hiding them saved nothing and cost a keypress. Longer diffs still wait for `ctrl+o`.
+- `CONTEXT.md`: a glossary of the domain (chrome, reclaim, slots, owner token, the snapshot
+  kinds, plan vs the legacy pi-gauntlet projection, activity rows, hints, turn rule, working
+  status). The 0.1 spec and plan moved to `doc/archive/`.
+- The plan slot can be addressed as `slot: "plan"`; `summary` stays accepted as its legacy
+  name and the ready event now lists `["activity", "plan", "summary"]`.
+
+### Changed
+
+- `hideGauntletWidgets` now defaults to `false`. Hiding another extension's widgets is
+  opt-in; set it to `true` to keep the previous behaviour.
+- Chrome is re-asserted only on events (session start and its two settle ticks, turn
+  end, tool end). The 200 ms interval that cleared pi-gauntlet's widgets five times a
+  second is gone; it never reinstalled the header or footer anyway.
+- All session-scoped state (config, cwd, the footer contribution registry, the git and
+  Herdr pollers, the chrome) now lives on one `Session` object created at session start
+  and disposed at shutdown or when the next session starts. Late async results from a
+  disposed session are dropped instead of drawing into the new one.
+- The compact, generic and codemode tool rows are now three small strategies over one
+  row lifecycle (`createRowRenderers`): running state, live spinner, status colours,
+  the error line and expansion are implemented once. Edit-diff colouring moved to
+  `src/edit-diff.ts`. No visible change beyond the two items above.
+- Internal renames for clarity: `TrackerSnapshot` → `GauntletProjection`,
+  `readSnapshot` → `readGauntletProjection`, the tracker's `TaskStatus` →
+  `GauntletTaskStatus`, and the slot's authority symbol is `ownerToken`. No wire change.
+- `doc/footer-contributions.md` now states precisely when the legacy projection is replaced
+  (only while a plan line renders), how control characters are sanitised (VT stripped,
+  C0/C1/bidi replaced with spaces), and that `inReview`/`blocked` are bounded individually.
+
+### Fixed
+
+- The working message is cleared on session shutdown; it used to drop the context
+  before clearing and leave the last status on screen.
+- Git state reads the working directory once per refresh, so branch and dirty count
+  always describe the same tree, and one throwing change listener no longer blocks
+  the others.
+
+## [0.4.0] - 2026-10-27
+
+### Added
+
+- `editDiff` setting in `pi-minimal.json`: controls whether an `edit` row shows the
+  change itself. `"expanded"` (default) shows the unified diff in the `│`-ruled
+  block when the row is expanded with `ctrl+o`, where the bare "Successfully
+  replaced" text used to be. `"always"` shows it inline as soon as the edit lands,
+  capped at 40 lines with `… N more lines (ctrl+o)` for the rest. `"never"` keeps
+  the stats-only row. Lines use the theme's `toolDiffAdded` / `toolDiffRemoved` /
+  `toolDiffContext` colours and keep pi's line-number gutter; when one line
+  replaces one line, only the changed tokens are inverse-highlighted, as in pi's
+  own edit renderer. Failed edits and results without a diff are unchanged.
+
 ## [0.3.1] - 2026-10-25
 
 ### Added

package/CONTEXT.md

@@ -0,0 +1,83 @@
+# pi-minimal domain glossary
+
+The vocabulary used in code and docs, one entry per concept, with the file that defines it.
+When a word below has a narrower meaning than in everyday use, the narrower meaning wins.
+
+## Surfaces pi-minimal owns
+
+- **Chrome** — the three host slots pi-minimal draws into: the header (`src/header.ts`, intentionally
+  empty), the footer (`src/footer.ts`) and the status line (`src/cwd.ts`, a widget above the editor;
+  it is *not* pi's `setStatus`). pi has no owner concept for these, so chrome is re-asserted on
+  events; see *reclaim*.
+- **Reclaim** — re-installing chrome after an event that may have let another extension draw over
+  it (`src/reclaim.ts`). A *reclaim reason* (`session_start`, `session_settle`, `turn_end`,
+  `tool_execution_end`) maps to a policy: whether to reset the editor and whether to reinstall chrome.
+- **Status line** — `model · thinking · context meter · cwd · ⎇ branch ±dirty · Herdr siblings`
+  (`src/cwd.ts`). *Siblings* are other Herdr panes in the same workspace (`src/herdr.ts`).
+- **Hints** — the keybinding labels in the footer (`send · thinking · expand tools`, plus
+  `/compact` from 70 % context), shown only when idle with an empty editor (`src/footer.ts`).
+  Not task hints and not the change hints other extensions emit.
+- **Tool row** — one line per tool call: `glyph verb item … outcome` (`src/tools.ts`,
+  `src/tool-rows.ts`). *Compact* rows are the built-in tools, *generic* rows are tools with no
+  renderer of their own (most MCP tools), the *codemode* row has one child row per nested call.
+  A row's **outcome** is its right-aligned summary (`34 lines · 1.0s`, `+3 −1`, `exit 1`).
+- **Turn rule** — the dim `── 15:51 · 12s · 4 tools ──` separator appended after each agent run
+  (`src/turn-rule.ts`). Stored as a `pi-minimal.turn` custom session entry, never sent to the model.
+  Its data is a *TurnSummary*, unrelated to the plan slot.
+- **Working status** — the transient `Thinking · 3s` / `Running ls · 2 tools · 5s` message while
+  an agent runs (`src/working-status.ts`), driven by agent/tool/message events and cleared when
+  the agent settles. Its state object is a *WorkingSnapshot*.
+- **Thinking gutter** — the `┊` column in front of assistant thinking text (`src/transcript.ts`).
+- **Code box** — the faint frame around fenced code blocks (`src/code-box.ts`, a pi-tui
+  `Markdown.prototype.renderToken` patch).
+
+## Footer contributions (the extension point)
+
+- **Contribution** — data another extension publishes for pi-minimal to render in the footer,
+  through the in-process `pi-minimal:footer:v1:*` events (`src/footer-contribution-events.ts`).
+  pi-minimal keeps ownership of the footer; contributors never draw.
+- **Slot** — one of two independent places a contribution can go: `activity` (agent rows) and
+  `plan` (one plan bar). `summary` is the legacy wire name of the plan slot and stays accepted.
+  One owner per slot per session (`src/footer-contributions.ts`).
+- **Owner** vs **owner token** — `owner` is the registrant's display identity (a validated
+  string). The *owner token* is the `Symbol` handed back on registration; it alone authorises
+  `publish`/`dispose`. A slot is *occupied* while a token is live.
+- **Snapshot** — a complete replacement value published to a slot. Two kinds:
+  **ActivitySnapshot** (`revision`, `rows`, `omitted`, `motion`, `format`) and **PlanSnapshot**
+  (`revision`, `format`, optional `plan`). Publishing never patches; it replaces.
+- **Revision** — a per-slot monotonic counter on each snapshot. A publish whose revision is not
+  greater than the current one is *stale* and ignored.
+- **Activity row** — one keyed line in the activity slot: `agent`, `state`, `text`, optional
+  `parentKey` (two levels of nesting), `metrics` (`elapsedMs`, `tokens`), `task`
+  (`planId`, `id`, `status`). Rendered in producer order, at most four plus `+ N more`
+  (`src/footer-activity.ts`, `src/footer-activity-details.ts`).
+- **Activity state** — `queued | running | waiting | paused | stopping | completed | failed |
+  stopped | unknown`. Display-only; pi-minimal infers nothing about execution from it.
+- **Plan** — the plan slot's payload: `id`, `accepted`, `total`, `inReview`, `blocked`. Counts
+  are supplied by the contributor, never inferred from agent runs (`src/footer-plan.ts`).
+- **Task status (contribution)** — `todo | in_progress | blocked | in_review | done | cancelled`
+  on an activity row's `task`. Distinct from the gauntlet task status below.
+
+## Legacy pi-gauntlet projection
+
+- **Gauntlet projection** — what pi-gauntlet last reported on the session branch, read from its
+  `phase_tracker` / `plan_tracker` tool-result `details` (`src/tracker.ts`,
+  `readGauntletProjection`). A projection of another extension's history, not a contribution:
+  unversioned and only as stable as those tools' result shapes. A rendered plan line from the
+  plan slot replaces it in the footer.
+- **Phase** — `brainstorm → plan → implement → verify → ship`, each
+  `pending | in_progress | complete | skipped`.
+- **Gauntlet task status** — `pending | in_progress | complete | failed` (`GauntletTaskStatus`).
+  Not interchangeable with the contribution task status.
+- **hideGauntletWidgets** — opt-in setting to clear pi-gauntlet's own widgets on each reclaim,
+  since the footer already shows that data (`src/config.ts`).
+
+## Process vs session
+
+- **Load-time hooks** — installed once per extension instance: tool renderers, the markdown
+  transformer, the code-box patch, working status and the turn rule (`src/index.ts`).
+- **Session** — everything scoped to one pi session: config, cwd, the contribution registry,
+  git and Herdr pollers, settle timers and chrome (`src/session.ts`, when present). Created on
+  `session_start`, disposed on `session_shutdown` or when the next session starts.
+- **Chrome margin** — pi's `outputPad`, mirrored on `globalThis` so module copies reloaded by
+  `/reload` agree (`src/chrome.ts`).

package/README.md

@@ -11,7 +11,7 @@ No other Pi extension is required. Pi supplies the peer packages used by this ex
 
 Optional integrations:
 
-- `pi-gauntlet`: supplies the phase and task data shown in the footer. Its widgets are hidden by default.
+- `pi-gauntlet`: supplies the phase and task data shown in the footer. Set `hideGauntletWidgets: true` to also hide its own widgets, since the footer already shows that data.
 - Herdr: sibling status appears only when Pi is running inside Herdr.
 
 ## Installation
@@ -49,10 +49,13 @@ The package loads JSON in this order:
 
 Project values override global values. A missing file, omitted key, or invalid value does not override the lower-precedence value.
 
-The only supported key is `hideGauntletWidgets`. It defaults to `true`.
+Supported keys:
+
+- `hideGauntletWidgets` (boolean, default `false`) – when `true`, pi-minimal clears pi-gauntlet's `phase_tracker` and `plan_tracker` widgets each time it re-asserts its chrome (session start, turn end, tool end).
+- `editDiff` (`"always"` | `"never"` | `"expanded"`, default `"expanded"`) – when an `edit` row shows its diff. `"expanded"` shows diffs of up to 8 lines inline and puts longer ones behind `ctrl+o`; `"always"` shows every diff inline as the edit lands (first 40 lines, the rest behind `ctrl+o`); `"never"` keeps the `+3 −1` stats only. `write` rows show the written content behind `ctrl+o`.
 
 ```json
-{ "hideGauntletWidgets": true }
+{ "hideGauntletWidgets": true, "editDiff": "always" }
 ```
 
 ## Optional footer activity API

package/dist/config.js

@@ -1,8 +1,11 @@
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
 import { CONFIG_DIR_NAME } from "@earendil-works/pi-coding-agent";
+export const EDIT_DIFF_MODES = ["always", "never", "expanded"];
 const DEFAULTS = {
-    hideGauntletWidgets: true,
+    // Hiding another extension's widgets is opt-in.
+    hideGauntletWidgets: false,
+    editDiff: "expanded",
 };
 export function loadPiMinimalConfig(options) {
     const config = { ...DEFAULTS };
@@ -32,14 +35,23 @@ function applyLayer(config, path) {
         console.error(`pi-minimal: expected an object in ${path}`);
         return;
     }
+    // Each key is validated on its own so one bad value does not discard the rest of the layer.
     const record = parsed;
-    if (!Object.hasOwn(record, "hideGauntletWidgets")) {
-        return;
-    }
-    const value = record.hideGauntletWidgets;
-    if (typeof value !== "boolean") {
-        console.error(`pi-minimal: hideGauntletWidgets must be a boolean in ${path}`);
-        return;
+    if (Object.hasOwn(record, "hideGauntletWidgets")) {
+        const value = record.hideGauntletWidgets;
+        if (typeof value === "boolean")
+            config.hideGauntletWidgets = value;
+        else
+            console.error(`pi-minimal: hideGauntletWidgets must be a boolean in ${path}`);
+    }
+    if (Object.hasOwn(record, "editDiff")) {
+        const value = record.editDiff;
+        if (isEditDiffMode(value))
+            config.editDiff = value;
+        else
+            console.error(`pi-minimal: editDiff must be one of ${EDIT_DIFF_MODES.map((mode) => `"${mode}"`).join(", ")} in ${path}`);
     }
-    config.hideGauntletWidgets = value;
+}
+function isEditDiffMode(value) {
+    return typeof value === "string" && EDIT_DIFF_MODES.includes(value);
 }

package/dist/edit-diff.js

@@ -0,0 +1,74 @@
+import { diffWords } from "diff";
+/** The edit tool's `details.diff`, when present and non-empty. */
+export function editDiffText(result) {
+    const details = result?.details;
+    return typeof details?.diff === "string" && details.diff.trim() ? details.diff : undefined;
+}
+/** pi's edit diff lines: "+123 content", "-123 content", " 123 context"; anything else (e.g. "...") is a separator. */
+function parseDiffLine(line) {
+    const match = /^([+\- ])(\s*\d*) (.*)$/.exec(line);
+    if (!match)
+        return undefined;
+    return { prefix: match[1], lineNum: match[2], content: match[3].replace(/\t/g, "   ") };
+}
+/** Word-level diff of a 1:1 replacement; changed tokens are inverted, leading indentation is left alone, as in pi. */
+function highlightPair(removed, added, theme) {
+    let out = { removed: "", added: "" };
+    let firstRemoved = true;
+    let firstAdded = true;
+    for (const part of diffWords(removed, added)) {
+        if (part.removed || part.added) {
+            const key = part.removed ? "removed" : "added";
+            let value = part.value;
+            if (part.removed ? firstRemoved : firstAdded) {
+                const ws = /^(\s*)/.exec(value)?.[1] ?? "";
+                value = value.slice(ws.length);
+                out = { ...out, [key]: out[key] + ws };
+                if (part.removed)
+                    firstRemoved = false;
+                else
+                    firstAdded = false;
+            }
+            if (value)
+                out = { ...out, [key]: out[key] + theme.inverse(value) };
+        }
+        else {
+            out = { removed: out.removed + part.value, added: out.added + part.value };
+        }
+    }
+    return out;
+}
+/** Colours pi's edit diff like pi does: theme diff colours per line, inverse on changed tokens of single-line replacements. */
+export function colorDiffLines(lines, theme) {
+    const out = [];
+    for (let i = 0; i < lines.length;) {
+        const parsed = parseDiffLine(lines[i]);
+        if (!parsed) {
+            out.push(theme.fg("toolDiffContext", lines[i]));
+            i++;
+            continue;
+        }
+        if (parsed.prefix === " ") {
+            out.push(theme.fg("toolDiffContext", ` ${parsed.lineNum} ${parsed.content}`));
+            i++;
+            continue;
+        }
+        const removed = [];
+        const added = [];
+        for (let p = parseDiffLine(lines[i] ?? ""); p?.prefix === "-"; p = parseDiffLine(lines[++i] ?? ""))
+            removed.push(p);
+        for (let p = parseDiffLine(lines[i] ?? ""); p?.prefix === "+"; p = parseDiffLine(lines[++i] ?? ""))
+            added.push(p);
+        if (removed.length === 1 && added.length === 1) {
+            const pair = highlightPair(removed[0].content, added[0].content, theme);
+            out.push(theme.fg("toolDiffRemoved", `-${removed[0].lineNum} ${pair.removed}`));
+            out.push(theme.fg("toolDiffAdded", `+${added[0].lineNum} ${pair.added}`));
+            continue;
+        }
+        for (const line of removed)
+            out.push(theme.fg("toolDiffRemoved", `-${line.lineNum} ${line.content}`));
+        for (const line of added)
+            out.push(theme.fg("toolDiffAdded", `+${line.lineNum} ${line.content}`));
+    }
+    return out;
+}

package/dist/footer-contribution-events.js

@@ -3,6 +3,8 @@ export const FOOTER_EVENTS = {
     ready: "pi-minimal:footer:v1:ready",
     unavailable: "pi-minimal:footer:v1:unavailable",
 };
+/** Slot names on the wire. `summary` is the legacy name of the plan slot and stays accepted. */
+export const FOOTER_SLOTS = ["activity", "plan", "summary"];
 /** 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);
@@ -13,15 +15,15 @@ export function bindFooterContributionEvents(events, registry, sessionId, mode)
         // 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"))
+        if (request.version !== 1 || !FOOTER_SLOTS.includes(request.slot))
             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);
+            request.result = request.slot === "activity" ? registry.register(request) : registry.registerPlan(request);
     });
     if (mode === "tui")
-        events.emit(FOOTER_EVENTS.ready, { version: 1, sessionId, slots: ["activity", "summary"] });
+        events.emit(FOOTER_EVENTS.ready, { version: 1, sessionId, slots: [...FOOTER_SLOTS] });
     let disposed = false;
     return () => {
         if (disposed)

package/dist/footer-contributions.js

@@ -60,7 +60,8 @@ function normalizeSnapshot(input) {
 }
 function createFooterSlot(normalize, initialSessionId) {
     let sessionId = initialSessionId;
-    let owner;
+    // The registrant's `owner` string is a display identity; this symbol is the actual authority to publish.
+    let ownerToken;
     let snapshot;
     const observers = new Set();
     const notify = () => {
@@ -76,7 +77,7 @@ function createFooterSlot(normalize, initialSessionId) {
         subscribe(observer) { observers.add(observer); return () => { observers.delete(observer); }; },
         reset(nextSessionId) {
             sessionId = nextSessionId;
-            owner = undefined;
+            ownerToken = undefined;
             snapshot = undefined;
             notify();
         },
@@ -85,13 +86,13 @@ function createFooterSlot(normalize, initialSessionId) {
                 return { ok: false, code: "invalid" };
             if (sessionId === null || input.sessionId !== sessionId)
                 return { ok: false, code: "wrong-session" };
-            if (owner)
+            if (ownerToken)
                 return { ok: false, code: "occupied" };
             const token = Symbol(input.owner);
-            owner = token;
+            ownerToken = token;
             return { ok: true, registration: {
                     publish(input) {
-                        if (owner !== token)
+                        if (ownerToken !== token)
                             return { ok: false, code: "disposed" };
                         const next = normalize(input);
                         if (!next)
@@ -103,9 +104,9 @@ function createFooterSlot(normalize, initialSessionId) {
                         return { ok: true };
                     },
                     dispose() {
-                        if (owner !== token)
+                        if (ownerToken !== token)
                             return;
-                        owner = undefined;
+                        ownerToken = undefined;
                         snapshot = undefined;
                         notify();
                     },
@@ -115,16 +116,17 @@ function createFooterSlot(normalize, initialSessionId) {
 }
 export function createFooterContributions(initialSessionId = null) {
     const activity = createFooterSlot(normalizeSnapshot, initialSessionId);
-    const summary = createFooterSlot(normalizePlanSnapshot, initialSessionId);
+    // The plan slot; "summary" is its legacy wire name.
+    const plan = createFooterSlot(normalizePlanSnapshot, initialSessionId);
     return {
         read: activity.read,
-        readPlan: summary.read,
+        readPlan: plan.read,
         register: activity.register,
-        registerPlan: summary.register,
+        registerPlan: plan.register,
         subscribe(observer) {
-            const offActivity = activity.subscribe(observer), offSummary = summary.subscribe(observer);
-            return () => { offActivity(); offSummary(); };
+            const offActivity = activity.subscribe(observer), offPlan = plan.subscribe(observer);
+            return () => { offActivity(); offPlan(); };
         },
-        reset(sessionId) { activity.reset(sessionId); summary.reset(sessionId); },
+        reset(sessionId) { activity.reset(sessionId); plan.reset(sessionId); },
     };
 }

package/dist/git-state.js

@@ -21,34 +21,50 @@ export function createGitState(pi, cwd, minIntervalMs = 5000) {
     let state;
     let lastRun = 0;
     let inFlight;
+    let disposed = false;
     const listeners = new Set();
+    const notify = () => {
+        for (const listener of listeners) {
+            try {
+                listener();
+            }
+            catch {
+                // One listener's failure must not starve the others.
+            }
+        }
+    };
     const refresh = (force = false) => {
+        if (disposed)
+            return Promise.resolve();
         const now = Date.now();
         if (inFlight)
             return inFlight;
         if (!force && now - lastRun < minIntervalMs)
             return Promise.resolve();
         lastRun = now;
+        // Read the directory once so both commands describe the same tree even if cwd changes mid-refresh.
+        const dir = cwd();
         inFlight = (async () => {
+            let next;
             try {
-                const branchRun = await pi.exec("git", ["rev-parse", "--abbrev-ref", "HEAD"], { cwd: cwd(), timeout: 2000 });
-                if (branchRun.code !== 0) {
-                    state = undefined;
-                    return;
+                const branchRun = await pi.exec("git", ["rev-parse", "--abbrev-ref", "HEAD"], { cwd: dir, timeout: 2000 });
+                if (branchRun.code === 0) {
+                    const branch = parseBranch(branchRun.stdout);
+                    const statusRun = await pi.exec("git", ["status", "--porcelain"], { cwd: dir, timeout: 3000 });
+                    next = { branch, dirty: statusRun.code === 0 ? parsePorcelain(statusRun.stdout) : undefined };
                 }
-                const branch = parseBranch(branchRun.stdout);
-                const statusRun = await pi.exec("git", ["status", "--porcelain"], { cwd: cwd(), timeout: 3000 });
-                const dirty = statusRun.code === 0 ? parsePorcelain(statusRun.stdout) : undefined;
-                state = { branch, dirty };
             }
             catch {
-                state = undefined;
+                next = undefined;
             }
             finally {
                 inFlight = undefined;
-                for (const listener of listeners)
-                    listener();
             }
+            // A result that lands after dispose belongs to a session that no longer exists.
+            if (disposed)
+                return;
+            state = next;
+            notify();
         })();
         return inFlight;
     };
@@ -59,5 +75,9 @@ export function createGitState(pi, cwd, minIntervalMs = 5000) {
             listeners.add(listener);
             return () => listeners.delete(listener);
         },
+        dispose() {
+            disposed = true;
+            listeners.clear();
+        },
     };
 }