killeros 1.4.8 → 1.5.0

package/README.md

@@ -33,7 +33,7 @@ pi install git:github.com/KyrosHendrix/pi-KillerOS
 Pin an install to a release:
 
 ```bash
-pi install git:github.com/KyrosHendrix/pi-KillerOS@v1.4.8
+pi install git:github.com/KyrosHendrix/pi-KillerOS@v1.5.0
 ```
 
 Add `-l` to either command for a project-only install. Restart Pi after installing.
@@ -97,13 +97,28 @@ KillerOS ships `planner`, `reviewer`, `scout`, and `security` as read-only roles
 
 The default `agentScope: "user"` uses bundled and personal roles. Use `"project"` or `"both"` to opt into trusted project roles; a selected project override requires interactive confirmation. Role frontmatter requires `name`, `description`, `access`, and an explicit `tools` list. Optional fields are `model`, `thinking`, and `timeoutMs`. Every bundled role shows `model: inherit` and `thinking: inherit` as editable placeholders. Replace them with an available `provider/model` and a separate thinking level when you want to pin a role; `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max` are checked against that model’s supported capabilities.
 
-The tool supports a single `agent` + `task`, parallel `tasks`, or a sequential `chain` whose task text may include `{previous}`. Read-only-only batches run concurrently, up to four at a time. Batches with write-capable roles use one shared pool by default, up to ten tasks at once; set `writerConcurrency` to choose a smaller cap, or set it to `1` to serialize the entire batch. Reader-only batches reject `writerConcurrency` because it does not apply. All children share the parent worktree, so concurrent writers must avoid file conflicts. A call can also set `model` and `thinking` for every task, overriding role settings; use `inherit` to fall back to each role and then the active parent model. The `message` field is only valid with `action: "steer"`. For example:
+The tool supports a single `agent` + `task`, parallel `tasks`, or a sequential `chain` whose task text may include `{previous}`. Read-only-only batches run concurrently, up to four at a time. Batches with write-capable roles use one shared slot by default; set `writerConcurrency` above `1` only after proving path ownership in the shared worktree. Reader-only batches reject `writerConcurrency` because it does not apply. All children share the parent worktree, so concurrent writers must avoid file conflicts. A call can also set `model` and `thinking` for every task, overriding role settings; use `inherit` to fall back to each role and then the active parent model.
+
+| Action | Required fields | Allowed optional fields |
+|---|---|---|
+| omitted / `spawn` single | `agent`, `task` | `model`, `thinking`, `agentScope` |
+| omitted / `spawn` parallel | `tasks` | `writerConcurrency`, `model`, `thinking`, `agentScope` |
+| omitted / `spawn` chain | `chain` | `model`, `thinking`, `agentScope` |
+| `list` | none | none |
+| `inspect` | `threadId` | none |
+| `steer` | `threadId`, `message` | none |
+| `interrupt` one | `threadId` | none |
+| `interrupt` all | `all: true` | none |
+| `collect` | `threadId` | none |
+| `close` | `threadId` | none |
+
+The three spawn shapes cannot be mixed. The `message` field is only valid with `action: "steer"`, and lifecycle actions reject spawn fields. KillerOS rejects malformed requests before role discovery, project confirmation, thread creation, or child launch. The TUI shows a parallel or shared-pool schedule only after shape validation; malformed calls show `invalid request` instead of queued work. For example:
 
 ```json
 {"agent":"reviewer","task":"Review the change","model":"provider/model","thinking":"high"}
 ```
 
