pi-minimal 0.4.0 → 0.5.0

package/dist/tracker.js

@@ -1,5 +1,5 @@
 const PHASES = ["brainstorm", "plan", "implement", "verify", "ship"];
-function readSnapshot(ctx) {
+export function readGauntletProjection(ctx) {
     let phases;
     let tasks;
     for (const entry of ctx.sessionManager.getBranch()) {
@@ -21,7 +21,7 @@ function phaseActive(phases) {
     return PHASES.some((p) => phases[p]?.status && phases[p].status !== "pending");
 }
 export function formatTrackerLines(ctx, theme) {
-    const { phases, tasks } = readSnapshot(ctx);
+    const { phases, tasks } = readGauntletProjection(ctx);
     const lines = [];
     if (phases && phaseActive(phases)) {
         const parts = PHASES.map((p) => {

package/dist/working-status.js

@@ -184,8 +184,9 @@ export function installWorkingStatus(pi) {
         stop();
     });
     pi.on("session_shutdown", () => {
-        ctx = undefined;
+        // Clear the message while ctx is still known; dropping ctx first left it on screen.
         stop();
+        ctx = undefined;
     });
     return stop;
 }

package/doc/archive/README.md

@@ -0,0 +1,3 @@
+# Archive
+
+The spec and plan here describe the 0.1 package (September 2026) and are superseded by [README.md](../../README.md) and [CONTEXT.md](../../CONTEXT.md).

package/doc/footer-contributions.md

@@ -4,14 +4,14 @@ Pi-minimal remains the single footer owner. A trusted companion extension can pu
 
 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.
+Two independent slots are supported: `activity` and `plan`, with one owner per slot. (`summary` is the legacy wire name of the plan slot and remains accepted.) A rendered plan line replaces the legacy pi-gauntlet projection, avoiding duplicate plan bars; a plan snapshot that omits `plan`, or clearing the slot, lets the legacy projection show again. 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:ready` | host → consumers | `{ version: 1, sessionId, slots: ["activity", "plan", "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.
@@ -51,7 +51,7 @@ type RegisterRequest = {
   version: 1;
   sessionId: string;
   owner: string;
-  slot: "activity" | "summary";
+  slot: "activity" | "plan" | "summary"; // "summary" is the legacy alias of "plan"
   result?:
     | { ok: true; registration: {
         publish(snapshot: unknown): { ok: true } | { ok: false; code: string };
@@ -63,7 +63,7 @@ type RegisterRequest = {
 
 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)
+## Plan snapshot (`plan` slot; legacy name `summary`)
 
 ```ts
 {
@@ -74,8 +74,8 @@ No result means the host is absent/not ready. Registration errors include `inval
 ```
 
 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
+accepted cannot exceed total; `inReview` and `blocked` are each bounded by
+`total - accepted`, but their sum is not checked (a task may be both). 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.
@@ -109,7 +109,7 @@ Metrics are right-aligned only if the full activity text still fits with at leas
 
 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.
+Owner uses the same character/length rules as row keys. Display text has ANSI/OSC sequences stripped; remaining C0/C1 and bidi control characters are replaced with spaces, then whitespace is collapsed and trimmed. 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
 

package/package.json

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

package/release-notes.md

@@ -1,23 +1,57 @@
+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
 
-- `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.
+- `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.
 
 ## What's Changed
-* feat: editDiff setting — show edit diffs always, never, or behind ctrl+o (0.4.0) by @raviy06 in https://github.com/raviy06/pi-minimal/pull/18
+* refactor: per-session lifecycle, no chrome steal interval, hideGauntletWidgets opt-in by @raviy06 in https://github.com/raviy06/pi-minimal/pull/19
+* refactor(tools): one row lifecycle + strategies; write content on expand; small diffs inline by @raviy06 in https://github.com/raviy06/pi-minimal/pull/20
+* docs: CONTEXT.md glossary, clearer internal names, 'plan' slot alias (0.5.0) by @raviy06 in https://github.com/raviy06/pi-minimal/pull/21
 
 
-**Full Changelog**: https://github.com/raviy06/pi-minimal/compare/v0.3.1...v0.4.0
+**Full Changelog**: https://github.com/raviy06/pi-minimal/compare/v0.4.0...v0.5.0
 
 ---
 **Install / upgrade**
 ```bash
-pi install npm:pi-minimal@0.4.0   # or: pi update --extensions
+pi install npm:pi-minimal@0.5.0   # or: pi update --extensions
 ```

package/src/config.ts

@@ -12,7 +12,8 @@ export type PiMinimalConfig = {
 }
 
 const DEFAULTS: PiMinimalConfig = {
-	hideGauntletWidgets: true,
+	// Hiding another extension's widgets is opt-in.
+	hideGauntletWidgets: false,
 	editDiff: "expanded",
 }
 

package/src/edit-diff.ts

@@ -0,0 +1,73 @@
+import type { Theme } from "@earendil-works/pi-coding-agent"
+import { diffWords } from "diff"
+import type { ToolResultLike } from "./tool-rows.js"
+
+/** The edit tool's `details.diff`, when present and non-empty. */
+export function editDiffText(result: ToolResultLike | undefined): string | undefined {
+  const details = result?.details as { diff?: unknown } | undefined
+  return typeof details?.diff === "string" && details.diff.trim() ? details.diff : undefined
+}
+
+type DiffLine = { prefix: "+" | "-" | " "; lineNum: string; content: string }
+
+/** pi's edit diff lines: "+123 content", "-123 content", " 123 context"; anything else (e.g. "...") is a separator. */
+function parseDiffLine(line: string): DiffLine | undefined {
+  const match = /^([+\- ])(\s*\d*) (.*)$/.exec(line)
+  if (!match) return undefined
+  return { prefix: match[1] as DiffLine["prefix"], 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: string, added: string, theme: Theme): { removed: string; added: string } {
+  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: string[], theme: Theme): string[] {
+  const out: string[] = []
+  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: DiffLine[] = []
+    const added: DiffLine[] = []
+    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/src/footer-contribution-events.ts

@@ -5,8 +5,11 @@ export const FOOTER_EVENTS = {
   ready: "pi-minimal:footer:v1:ready",
   unavailable: "pi-minimal:footer:v1:unavailable",
 } as const
+/** Slot names on the wire. `summary` is the legacy name of the plan slot and stays accepted. */
+export const FOOTER_SLOTS = ["activity", "plan", "summary"] as const
+export type FooterSlot = typeof FOOTER_SLOTS[number]
 export type RegisterRequest = {
-  version: 1; sessionId: string; owner: string; slot: "activity" | "summary"
+  version: 1; sessionId: string; owner: string; slot: FooterSlot
   result?: RegistrationResult | { ok: false; code: "not-tui" }
 }
 type Events = {
@@ -22,11 +25,11 @@ export function bindFooterContributionEvents(events: Events, registry: FooterCon
     const request = value as Partial<RegisterRequest>
     // 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" }
+    if (request.version !== 1 || !FOOTER_SLOTS.includes(request.slot as FooterSlot)) 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)
+    else 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"] })
+  if (mode === "tui") events.emit(FOOTER_EVENTS.ready, { version: 1, sessionId, slots: [...FOOTER_SLOTS] })
   let disposed = false
   return () => {
     if (disposed) return

package/src/footer-contributions.ts

@@ -77,7 +77,8 @@ function normalizeSnapshot(input: unknown): ActivitySnapshot | undefined {
 
 function createFooterSlot<T extends { revision: number }>(normalize: (input: unknown) => T | undefined, initialSessionId: string | null) {
   let sessionId = initialSessionId
-  let owner: symbol | undefined
+  // The registrant's `owner` string is a display identity; this symbol is the actual authority to publish.
+  let ownerToken: symbol | undefined
   let snapshot: T | undefined
   const observers = new Set<() => void>()
   const notify = () => {
@@ -89,17 +90,17 @@ function createFooterSlot<T extends { revision: number }>(normalize: (input: unk
     read: () => snapshot,
     subscribe(observer: () => void) { observers.add(observer); return () => { observers.delete(observer) } },
     reset(nextSessionId: string | null) {
-      sessionId = nextSessionId; owner = undefined; snapshot = undefined; notify()
+      sessionId = nextSessionId; ownerToken = undefined; snapshot = undefined; notify()
     },
     register(input: unknown): RegistrationResult {
       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" }
+      if (ownerToken) return { ok: false, code: "occupied" }
       const token = Symbol(input.owner)
-      owner = token
+      ownerToken = token
       return { ok: true, registration: {
         publish(input: unknown) {
-          if (owner !== token) return { ok: false, code: "disposed" }
+          if (ownerToken !== 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" }
@@ -107,8 +108,8 @@ function createFooterSlot<T extends { revision: number }>(normalize: (input: unk
           return { ok: true }
         },
         dispose() {
-          if (owner !== token) return
-          owner = undefined; snapshot = undefined; notify()
+          if (ownerToken !== token) return
+          ownerToken = undefined; snapshot = undefined; notify()
         },
       } }
     },
@@ -116,17 +117,18 @@ function createFooterSlot<T extends { revision: number }>(normalize: (input: unk
 }
 export function createFooterContributions(initialSessionId: string | null = 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: () => void) {
-      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: string | null) { activity.reset(sessionId); summary.reset(sessionId) },
+    reset(sessionId: string | null) { activity.reset(sessionId); plan.reset(sessionId) },
   }
 }
 export type FooterContributions = ReturnType<typeof createFooterContributions>

package/src/git-state.ts

@@ -30,30 +30,45 @@ export function createGitState(pi: ExtensionAPI, cwd: () => string, minIntervalM
   let state: GitState | undefined
   let lastRun = 0
   let inFlight: Promise<void> | undefined
+  let disposed = false
   const listeners = new Set<() => void>()
 
+  const notify = () => {
+    for (const listener of listeners) {
+      try {
+        listener()
+      } catch {
+        // One listener's failure must not starve the others.
+      }
+    }
+  }
+
   const refresh = (force = false): Promise<void> => {
+    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: GitState | undefined
       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
   }
@@ -65,6 +80,10 @@ export function createGitState(pi: ExtensionAPI, cwd: () => string, minIntervalM
       listeners.add(listener)
       return () => listeners.delete(listener)
     },
+    dispose() {
+      disposed = true
+      listeners.clear()
+    },
   }
 }