@pi-archimedes/footer 2.1.0 → 2.3.0

package/README.md

@@ -2,14 +2,14 @@
 
 A status bar that shows what matters — at a glance, without getting in the way.
 
-Your terminal is already full of information. The footer gives you exactly what you need to know about your session — where you are, what model you're using, how many tokens you've burned, and how close you are to the context limit — all in one clean line at the bottom. When subagents run, their costs merge seamlessly into the same view.
+Your terminal is already full of information. The footer gives you exactly what you need to know about your session — where you are, what model you're using, how many tokens you've burned, and how close you are to the context limit — laid out at the bottom of the terminal, adapting to its width without ever clipping. When subagents run, their costs merge seamlessly into the same view.
 
 ## What you get
 
-- **Session context at a glance** — directory, git branch (with clean/dirty indicator), active model, thinking level, and worktree
+- **Session context at a glance** — directory, git branch (with clean/dirty indicators), active model, thinking level; the branch icon switches from `⎇` to `🌲` when cwd is inside a linked worktree — no extra chip, no duplication
 - **Token stats** — input ↑, output ↓, cache read/write, and real-dollar cost, all in one compact display
 - **Context window bar** — color-coded progress bar (green → yellow → red) showing how much of your context window is used
-- **Smart layout** — single line on wide terminals, auto-splits to two lines when space is tight (threshold configurable)
+- **Adaptive layout** — everything on one line when it fits; otherwise it wraps to additional lines (two or three) instead of clipping. Width at which it switches is configurable
 - **Unified subagent costs** — when subagents run, their token usage and cost merge into the main footer automatically
 
 ## Install
@@ -28,19 +28,18 @@ pi install npm:pi-archimedes
 
 Footer renders automatically at the bottom of the Pi TUI. No commands to run.
 
-On wide terminals, the footer displays as a single clean line containing all session context, token usage, cost, and context window progress. When the terminal width falls below the configured split threshold, the footer automatically splits into two lines to keep all information clear and readable without clipping.
+On wide terminals, the footer displays as one compact line with all session context, token usage, cost, and a context window progress bar that fills the remaining space. When that no longer fits on one line, the footer wraps — usage moves to a second line, and sections themselves overflow to a third line if the terminal is truly narrow — so nothing ever gets clipped. Below the configured split threshold, it always uses at least the two-line layout (system info above, stats below).
 
 ## Settings
 
 | Setting | Type | Default | Description |
 |---------|------|---------|-------------|
-| `splitThreshold` | number | `150` | Minimum terminal width (columns) to display footer on a single line. Below this width, the footer splits into two lines. |
+| `splitThreshold` | number | `150` | Minimum terminal width (columns) where a single-line footer is still allowed. Below it, the footer always uses at least the two-line layout; above it, it stays on one line as long as the content fits and wraps otherwise — never clipping. |
 
 Settings are stored in `~/.pi/agent/settings.json` under the `archimedes.footer` namespace.
 
 ## Integration
 