-Use the separate `model` and `thinking` fields for new configuration. The older `provider/model:thinking` model form remains accepted. Children run as isolated `pi --mode json -p` processes with a private `--session-dir` and `--session-id`, plus explicit local tools and `web_search`, `source_check`, `fetch_content`, and `get_search_content`. Steering restarts the same child session, so the child keeps its prior conversation. Each child explicitly loads `npm:pi-web-access`, discovers available skills, and keeps arbitrary extensions and prompt templates disabled; project-local skills load only when the parent project is trusted. Every bundled role is instructed to load the most relevant `SKILL.md` and report useful evidence. Children have no default token, dollar, turn, tool-call, research, wall-time, JSONL-line, trace, stderr, or returned-output execution quota. KillerOS bounds retained trace, stderr, and returned text and spills a large JSONL line to temporary storage; retention never stops a child or marks it `limited`. The parent limits each request to ten tasks, read-only-only batches to four concurrent readers, and bounds role files, task input, and combined parent output. An embedding caller may opt into named child resource guards. A parent tool-call abort cancels queued tasks but lets already-running children finish; explicit `interrupt` actions and session shutdown terminate active children and escalate after five seconds.
+Use the separate `model` and `thinking` fields for new configuration. The older `provider/model:thinking` model form remains accepted. Children run as isolated `pi --mode json -p` processes with a private `--session-dir` and `--session-id`, plus explicit local tools and `web_search`, `source_check`, `fetch_content`, and `get_search_content`. Steering restarts the same child session, so the child keeps its prior conversation. Each child explicitly loads `npm:pi-web-access`, discovers available skills, and keeps arbitrary extensions and prompt templates disabled; project-local skills load only when the parent project is trusted. Every bundled role is instructed to load the most relevant `SKILL.md` and report useful evidence. Children have no default token, dollar, turn, tool-call, research, wall-time, trace, stderr, or returned-output execution quota; each JSONL record still has a bounded 8 MiB parser ceiling. KillerOS bounds retained trace, stderr, and returned text and spills a large JSONL line to temporary storage; retention never stops a child or marks it `limited`. The parent limits each request to ten tasks, read-only-only batches to four concurrent readers, and bounds role files, task input, and combined parent output. An embedding caller may opt into named child resource guards. A parent tool-call abort cancels queued tasks but lets already-running children finish; explicit `interrupt` actions and session shutdown terminate active children and escalate after five seconds.
 
 ### Thread lifecycle
 
@@ -111,9 +126,9 @@ Each delegated task creates a named child thread. Its contract records the paren
 
 Threads move through `queued`, `active`, `done`, `failed`, `stopped`, and `closed`. The parent renders separate **Active** and **Done** lists. Active threads show their name, task, model, usage, and direct controls. Done threads keep their handoff and trace available until the parent closes them.
 
-The parent can inspect a thread’s prompt, role, model, tools, trace, usage, and handoff; steer an active thread with one bounded follow-up; interrupt one child or all active children; collect a concise handoff into parent context; and close a finished or stopped thread. An interrupt preserves the partial trace, states the reason, and reports the handoff as partial rather than successful.
+The parent can inspect a thread’s prompt, role, model, tools, trace, usage, and handoff; steer an active thread with one bounded follow-up; interrupt one child or all active children; collect a concise handoff into parent context; and close a finished or stopped thread. An interrupt preserves the partial trace, states the reason, and reports the handoff as partial rather than successful. Closing removes a thread from the active workspace; heavy trace and result payloads are evicted as needed under the bounded retention budget, leaving a small inspectable tombstone.
 
-A child completes naturally when it returns a final answer. The default path has no per-child execution quota. Explicit embedding options can add wall-time, output, trace, stderr, JSONL, token, or cost guards; those guards report their cause and return partial work clearly. The parent still bounds task count, reader concurrency, role files, task input, and combined parent output. Parent tool-call aborts leave active children running while queued work is settled as cancelled; explicit `interrupt` actions and real child-process failures remain visible. Session shutdown still terminates active children and escalates after five seconds.
+A child completes naturally when it returns a final answer. The default path has no per-child execution quota, while every JSONL record has an 8 MiB parser ceiling. Explicit embedding options can add wall-time, output, trace, stderr, JSONL, token, or cost guards; those guards report their cause and return partial work clearly. The parent still bounds task count, reader concurrency, role files, task input, and combined parent output. Parent tool-call aborts leave active children running while queued work is settled as cancelled; explicit `interrupt` actions and real child-process failures remain visible. Session shutdown still terminates active children and escalates after five seconds.
 
 The replacement lifecycle has nine phases:
 
@@ -124,8 +139,8 @@ The replacement lifecycle has nine phases:
 5. **Interrupt:** stop one or all active children while preserving partial work.
 6. **Collect:** return a concise handoff while retaining the expanded trace.
 7. **Guard:** honor only explicitly configured child resource guards; do not impose a routine turn stop.
