pi-message-sidebar 1.5.0 → 2.0.0

package/CHANGELOG.md

@@ -1,5 +1,92 @@
 # Changelog
 
+## 2.0.0
+
+> The obsidian rail: a deep canvas, one raised goal card, ghost chrome, and a motion language that only moves when the session does.
+
+- **Palette and depth.** The rail is a truecolor ladder: a deep well (`#0c0d14`) as canvas, a raised panel step for the goal card, an accent-tinted selection, and two ghost tiers for chrome. 256-color and light-terminal variants throughout. The old flat 234/235/233 slab and the theme's raw selection color are gone.
+- **Ghost headers.** Section rules are gone. SESSION, FILES, MESSAGES and RUNTIME are quiet left-aligned labels with right-aligned metadata, each preceded by an air row; sections separate by whitespace and background steps.
+- **Goal card.** The hero block: breathing status dot (2.4s), budget share on the right, bold objective across up to three lines, and a `bdg`-labeled twelve-cell meter in eighths-of-a-cell resolution. A missing goal is one ghost row on the deep canvas.
+- **Message slots.** Ordinals are gone; their four cells buy summary text (32 cells per line). Selection is a two-row yellow bar plus a soft accent tint; pending summaries pulse; landed summaries sweep accent then glow-decay over the canvas; age fade keeps newest bright and old muted.
+- **Motion language.** Eased meters (context and budget glide toward their targets), a shimmer cell riding a meter while it eases, left-to-right reveal as a message arrives, a victory flash when a goal completes, and a sheen band crossing the flag while the rail is live. The tick runs only while something moves, plus the ambient goal breath; idle costs nothing.
+- **The Fornace flag.** The rail's crown row is the seven brand hues sampled from the production logo, painted solid edge to edge.
+- Pressure thresholds moved to 70/90 percent so ordinary sessions read accent, not alarm.
+
+## 1.11.0
+
+> Plain-text summaries and an honest copy key: what you copy from the rail is finally clean.
+
+- Stored summaries and fallback previews no longer contain ANSI resets: pi-tui's `truncateToWidth` wraps its ellipsis in `\x1b[0m` resets, and that helper was applied to plain text, so every clipped summary persisted and rendered with escape bytes (visible as garbage when copied, and resetting rail row colors mid-row). Both paths now strip ANSI after truncation; existing polluted summary caches self-heal on next session load.
+- The focused rail's `c` key now copies the selected prompt's full text, matching the `[c] copy` hint. Previously `c` always copied the session file path even while the messages panel was focused and its hint advertised message copy. The unfocused rail keeps `c` as copy-session-path.
+
+## 1.10.0
+
+> Embedded section headers, usage meters, and a tighter rail: every section now spends one row where it used to spend two.
+
+- Section headers embed their label in the rule itself (`── SESSION ───────── main`) with right-aligned metadata: branch for SESSION, status for GOAL, position for MESSAGES, thinking level for RUNTIME, count for FILES. The old label-row-plus-separator pairs are gone; the minimum rail shrinks from 17 to 14 rows and the message viewport grows by three.
+- Usage meters in the same language as the rules: `━━━━──────`. The goal budget row draws its meter with counts and elapsed time (compacting when crowded, drawing nothing for unlimited budgets), and the runtime context row meters context pressure with color thresholds: accent normally, warning at 60 percent, danger at 85. Goal states override: complete reads green, budget-limited or over-budget reads danger.
+- A missing goal is now a single quiet rule row (`── no goal · /goal <objective> ──`) instead of a three-row block.
+- Hint strips use bracketed keys: `[Ctrl+Shift+H] focus`, `[↑↓] select  [↵] open  [c] copy`, `[Esc] back  [↑↓] scroll`.
+- Budget allocation between sections is content-first: the session id row, then FILES rows, then goal breathing, then runtime breath, with everything else to the message viewport.
+
+## 1.9.0
+
+> Theme-harmonized rail: universal content colors, a three-step background ladder, git-style file badges, age fade, and pi-recap motion.
+
+- Colors now resolve from the active pi theme (accent, muted, dim, warning, diff and border tokens, `selectedBg` for the selection) with theme-agnostic universal grays for content text, the way pi-recap keeps recap bodies readable under any theme. The old hardcoded 256-color slabs are gone: backgrounds are a three-step ladder (base, raised for goal and detail, sunken for the hint strip) instead of contrasting blocks.
+- Fixed a real leak: bare `\x1b[0m` resets inside composed rows (from pi-tui's truncation ellipsis and segment joins) painted the terminal's default foreground mid-row. All truncation now happens on plain text before coloring, and a regression test asserts no row leaks the default foreground.
+- FILES rows carry the git letter convention shared by git, VS Code, and GitHub: M modified, A added, U untracked, D deleted, R renamed, colored through theme diff/warning tokens, fed by a throttled `git status --porcelain` provider that is symlink-safe, spans all repositories edited in the session (not just the session cwd), and stays silent outside repositories.
+- Empty goal state rests on the neutral base background instead of claiming the raised step; the raised ground is reserved for live objectives with active budgets.
+- Message streams shorter than the viewport bottom-anchor directly above the hint strip, letting spare space collect under the heading like a terminal chat stream rather than opening a dead gap above the hint.
+- Message summaries fade with age like pi-recap recaps: newest bright, recent normal, older muted, deterministic previews dimmer still.
+- Motion in the pi-recap spirit, ticking at 90 ms only while something moves: a truecolor pulsing dot (sine lerp, 256-color fallback) marks messages whose summary is still in flight, and a landing summary sweeps accent then bold accent over 360 ms before settling into its age color.
+- The message detail header reports the message size: `#N HH:MM` left, `1.4k chars · 12 lines` right.
+- Light terminals get an inverted background ladder and content grays via COLORFGBG, matching pi-recap's detection.
+- `PI_SIDEBAR_SUMMARY_MODEL` overrides the summary route; a gateway microbench (fornace-flash 739 ms TTFB vs 1.1-3.1 s for the alternates) keeps `fornace-flash` as the default.
+
+## 1.8.0
+
+> AI message summaries, a structured two-row message grid with hidden-count ellipsis rows, and an edited-files section.
+
+- Messages are now AI summaries: `SummaryService` asks `fornace-flash` for one plain sentence (at most 12 words, essential names preserved) per prompt, stores up to 58 cells so a summary fills two rail rows, and keeps the deterministic preview as the placeholder until the model answers. Previews render dimmed while no model summary exists. The cache lives in `sidebar-summaries` with `PI_SUMMARIES_DIR` as its override.
+- An unconfigured gateway now shows a setup hint (`AI summaries need FORNACE_LLM_API_KEY`) under the MESSAGES heading instead of staying fully silent; it never costs a message slot and never warns as a failure.
+- The message list is a structured grid instead of a text blob: every message renders as a two-row slot with a selection marker, right-aligned ordinal, timestamp, and the summary wrapped across two 29-cell lines.
+- When the history outgrows the viewport, faint ellipsis rows count the hidden messages (`… 11 earlier`, `… 2 later`); a message pair outranks the second ellipsis row when both cannot fit.
+- New FILES section summarizes the session's write footprint between SESSION and MESSAGES: the heading counts distinct files, the rows list the most recently written ones (latest first, front-trimmed paths, repeat counts) from `edit`/`write`/`fast_write` tool calls. The section yields its space to the goal block and the message viewport on short terminals and does not render at all without edits.
+- Message rendering moved into `src/messages.ts` (`MessagePanel`), which also owns the detail view; `sidebar-component.ts` returns below 400 lines, restoring the README claim.
+- The message section's mandatory budget grows to four rows (heading, one two-row message, hint), so a viable rail always shows a full message slot.
+
+## 1.7.0
+
+> Goal-first rail with model-written message titles. Replaces the bottom status dock with stacked sections.
+
+- Message rows now show a short generated title instead of the raw prompt: `TitleService` calls `fornace-flash` through the Fornace gateway, caches per session on disk, and falls back to a deterministic first-words title when the gateway is unavailable or unconfigured. Titles never generate on the render path. Title generation that fails while the gateway is configured reports once per session instead of silently degrading, and a replaced service is disposed on session restart.
+- Each message now actually receives its one refinement pass on a later turn; the previous cadence only ever inspected the newest message, so refinement never fired in normal use.
+- Rail is now GOAL / SESSION / MESSAGES / runtime, top to bottom, replacing the bottom status dock.
+- Fixed the crash on any populated render: the extension never passed `getTitle`, so `SidebarComponent.renderMessageRow` threw `TypeError: this.options.getTitle is not a function` and took the TUI down.
+- Rail rows paint all 42 columns; they previously painted 40 and left a two-column seam down the rail.
+- Right-aligned rail elements (elapsed time, position counter) sit flush against the rail edge; they were three cells short after the geometry fix. Detail text uses the full 39-column content width.
+- Row allocation reserves every section's mandatory rows before distributing optional ones, so the message row, the `/goal` guidance line, and the branch · session row can no longer be silently sliced away. Below the mandatory budget the rail shows a bounded resize notice instead of clipped sections.
+- Sections fill their exact row budgets and render with no masking slices: a message vanishing under an open detail (compaction, branch switch), an empty history, and a one-row resize notice all render complete sections instead of crashing the TUI.
+- The detail scroll indicator reports a truthful range like `34-46 of 46` instead of an inaccurate `…0 more lines`, and the detail hint offers scrolling (`Esc back · ↑↓ scroll`) only when content actually overflows the body, otherwise just `Esc back`.
+- Message ordinals count only the messages the rail displays, so the detail header `#N` stays in agreement with the heading `N/total` after image-only or whitespace-only turns.
+- A missing `FORNACE_LLM_API_KEY` is treated as an unconfigured gateway (deterministic fallback titles) rather than a generation failure, so the session no longer warns spuriously.
+- A slot narrower than 42 columns renders the width-bounded notice rather than overflowing its column.
+- Non-home working directories keep their identity: `/private/tmp/x` no longer collapses to `x`, and long paths ellipsize from the front.
+- Escape while the rail is focused closes an open message detail first and only unfocuses on the second press.
+
+## 1.6.0
+
+> Readability pass driven by a live populated PTY audit: less cropping, more signal per row.
+
+- Collapsed message previews now use up to two wrapped lines instead of one clipped line.
+- Single header row: `Messages 5/5 · #5 01:26` replaces the two-row header.
+- Goal recap shows the objective on its own line(s) again, with a second line when dock space allows.
+- cmux row drops the label and leads with the surface ref (`surface:38 · title`), so operational identity never truncates away.
+- Status dock is priority-ordered (identity, goal status, objective, runtime, hint) and degrades to goal-status-only before dropping the goal.
+- Dock budget raised to five rows at normal heights; tiny-height behavior unchanged.
+
+
 ## 1.5.0
 
 - Replaced selected/newest pinning with a row-aware contiguous chronological viewport.

package/README.md

@@ -4,25 +4,20 @@ Persistent message history sidebar for [Pi](https://pi.dev).
 
 ## Features
 
-- Fixed 42-column panel on the right
-- Two-row message header with position and selected-message metadata
-- Contiguous chronological message viewport that top-aligns short histories and follows new messages until you browse away
-- Compact status dock of at most four rows, including an optional two-line goal
+- The obsidian rail: a 42-column truecolor ladder with a deep well as canvas, a raised panel step for the goal card, accent-tinted selection, and two ghost tiers for chrome; 256-color and light-terminal variants included
+- The Fornace flag crowns the rail: the seven brand hues from the production logo, painted solid edge to edge, with a sheen band while the rail is live
+- Goal card as the hero: breathing status dot, budget share, bold objective across up to three lines, and a `bdg`-labeled meter in eighths-of-a-cell resolution that eases toward the live ratio
+- Ghost chrome: section labels sit flush left in a near-invisible tier with right-aligned metadata and an air row above; no rules, no dashes
+- Structured two-row message slots without ordinals: time, then the summary across 32-cell lines; selection is a two-row yellow bar on a soft accent tint
+- Motion language that idles for free: pulsing pending dots, landing sweeps, decaying arrival glows, left-to-right reveals, eased meters with a riding shimmer, and a victory flash when a goal completes
+- AI message summaries (`fornace-flash` through the Fornace gateway, `PI_SIDEBAR_SUMMARY_MODEL` to override): one plain sentence per prompt, cached per session on disk, with a deterministic preview until the model answers; an unconfigured gateway shows a setup hint
+- Age-faded summaries like pi-recap: newest bright, recent normal, older muted, previews dimmer still
+- Git-style change badges (M/A/U/D/R) on the FILES rows, from a throttled `git status` provider
+- Message detail view with size in chars and wrapped lines, scrollable when the text overflows
+- Ellipsis rows counting hidden messages whenever the history outgrows the viewport
+- Contiguous chronological viewport that bottom-anchors the stream and follows new messages until you browse away
+- Mandatory rows reserved before optional rows are handed out; too short a terminal shows a resize notice rather than clipped sections
 - cmux session context that preserves the complete surface ref by truncating the workspace title first
-- Main transcript and editor render in their own reserved width
-- Persistent native right rail in fullscreen TUI mode
-- Compact regular-mode compositor in terminal-owned scrollback mode
-- Automatic collapse when the terminal cannot keep an 80-column main pane
-- `Ctrl+Shift+H` focuses the sidebar
-- Arrow keys navigate messages
-- `Enter` expands or collapses a message
-- `c` copies the session path
-- `Escape` returns focus to Pi
-- Width assertions cover every rendered sidebar line
-
-## Requirements
-
-Pi 0.84.4 or newer. This extension uses the renderer-switching and fullscreen layout APIs shipped with the 0.84 series.
 
 ## Installation
 
@@ -50,16 +45,24 @@ The message body is one contiguous chronological viewport. New messages remain s
 - Press `Ctrl+Shift+H` to focus or unfocus the sidebar.
 - Press `↑` or `↓` to navigate.
 - Press `PageUp`, `PageDown`, `Home`, or `End` for larger jumps.
-- Press `Enter` to expand or collapse the selected message.
-- Press `c` to copy the current session path.
-- Press `Escape` to return focus to Pi.
+- Press `Enter` to open the selected message's full text; scroll with `↑`/`↓` when the hint offers it.
+- Press `c` to copy the selected prompt while the rail is focused, or the session path when it is not.
+- Press `Escape` to close an open message, and again to return focus to Pi.
 
 ## Architecture
 
 - `index.ts` is the auto-discovered extension entrypoint.
 - `src/layout.ts` reserves a persistent horizontal region in fullscreen mode and composes the current screenful in regular mode.
-- `src/sidebar-component.ts` owns ID-stable navigation, expansion, follow-tail behavior, and the row-aware contiguous viewport.
-- `src/status-dock.ts` renders a compact, height-bounded goal, runtime, cmux, and validated status summary.
+- `src/sidebar-component.ts` owns section budgets, the render cache, and focus handling.
+- `src/messages.ts` renders the message grid and detail view, and owns ID-stable navigation and follow-tail behavior.
+- `src/goal-card.ts` renders the goal card; `src/sections.ts` renders ghost headers plus the session, files, and runtime sections into fixed row budgets.
+- `src/slots.ts` renders message slots; `src/flag.ts` paints the Fornace crown; `src/palette.ts` and `src/anim.ts` own the color ladder and the motion timing.
+- `src/summaries.ts` generates and caches one-line AI summaries off the render path.
+- `src/files.ts` collects the session's edited files from write tool calls.
+- `src/git-status.ts` maps the worktree status onto the shared M/A/U/D/R letter convention.
+- `src/palette.ts` resolves theme tokens, universal content grays, and the background ladder per render.
+- `src/anim.ts` owns the pulse and settle timing; the tick runs only while something moves.
+- `src/status-dock.ts` supplies context-usage and status validation helpers.
 - `src/goal.ts` reconstructs the active pi-codex-goal from session entries.
 - `src/cmux.ts` resolves the cmux workspace title and surface ref once per session.
 - `src/style.ts` provides ANSI-safe row filling and width helpers.

package/message-sidebar.ts

@@ -8,8 +8,13 @@ import { isViewportTUI, matchesKey, truncateToWidth } from "@earendil-works/pi-t
 import type { CmuxContext } from "./src/cmux.ts";
 import { resolveCmuxContext } from "./src/cmux.ts";
 import { isSidebarVisible } from "./src/constants.ts";
+import { readSessionFileEdits } from "./src/files.ts";
+import { GitStatusProvider } from "./src/git-status.ts";
 import { SidebarLayoutBridge } from "./src/layout.ts";
-import { SidebarComponent, type UserMessage } from "./src/sidebar-component.ts";
+import { SidebarComponent } from "./src/sidebar-component.ts";
+import { isGatewayConfigured, SummaryService, fallbackSummary } from "./src/summaries.ts";
+import { stripControl } from "./src/style.ts";
+import type { UserMessage } from "./src/types.ts";
 
 function extractUserText(message: { content: unknown }): string {
   if (typeof message.content === "string") return message.content;
@@ -24,12 +29,12 @@ function extractUserText(message: { content: unknown }): string {
 
 export function collectUserMessages(ctx: ExtensionContext): UserMessage[] {
   const messages: UserMessage[] = [];
-  let index = 0;
   for (const entry of ctx.sessionManager.getBranch()) {
     if (entry.type !== "message" || entry.message.role !== "user") continue;
-    index++;
-    const text = extractUserText(entry.message).trim();
-    if (text) messages.push({ id: entry.id, text, index, timestamp: entry.timestamp });
+    const text = stripControl(extractUserText(entry.message)).trim();
+    // A user turn with no text (image-only, say) is not shown, so it must not
+    // consume an ordinal: the detail's "#N" has to match the heading's "N/total".
+    if (text) messages.push({ id: entry.id, text, index: messages.length + 1, timestamp: entry.timestamp });
   }
   return messages;
 }
@@ -64,6 +69,8 @@ export default function messageSidebar(pi: ExtensionAPI): void {
   let cachedContext: ExtensionContext | null = null;
   let footerData: ReadonlyFooterDataProvider | null = null;
   let cmuxContext: CmuxContext | null = null;
+  let summaries: SummaryService | null = null;
+  const gitStatus = new GitStatusProvider();
   let refreshQueued = false;
 
   const scheduleRefresh = (ctx: ExtensionContext | null = cachedContext) => {
@@ -94,6 +101,15 @@ export default function messageSidebar(pi: ExtensionAPI): void {
   pi.on("session_start", (_event, ctx) => {
     if (ctx.mode !== "tui") return;
     cachedContext = ctx;
+    summaries?.dispose();
+    summaries = new SummaryService(
+      ctx.sessionManager.getSessionId(),
+      () => scheduleRefresh(ctx),
+      undefined,
+      (err) => ctx.ui.notify(err, "warning"),
+    );
+    summaries.seed(collectUserMessages(ctx));
+    void gitStatus.refresh(ctx.sessionManager.getCwd(), true, readSessionFileEdits(ctx).map((file) => file.path));
     void resolveCmuxContext().then((resolved) => {
       cmuxContext = resolved;
       scheduleRefresh(ctx);
@@ -108,6 +124,13 @@ export default function messageSidebar(pi: ExtensionAPI): void {
           getFooterData: () => footerData,
           getThinkingLevel: () => pi.getThinkingLevel(),
           getCmuxContext: () => cmuxContext,
+          getTheme: () => ctx.ui.theme,
+          getSummary: (messageId, text) => summaries?.get(messageId, text) ?? fallbackSummary(text),
+          hasSummary: (messageId) => summaries?.hasSummary(messageId) ?? false,
+          isPending: (messageId) => summaries?.isPending(messageId) ?? false,
+          summariesConfigured: isGatewayConfigured,
+          getEditedFiles: () => readSessionFileEdits(ctx),
+          getGitStatus: (path) => gitStatus.statusFor(path),
           messages: collectUserMessages(ctx),
         });
         return new SidebarLayoutBridge(currentTui, sidebar);
@@ -133,12 +156,9 @@ export default function messageSidebar(pi: ExtensionAPI): void {
         return undefined;
       }
       if (tui && isViewportTUI(tui)) return undefined;
-      if (matchesKey(data, "escape") && sidebar?.isFocused()) {
-        sidebar.setFocused(false);
-        tui?.requestRender();
-        return { consume: true };
-      }
       if (sidebar?.isFocused()) {
+        // The component owns every key while focused, Escape included: it
+        // closes an open message detail first and unfocuses on the second press.
         sidebar.handleInput(data);
         return { consume: true };
       }
@@ -147,6 +167,9 @@ export default function messageSidebar(pi: ExtensionAPI): void {
   });
 
   pi.on("session_shutdown", () => {
+    sidebar?.stopAnimations();
+    summaries?.dispose();
+    summaries = null;
     sidebar = null;
     tui = null;
     cachedContext = null;
@@ -165,8 +188,15 @@ export default function messageSidebar(pi: ExtensionAPI): void {
   });
 
   pi.on("message_end", (_event, ctx) => scheduleRefresh(ctx));
-  pi.on("turn_end", (_event, ctx) => scheduleRefresh(ctx));
-  pi.on("agent_end", (_event, ctx) => scheduleRefresh(ctx));
+  pi.on("turn_end", (_event, ctx) => {
+    summaries?.turnCompleted(collectUserMessages(ctx));
+    void gitStatus.refresh(ctx.sessionManager.getCwd(), false, readSessionFileEdits(ctx).map((file) => file.path));
+    scheduleRefresh(ctx);
+  });
+  pi.on("agent_end", (_event, ctx) => {
+    void gitStatus.refresh(ctx.sessionManager.getCwd(), false, readSessionFileEdits(ctx).map((file) => file.path));
+    scheduleRefresh(ctx);
+  });
   pi.on("agent_settled", (_event, ctx) => scheduleRefresh(ctx));
   pi.on("model_select", (_event, ctx) => scheduleRefresh(ctx));
   pi.on("thinking_level_select", (_event, ctx) => scheduleRefresh(ctx));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-message-sidebar",
-  "version": "1.5.0",
+  "version": "2.0.0",
   "description": "Persistent responsive message history sidebar for Pi",
   "keywords": [
     "pi-package",

package/src/anim.ts

@@ -0,0 +1,134 @@
+/**
+ * Animation timing for the rail, in the spirit of pi-recap: an 80-90 ms tick
+ * runs only while something is actually moving, and idle costs nothing.
+ * Two cadences carry the whole rail: a fast pulse for live work and a slow
+ * breath for ambient state, so motion reads as one language.
+ */
+
+/** One sine cycle of the pulsing pending dot. */
+export const DOT_CYCLE_MS = 900;
+/** Ambient cycle of the goal status dot: present, not urgent. */
+export const BREATHE_CYCLE_MS = 2400;
+/** Color sweep after a summary lands: accent, bold accent, then rest. */
+export const SETTLE_MS = 360;
+/** How long a fresh message keeps its soft landing glow. */
+export const GLOW_MS = 2200;
+/** Left-to-right reveal of a message slot as it arrives. */
+export const ARRIVE_MS = 350;
+/** One sheen band crossing the flag while the rail is live. */
+export const SHEEN_CYCLE_MS = 2800;
+/** The goal-complete flash on the card title. */
+export const VICTORY_MS = 700;
+/** Tick cadence while any animation is live. */
+export const ANIM_TICK_MS = 90;
+/** Per-tick share of the gap a meter closes while easing toward its target. */
+export const METER_EASE = 0.35;
+/** Meters closer than this to their target are considered settled. */
+export const METER_EPSILON = 0.004;
+export const DOT_GLYPH = "●";
+
+/** Cosine pulse 0..1, starting at the trough so a dot fades up, not blinks on. */
+export function pulse(now: number, startedAt: number, cycleMs = DOT_CYCLE_MS): number {
+  const phase = ((now - startedAt) % cycleMs) / cycleMs;
+  return 0.5 - 0.5 * Math.cos(phase * 2 * Math.PI);
+}
+
+/** The ambient breath: same cosine, slower cycle. */
+export function breathe(now: number): number {
+  return pulse(now, 0, BREATHE_CYCLE_MS);
+}
+
+/** 0 = settled, 1 = accent flash, 2 = bold accent. */
+export function settlePhase(now: number, landedAt: number): 0 | 1 | 2 {
+  const elapsed = now - landedAt;
+  if (elapsed >= SETTLE_MS) return 0;
+  return elapsed < SETTLE_MS / 2 ? 1 : 2;
+}
+
+export function isSettling(now: number, landedAt: number): boolean {
+  return now - landedAt < SETTLE_MS;
+}
+
+/** 1 right after a message lands, decaying to 0 over GLOW_MS. */
+export function glowStrength(now: number, landedAt: number): number {
+  const elapsed = now - landedAt;
+  if (elapsed >= GLOW_MS) return 0;
+  return 1 - elapsed / GLOW_MS;
+}
+
+/** 0..1 left-to-right reveal progress for a slot that arrived at `arrivedAt`. */
+export function arriveProgress(now: number, arrivedAt: number): number {
+  const elapsed = now - arrivedAt;
+  if (elapsed >= ARRIVE_MS) return 1;
+  return Math.max(0, elapsed / ARRIVE_MS);
+}
+
+export function isArriving(now: number, arrivedAt: number): boolean {
+  return now - arrivedAt < ARRIVE_MS;
+}
+
+/** Index of the sheen band crossing `cells` flag cells, or -1 between sweeps. */
+export function sheenBand(now: number, cells: number): number {
+  const phase = (now % SHEEN_CYCLE_MS) / SHEEN_CYCLE_MS;
+  const position = Math.floor(phase * (cells + 4)) - 2;
+  return position >= 0 && position < cells ? position : -1;
+}
+
+/** True while the goal-complete flash is still on the card. */
+export function isVictory(now: number, completedAt: number): boolean {
+  return now - completedAt < VICTORY_MS;
+}
+
+/**
+ * A meter value that eases toward its target instead of snapping, so a jump
+ * in context pressure or budget spend reads as motion. Tick returns true
+ * while the value is still moving, which is what keeps the animation tick
+ * alive; a settled meter costs nothing.
+ */
+export class EasedMeter {
+  private value: number | null = null;
+
+  set(target: number | null): void {
+    if (target === null || !Number.isFinite(target)) {
+      this.value = null;
+      return;
+    }
+    if (this.value === null) this.value = target;
+  }
+
+  get(): number | null {
+    return this.value;
+  }
+
+  target(target: number | null): number | null {
+    return target === null || !Number.isFinite(target) ? null : Math.max(0, Math.min(1, target));
+  }
+
+  /** True while a tick would still move the value toward `target`. */
+  moving(target: number | null): boolean {
+    const clamped = this.target(target);
+    if (clamped === null) return this.value !== null;
+    if (this.value === null) return false;
+    return Math.abs(clamped - this.value) >= METER_EPSILON;
+  }
+
+  /** Advance one tick; true while still converging toward `target`. */
+  tick(target: number | null): boolean {
+    const clamped = this.target(target);
+    if (clamped === null) {
+      this.value = null;
+      return false;
+    }
+    if (this.value === null) {
+      this.value = clamped;
+      return false;
+    }
+    const gap = clamped - this.value;
+    if (Math.abs(gap) < METER_EPSILON) {
+      this.value = clamped;
+      return false;
+    }
+    this.value += gap * METER_EASE;
+    return true;
+  }
+}

package/src/files.ts

@@ -0,0 +1,58 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+/** One distinct file the session wrote to, with its edit count. */
+export type FileEdit = { path: string; edits: number };
+
+/** Tools whose primary effect is writing a file path. */
+const WRITE_TOOLS = new Set(["edit", "write", "fast_write"]);
+
+type BranchEntry = { type?: string; id?: string; timestamp?: string; message?: { role?: string; content?: unknown } };
+
+/**
+ * Distinct files written by the session's edit/write tool calls, most
+ * recently touched first. Read-only tools and every other shape are skipped.
+ */
+export function collectFileEdits(entries: Iterable<BranchEntry>): FileEdit[] {
+  const touched = new Map<string, { edits: number; last: number }>();
+  let sequence = 0;
+  for (const entry of entries) {
+    if (entry.type !== "message") continue;
+    const message = entry.message;
+    if (!message || message.role !== "assistant") continue;
+    const content = message.content;
+    if (!Array.isArray(content)) continue;
+    for (const part of content) {
+      if (!part || typeof part !== "object" || (part as { type?: unknown }).type !== "toolCall") continue;
+      const call = part as { name?: unknown; arguments?: unknown };
+      if (typeof call.name !== "string" || !WRITE_TOOLS.has(call.name)) continue;
+      const path = (call.arguments as { path?: unknown } | null | undefined)?.path;
+      if (typeof path !== "string" || !path) continue;
+      const record = touched.get(path);
+      if (record) {
+        record.edits++;
+        record.last = sequence;
+      } else {
+        touched.set(path, { edits: 1, last: sequence });
+      }
+      sequence++;
+    }
+  }
+  return [...touched.entries()]
+    .sort(([, a], [, b]) => b.last - a.last)
+    .map(([path, record]) => ({ path, edits: record.edits }));
+}
+
+type FileEditCache = { key: string; files: FileEdit[] };
+const caches = new WeakMap<ExtensionContext, FileEditCache>();
+
+/** Cached per extension context, like the goal reconstruction. */
+export function readSessionFileEdits(ctx: ExtensionContext): FileEdit[] {
+  const branch = ctx.sessionManager.getBranch();
+  const last = branch.at(-1);
+  const key = `${branch.length}:${last?.id ?? ""}:${last?.timestamp ?? ""}`;
+  const previous = caches.get(ctx);
+  if (previous?.key === key) return previous.files;
+  const files = collectFileEdits(branch);
+  caches.set(ctx, { key, files });
+  return files;
+}

package/src/flag.ts

@@ -0,0 +1,29 @@
+import { sheenBand } from "./anim.ts";
+import { FORNACE_FLAG, FORNACE_FLAG_256, type Palette, type RGB, bgRgb, blend } from "./palette.ts";
+import { RST } from "./style.ts";
+
+/**
+ * The Fornace flag: the rail's crown row, a solid rainbow of the seven brand
+ * hues sampled from the production logo. While the rail is live a two-cell
+ * sheen band crosses it, so the mark breathes with the session and rests
+ * when the session rests.
+ */
+export function flagRow(palette: Palette, cells: number, now: number, live: boolean): string {
+  const band = live ? sheenBand(now, cells) : -1;
+  const lit = (index: number) => band >= 0 && (index === band || index === band + 1);
+  const parts: string[] = [palette.edge, "│", RST];
+  for (let index = 0; index < cells; index++) {
+    const hue = index % FORNACE_FLAG.length;
+    let cell: string;
+    if (palette.truecolor) {
+      const rgb: RGB = FORNACE_FLAG[hue]!;
+      cell = bgRgb(lit(index) ? blend(rgb, [255, 255, 255], 0.45) : rgb);
+    } else {
+      cell = `\x1b[48;5;${FORNACE_FLAG_256[hue]}m`;
+      if (lit(index)) cell = `\x1b[1m${cell}`;
+    }
+    parts.push(cell, " ");
+  }
+  parts.push(RST);
+  return parts.join("");
+}

package/src/git-status.ts

@@ -0,0 +1,123 @@
+import { execFile } from "node:child_process";
+import { realpathSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { promisify } from "node:util";
+
+const run = promisify(execFile);
+
+/** Distinct repositories queried per refresh; a session rarely edits across more. */
+const MAX_ROOTS = 8;
+
+/**
+ * Git worktree status per absolute path, in the letter convention shared by
+ * git, VS Code, and GitHub: M modified, A added, D deleted, R renamed,
+ * U untracked. Refresh is throttled and spans every repository the session
+ * edits in, not just the session cwd; failures leave the last good map.
+ */
+export class GitStatusProvider {
+  private status = new Map<string, string>();
+  private readonly realpaths = new Map<string, string>();
+  private readonly roots = new Map<string, string>();
+  private lastRun = 0;
+  private inflight: Promise<void> | null = null;
+  lastError: string | null = null;
+
+  constructor(
+    private readonly refreshIntervalMs = 4000,
+    private readonly exec: (file: string, args: string[], cwd: string) => Promise<string> = async (file, args, cwd) => {
+      const { stdout } = await run(file, args, { cwd, timeout: 5000, maxBuffer: 16 * 1024 * 1024 });
+      return stdout;
+    },
+  ) {}
+
+  /** Throttled refresh; concurrent callers share one run. */
+  refresh(cwd: string, force = false, extraPaths: readonly string[] = []): Promise<void> {
+    if (this.inflight) return this.inflight;
+    const now = Date.now();
+    if (!force && now - this.lastRun < this.refreshIntervalMs) return Promise.resolve();
+    this.lastRun = now;
+    this.inflight = this.run(cwd, extraPaths).finally(() => { this.inflight = null; });
+    return this.inflight;
+  }
+
+  /** One letter per the shared convention, or null when git has no opinion. */
+  statusFor(path: string): string | null {
+    const xy = this.status.get(this.realpath(path));
+    if (!xy) return null;
+    if (xy === "??") return "U";
+    const index = xy[0] ?? " ";
+    const worktree = xy[1] ?? " ";
+    const letter = index !== " " && index !== "?" ? index : worktree;
+    return letter === "M" || letter === "A" || letter === "D" || letter === "R" ? letter : null;
+  }
+
+  /** Symlink-safe identity; callers hand us /var paths while git says /private/var. */
+  private realpath(path: string): string {
+    const cached = this.realpaths.get(path);
+    if (cached) return cached;
+    let resolved = path;
+    try {
+      resolved = realpathSync(path);
+    } catch {
+      // A path git wrote but the disk renamed: keep the raw string.
+    }
+    this.realpaths.set(path, resolved);
+    return resolved;
+  }
+
+  /** Repository root for a directory; failures stay uncached so they retry. */
+  private async gitRoot(dir: string): Promise<string | null> {
+    const cached = this.roots.get(dir);
+    if (cached) return cached;
+    try {
+      const root = (await this.exec("git", ["rev-parse", "--show-toplevel"], dir)).trim();
+      const resolved = this.realpath(root);
+      this.roots.set(dir, resolved);
+      return resolved;
+    } catch (error) {
+      this.lastError = error instanceof Error ? error.message : String(error);
+      return null;
+    }
+  }
+
+  private async run(cwd: string, extraPaths: readonly string[]): Promise<void> {
+    const roots = new Set<string>();
+    const cwdRoot = await this.gitRoot(cwd);
+    if (cwdRoot) roots.add(cwdRoot);
+    for (const path of extraPaths) {
+      if (roots.size >= MAX_ROOTS) break;
+      const root = await this.gitRoot(dirname(path));
+      if (root) roots.add(root);
+    }
+    if (roots.size === 0) return;
+
+    const next = new Map<string, string>();
+    const failures: string[] = [];
+    await Promise.all([...roots].map(async (root) => {
+      try {
+        const stdout = await this.exec("git", ["status", "--porcelain=v1", "-z", "--untracked-files=all"], root);
+        for (const [path, xy] of parsePorcelain(stdout, root)) next.set(path, xy);
+      } catch (error) {
+        failures.push(error instanceof Error ? error.message : String(error));
+      }
+    }));
+    this.status = next;
+    this.lastError = failures.length > 0 ? failures.join("; ") : null;
+  }
+}
+
+/** -z records: "XY path\0" with an extra "origPath\0" record for renames. */
+function parsePorcelain(stdout: string, root: string): [string, string][] {
+  const entries: [string, string][] = [];
+  const records = stdout.split("\0");
+  for (let index = 0; index < records.length; index++) {
+    const record = records[index];
+    if (!record || record.length < 4) continue;
+    const xy = record.slice(0, 2);
+    const rel = record.slice(3);
+    if (!rel) continue;
+    entries.push([join(root, rel), xy]);
+    if (xy[0] === "R" || xy[0] === "C") index++; // skip the source-path record
+  }
+  return entries;
+}