-When installed via meta package, footer consumes cost events from subagents through the core bus, giving a unified token/cost view. Standalone install shows only the main agent's stats.
-
+When installed via the meta package, footer consumes cost events from subagents through the core bus, giving a unified token/cost view across the main agent and any running subagents. Standalone install shows only the main agent's stats.
 
 ← Back to [pi-archimedes](../../README.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-archimedes/footer",
-  "version": "2.1.0",
+  "version": "2.3.0",
   "type": "module",
   "keywords": [
     "pi-package"
@@ -15,13 +15,15 @@
     "./config": "./src/config.ts"
   },
   "dependencies": {
-    "@pi-archimedes/core": "2.1.0"
+    "@pi-archimedes/core": "2.3.0"
   },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": ">=0.1.0",
     "@earendil-works/pi-tui": ">=0.1.0"
   },
   "devDependencies": {
+    "@earendil-works/pi-coding-agent": "^0.84.2",
+    "@earendil-works/pi-tui": "^0.84.2",
     "typescript": "^6.0.0"
   },
   "pi": {

package/src/index.ts

@@ -1,19 +1,23 @@
 /**
- * dir | model | ◐thinking | branch [+status] | worktree | ↑↓R W $cost | ━━━━━ context%
- * Splits into two lines when terminal width < splitThreshold (default 150):
- *   Line 1: system info (dir, branch, model, thinking, worktree)
- *   Line 2: usage stats (↑↓R W $cost + context progress bar)
+ * dir | branch [+status] | worktree | model | ◐thinking | ↑↓R W $cost ━ context%
+ *
+ * Adaptive layout — wraps to additional lines instead of truncating:
+ * - fits width → single line (system info · stats · context bar)
+ * - doesn't fit → two lines (system info above, stats + bar below)
+ * - left sections alone overflow → three or more lines
+ * - below splitThreshold (default 150) → at least two lines, as configured
  */
 
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+import { visibleWidth } from "@earendil-works/pi-tui";
 import { clampLine } from "@pi-archimedes/core/text";
 import { loadFooterConfig } from "./config.js";
 import { CostAccumulator } from "./cost-accumulator.js";
-import { getGitStatus, getWorktreeBranch } from "./utils/git.js";
+import { getGitStatus, isInsideLinkedWorktree } from "./utils/git.js";
 import { getContextWindowInfo, getTokenUsageStats, type TokenUsageStats } from "./utils/stats.js";
 import { formatContextBar, formatGitStatusIndicators, formatThinkingIndicator, formatTokenCount } from "./utils/format.js";
 import { footerIcons } from "./utils/icons.js";
+import { packFooterLines, SEP_W, SEPARATOR } from "./utils/layout.js";
 
 export function registerFooter(pi: ExtensionAPI): void {
   // Module-level state for session lifecycle (shared between session_start and session_shutdown)
@@ -48,7 +52,7 @@ export function registerFooter(pi: ExtensionAPI): void {
             const currentBranch = footerData.getGitBranch();
             const currentDirectory = process.cwd().split("/").pop() || process.cwd();
             const gitStatus = getGitStatus();
-            const worktreeBranch = getWorktreeBranch();
+            const inWorktree = isInsideLinkedWorktree();
             const thinkingLevel = pi.getThinkingLevel();
 
             // Merge main agent stats with subagent stats from accumulator
@@ -65,29 +69,22 @@ export function registerFooter(pi: ExtensionAPI): void {
             const { totalInput, totalOutput, totalCacheRead, totalCacheWrite, totalCost } = mergedStats;
             const { percent: contextPercent, percentValue: contextPercentValue, windowSize: contextWindowSize } = getContextWindowInfo(ctx);
 
-            // ── Two-line split for narrow terminals ────────────────────────────
+            // ── Sections ──────────────────────────────────────────────────
 
-            const shouldSplit = width < splitThreshold;
-
-            // Thinking display
             const thinkingIndicatorStr = formatThinkingIndicator(thinkingLevel, colorize);
-
-            // Git status indicators
             const gitStatusStr = formatGitStatusIndicators(gitStatus, colorize);
 
-            // Left section: dir | branch [+status] | model | thinking | worktree
+            const branchIcon = inWorktree ? footerIcons.worktree : footerIcons.branch;
+
+            // System info sections: dir | branch [+status] | model | thinking
             const leftSections = [
               colorize("syntaxFunction", " " + footerIcons.directory + currentDirectory),
-              currentBranch ? colorize("success", footerIcons.branch + " " + currentBranch + (gitStatusStr ? " " + gitStatusStr : "")) : "",
+              currentBranch ? colorize("success", branchIcon + " " + currentBranch + (gitStatusStr ? " " + gitStatusStr : "")) : "",
               colorize("syntaxType", footerIcons.model + " " + activeModel),
               thinkingIndicatorStr,
-              worktreeBranch ? colorize("syntaxNumber", footerIcons.worktree + " " + worktreeBranch) : "",
             ].filter(Boolean);
 
-            const separator = theme.fg("dim", " · ");
-            const leftSectionStr = leftSections.join(separator);
-
-            // Token stats with context percentage
+            // Usage stats: ↑in ↓out RcacheRead WcacheWrite $cost contextWindow
             const statsParts: string[] = [];
             if (totalInput) statsParts.push("↑" + formatTokenCount(totalInput));
             if (totalOutput) statsParts.push("↓" + formatTokenCount(totalOutput));
@@ -108,56 +105,33 @@ export function registerFooter(pi: ExtensionAPI): void {
                   : contextDisplay;
             statsParts.push(contextColored);
 
-            const rawStatsSectionStr = statsParts.join(" ");
-            const statsSectionStr = theme.fg("dim", rawStatsSectionStr);
-
-            if (shouldSplit) {
-              // ── Two-line mode ──────────────────────────────────────────────
-
-              // Calculate available space for the context progress bar on line 2
-              const availableBarSpace = Math.max(2, width - visibleWidth(statsSectionStr) - 13);
-
-              // Context progress bar (expands to fill remaining space)
-              const contextBarStr = formatContextBar(colorize as (token: string, s: string) => string, contextPercentValue, availableBarSpace);
-
-              // Assemble line 2: stats | bar
-              const rightSections: string[] = [];
-              if (statsSectionStr) rightSections.push(statsSectionStr);
-              if (contextBarStr) rightSections.push(contextBarStr);
-              const rightSectionStr = rightSections.join(theme.fg("dim", " · "));
-
-              // Edge case: if both stats and bar are empty, return only line 1
-              if (!rightSectionStr) {
-                return [clampLine(leftSectionStr, width)];
-              }
-
-              return [
-                clampLine(leftSectionStr, width),
-                clampLine(rightSectionStr, width),
-              ];
+            const statsSectionStr = theme.fg("dim", statsParts.join(" "));
+
+            // ── Adaptive multi-line layout ──────────────────────────────
+            // Pack sections left-to-right; whatever doesn't fit wraps to the
+            // next line. Below the splitThreshold setting, force at least the
+            // two-line split (system info above, stats below) even when one
+            // line would fit. The context bar expands into the remainder of
+            // the last line and is dropped only if no reasonable space is left.
+            const separator = theme.fg("dim", SEPARATOR);
+            let groups = packFooterLines([...leftSections, statsSectionStr], width, SEP_W);
+            if (groups.length < 2 && width < splitThreshold && leftSections.length > 0) {
+              groups = [leftSections, [statsSectionStr]];
             }
 
-            // ── Single-line mode ───────────────────────────────────────────────
-
-            // Separator between left and right sections
-            const sectionSeparator = theme.fg("dim", " · ");
-
-            // Calculate available space for the context progress bar (after stats)
-            const availableBarSpace = Math.max(
-              2,
-              width - visibleWidth(leftSectionStr) - 1 - visibleWidth(sectionSeparator) - visibleWidth(statsSectionStr) - 10,
-            );
-
-            // Context progress bar (expands to fill remaining space)
-            const contextBarStr = formatContextBar(colorize as (token: string, s: string) => string, contextPercentValue, availableBarSpace);
-
-            // Assemble: left | stats | bar
-            const rightSections: string[] = [];
-            if (statsSectionStr) rightSections.push(statsSectionStr);
-            if (contextBarStr) rightSections.push(contextBarStr);
-            const rightSectionStr = rightSections.join(theme.fg("dim", " · "));
-
-            return [clampLine(leftSectionStr + sectionSeparator + rightSectionStr, width)];
+            return groups
+              .map((group, idx) => {
+                let line = group.join(separator);
+                if (idx === groups.length - 1) {
+                  const remaining = width - visibleWidth(line) - (line ? SEP_W : 0);
+                  const contextBarStr = formatContextBar(colorize, contextPercentValue, remaining);
+                  if (contextBarStr) {
+                    line = line ? line + separator + contextBarStr : contextBarStr;
+                  }
+                }
+                return clampLine(line, width);
+              })
+              .filter((line) => line.length > 0);
           } catch (e) {
             console.error("[archimedes:footer] Render error:", e);
             return [];

package/src/utils/format.test.ts

@@ -1,4 +1,5 @@
 import { describe, it, expect } from "vitest";
+import { visibleWidth } from "@earendil-works/pi-tui";
 import {
   formatTokenCount,
   formatContextBar,
@@ -76,6 +77,18 @@ describe("formatContextBar", () => {
     const result = formatContextBar(mockColor, 75, 10);
     expect(result).toContain("75%");
   });
+
+  it("occupies exactly totalSpace visible columns", () => {
+    expect(visibleWidth(formatContextBar(mockColor, 50, 24))).toBe(24);
+    expect(visibleWidth(formatContextBar(mockColor, 100, 30))).toBe(30);
+    expect(visibleWidth(formatContextBar(mockColor, 0, 16))).toBe(16);
+  });
+
+  it("returns empty when the fixed overhead alone would not fit", () => {
+    // icon + gaps (4) + label leave no room for a bar segment
+    expect(formatContextBar(mockColor, 50, 7)).toBe("");
+    expect(formatContextBar(mockColor, 100, 8)).toBe("");
+  });
 });
 
 // ── formatGitStatusIndicators ───────────────────────────────────────────────

package/src/utils/format.ts

@@ -12,12 +12,20 @@ export function formatTokenCount(count: number): string {
   return Math.round(count / TOKEN_M) + "M";
 }
 
-export function formatContextBar(colorize: ColorFn, percentValue: number, availableSpace: number): string {
-  if (availableSpace <= 2) return "";
-
-  const pct = Math.min(1, percentValue / 100);
-  const filledLength = percentValue > 0 ? Math.max(1, Math.round(pct * availableSpace)) : 0;
-  const emptyLength = availableSpace - filledLength;
+/**
+ * Context progress bar, sized to occupy EXACTLY `totalSpace` visible columns
+ * (icon + gaps + bar + percentage label). Returns "" when there isn't room
+ * for the icon, label and at least one bar segment.
+ */
+export function formatContextBar(colorize: ColorFn, percentValue: number, totalSpace: number): string {
+  const pct = Math.min(1, Math.max(0, percentValue / 100));
+  const pctLabel = Math.round(Math.max(0, percentValue)) + "%";
+  // Fixed overhead: icon (1) + "  " (2) + " " (1) + percentage label
+  const barLength = totalSpace - 4 - pctLabel.length;
+  if (barLength < 1) return "";
+
+  const filledLength = percentValue > 0 ? Math.max(1, Math.round(pct * barLength)) : 0;
+  const emptyLength = barLength - filledLength;
 
   const barToken = pct >= 0.9 ? "error" : pct >= 0.7 ? "warning" : "syntaxString";
 
@@ -25,7 +33,7 @@ export function formatContextBar(colorize: ColorFn, percentValue: number, availa
   const emptyBar = emptyLength > 0 ? colorize("dim", "━".repeat(emptyLength)) : "";
   const bar = filledBar + emptyBar;
 
-  return colorize(barToken, footerIcons.contextWindow) + "  " + bar + " " + colorize(barToken, Math.round(percentValue) + "%");
+  return colorize(barToken, footerIcons.contextWindow) + "  " + bar + " " + colorize(barToken, pctLabel);
 }
 
 export function formatGitStatusIndicators(

package/src/utils/git.test.ts

@@ -15,7 +15,7 @@ interface GitStatus {
 
 describe("getGitStatus", () => {
   let getGitStatus: () => GitStatus;
-  let getWorktreeBranch: () => string | null;
+  let isInsideLinkedWorktree: () => boolean;
 
   async function loadModule(mockExecSync: ReturnType<typeof vi.fn>) {
     vi.resetModules();
@@ -30,7 +30,7 @@ describe("getGitStatus", () => {
 
     const mod = await import("./git.js");
     getGitStatus = mod.getGitStatus;
-    getWorktreeBranch = mod.getWorktreeBranch;
+    isInsideLinkedWorktree = mod.isInsideLinkedWorktree;
   }
 
   afterEach(() => {
@@ -95,11 +95,36 @@ describe("getGitStatus", () => {
     expect(result.unstaged).toBe(1);
   });
 
-  it("getWorktreeBranch returns null when not in worktree", async () => {
+  it("isInsideLinkedWorktree returns false for a single (main) worktree", async () => {
     const mockExecSync = vi.fn(() => "head ref/heads/main\nworktree /path/to/repo\n");
     await loadModule(mockExecSync);
-    const result = getWorktreeBranch();
-    expect(result).toBeNull();
+    expect(isInsideLinkedWorktree()).toBe(false);
+  });
+
+  it("isInsideLinkedWorktree returns false when cwd is the MAIN worktree", async () => {
+    // cwd equals the first porcelain entry → main clone, not a linked worktree
+    const cwd = process.cwd();
+    const mockExecSync = vi.fn(() =>
+      `worktree ${cwd}\nbranch refs/heads/main\n\n` + "worktree /home/x/wt-other\nbranch refs/heads/other\n");
+    await loadModule(mockExecSync);
+    expect(isInsideLinkedWorktree()).toBe(false);
+  });
+
+  it("isInsideLinkedWorktree returns true when cwd is a linked worktree", async () => {
+    const cwd = process.cwd();
+    const mockExecSync = vi.fn(() =>
+      "worktree /nope/main\nbranch refs/heads/other\n\n" +
+      `worktree ${cwd}\n` + "branch refs/heads/feature/x\n");
+    await loadModule(mockExecSync);
+    expect(isInsideLinkedWorktree()).toBe(true);
+  });
+
+  it("isInsideLinkedWorktree returns true for a detached-HEAD linked worktree", async () => {
+    const cwd = process.cwd();
+    const mockExecSync = vi.fn(() =>
+      "worktree /nope/main\nbranch ref/heads/other\n\n" + `worktree ${cwd}\n` + "detached\n");
+    await loadModule(mockExecSync);
+    expect(isInsideLinkedWorktree()).toBe(true);
   });
 
   it("property: getGitStatus never throws (catches execSync errors gracefully)", async () => {

package/src/utils/git.ts

@@ -21,7 +21,7 @@ interface GitCacheEntry {
 }
 
 interface WorktreeCacheEntry {
-  value: string | null;
+  value: boolean;
   timestamp: number;
 }
 
@@ -131,7 +131,11 @@ export function getGitStatus(): GitStatus {
   return gitStatusCache.value;
 }
 
-export function getWorktreeBranch(): string | null {
+/**
+ * Returns true when cwd is inside a linked worktree (not the main clone).
+ * Returns false when cwd is the main clone or not a git repo.
+ */
+export function isInsideLinkedWorktree(): boolean {
   // Return cached result if still fresh
   if (worktreeCache && Date.now() - worktreeCache.timestamp < GIT_CACHE_TTL_MS) {
     return worktreeCache.value;
@@ -147,20 +151,23 @@ export function getWorktreeBranch(): string | null {
 
     const worktreeEntries = worktreeOutput.trim().split("\n\n").filter(Boolean);
     if (worktreeEntries.length <= 1) {
-      worktreeCache = { value: null, timestamp: Date.now() };
-      return null;
+      worktreeCache = { value: false, timestamp: Date.now() };
+      return false;
     }
 
     const currentDirectoryPath = realpathSync(process.cwd());
-    let result: string | null = null;
-    for (const entry of worktreeEntries) {
+    let result = false;
+    // The first porcelain entry is always the main worktree: being in the
+    // main clone isn't "being in a worktree", so only linked ones (index >= 1)
+    // can match.
+    for (let i = 1; i < worktreeEntries.length; i++) {
+      const entry = worktreeEntries[i]!;
       const entryLines = entry.split("\n");
       const pathLine = entryLines.find((l) => l.startsWith("worktree "));
-      const branchLine = entryLines.find((l) => l.startsWith("branch "));
       const worktreePath = pathLine?.replace("worktree ", "");
 
       if (worktreePath && (currentDirectoryPath === worktreePath || currentDirectoryPath.startsWith(worktreePath + "/"))) {
-        result = branchLine?.replace("branch refs/heads/", "") ?? null;
+        result = true;
         break;
       }
     }
@@ -168,7 +175,7 @@ export function getWorktreeBranch(): string | null {
     return result;
   } catch {
     /* not a git repo */
-    worktreeCache = { value: null, timestamp: Date.now() };
-    return null;
+    worktreeCache = { value: false, timestamp: Date.now() };
+    return false;
   }
 }

package/src/utils/layout.test.ts

@@ -0,0 +1,107 @@
+import { describe, it, expect } from "vitest";
+import { visibleWidth } from "@earendil-works/pi-tui";
+import { packFooterLines, SEP_W } from "./layout.js";
+
+/** Local copy of measureChunks (not exported from layout.ts — test-only helper). */
+function measureChunks(chunks: string[], sepWidth = SEP_W): number {
+  let w = 0;
+  for (let i = 0; i < chunks.length; i++) {
+    w += (i > 0 ? sepWidth : 0) + visibleWidth(chunks[i]!);
+  }
+  return w;
+}
+
+// Plain-Chinese chunks keep the math readable; packFooterLines only
+// needs to *measure* them, not render them.
+const DIR = "a"; // dir section
+const BRANCH = "b".repeat(40); // branch section
+const WORKTREE = "w".repeat(40); // worktree section
+const MODEL = "model"; // model section
+const THINKING = "high"; // thinking level
+const STATS = "s".repeat(20); // stats section
+
+describe("measureChunks", () => {
+  it("measures a single chunk", () => {
+    expect(measureChunks(["abcde"])).toBe(5);
+  });
+
+  it("measures joined chunks with the separator", () => {
+    expect(measureChunks(["ab", "cde"])) // 2 + 3 + 3
+      .toBe(8);
+    expect(measureChunks(["ab", "cde", "fg"])) // 2 + (3+3) + (2+3)
+      .toBe(13);
+  });
+
+  it("measures empty chunks as zero", () => {
+    expect(measureChunks([])).toBe(0);
+  });
+});
+
+describe("packFooterLines", () => {
+  it("returns an empty array for empty chunks", () => {
+    expect(packFooterLines([], 100, 3)).toEqual([]);
+  });
+
+  it("keeps everything on one line when it fits", () => {
+    const chunks = [DIR, BRANCH, WORKTREE, MODEL, THINKING, STATS];
+    const groups = packFooterLines(chunks, measureChunks(chunks) + 10, SEP_W);
+    expect(groups).toEqual([chunks]);
+  });
+
+  it("exactly-fits means one line (boundary is inclusive)", () => {
+    const chunks = [DIR, BRANCH];
+    const width = measureChunks(chunks); // 1 + SEP_W + 40
+    expect(packFooterLines(chunks, width, SEP_W)).toEqual([chunks]);
+  });
+
+  it("wraps the tail to a second line when it no longer fits", () => {
+    const chunks = [DIR, BRANCH, WORKTREE, MODEL, THINKING, STATS];
+    const oneLineW = measureChunks(chunks);
+
+    // One less column than needed → STATS drops to its own line
+    const groups = packFooterLines(chunks, oneLineW - 1, SEP_W);
+    expect(groups).toEqual([[DIR, BRANCH, WORKTREE, MODEL, THINKING], [STATS]]);
+  });
+
+  it("wraps left sections when they alone overflow (three lines)", () => {
+    // ""(1) + sep + 40"" fits, +worktree doesn't.
+    // worktree+model+thinking (55) fits, +stats (78) doesn't.
+    const chunks = [DIR, BRANCH, WORKTREE, MODEL, THINKING, STATS];
+    const groups = packFooterLines(chunks, 70, SEP_W);
+    expect(groups).toEqual([
+      [DIR, BRANCH],
+      [WORKTREE, MODEL, THINKING],
+      [STATS],
+    ]);
+  });
+
+  it("gives an over-wide chunk its own line", () => {
+    const huge = "x".repeat(120); // wider than the terminal
+    const groups = packFooterLines([DIR, huge, STATS], 60, SEP_W);
+    expect(groups).toEqual([[DIR], [huge], [STATS]]);
+  });
+
+  it("splits per chunk on a near-zero width", () => {
+    const groups = packFooterLines([DIR, MODEL], 0, SEP_W);
+    expect(groups).toEqual([[DIR], [MODEL]]);
+  });
+
+  it("respects a custom separator width", () => {
+    // separator of 0: dir(1) and branch(40) fit in 41
+    expect(packFooterLines(["a", "b".repeat(40)], 41, 0)).toHaveLength(1);
+    // no slack for separator SEP_W → wraps
+    expect(packFooterLines(["a", "b".repeat(40)], 41, SEP_W)).toHaveLength(2);
+  });
+
+  it("measures ANSI-escaped chunks by their visible width only", () => {
+    const plain = "branch"; // 6 visible cols
+    const ansi = "\x1b[32mbranch\x1b[0m"; // same 6 visible cols, with color escape
+    // Both should produce the same grouping structure:
+    // "branch" (6) + sep (3) + "stats" (5) = 14 ≤ 20 → one group of two
+    const plainGroups = packFooterLines([plain, "stats"], 20, 3);
+    const ansiGroups = packFooterLines([ansi, "stats"], 20, 3);
+    // Same number of lines and same number of chunks per line
+    expect(plainGroups.map((g) => g.length)).toEqual(ansiGroups.map((g) => g.length));
+    expect(plainGroups.length).toBe(1);
+  });
+});

package/src/utils/layout.ts

@@ -0,0 +1,70 @@
+import { visibleWidth } from "@earendil-works/pi-tui";
+
+/**
+ * Footer line-packing.
+ *
+ * Chunks are the individual footer pieces (dir, branch, worktree, model,
+ * thinking, stats, context bar). Packing decides how many lines the footer
+ * needs so nothing gets silently truncated:
+ *
+ * - one line, if everything fits
+ * - two lines, if the tail (e.g. stats) no longer fits
+ * - three or more, if the left sections themselves overflow the terminal
+ *
+ * Every chunk is atomic — it is never cut in half. A single chunk wider
+ * than the terminal occupies a line of its own; the caller is responsible
+ * for clamping it (last-resort truncation of one irreducibly long item).
+ */
+
+/** Visible width of the " · " footer separator. */
+export const SEP_W = 3;
+/** The footer section separator string (without ANSI colouring — colour it at the call site). */
+export const SEPARATOR = " · ";
+
+/**
+ * Total visible columns of chunks joined by a separator of `sepWidth`
+ * visible characters.
+ */
+function measureChunks(chunks: string[], sepWidth = 3): number {
+  let w = 0;
+  for (let i = 0; i < chunks.length; i++) {
+    w += (i > 0 ? sepWidth : 0) + visibleWidth(chunks[i]!);
+  }
+  return w;
+}
+
+/**
+ * Greedily pack chunks into groups of lines, each guaranteed to satisfy
+ * `sum(chunkWidth) + sepWidth * (count - 1) <= width` when joined — with the
+ * sole exception of a single chunk wider than `width` (own line).
+ *
+ * @param chunks atomic footer pieces, in desired display order
+ * @param width  terminal width in visible columns
+ * @param sepWidth visible width of the join separator (default 3, for " · ")
+ */
+export function packFooterLines(chunks: string[], width: number, sepWidth = 3): string[][] {
+  if (chunks.length === 0) return [];
+  if (width <= 0) return chunks.map((c) => [c]);
+
+  const groups: string[][] = [];
+  let group: string[] = [];
+  let groupW = 0;
+
+  for (const chunk of chunks) {
+    const w = visibleWidth(chunk);
+    if (group.length === 0) {
+      group = [chunk];
+      groupW = w;
+    } else if (groupW + sepWidth + w <= width) {
+      group.push(chunk);
+      groupW += sepWidth + w;
+    } else {
+      groups.push(group);
+      group = [chunk];
+      groupW = w;
+    }
+  }
+  if (group.length > 0) groups.push(group);
+
+  return groups;
+}

package/src/utils/render-smoke.test.ts

@@ -0,0 +1,87 @@
+import { describe, it, expect } from "vitest";
+import { stripAnsi } from "@pi-archimedes/core/text";
+import { packFooterLines, SEP_W, SEPARATOR } from "./layout.js";
+import { formatContextBar } from "./format.js";
+import { visibleWidth } from "@earendil-works/pi-tui";
+
+// Minimal stand-ins: same visible chars as the real footer, no ANSI
+// left joined: dir(7)+sep+branch(38)+sep+worktree(36)+sep+model(20)+sep+thinking(6) = 119
+// full single line (left + stats 37): 159
+const DIR = "📁 auth";
+const BRANCH = "⎇ feat/plan-040-jwt-cookie-security+~3"; // + fake status
+const WORKTREE = "⛅ feat/plan-040-jwt-cookie-security";
+const MODEL = "🧠 claude-sonnet-4-6";
+const THINKING = "◐ high";
+const STATS = "↑141 ↓42k R8.7M W220k $4.25 116k/977k";
+
+function buildLines(width: number, pct: number, splitThreshold = 150) {
+  const leftSections = [
+    DIR,
+    BRANCH,
+    WORKTREE,
+    MODEL,
+    THINKING,
+  ].filter(Boolean);
+  let groups = packFooterLines([...leftSections, STATS], width, SEP_W);
+  if (groups.length < 2 && width < splitThreshold && leftSections.length > 0) {
+    groups = [leftSections, [STATS]];
+  }
+  return groups
+    .map((g, idx) => {
+      let line = g.join(SEPARATOR);
+      if (idx === groups.length - 1) {
+        const remaining = width - visibleWidth(line) - (line ? SEP_W : 0);
+        const bar = formatContextBar((t, s) => s, pct, remaining);
+        if (bar) line = line ? line + SEPARATOR + bar : bar;
+      }
+      return line;
+    })
+    .map((l) => "\x1b[0m" + l); // put a dummy escape in to exercise stripAnsi below
+}
+
+describe("render glue simulation", () => {
+  it("wide terminal (width 200): single line, nothing clipped, bar exactly fills", () => {
+    const lines = buildLines(200, 12);
+    expect(lines.length).toBe(1);
+    // clamp to terminal — must survive (nothing cut)
+    const clamped = lines[0];
+    expect(stripAnsi(clamped!)).toContain("116k/977k");
+    expect(visibleWidth(stripAnsi(clamped!))).toBeLessThanOrEqual(200);
+    // stats line ends with the bar percentage label
+    expect(stripAnsi(lines[0]!)).toContain("12%");
+  });
+
+  it("user's terminal: one column short of fitting → two lines, nothing lost", () => {
+    const lines = buildLines(158, 12);
+    expect(lines.length).toBe(2);
+    expect(stripAnsi(lines[0]!)).toContain("auth");
+    expect(stripAnsi(lines[0]!)).toContain("feat/plan-"); // worktree on line 1
+    expect(stripAnsi(lines[1]!)).toContain("116k/977k");
+    expect(stripAnsi(lines[1]!)).toContain("12%");
+  });
+
+  it("narrow (width 69): three lines", () => {
+    const lines = buildLines(69, 12, 150);
+    expect(lines.length).toBe(3);
+    const all = lines.map((l) => stripAnsi(l)).join(" | ");
+    expect(all).toContain("116k/977k");
+    expect(all).toContain("12%");
+  });
+
+  it("below splitThreshold but fits in one line → forced two lines", () => {
+    const lines = buildLines(165, 12, 200); // 159 + bar ≤ 165 fits one line; 165 < 200 forces split
+    expect(lines.length).toBe(2);
+  });
+
+  it("very narrow (width 40): bar is dropped, stats still present, no line exceeds 40 cols", () => {
+    const lines = buildLines(40, 12);
+    const stripped = lines.map((l) => stripAnsi(l));
+    // Bar should be dropped — no % sign in any line
+    expect(stripped.every((l) => !l.includes("%"))).toBe(true);
+    // Stats should still appear somewhere
+    const all = stripped.join(" ");
+    expect(all).toContain("116k/977k");
+    // No line exceeds 40 visible columns
+    expect(lines.every((l) => visibleWidth(stripAnsi(l)) <= 40)).toBe(true);
+  });
+});