-8. **Close:** remove a finished or stopped thread from the workspace without deleting its result record.
-9. **Prove:** test identity, visibility, controls, natural completion, guards, partial handoffs, and closure.
+8. **Close:** remove a finished or stopped thread from the workspace while retaining a small inspectable tombstone; heavy payloads may be evicted under the retention budget.
+9. **Prove:** test identity, visibility, controls, natural completion, guards, partial handoffs, bounded retention, and closure.
 
 ## Configuration
 
@@ -163,7 +178,7 @@ The package manifest lists Pi’s built-in modules as peer dependencies, so npm
 
 The [`pi-package`](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/packages.md) keyword makes a published npm release visible in Pi’s package catalog.
 
-For release `1.4.8`, publish after the validation checks pass:
+For release `1.5.0`, publish after the validation checks pass:
 
 ```bash
 npm login

package/killeros/commands.ts

@@ -0,0 +1,164 @@
+import { type ExtensionAPI, type ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import type { AutocompleteItem } from "@earendil-works/pi-tui";
+
+async function confirmNewSession(ctx: ExtensionCommandContext): Promise<boolean> {
+  if (!ctx.hasUI) return true;
+  return ctx.ui.confirm("Start new session", "Start a new session and leave the current history?");
+}
+
+export function registerAliases(pi: ExtensionAPI): void {
+  const startNewSession = async (_args: string, ctx: ExtensionCommandContext): Promise<void> => {
+    await ctx.waitForIdle();
+    if (!await confirmNewSession(ctx)) return;
+    await ctx.newSession();
+  };
+  pi.registerCommand("clear", { description: "Start a new session after confirmation", handler: startNewSession });
+  pi.registerCommand("exit", {
+    description: "Quit Pi gracefully",
+    handler: async (_args, ctx) => ctx.shutdown(),
+  });
+}
+
+interface CommandInfo {
+  name: string;
+  description?: string;
+  category: "Built-in" | "Extension" | "Prompt" | "Skill";
+  syntaxHint?: string;
+}
+
+const BUILTIN_COMMANDS: ReadonlyArray<{ name: string; description: string }> = [
+  { name: "settings", description: "Open settings menu" },
+  { name: "model", description: "Select model" },
+  { name: "scoped-models", description: "Configure models for Ctrl+P cycling" },
+  { name: "export", description: "Export the current session" },
+  { name: "import", description: "Import and resume a JSONL session" },
+  { name: "share", description: "Share the session as a secret GitHub gist" },
+  { name: "copy", description: "Copy the last agent message" },
+  { name: "name", description: "Set the session display name" },
+  { name: "session", description: "Show session usage and stats" },
+  { name: "changelog", description: "Show changelog entries" },
+  { name: "hotkeys", description: "Show keyboard shortcuts" },
+  { name: "fork", description: "Fork from a previous user message" },
+  { name: "clone", description: "Duplicate the session at the current position" },
+  { name: "tree", description: "Navigate the session tree" },
+  { name: "trust", description: "Save the project trust decision" },
+  { name: "login", description: "Configure provider authentication" },
+  { name: "logout", description: "Remove provider authentication" },
+  { name: "new", description: "Start a new session" },
+  { name: "compact", description: "Compact the session context" },
+  { name: "resume", description: "Resume a different session" },
+  { name: "reload", description: "Reload extensions and resources" },
+  { name: "quit", description: "Quit Pi" },
+];
+
+const COMMAND_SYNTAX_HINTS: Readonly<Record<string, string>> = {
+  goal: "/goal [objective|clear|edit|pause|resume]",
+  variants: "/variants [level]",
+  model: "/model [provider/model]",
+  "scoped-models": "/scoped-models",
+  login: "/login [provider]",
+  export: "/export [filename]",
+  import: "/import [path]",
+  name: "/name [session-name]",
+};
+
+interface TaggedAutocompleteItem extends AutocompleteItem {
+  killerosCommand?: string;
+}
+
+function scoreCommandMatch(name: string, prefix: string): number {
+  if (!prefix) return 1;
+  const normalizedName = name.toLocaleLowerCase();
+  const normalizedPrefix = prefix.toLocaleLowerCase();
+  if (normalizedName.startsWith(normalizedPrefix)) return 100;
+  if (normalizedName.split(/[:\-_]/).some((token) => token.startsWith(normalizedPrefix))) return 80;
+  if (normalizedName.includes(normalizedPrefix)) return 50;
+  return 0;
+}
+
+export function registerSlashAutocomplete(pi: ExtensionAPI): void {
+  const usage = new Map<string, number>();
+  pi.on("session_start", (_event, ctx) => {
+    if (ctx.mode !== "tui") return;
+    ctx.ui.addAutocompleteProvider((current) => ({
+      triggerCharacters: ["/"],
+      async getSuggestions(lines, cursorLine, cursorCol, options) {
+        const line = lines[cursorLine] ?? "";
+        const beforeCursor = line.slice(0, cursorCol);
+        const match = beforeCursor.match(/(?:^|[ \t])\/([^\s/]*)$/);
+        if (!match) return current.getSuggestions(lines, cursorLine, cursorCol, options);
+
+        const prefix = (match[1] ?? "").toLocaleLowerCase();
+        const baseSuggestions = await current.getSuggestions(lines, cursorLine, cursorCol, options);
+        const commands = new Map<string, CommandInfo>();
+        BUILTIN_COMMANDS.forEach((command) => commands.set(command.name, {
+          ...command,
+          category: "Built-in",
+          syntaxHint: COMMAND_SYNTAX_HINTS[command.name],
+        }));
+
+        for (const command of pi.getCommands()) {
+          const category: CommandInfo["category"] = command.source === "skill"
+            ? "Skill"
+            : command.source === "prompt"
+              ? "Prompt"
+              : "Extension";
+          commands.set(command.name, {
+            name: command.name,
+            description: command.description,
+            category,
+            syntaxHint: COMMAND_SYNTAX_HINTS[command.name],
+          });
+        }
+
+        for (const item of baseSuggestions?.items ?? []) {
+          const name = (item.value || item.label).replace(/^\//, "").trim().split(/\s+/)[0] ?? "";
+          if (name && !commands.has(name)) {
+            commands.set(name, { name, description: item.description, category: "Built-in" });
+          }
+        }
+
+        const ranked = [...commands.values()]
+          .map((command) => ({
+            command,
+            score: scoreCommandMatch(command.name, prefix) + Math.min((usage.get(command.name) ?? 0) * 2, 15),
+          }))
+          .filter(({ command }) => scoreCommandMatch(command.name, prefix) > 0)
+          .sort((left, right) => right.score - left.score || left.command.name.localeCompare(right.command.name));
+        if (!ranked.length) return baseSuggestions;
+
+        return {
+          prefix: `/${prefix}`,
+          items: ranked.map(({ command }): TaggedAutocompleteItem => {
+            const syntax = command.syntaxHint ? `${command.syntaxHint} — ` : "";
+            return {
+              value: `/${command.name} `,
+              label: `/${command.name}`,
+              description: `[${command.category}] ${syntax}${command.description ?? ""}`.trim(),
+              killerosCommand: command.name,
+            };
+          }),
+        };
+      },
+      applyCompletion(lines, cursorLine, cursorCol, item, prefix) {
+        const tagged = item as TaggedAutocompleteItem;
+        if (!tagged.killerosCommand) return current.applyCompletion(lines, cursorLine, cursorCol, item, prefix);
+        usage.set(tagged.killerosCommand, (usage.get(tagged.killerosCommand) ?? 0) + 1);
+        const line = lines[cursorLine] ?? "";
+        const beforeCursor = line.slice(0, cursorCol);
+        let afterCursor = line.slice(cursorCol);
+        const match = beforeCursor.match(/(?:^|[ \t])\/([^\s/]*)$/);
+        if (!match || match.index === undefined) return current.applyCompletion(lines, cursorLine, cursorCol, item, prefix);
+        const slashIndex = match.index + (match[0].startsWith("/") ? 0 : 1);
+        const newBefore = beforeCursor.slice(0, slashIndex) + item.value;
+        if (item.value.endsWith(" ") && afterCursor.startsWith(" ")) afterCursor = afterCursor.trimStart();
+        const nextLines = [...lines];
+        nextLines[cursorLine] = newBefore + afterCursor;
+        return { lines: nextLines, cursorLine, cursorCol: newBefore.length };
+      },
+      shouldTriggerFileCompletion(lines, cursorLine, cursorCol) {
+        return current.shouldTriggerFileCompletion?.(lines, cursorLine, cursorCol) ?? true;
+      },
+    }));
+  });
+}

package/killeros/concise.ts

@@ -0,0 +1,23 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+export const CONCISE_SYSTEM_PROMPT = `
+# Concise output rules
+1. Start with the answer or next action; omit conversational preambles.
+2. Use numbered steps only when order matters, with one bounded action per step.
+3. Finish the primary task before mentioning optional follow-up work.
+4. State failures directly and include the recovery action.
+5. Keep lists focused; group long inventories under clear headings.
+6. Do not invent time estimates, completion claims, or facts.
+7. Preserve exact code, commands, paths, quoted text, warnings, and user-requested formats.
+8. Omit recap sections and generic closing pleasantries.
+`.trim();
+
+export function isConcisedEnabled(): boolean {
+  return true;
+}
+
+export function registerConcisePrompt(pi: ExtensionAPI): void {
+  pi.on("before_agent_start", (event) => ({
+    systemPrompt: `${event.systemPrompt}\n\n${CONCISE_SYSTEM_PROMPT}`,
+  }));
+}

package/killeros/display.ts

@@ -0,0 +1,39 @@
+import os from "node:os";
+import { truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+
+export function formatCwd(cwd: string): string {
+  const home = process.env.HOME || process.env.USERPROFILE || os.homedir();
+  if (!home) return cwd;
+  const normalizedHome = home.replace(/[\\/]+$/, "");
+  const normalizedCwd = cwd.replace(/[\\/]+$/, "");
+  if (normalizedCwd === normalizedHome) return "~";
+  const separator = normalizedCwd.slice(normalizedHome.length, normalizedHome.length + 1);
+  return normalizedCwd.startsWith(normalizedHome) && (separator === "/" || separator === "\\")
+    ? `~${normalizedCwd.slice(normalizedHome.length)}`
+    : cwd;
+}
+
+export function padRight(text: string, width: number): string {
+  if (width <= 0) return "";
+  const clipped = truncateToWidth(text, width, "");
+  return clipped + " ".repeat(Math.max(0, width - visibleWidth(clipped)));
+}
+
+export function formatTime(milliseconds: number): string {
+  const totalSeconds = Math.max(0, Math.floor(milliseconds / 1_000));
+  if (totalSeconds < 60) return `${totalSeconds}s`;
+  const minutes = Math.floor(totalSeconds / 60);
+  if (minutes < 60) return `${minutes}m`;
+  return `${Math.floor(minutes / 60)}h${minutes % 60}m`;
+}
+
+export function formatTokens(value: number): string {
+  const amount = Math.max(0, value);
+  if (amount < 1_000) return `${Math.round(amount)}`;
+  if (amount >= 1_000_000) {
+    const precision = amount >= 10_000_000 ? 0 : 1;
+    return `${Number((amount / 1_000_000).toFixed(precision))}M`;
+  }
+  const precision = amount >= 100_000 ? 0 : 1;
+  return `${Number((amount / 1_000).toFixed(precision))}k`;
+}

package/killeros/errors.ts

@@ -0,0 +1,6 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+export function reportError(ctx: ExtensionContext, area: string, error: unknown): void {
+  const message = error instanceof Error ? error.message : String(error);
+  ctx.ui.notify(`${area}: ${message}`, "error");
+}

package/killeros/footer.ts

@@ -0,0 +1,209 @@
+import { DynamicBorder, type ExtensionAPI, type ExtensionContext, type Theme, type ThemeColor } from "@earendil-works/pi-coding-agent";
+import { Container, Text, truncateToWidth, visibleWidth, type TUI } from "@earendil-works/pi-tui";
+import { formatCwd, formatTime, formatTokens, padRight } from "./display.ts";
+import { goalElapsedMilliseconds } from "./goals.ts";
+import type { GoalRuntime, GoalState } from "./runtime.ts";
+import { LEVEL_COLORS, type ThinkingLevel } from "./variants.ts";
+
+const FOOTER_REFRESH_INTERVAL_MS = 1_000;
+
+export function formatCost(usd: number): string {
+  if (!Number.isFinite(usd)) return "$—";
+  return `$${usd.toFixed(2)}`;
+}
+
+export function formatContextProgress(tokensUsed: number | null, contextWindow: number, theme: Theme): string {
+  if (tokensUsed === null) return theme.fg("dim", "—% left (—)");
+  const windowSize = contextWindow > 0 ? contextWindow : 128_000;
+  const remaining = Math.max(0, Math.min(windowSize, windowSize - Math.max(0, tokensUsed)));
+  const percentLeft = Math.max(0, Math.min(100, Math.round((remaining / windowSize) * 100)));
+  const color: ThemeColor = percentLeft < 20 ? "error" : percentLeft <= 50 ? "warning" : "success";
+  const action = percentLeft < 15 ? " · /compact" : "";
+  return theme.fg(color, `${percentLeft}% left (${formatTokens(remaining)})${action}`);
+}
+
+function sumSessionCost(ctx: ExtensionContext): number {
+  let total = 0;
+  for (const entry of ctx.sessionManager.getEntries()) {
+    if (entry.type === "message" && entry.message.role === "assistant") total += entry.message.usage.cost.total;
+    else if (entry.type === "message" && entry.message.role === "toolResult" && entry.message.usage) {
+      total += entry.message.usage.cost.total;
+    } else if ((entry.type === "compaction" || entry.type === "branch_summary") && entry.usage) {
+      total += entry.usage.cost.total;
+    }
+  }
+  return total;
+}
+
+const PROVIDER_LABELS: Readonly<Record<string, string>> = {
+  "amazon-bedrock": "Amazon Bedrock",
+  "azure-openai-responses": "Azure OpenAI",
+  "github-copilot": "GitHub Copilot",
+  "google-vertex": "Google Vertex",
+  "openai-codex": "OpenAI",
+  anthropic: "Anthropic",
+  deepseek: "DeepSeek",
+  google: "Google",
+  ollama: "Ollama",
+  openai: "OpenAI",
+  openrouter: "OpenRouter",
+};
+
+const PROVIDER_WORDS: Readonly<Record<string, string>> = {
+  ai: "AI",
+  api: "API",
+  deepseek: "DeepSeek",
+  github: "GitHub",
+  llm: "LLM",
+  openai: "OpenAI",
+  openrouter: "OpenRouter",
+};
+
+function formatProviderName(provider: string): string {
+  const normalized = provider.trim();
+  const known = PROVIDER_LABELS[normalized.toLocaleLowerCase()];
+  if (known) return known;
+  return normalized
+    .split(/[-_]+/u)
+    .filter(Boolean)
+    .map((word) => PROVIDER_WORDS[word.toLocaleLowerCase()] ?? `${word.charAt(0).toLocaleUpperCase()}${word.slice(1)}`)
+    .join(" ") || "Unknown provider";
+}
+
+function modelDisplayName(model: NonNullable<ExtensionContext["model"]>): string {
+  return model.name?.trim() || model.id;
+}
+
+export function formatModel(model: ExtensionContext["model"], theme: Theme, includeProvider = true): string {
+  if (!model) return theme.fg("dim", "No model");
+  const name = theme.fg("text", theme.bold(modelDisplayName(model)));
+  return includeProvider ? `${name} ${theme.fg("dim", formatProviderName(model.provider))}` : name;
+}
+
+function compactDirectory(cwd: string): string {
+  if (cwd === "~" || cwd === "/" || /^[A-Za-z]:[\\/]?$/u.test(cwd)) return cwd;
+  const normalized = cwd.replace(/\\/gu, "/").replace(/\/$/u, "");
+  const finalSegment = normalized.split("/").at(-1);
+  return finalSegment ? `…/${finalSegment}` : cwd;
+}
+
+function joinFooterParts(parts: string[], theme: Theme): string {
+  return parts.filter(Boolean).join(theme.fg("dim", " · "));
+}
+
+function footerRowFits(left: string, right: string, width: number): boolean {
+  const contentWidth = visibleWidth(left) + (right ? visibleWidth(right) + 1 : 0);
+  return contentWidth + 2 <= width;
+}
+
+function renderFooterRow(left: string, right: string, width: number): string {
+  if (width <= 0) return "";
+  if (width < 3) return " ".repeat(width);
+
+  const innerWidth = width - 2;
+  if (!right) return ` ${padRight(left, innerWidth)} `;
+
+  const clippedRight = truncateToWidth(right, innerWidth, "");
+  const rightWidth = visibleWidth(clippedRight);
+  const leftBudget = Math.max(0, innerWidth - rightWidth - 1);
+  const clippedLeft = truncateToWidth(left, leftBudget, "…");
+  const gap = " ".repeat(Math.max(0, innerWidth - visibleWidth(clippedLeft) - rightWidth));
+  return ` ${clippedLeft}${gap}${clippedRight} `;
+}
+
+function formatGoalFooter(state: GoalState | undefined, theme: Theme): string {
+  if (!state) return "";
+  if (state.status === "active") return theme.fg("accent", `✻ goal · ${formatTime(goalElapsedMilliseconds(state))}`);
+  if (state.status === "paused") return theme.fg("warning", "Ⅱ goal paused");
+  if (state.status === "blocked") return theme.fg("error", "! goal blocked");
+  return theme.fg("success", "✓ goal complete");
+}
+
+export function registerFooter(pi: ExtensionAPI, goalRuntime: GoalRuntime): void {
+  let currentModel: ExtensionContext["model"];
+  let thinkingLevel: ThinkingLevel = "off";
+  let activeTui: TUI | undefined;
+  goalRuntime.requestRender = () => activeTui?.requestRender();
+
+  pi.on("session_start", (_event, ctx) => {
+    if (ctx.mode !== "tui") return;
+    const sessionStart = Date.now();
+    currentModel = ctx.model;
+    thinkingLevel = pi.getThinkingLevel() as ThinkingLevel;
+    const cwd = formatCwd(ctx.cwd);
+
+    ctx.ui.setFooter((tui, theme, footerData) => {
+      activeTui = tui;
+      const unsubscribe = footerData.onBranchChange(() => tui.requestRender());
+      const refreshTimer = setInterval(() => tui.requestRender(), FOOTER_REFRESH_INTERVAL_MS);
+      refreshTimer.unref?.();
+      return {
+        dispose() {
+          unsubscribe();
+          clearInterval(refreshTimer);
+          if (activeTui === tui) activeTui = undefined;
+        },
+        invalidate() {},
+        render(width: number): string[] {
+          if (width <= 0) return [];
+          const model = currentModel ?? ctx.model;
+          const level = model?.reasoning === false
+            ? theme.fg("thinkingOff", "no reasoning")
+            : theme.fg(LEVEL_COLORS[thinkingLevel], thinkingLevel);
+          const usage = ctx.getContextUsage();
+          const contextWindow = usage?.contextWindow ?? model?.contextWindow ?? 128_000;
+          const context = formatContextProgress(usage?.tokens ?? null, contextWindow, theme);
+          const branch = footerData.getGitBranch();
+          const signature = formatModel(model, theme);
+          const fullDirectory = theme.fg("dim", cwd);
+          const focusedDirectory = theme.fg("dim", compactDirectory(cwd));
+          const goal = formatGoalFooter(goalRuntime.state, theme);
+          const rich = joinFooterParts([
+            signature,
+            level,
+            context,
+            goal,
+            branch ? theme.fg("dim", branch) : "",
+            theme.fg("dim", formatTime(Date.now() - sessionStart)),
+            theme.fg("dim", formatCost(sumSessionCost(ctx))),
+          ], theme);
+          const focused = joinFooterParts([signature, context, goal], theme);
+
+          if (footerRowFits(rich, fullDirectory, width)) {
+            return [renderFooterRow(rich, fullDirectory, width)];
+          }
+          if (footerRowFits(rich, focusedDirectory, width)) {
+            return [renderFooterRow(rich, focusedDirectory, width)];
+          }
+          if (footerRowFits(focused, focusedDirectory, width)) {
+            return [renderFooterRow(focused, focusedDirectory, width)];
+          }
+          if (footerRowFits(focused, "", width)) {
+            return [renderFooterRow(focused, "", width)];
+          }
+          if (goal) {
+            const essentialGoal = joinFooterParts([context, goal], theme);
+            if (footerRowFits(essentialGoal, "", width)) return [renderFooterRow(essentialGoal, "", width)];
+            return [renderFooterRow(goal, context, width)];
+          }
+
+          const essentialModel = formatModel(model, theme, false);
+          return [renderFooterRow(essentialModel, context, width)];
+        },
+      };
+    });
+  });
+
+  pi.on("model_select", (event) => {
+    currentModel = event.model;
+    activeTui?.requestRender();
+  });
+  pi.on("thinking_level_select", (event) => {
+    thinkingLevel = event.level;
+    activeTui?.requestRender();
+  });
+  pi.on("session_shutdown", () => {
+    activeTui = undefined;
+    goalRuntime.requestRender = undefined;
+  });
+}