pi-skill-stacks 0.4.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 oscabriel
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,111 @@
+# pi-skill-stacks
+
+A [pi](https://github.com/earendil-works/pi-mono) package that groups your skills into named stacks you can toggle on and off, so an agent session only pays for the skills it needs. `/stacks` opens an overlay; disabled skills vanish from the system prompt, `/skill:` commands, and discovery.
+
+## What it does
+
+- `/stacks` opens a two-pane overlay. Left: stacks with on/off state, create (`n`), delete (`d`), and `a` to add skills that aren't in any stack yet. Right: the selected stack's members; `space` removes one, `enter` opens the skill's full markdown in a viewer pane. So you can build and edit stacks without touching JSON. Changes persist as you make them; pi reloads once when you close the overlay, and only if a toggle actually changed `settings.json`.
+- `/stacks on <stack>` / `/stacks off <stack>` toggle a single stack (with argument completion); `/stacks list` prints state without changing anything. Bare `/stacks` outside the TUI (RPC/print mode) prints the list too.
+- Toggling off writes `!skills/<dir>/SKILL.md` exclusion patterns into the global settings `skills` array — pi's own override mechanism — so disabled skills are excluded everywhere, not just from the prompt. The extension only ever removes patterns it wrote itself (tracked in `managedExclusions`); hand-written `pi config` entries are left alone.
+- The bundled header extension replaces pi's startup `[Skills]` listing with a compact line like `matt-pocock (28), firecrawl (28) · 76/76 skills active` (with `off: <name> (n)` segments for disabled stacks) and hides the `[Themes]` section.
+
+## Install
+
+```bash
+pi install npm:pi-skill-stacks
+```
+
+or from git:
+
+```bash
+pi install git:github.com/oscabriel/pi-skill-stacks
+```
+
+Or from a local checkout:
+
+```bash
+pi install /path/to/pi-skill-stacks
+```
+
+Use `-l` to install project-local instead of global. Try it without installing:
+
+```bash
+pi -e git:github.com/oscabriel/pi-skill-stacks
+```
+
+## Configure stacks
+
+The package ships with no stacks. Open `/stacks` and press `n` to create one, or write `~/.pi/agent/skill-stacks.json` (or `<agentDir>/skill-stacks.json`; `PI_CODING_AGENT_DIR` is honoured like pi does) by hand:
+
+```json
+{
+  "stacks": {
+    "frontend": ["react", "tailwind", "vite"],
+    "writing": ["writing-beats", "writing-fragments"]
+  }
+}
+```
+
+Each stack maps a name to skill names. Skills are discovered the way pi discovers them: every `SKILL.md` under `~/.agents/skills/` and `<agentDir>/skills/`, recursing into subdirectories (skipping dot-directories and `node_modules`), named by the frontmatter `name` or, failing that, the directory name. Nested skills get full-path exclusion patterns such as `!skills/group/nested/SKILL.md`.
+
+A project can add or override stack definitions in `<project>/.pi/skill-stacks.json`. Project stacks contribute definitions only; on/off state is global. In the overlay they can be toggled but not edited or deleted — edit the project file instead.
+
+The config file is validated on every load. A malformed entry (a stack that isn't an array, invalid JSON, and so on) aborts the command with an error and nothing is written, rather than defaulting to an empty config and saving that back.
+
+## Overlay keys
+
+Navigation is consistent across panes: `←`/`esc` always goes back a pane, `→`/`tab` (or `enter` on a member) always goes forward. `←` in the leftmost pane and `→` in the viewer do nothing.
+
+| Pane | Keys |
+| --- | --- |
+| stacks | `↑`/`↓` (or `k`/`j`) select · `space` on/off · `→`/`l`/`tab`/`enter` into members · `a` add skills · `n` new stack · `d` delete · `esc`/`q` close |
+| members | `↑`/`↓` (or `k`/`j`) move · `space` remove the skill · `enter`/`→`/`tab` view skill · `a` add skills · `←`/`h`/`esc` back to stacks |
+| skill viewer | `↑`/`↓` (or `k`/`j`) scroll · `enter`/`←`/`h`/`esc` back to members |
+| add skills dialog | `↑`/`↓` move · `space` mark · `enter` add the marked skills (or the highlighted one) · `esc` cancel |
+| new stack / delete dialogs | `enter` confirm · `esc` cancel |
+
+The `a`, `n` and `d` dialogs open as small overlays on top of `/stacks`. `a` lists only skills that no stack holds yet. To move a skill between stacks, `space` it out of one and `a` it into the other.
+
+In fullscreen TUI mode the mouse wheel scrolls the skill viewer when the pointer is over the overlay. In regular mode the terminal owns the mouse and wheel input goes to its own scrollback.
+
+`enter` in the members pane opens the skill's full markdown in a viewer pane inside the overlay: frontmatter dim, headings bold, bullets and indented code rendered, links shown as their text.
+
+The title bar shows `reload pending` once a change has touched `settings.json`; the reload runs when you close the overlay.
+
+## Rules
+
+- **Overlap:** a skill is excluded only when it appears in at least one stack and no enabled stack contains it. Skills in no stack are never touched. So disabling a stack whose members all also belong to an enabled stack excludes nothing.
+- **Stacks, not skills:** `on`/`off` take stack names only. To exclude a single skill regardless of stacks, use `pi config` (its `!` entries are respected and never claimed).
+- **Persist-then-reload:** `on`/`off` commands write immediately and reload if `settings.json` changed. In the overlay every change is written as you make it and a single reload runs on close, again only if `settings.json` changed; re-stacking alone doesn't need one (the header line catches up on the next reload).
+- **Other projects' stacks:** a project stack you disabled from inside its project stays disabled when you toggle things elsewhere. Its `disabledStacks` entry and the exclusions written for its skills are preserved, because from another directory those skills are "in no stack" and so left alone.
+
+## Header
+
+The header extension swaps pi's full skills listing for a compact summary and hides `[Themes]`. It also replaces the stock header banner with a minimal one-line directory label. If you run your own header extension (custom art, dashboard, and so on), disable this one and keep yours — add a filter to the package entry in `settings.json`:
+
+```json
+{
+  "packages": [
+    {
+      "source": "git:github.com/oscabriel/pi-skill-stacks",
+      "extensions": ["!extensions/header.ts"]
+    }
+  ]
+}
+```
+
+Your header extension can import the section machinery from this package's `extensions/header.ts` to render the same compact line itself: `buildSkillsSection(cwd, theme)` builds the node, `replaceSkillsSection(root, node)` and `hideThemesSection(root)` splice pi's sections, `isOurSection`, `firstLineOf`, and `renderedText` are the matchers, and `SectionTheme`/`RenderableNode` are the structural types they take.
+
+## Notes
+
+- If a stack references skill names that don't resolve to a discovered skill, every `/stacks` invocation warns with the missing names, and the overlay flags them inline as `missing`.
+- Counts in the overlay and header only include discovered skills, so a stale name doesn't inflate the numbers.
+- `settings.json` is rewritten without a trailing newline to match pi's own formatting; `skill-stacks.json` ends with one.
+
+## Develop
+
+```bash
+npm install        # dev-only: pi's type declarations for tsc
+npm run check      # typecheck
+npm test           # node --test
+```

package/extensions/dialogs.ts

@@ -0,0 +1,182 @@
+// Small dialogs the /stacks overlay opens on top of itself. pi's own
+// ctx.ui.input/confirm render in the main layout, underneath any visible
+// overlay, so these are overlays in their own right: opened with
+// ctx.ui.custom({ overlay: true }) they stack above /stacks, take focus while
+// open, and hand it back when done.
+
+import { type Component, type Focusable, Input, Key, matchesKey } from "@earendil-works/pi-tui";
+import { frameEdge, frameInnerWidth, frameRow, type OverlayTheme, padToWidth } from "./frame.ts";
+
+/** Single-line text prompt. Resolves with the trimmed value, or undefined on escape. */
+export class PromptDialog implements Component, Focusable {
+  private readonly input = new Input();
+  private _focused = false;
+  private readonly theme: OverlayTheme;
+  private readonly title: string;
+  private readonly placeholder: string | undefined;
+  private readonly done: (value: string | undefined) => void;
+
+  constructor(
+    theme: OverlayTheme,
+    title: string,
+    placeholder: string | undefined,
+    done: (value: string | undefined) => void,
+  ) {
+    this.theme = theme;
+    this.title = title;
+    this.placeholder = placeholder;
+    this.done = done;
+  }
+
+  /** Propagate focus to the Input so it emits the hardware-cursor marker (IME placement). */
+  get focused() {
+    return this._focused;
+  }
+
+  set focused(value: boolean) {
+    this._focused = value;
+    this.input.focused = value;
+  }
+
+  handleInput(data: string) {
+    if (matchesKey(data, Key.enter) || data === "\n") {
+      this.done(this.input.getValue().trim());
+    } else if (matchesKey(data, Key.escape)) {
+      this.done(undefined);
+    } else {
+      this.input.handleInput(data);
+    }
+  }
+
+  invalidate() {}
+
+  render(width: number) {
+    const inner = frameInnerWidth(width);
+    const [inputLine = ""] = this.input.render(inner);
+    const showPlaceholder = this.placeholder && this.input.getValue() === "";
+    return [
+      frameEdge(this.theme, width, this.title, true),
+      frameRow(this.theme, width, ""),
+      frameRow(this.theme, width, inputLine),
+      frameRow(this.theme, width, showPlaceholder ? this.theme.fg("dim", `  ${this.placeholder}`) : ""),
+      frameEdge(this.theme, width, "enter confirm · esc cancel", false),
+    ];
+  }
+}
+
+/** Yes/no confirmation. Resolves true on enter, false on escape. */
+export class ConfirmDialog implements Component {
+  private readonly theme: OverlayTheme;
+  private readonly title: string;
+  private readonly message: string;
+  private readonly done: (confirmed: boolean) => void;
+
+  constructor(theme: OverlayTheme, title: string, message: string, done: (confirmed: boolean) => void) {
+    this.theme = theme;
+    this.title = title;
+    this.message = message;
+    this.done = done;
+  }
+
+  handleInput(data: string) {
+    if (matchesKey(data, Key.enter) || data === "\n") {
+      this.done(true);
+    } else if (matchesKey(data, Key.escape)) {
+      this.done(false);
+    }
+  }
+
+  invalidate() {}
+
+  render(width: number) {
+    return [
+      frameEdge(this.theme, width, this.title, true),
+      frameRow(this.theme, width, ""),
+      frameRow(this.theme, width, this.theme.fg("text", this.message)),
+      frameRow(this.theme, width, ""),
+      frameEdge(this.theme, width, "enter confirm · esc cancel", false),
+    ];
+  }
+}
+
+/**
+ * Pick one or more skills from a list. `space` marks, `enter` resolves with the
+ * marked set (or just the highlighted skill when nothing is marked), `esc`
+ * resolves undefined.
+ */
+export class PickDialog implements Component {
+  static readonly MAX_ROWS = 16;
+
+  private readonly theme: OverlayTheme;
+  private readonly title: string;
+  private readonly items: readonly string[];
+  private readonly done: (picked: string[] | undefined) => void;
+  private readonly marked = new Set<string>();
+  private cursor = 0;
+  private offset = 0;
+
+  constructor(
+    theme: OverlayTheme,
+    title: string,
+    items: readonly string[],
+    done: (picked: string[] | undefined) => void,
+  ) {
+    this.theme = theme;
+    this.title = title;
+    this.items = items;
+    this.done = done;
+  }
+
+  handleInput(data: string) {
+    if (matchesKey(data, Key.enter) || data === "\n") {
+      const highlighted = this.items[this.cursor];
+      const picked = this.marked.size > 0 ? this.items.filter((s) => this.marked.has(s)) : highlighted ? [highlighted] : [];
+      this.done(picked);
+    } else if (matchesKey(data, Key.escape)) {
+      this.done(undefined);
+    } else if (matchesKey(data, Key.down) || data === "j") {
+      this.move(1);
+    } else if (matchesKey(data, Key.up) || data === "k") {
+      this.move(-1);
+    } else if (data === " ") {
+      const skill = this.items[this.cursor];
+      if (!skill) return;
+      if (this.marked.has(skill)) this.marked.delete(skill);
+      else this.marked.add(skill);
+    }
+  }
+
+  invalidate() {}
+
+  render(width: number) {
+    const rows = this.visibleRows();
+    const lines = [frameEdge(this.theme, width, this.title, true)];
+    for (let row = 0; row < rows; row += 1) {
+      const index = this.offset + row;
+      const skill = this.items[index];
+      lines.push(frameRow(this.theme, width, skill ? this.cell(skill, index, frameInnerWidth(width)) : ""));
+    }
+    const marked = this.marked.size > 0 ? ` · ${this.marked.size} marked` : "";
+    lines.push(frameEdge(this.theme, width, `↑↓ move · space mark · enter add${marked} · esc cancel`, false));
+    return lines;
+  }
+
+  private visibleRows() {
+    return Math.max(1, Math.min(PickDialog.MAX_ROWS, this.items.length));
+  }
+
+  private move(delta: number) {
+    if (this.items.length === 0) return;
+    this.cursor = Math.max(0, Math.min(this.items.length - 1, this.cursor + delta));
+    const rows = this.visibleRows();
+    if (this.cursor < this.offset) this.offset = this.cursor;
+    else if (this.cursor >= this.offset + rows) this.offset = this.cursor - rows + 1;
+  }
+
+  private cell(skill: string, index: number, width: number) {
+    const selected = index === this.cursor;
+    const box = this.marked.has(skill) ? "[x]" : "[ ]";
+    const text = padToWidth(`${selected ? "› " : "  "}${box} ${skill}`, width);
+    return selected ? this.theme.bg("selectedBg", this.theme.fg("accent", text)) : this.theme.fg("text", text);
+  }
+}

package/extensions/frame.ts

@@ -0,0 +1,39 @@
+// Shared drawing helpers for the /stacks overlay and its dialogs. Every helper
+// returns lines of exactly the requested width so overlays keep a straight edge.
+
+import type { ThemeColor } from "@earendil-works/pi-coding-agent";
+import { truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+
+/** Minimal slice of pi's Theme the overlay touches (kept small so tests can fake it). */
+export interface OverlayTheme {
+  fg(color: ThemeColor, text: string): string;
+  bg(color: "selectedBg" | "customMessageBg", text: string): string;
+  bold(text: string): string;
+}
+
+/** Truncate or right-pad `text` to exactly `width` columns. */
+export function padToWidth(text: string, width: number) {
+  const truncated = truncateToWidth(text, width, "");
+  return `${truncated}${" ".repeat(Math.max(0, width - visibleWidth(truncated)))}`;
+}
+
+/** `┌─ label ────┐` or `└─ label ────┘`, exactly `width` wide. */
+export function frameEdge(theme: OverlayTheme, width: number, label: string, top: boolean) {
+  const left = top ? "┌" : "└";
+  const right = top ? "┐" : "┘";
+  const text = `─ ${label} `;
+  const remaining = Math.max(0, width - visibleWidth(text) - 2);
+  return theme.fg(
+    "borderAccent",
+    truncateToWidth(`${left}${text}${"─".repeat(remaining)}${right}`, width, ""),
+  );
+}
+
+/** `│ content │` with one column of padding inside each border, exactly `width` wide. */
+export function frameRow(theme: OverlayTheme, width: number, content: string) {
+  const edge = theme.fg("borderAccent", "│");
+  return padToWidth(`${edge} ${padToWidth(content, frameInnerWidth(width))} ${edge}`, width);
+}
+
+/** Width available to content inside `frameRow`. */
+export const frameInnerWidth = (width: number) => Math.max(0, width - 4);

package/extensions/header.ts

@@ -0,0 +1,262 @@
+/**
+ * pi-skill-stacks header extension: replaces pi's startup `[Skills]` section
+ * with a compact one-line summary (e.g. `matt-pocock (28), firecrawl (28) ·
+ * 76/76 skills active`), hides the `[Themes]` section, and renders a minimal
+ * one-line banner in place of pi's stock header.
+ *
+ * Disable this file (settings.json package filter `!extensions/header.ts`) to
+ * keep your own header extension; the /stacks command extension is unaffected.
+ * The section-building helpers are exported so a custom header can reuse them.
+ *
+ * Mechanism notes:
+ * - pi's startup sections are childless leaves inside one container. The
+ *   container's first rendered line can itself be "[Skills]" (when no
+ *   [Context] section precedes it), so matchers require !hasChildren.
+ * - showLoadedResources runs after extension session_start handlers, so
+ *   post-paint sweeps alone flash the full listing for a frame. addChild
+ *   wrapping swaps our node in at insertion time instead. Timed sweeps stay
+ *   as fallback for late installs; resources_discover re-runs the walk.
+ */
+import { homedir } from "node:os";
+import { isAbsolute, relative } from "node:path";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Text, truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+import { loadStacksSummary } from "../src/store.ts";
+
+export interface RenderableNode {
+  children?: RenderableNode[];
+  addChild?(component: RenderableNode): void;
+  invalidate(): void;
+  render(width: number): string[];
+}
+
+/** Subset of pi's Theme we use; the real Theme is assignable to it. */
+export interface SectionTheme {
+  fg(color: "mdHeading" | "dim", text: string): string;
+}
+
+export interface DashboardTui extends RenderableNode {
+  requestRender(force?: boolean): void;
+}
+
+const RESET = "\x1b[0m";
+const BOLD = "\x1b[1m";
+const DIM = "\x1b[2m";
+const ANSI_PATTERN =
+  /[\u001B\u009B][[\]()#;?]*(?:(?:(?:[a-zA-Z\d]*(?:;[a-zA-Z\d]*)*)?\u0007)|(?:(?:\d{1,4}(?:;\d{0,4})*)?[\dA-PR-TZcf-nq-uy=><~]))/g;
+
+const hasChildren = (
+  component: RenderableNode,
+): component is RenderableNode & { children: RenderableNode[] } => Array.isArray(component.children);
+
+export function renderedText(component: RenderableNode) {
+  try {
+    return component.render(200).join("\n").replace(ANSI_PATTERN, "");
+  } catch {
+    return "";
+  }
+}
+
+export function firstLineOf(component: RenderableNode) {
+  return renderedText(component)
+    .split("\n")
+    .find((line) => line.trim())
+    ?.trim();
+}
+
+// Marks the section nodes we build, so the addChild interceptor and the sweep
+// never re-match them (their first rendered line is also exactly "[Skills]").
+const ourSections = new WeakSet<object>();
+
+export const isOurSection = (component: object) => ourSections.has(component);
+
+/** A pi section leaf we should act on: exact header line, childless, not one of ours. */
+const isPiSection = (child: RenderableNode, header: string) =>
+  firstLineOf(child) === header && !hasChildren(child) && !isOurSection(child);
+
+export function hideThemesSection(component: RenderableNode): boolean {
+  if (!hasChildren(component)) return false;
+
+  for (let index = 0; index < component.children.length; index += 1) {
+    const child = component.children[index]!;
+    // Leaf check: pi's section components are childless ExpandableText nodes.
+    // The parent resources container can render the same first line when it's
+    // the first section, and matching it would splice out every section.
+    if (isPiSection(child, "[Themes]")) {
+      const next = component.children[index + 1];
+      const removeCount = next && renderedText(next).trim() === "" ? 2 : 1;
+      component.children.splice(index, removeCount);
+      component.invalidate();
+      return true;
+    }
+    if (hideThemesSection(child)) return true;
+  }
+  return false;
+}
+
+/**
+ * Build a replacement [Skills] section styled like pi's own sections:
+ * mdHeading header line, dim indented body listing each stack with its size,
+ * disabled stacks separately, plus the active-skill count. Data is read fresh
+ * from disk so it stays correct across /reload. Returns undefined when no
+ * stacks are configured or the config is unreadable (pi's section is left alone).
+ */
+export function buildSkillsSection(cwd: string, theme: SectionTheme | undefined) {
+  let summary;
+  try {
+    summary = loadStacksSummary(cwd);
+  } catch {
+    return undefined;
+  }
+  if (!summary) return undefined;
+  const heading = (text: string) => (theme ? theme.fg("mdHeading", text) : `${BOLD}${text}${RESET}`);
+  const dim = (text: string) => (theme ? theme.fg("dim", text) : `${DIM}${text}${RESET}`);
+  const label = (stack: { name: string; size: number }) => `${stack.name} (${stack.size})`;
+  const on = summary.stacks.filter((stack) => stack.enabled).map(label).join(", ");
+  const off = summary.stacks.filter((stack) => !stack.enabled).map(label).join(", ");
+  const parts: string[] = [];
+  if (on) parts.push(on);
+  if (off) parts.push(`off: ${off}`);
+  parts.push(`${summary.activeCount}/${summary.totalCount} skills active`);
+  const section = new Text(`${heading("[Skills]")}\n${dim(`  ${parts.join(" · ")}`)}`, 0, 0);
+  ourSections.add(section);
+  return section;
+}
+
+export function replaceSkillsSection(component: RenderableNode, section: Text): boolean {
+  if (!hasChildren(component)) return false;
+
+  for (let index = 0; index < component.children.length; index += 1) {
+    const child = component.children[index]!;
+    if (isPiSection(child, "[Skills]")) {
+      component.children.splice(index, 1, section);
+      component.invalidate();
+      return true;
+    }
+    if (replaceSkillsSection(child, section)) return true;
+  }
+  return false;
+}
+
+function formatDirectory(cwd: string) {
+  const home = homedir();
+  if (cwd === home) return "~";
+  const rel = relative(home, cwd);
+  return rel.startsWith("..") || isAbsolute(rel) ? cwd : `~/${rel}`;
+}
+
+export default function skillStacksHeader(pi: ExtensionAPI) {
+  let cwd = process.cwd();
+  let activeTui: DashboardTui | undefined;
+  let sectionTheme: SectionTheme | undefined;
+  let banner: string[] = [];
+  let fixupTimers: Array<ReturnType<typeof setTimeout>> = [];
+  const interceptedContainers = new WeakSet<object>();
+
+  // One disk read per fixup cycle: the interceptor and every sweep in the
+  // cycle share the same section instead of re-scanning the skill roots.
+  let cachedSection: { cwd: string; section: Text | undefined } | undefined;
+  function skillsSection() {
+    if (!cachedSection || cachedSection.cwd !== cwd) {
+      cachedSection = { cwd, section: buildSkillsSection(cwd, sectionTheme) };
+    }
+    return cachedSection.section;
+  }
+
+  // Wrap addChild on every container reachable from the TUI root so pi's
+  // [Skills] section is swapped (and [Themes] dropped) at insertion time,
+  // before the first paint.
+  function interceptContainers(node: RenderableNode) {
+    if (hasChildren(node) && typeof node.addChild === "function" && !interceptedContainers.has(node)) {
+      interceptedContainers.add(node);
+      const original = node.addChild.bind(node);
+      let dropNextBlank = false;
+      node.addChild = (child: RenderableNode) => {
+        if (dropNextBlank) {
+          dropNextBlank = false;
+          // The spacer pi adds right after the section it belongs to.
+          if (!renderedText(child).trim()) return;
+        }
+        if (!isOurSection(child)) {
+          const firstLine = firstLineOf(child);
+          if (firstLine === "[Themes]") {
+            dropNextBlank = true;
+            return;
+          }
+          if (firstLine === "[Skills]") {
+            const section = skillsSection();
+            if (section) {
+              original(section);
+              return;
+            }
+          }
+        }
+        original(child);
+      };
+    }
+    if (hasChildren(node)) {
+      for (const child of node.children) interceptContainers(child);
+    }
+  }
+
+  // Fallback for sections that were inserted before we wrapped their
+  // container (e.g. this extension loading into an already-painted session).
+  function sweepHeader(tui: DashboardTui) {
+    let changed = hideThemesSection(tui);
+    const section = skillsSection();
+    if (section && replaceSkillsSection(tui, section)) changed = true;
+    if (changed) tui.requestRender(true);
+  }
+
+  function clearFixupTimers() {
+    for (const timer of fixupTimers) clearTimeout(timer);
+    fixupTimers = [];
+  }
+
+  function scheduleHeaderFixups(tui: DashboardTui) {
+    clearFixupTimers();
+    cachedSection = undefined;
+    interceptContainers(tui);
+    sweepHeader(tui);
+    for (const delay of [0, 50, 250, 1_000]) {
+      fixupTimers.push(setTimeout(() => sweepHeader(tui), delay));
+    }
+  }
+
+  pi.on("session_start", (_event, ctx) => {
+    cwd = ctx.cwd;
+    if (ctx.mode !== "tui") return;
+
+    ctx.ui.setHeader((tui, theme) => {
+      activeTui = tui;
+      sectionTheme = theme;
+      const label = theme.fg("muted", formatDirectory(cwd));
+      banner = [];
+      scheduleHeaderFixups(tui);
+
+      return {
+        render(width: number) {
+          // One dim centered line: the working directory.
+          if (banner.length === 0) {
+            const padding = Math.max(0, Math.floor((width - visibleWidth(label)) / 2));
+            banner = [truncateToWidth(`${" ".repeat(padding)}${label}`, width)];
+          }
+          return banner;
+        },
+        invalidate() {
+          banner = [];
+        },
+      };
+    });
+  });
+
+  pi.on("resources_discover", () => {
+    if (activeTui) scheduleHeaderFixups(activeTui);
+  });
+
+  pi.on("session_shutdown", (_event, ctx) => {
+    clearFixupTimers();
+    activeTui = undefined;
+    if (ctx.mode === "tui") ctx.ui.setHeader(undefined);
+  });
+}