@astrofoundry/pi-astro 0.13.2 → 0.14.1

package/README.md

@@ -67,6 +67,7 @@ pi                # launch; confirm [Extensions] lists astro-agents, grimoire, a
 - `vscode-image` — only active inside VS Code's integrated terminal (`TERM_PROGRAM=vscode`). Switches pi-tui's image output to the **Kitty graphics protocol** so images returned by tools like `gemini_image` render as real pixels instead of the `[Image: …]` text fallback. **Requires enabling `Terminal › Integrated: Enable Images` in VS Code settings** (off by default); restart the integrated terminal after flipping it. Disable with `PI_VSCODE_IMAGE_OFF=1`. `/vscode-image` prints current status.
 - `astro-footer` — two-line powerline-style footer (row 2 only when there's info to show). Row 1: pi · pretty-printed model · thinking · path · git branch + `±` counts · tokens (in/out split) · cost (or `(sub)` for OAuth-authed plans) · context %/total + auto-compact `AC`. Row 2: subagent count · session time · session name · cache read/write · extension statuses. Auto-detects Nerd Fonts (iTerm/WezTerm/Kitty/Ghostty/Alacritty) with ASCII fallback. Env overrides: `ASTRO_FOOTER_NERD_FONTS=0|1`, `ASTRO_FOOTER_PATH=basename|abbreviated|full`. Toggle with `/footer [on|off|status]`. See [extensions/astro-footer/README.md](extensions/astro-footer/README.md).
 - `astro-snake` — `/snake` launches an in-pi Snake game (Astro-themed, theme-aware colours, speed ramp, no persistence). See [extensions/astro-snake/README.md](extensions/astro-snake/README.md).
+- `astro-welcome` — pixel-art astronaut welcome screen (24-bit colour, twinkling starfield, rotating funny tagline, live stats) rendered on session start; auto-dismisses after 6 s, on first keystroke, or on first prompt submit. See [extensions/astro-welcome/README.md](extensions/astro-welcome/README.md).
 - `caveman` — `/caveman [lite|full|ultra|wenyan-lite|wenyan-full|wenyan-ultra|off|status]` toggles a persistent compressed-output mode. No argument toggles between off and the default level (`full`). Active level is shown as a footer badge and survives `/reload`. The skill body at `skills/caveman/SKILL.md` is also available as a one-shot via `/skill:caveman`.
 
 **Bundled subagents** (callable via `astro_agent`):

package/extensions/astro-welcome/README.md

@@ -0,0 +1,46 @@
+# astro-welcome
+
+A short astro-themed welcome screen rendered as the pi startup header on every fresh session.
+
+- Pixel-art astronaut (Unicode halfblocks + 24-bit colour) — two variants rotated per session
+- Twinkling starfield in the background, deterministically seeded from session-start time
+- Funny tagline rotated from a pool of ~12
+- Live stats: model, context-window total, extension count, current caveman level
+- Auto-dismisses after 6 seconds, on the first keystroke, or when you submit your first prompt — whichever comes first
+
+Ships as part of [`@astrofoundry/pi-astro`](../../README.md). No extra install, no command — activates automatically on `session_start` with reason `startup`. Reload and resume don't trigger the splash.
+
+## Behaviour
+
+| Event | Action |
+|---|---|
+| `session_start` (`startup`) | Render via `ctx.ui.setHeader(…)`, arm 6 s timeout, register raw-input listener |
+| 6 s elapsed | Auto-dismiss |
+| any keystroke | Dismiss (keystroke passes through to the editor — not consumed) |
+| `before_agent_start` | Dismiss (covers the pasted-prompt-then-Enter case) |
+| dismissed once | Idempotent — further triggers are no-ops |
+
+## Layout
+
+```
+                            ★ ASTRO PI ★
+
+                          [pixel-art astronaut]
+
+           Welcome aboard, Astronaute. <funny tagline>
+
+   ◈ <model>     ◫ <ctx window>     ⚙ <N> extensions     ✦ caveman: <level>
+
+                Press any key to launch · auto-dismiss in 6s
+```
+
+The astronaut and starfield use raw 24-bit ANSI colour escapes so the look is the same across iTerm2 / Ghostty / WezTerm / Kitty / Alacritty.
+
+## Customising
+
+There's no config surface at the moment. To tweak:
+
+- **Taglines**: edit `messages.ts` — array `MESSAGES`. Add or remove freely.
+- **Astronaut variants**: edit `art.ts` — `ASTRONAUT_FLOATING` and `ASTRONAUT_FLAG` are pixel grids where each character maps to a colour key (`S`, `X`, `D`, `M`, `W`, `Y`, `G`, `T`, `E`, `F`, `O`, `R`). Each grid is rendered with halfblocks, doubling vertical resolution.
+- **Palette**: `colors.ts` exports `PALETTE` — every colour is a `[R, G, B]` triple. Tweak in place.
+- **Dismiss timeout**: `DISMISS_AFTER_MS` in `index.ts`.

package/extensions/astro-welcome/art.test.ts

@@ -0,0 +1,35 @@
+import { describe, expect, it } from "vitest";
+import { ART_HEIGHT, ART_WIDTH, pickVariant, renderArt, VARIANTS } from "./art.ts";
+
+describe("art", () => {
+    it("exposes ART_WIDTH and ART_HEIGHT consistent with the variants", () => {
+        expect(ART_WIDTH).toBeGreaterThan(0);
+        expect(ART_HEIGHT).toBeGreaterThan(0);
+        for (const v of VARIANTS) {
+            expect(v[0].length).toBe(ART_WIDTH);
+            expect(Math.ceil(v.length / 2)).toBe(ART_HEIGHT);
+        }
+    });
+
+    it("pickVariant is deterministic for the same seed", () => {
+        expect(pickVariant(0)).toBe(pickVariant(0));
+        expect(pickVariant(7)).toBe(pickVariant(7));
+    });
+
+    it("pickVariant handles negative seeds without throwing", () => {
+        expect(() => pickVariant(-100)).not.toThrow();
+    });
+
+    it("renderArt produces ART_HEIGHT rows", () => {
+        const lines = renderArt(VARIANTS[0]);
+        expect(lines).toHaveLength(ART_HEIGHT);
+    });
+
+    it("renderArt embeds 24-bit ANSI fg+bg colours and the upper-half block glyph", () => {
+        const lines = renderArt(VARIANTS[0]);
+        const joined = lines.join("\n");
+        expect(joined).toContain("[38;2;");
+        expect(joined).toContain(";48;2;");
+        expect(joined).toContain("▀");
+    });
+});

package/extensions/astro-welcome/art.ts

@@ -0,0 +1,125 @@
+import { fgBg, PALETTE, type RGB } from "./colors.ts";
+
+const _ = "·";
+const S = "S";
+const X = "X";
+const A = "A";
+const Y = "Y";
+const W = "W";
+const M = "M";
+const D = "D";
+const G = "G";
+const T = "T";
+const E = "E";
+const F = "F";
+const O = "O";
+const R = "R";
+
+type PaletteKey = typeof _ | typeof S | typeof X | typeof A | typeof Y | typeof W | typeof M | typeof D | typeof G | typeof T | typeof E | typeof F | typeof O | typeof R;
+
+const PIXEL_COLOR: Record<PaletteKey, RGB | null> = {
+    [_]: null,
+    [S]: PALETTE.suitLight,
+    [X]: PALETTE.suitMid,
+    [A]: PALETTE.suitShadow,
+    [Y]: PALETTE.suitTrim,
+    [W]: PALETTE.visorLow,
+    [M]: PALETTE.visorMid,
+    [D]: PALETTE.visorTop,
+    [G]: PALETTE.backpack,
+    [T]: PALETTE.earthBlue,
+    [E]: PALETTE.earthGreen,
+    [F]: PALETTE.flameYellow,
+    [O]: PALETTE.flameOrange,
+    [R]: PALETTE.flameRed,
+};
+
+const ASTRONAUT_FLOATING: readonly string[] = [
+    "··········SSSSSSSSSS··········",
+    "·······SSSSXXXXXXXXSSSS·······",
+    "·····SSXXMMMMMMMMMMMMXXSS·····",
+    "····SXMMDDDDDDDDDDDDDDMMSS····",
+    "···SXMDDDDWWDDDDDDWWDDDDMMS···",
+    "···SXMDDWWWWDDDDDDWWWWDDMMS···",
+    "···SXMDDDDDDDDDDDDDDDDDDMMS···",
+    "···SXMDDDDDDDDWWDDDDDDDDMMS···",
+    "····SXMMDDDDDDDDDDDDDDMMSS····",
+    "·····SSXXMMMMMMMMMMMMXXSS·····",
+    "·······SSXXXXXXXXXXXXSS·······",
+    "··········SXAAAAAAXSS·········",
+    "·······SSSSSSSSSSSSSSSS·······",
+    "······SSSSGGGGSSSSGGGGSSS·····",
+    "·····SSSSGGGGSSAAYAASSGGSSS···",
+    "·····SSGGGGSSSAYYYAASSGGGGS···",
+    "·····SSGGGSSSSAYAYASSSSGGGS···",
+    "·····SSGGGSSSSAAAASSSSSGGGS···",
+    "·····SSGGGSSSSSSSSSSSSGGGS····",
+    "······SSSSSSSSSSSSSSSSSS······",
+    "········SSAAAAAASSSSSSAAAA····",
+    "········SSSAAAASSSSAAAAS······",
+    "········SXXSSSSSSSXXXSS·······",
+    "·········SSSS·····SSSS········",
+    "··········SSS······SSS········",
+    "··········SS········SS········",
+];
+
+const ASTRONAUT_FLAG: readonly string[] = [
+    "··········SSSSSSSSSS··········",
+    "·······SSSSXXXXXXXXSSSS·······",
+    "·····SSXXMMMMMMMMMMMMXXSS·····",
+    "····SXMMDDDDDDDDDDDDDDMMSS····",
+    "···SXMDDDDWWDDDDDDWWDDDDMMS···",
+    "···SXMDDWWWWDDDDDDWWWWDDMMS···",
+    "···SXMDDDDDDDDDDDDDDDDDDMMS···",
+    "···SXMDDDDDDDDWWDDDDDDDDMMS···",
+    "····SXMMDDDDDDDDDDDDDDMMSS····",
+    "·····SSXXMMMMMMMMMMMMXXSS·····",
+    "·······SSXXXXXXXXXXXXSS·······",
+    "··········SXAAAAAAXSS·········",
+    "······YYYYYSSSSSSSSSSSSSS·····",
+    "······YYYYYSSGGGGSSSGGGGSSS···",
+    "······YYYYYSSGGGGSSSSGGGSS····",
+    "······YYYYYSSGGGSSSSSSGGGS····",
+    "······YYYYYSSGGSSSSSSSSGGS····",
+    "········SSSSSSSSSSSSSSSSSS····",
+    "········SSAAAAAASSSAAAASS·····",
+    "········SSSAAAASSSAAAAAS······",
+    "········SXXSSSSSSSXXXSS·······",
+    "·········SSSS·····SSSS········",
+    "··········SSS······SSS········",
+    "··········SS········SS········",
+    "·························E····",
+    "·························TT···",
+];
+
+export const VARIANTS = [ASTRONAUT_FLOATING, ASTRONAUT_FLAG] as const;
+
+export function pickVariant(seed: number): readonly string[] {
+    const idx = Math.abs(seed) % VARIANTS.length;
+    return VARIANTS[idx];
+}
+
+export function renderArt(grid: readonly string[]): string[] {
+    const rows: string[] = [];
+    for (let y = 0; y < grid.length; y += 2) {
+        const top = grid[y];
+        const bot = grid[y + 1] ?? "·".repeat(top.length);
+        let line = "";
+        for (let x = 0; x < top.length; x++) {
+            const tk = (top[x] ?? "·") as PaletteKey;
+            const bk = (bot[x] ?? "·") as PaletteKey;
+            const tc = PIXEL_COLOR[tk] ?? null;
+            const bc = PIXEL_COLOR[bk] ?? null;
+            if (!tc && !bc) {
+                line += " ";
+                continue;
+            }
+            line += fgBg(tc ?? PALETTE.space, bc ?? PALETTE.space);
+        }
+        rows.push(line);
+    }
+    return rows;
+}
+
+export const ART_WIDTH = ASTRONAUT_FLOATING[0].length;
+export const ART_HEIGHT = Math.ceil(ASTRONAUT_FLOATING.length / 2);

package/extensions/astro-welcome/colors.ts

@@ -0,0 +1,33 @@
+export type RGB = readonly [number, number, number];
+
+export function fg(rgb: RGB, text: string): string {
+    return `\x1b[38;2;${rgb[0]};${rgb[1]};${rgb[2]}m${text}\x1b[0m`;
+}
+
+export function fgBg(top: RGB, bottom: RGB): string {
+    return `\x1b[38;2;${top[0]};${top[1]};${top[2]};48;2;${bottom[0]};${bottom[1]};${bottom[2]}m▀\x1b[0m`;
+}
+
+export const PALETTE = {
+    space: [10, 12, 30] as const,
+    starDim: [70, 90, 130] as const,
+    starBright: [180, 200, 240] as const,
+    starGold: [240, 200, 80] as const,
+    visorTop: [40, 80, 180] as const,
+    visorMid: [80, 160, 240] as const,
+    visorLow: [180, 220, 255] as const,
+    suitLight: [240, 240, 230] as const,
+    suitMid: [200, 200, 195] as const,
+    suitShadow: [120, 120, 130] as const,
+    suitTrim: [240, 200, 60] as const,
+    backpack: [80, 80, 90] as const,
+    earthBlue: [50, 110, 200] as const,
+    earthGreen: [70, 160, 100] as const,
+    flameYellow: [255, 220, 60] as const,
+    flameOrange: [255, 140, 30] as const,
+    flameRed: [220, 60, 30] as const,
+    title: [255, 210, 80] as const,
+    tagline: [200, 200, 220] as const,
+    stats: [220, 180, 100] as const,
+    hint: [110, 130, 160] as const,
+} satisfies Record<string, RGB>;

package/extensions/astro-welcome/compose.test.ts

@@ -0,0 +1,56 @@
+import { describe, expect, it } from "vitest";
+import { composeWelcome, type WelcomeStats } from "./compose.ts";
+
+const baseStats: WelcomeStats = {
+    modelDisplay: "MoonshotAI: Kimi K2.6",
+    contextWindow: 1_000_000,
+    extensionCount: 9,
+    cavemanLevel: undefined,
+};
+
+describe("composeWelcome", () => {
+    it("returns a non-empty grid of lines", () => {
+        const lines = composeWelcome(120, 1, baseStats);
+        expect(lines.length).toBeGreaterThan(8);
+    });
+
+    it("includes the title text on the first line", () => {
+        const lines = composeWelcome(120, 1, baseStats);
+        expect(lines[0]).toContain("ASTRO PI");
+    });
+
+    it("includes the model in the stats line", () => {
+        const lines = composeWelcome(120, 1, baseStats);
+        const joined = lines.join("\n");
+        expect(joined).toContain("MoonshotAI: Kimi K2.6");
+    });
+
+    it("formats context window as 1.0M ctx", () => {
+        const lines = composeWelcome(120, 1, baseStats);
+        expect(lines.join("\n")).toContain("1.0M ctx");
+    });
+
+    it("shows caveman idle when no level set", () => {
+        expect(composeWelcome(120, 1, baseStats).join("\n")).toContain("caveman: idle");
+    });
+
+    it("shows caveman level when set", () => {
+        expect(
+            composeWelcome(120, 1, { ...baseStats, cavemanLevel: "ultra" }).join("\n"),
+        ).toContain("caveman: ultra");
+    });
+
+    it("contains the dismiss hint", () => {
+        expect(composeWelcome(120, 1, baseStats).join("\n")).toContain("Press any key");
+    });
+
+    it("handles narrow widths without crashing", () => {
+        expect(() => composeWelcome(40, 1, baseStats)).not.toThrow();
+    });
+
+    it("produces deterministic output for the same seed", () => {
+        const a = composeWelcome(120, 99, baseStats);
+        const b = composeWelcome(120, 99, baseStats);
+        expect(a).toEqual(b);
+    });
+});

package/extensions/astro-welcome/compose.ts

@@ -0,0 +1,134 @@
+import { visibleWidth } from "@mariozechner/pi-tui";
+import { fg, PALETTE } from "./colors.ts";
+import { ART_HEIGHT, ART_WIDTH, pickVariant, renderArt } from "./art.ts";
+import { pickMessage } from "./messages.ts";
+import { renderStarfield, type Mask } from "./stars.ts";
+
+export interface WelcomeStats {
+    modelDisplay: string | undefined;
+    contextWindow: number | undefined;
+    extensionCount: number;
+    cavemanLevel: string | undefined;
+}
+
+const TITLE = "★ ASTRO PI ★";
+const HINT = "Press any key to launch · auto-dismiss in 6s";
+
+function formatTokens(n: number | undefined): string {
+    if (n === undefined || n <= 0) return "—";
+    if (n < 1000) return `${n}`;
+    if (n < 1_000_000) return `${(n / 1000).toFixed(0)}k`;
+    return `${(n / 1_000_000).toFixed(1)}M`;
+}
+
+function statsLine(stats: WelcomeStats): string {
+    const parts: string[] = [];
+    if (stats.modelDisplay) parts.push(`◈ ${stats.modelDisplay}`);
+    parts.push(`◫ ${formatTokens(stats.contextWindow)} ctx`);
+    parts.push(`⚙ ${stats.extensionCount} extensions`);
+    parts.push(`✦ caveman: ${stats.cavemanLevel ?? "idle"}`);
+    return parts.join("   ");
+}
+
+function centerInLine(line: string, width: number): { line: string; col: number } {
+    const w = visibleWidth(line);
+    if (w >= width) return { line, col: 0 };
+    const pad = Math.floor((width - w) / 2);
+    return { line: " ".repeat(pad) + line, col: pad };
+}
+
+class CompositeMask implements Mask {
+    public readonly rows: number;
+    public readonly cols: number;
+    private readonly grid: boolean[][];
+
+    constructor(rows: number, cols: number) {
+        this.rows = rows;
+        this.cols = cols;
+        this.grid = Array.from({ length: rows }, () => new Array<boolean>(cols).fill(false));
+    }
+
+    occupy(row: number, col: number, length: number): void {
+        if (row < 0 || row >= this.rows) return;
+        for (let c = col; c < col + length && c < this.cols; c++) {
+            if (c >= 0) this.grid[row][c] = true;
+        }
+    }
+
+    occupyArt(startRow: number, startCol: number, height: number, width: number): void {
+        for (let r = startRow; r < startRow + height; r++) {
+            this.occupy(r, startCol, width);
+        }
+    }
+
+    isOccupied(row: number, col: number): boolean {
+        if (row < 0 || row >= this.rows) return false;
+        if (col < 0 || col >= this.cols) return false;
+        return this.grid[row][col];
+    }
+}
+
+export function composeWelcome(width: number, seed: number, stats: WelcomeStats): string[] {
+    const totalRows = ART_HEIGHT + 7;
+    const safeWidth = Math.max(40, width);
+    const artStartCol = Math.max(0, Math.floor((safeWidth - ART_WIDTH) / 2));
+    const artStartRow = 1;
+
+    const mask = new CompositeMask(totalRows, safeWidth);
+    mask.occupyArt(artStartRow, artStartCol, ART_HEIGHT, ART_WIDTH);
+
+    const titleLine = fg(PALETTE.title, TITLE);
+    const titlePlaced = centerInLine(titleLine, safeWidth);
+    mask.occupy(0, titlePlaced.col, visibleWidth(titleLine));
+
+    const taglineRaw = pickMessage(seed);
+    const taglineLine = fg(PALETTE.tagline, taglineRaw);
+    const taglineRow = artStartRow + ART_HEIGHT + 1;
+    const taglinePlaced = centerInLine(taglineLine, safeWidth);
+    mask.occupy(taglineRow, taglinePlaced.col, visibleWidth(taglineLine));
+
+    const statsRaw = statsLine(stats);
+    const statsColored = fg(PALETTE.stats, statsRaw);
+    const statsRow = taglineRow + 2;
+    const statsPlaced = centerInLine(statsColored, safeWidth);
+    mask.occupy(statsRow, statsPlaced.col, visibleWidth(statsColored));
+
+    const hintColored = fg(PALETTE.hint, HINT);
+    const hintRow = statsRow + 2;
+    const hintPlaced = centerInLine(hintColored, safeWidth);
+    mask.occupy(hintRow, hintPlaced.col, visibleWidth(hintColored));
+
+    const stars = renderStarfield(safeWidth, totalRows, seed, mask);
+    const artLines = renderArt(pickVariant(seed));
+
+    const composed: string[] = [];
+    for (let r = 0; r < totalRows; r++) {
+        let line = stars[r] ?? " ".repeat(safeWidth);
+
+        if (r === 0) line = overlay(line, titlePlaced.line, safeWidth);
+        if (r === taglineRow) line = overlay(line, taglinePlaced.line, safeWidth);
+        if (r === statsRow) line = overlay(line, statsPlaced.line, safeWidth);
+        if (r === hintRow) line = overlay(line, hintPlaced.line, safeWidth);
+
+        if (r >= artStartRow && r < artStartRow + ART_HEIGHT) {
+            const artLine = artLines[r - artStartRow];
+            const artLineWidth = visibleWidth(artLine);
+            line = overlayAt(line, " ".repeat(artStartCol) + artLine, safeWidth, artStartCol, artLineWidth);
+        }
+
+        composed.push(line);
+    }
+    return composed;
+}
+
+function overlay(starLine: string, payload: string, width: number): string {
+    return truncate(payload, width);
+}
+
+function overlayAt(_starLine: string, payload: string, width: number, _startCol: number, _payloadWidth: number): string {
+    return truncate(payload, width);
+}
+
+function truncate(line: string, width: number): string {
+    return visibleWidth(line) <= width ? line : line.slice(0, width);
+}

package/extensions/astro-welcome/index.test.ts

@@ -0,0 +1,168 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+type Handler = (event: unknown, ctx: unknown) => void | Promise<void>;
+
+interface FakePi {
+    handlers: Record<string, Handler>;
+    getAllTools: ReturnType<typeof vi.fn>;
+    on: (event: string, h: Handler) => void;
+}
+
+function makePi(): FakePi {
+    const handlers: Record<string, Handler> = {};
+    return {
+        handlers,
+        getAllTools: vi.fn(() => [{ name: "a" }, { name: "b" }, { name: "c" }]),
+        on: (event, h) => {
+            handlers[event] = h;
+        },
+    };
+}
+
+interface FakeCtx {
+    hasUI: boolean;
+    cwd: string;
+    model: { id: string; contextWindow: number } | undefined;
+    sessionManager: { getEntries: () => unknown[] };
+    ui: {
+        setHeader: ReturnType<typeof vi.fn>;
+        onTerminalInput: ReturnType<typeof vi.fn>;
+    };
+}
+
+function makeCtx(overrides: Partial<FakeCtx> = {}): FakeCtx & { _terminalListener: ((data: string) => unknown) | null } {
+    const state = { listener: null as ((data: string) => unknown) | null };
+    const onTerminalInput = vi.fn((handler: (data: string) => unknown) => {
+        state.listener = handler;
+        return () => {
+            state.listener = null;
+        };
+    });
+    return {
+        hasUI: true,
+        cwd: "/Users/astro/proj",
+        model: { id: "anthropic/claude-sonnet-4-6", contextWindow: 1_000_000 },
+        sessionManager: { getEntries: () => [] },
+        ui: {
+            setHeader: vi.fn(),
+            onTerminalInput,
+        },
+        get _terminalListener() {
+            return state.listener;
+        },
+        ...overrides,
+    } as FakeCtx & { _terminalListener: ((data: string) => unknown) | null };
+}
+
+describe("astro-welcome extension", () => {
+    beforeEach(() => {
+        vi.useFakeTimers();
+        vi.resetModules();
+    });
+
+    afterEach(() => {
+        vi.useRealTimers();
+        vi.clearAllMocks();
+    });
+
+    async function install(): Promise<{ pi: FakePi; mod: typeof import("./index.ts") }> {
+        const mod = await import("./index.ts");
+        const pi = makePi();
+        mod.default(pi as unknown as Parameters<typeof mod.default>[0]);
+        return { pi, mod };
+    }
+
+    it("registers session_start and before_agent_start listeners", async () => {
+        const { pi } = await install();
+        expect(pi.handlers.session_start).toBeDefined();
+        expect(pi.handlers.before_agent_start).toBeDefined();
+    });
+
+    it("on startup session_start, sets a header and arms a terminal-input listener", async () => {
+        const { pi } = await install();
+        const ctx = makeCtx();
+        await pi.handlers.session_start({ reason: "startup" }, ctx);
+        expect(ctx.ui.setHeader).toHaveBeenCalledTimes(1);
+        expect(ctx.ui.onTerminalInput).toHaveBeenCalledTimes(1);
+    });
+
+    it("does nothing when ctx.hasUI is false", async () => {
+        const { pi } = await install();
+        const ctx = makeCtx({ hasUI: false });
+        await pi.handlers.session_start({ reason: "startup" }, ctx);
+        expect(ctx.ui.setHeader).not.toHaveBeenCalled();
+    });
+
+    it("clears the header automatically after 6 seconds", async () => {
+        const { pi } = await install();
+        const ctx = makeCtx();
+        await pi.handlers.session_start({ reason: "startup" }, ctx);
+        vi.advanceTimersByTime(6_000);
+        const calls = ctx.ui.setHeader.mock.calls;
+        expect(calls.length).toBe(2);
+        expect(calls[1][0]).toBeUndefined();
+    });
+
+    it("clears the header on the first terminal input keystroke", async () => {
+        const { pi } = await install();
+        const ctx = makeCtx();
+        await pi.handlers.session_start({ reason: "startup" }, ctx);
+        const listener = ctx._terminalListener;
+        expect(listener).not.toBeNull();
+        const result = listener!("a");
+        expect(result).toBeUndefined();
+        expect(ctx.ui.setHeader).toHaveBeenLastCalledWith(undefined);
+    });
+
+    it("clears the header on before_agent_start", async () => {
+        const { pi } = await install();
+        const ctx = makeCtx();
+        await pi.handlers.session_start({ reason: "startup" }, ctx);
+        await pi.handlers.before_agent_start({ prompt: "hi" }, ctx);
+        expect(ctx.ui.setHeader).toHaveBeenLastCalledWith(undefined);
+    });
+
+    it("dismiss is idempotent — second trigger does not double-clear", async () => {
+        const { pi } = await install();
+        const ctx = makeCtx();
+        await pi.handlers.session_start({ reason: "startup" }, ctx);
+        await pi.handlers.before_agent_start({ prompt: "hi" }, ctx);
+        const before = ctx.ui.setHeader.mock.calls.length;
+        vi.advanceTimersByTime(6_000);
+        expect(ctx.ui.setHeader.mock.calls.length).toBe(before);
+    });
+
+    it("renders header with all stats and dismiss hint visible", async () => {
+        const { pi } = await install();
+        const ctx = makeCtx();
+        await pi.handlers.session_start({ reason: "startup" }, ctx);
+        const factory = ctx.ui.setHeader.mock.calls[0][0] as (
+            tui: unknown,
+            theme: unknown,
+        ) => { render: (w: number) => string[] };
+        const lines = factory({}, {}).render(120);
+        const joined = lines.join("\n");
+        expect(joined).toContain("ASTRO PI");
+        expect(joined).toContain("anthropic/claude-sonnet-4-6");
+        expect(joined).toContain("1.0M ctx");
+        expect(joined).toContain("3 extensions");
+        expect(joined).toContain("Press any key");
+    });
+
+    it("reads caveman level from session entries", async () => {
+        const { pi } = await install();
+        const ctx = makeCtx({
+            sessionManager: {
+                getEntries: () => [
+                    { type: "custom", customType: "caveman-mode", data: { level: "ultra" } },
+                ],
+            },
+        });
+        await pi.handlers.session_start({ reason: "startup" }, ctx);
+        const factory = ctx.ui.setHeader.mock.calls[0][0] as (
+            tui: unknown,
+            theme: unknown,
+        ) => { render: (w: number) => string[] };
+        expect(factory({}, {}).render(120).join("\n")).toContain("caveman: ultra");
+    });
+});

package/extensions/astro-welcome/index.ts

@@ -0,0 +1,87 @@
+import type { ExtensionAPI, ExtensionContext } from "@mariozechner/pi-coding-agent";
+import { composeWelcome, type WelcomeStats } from "./compose.ts";
+
+const DISMISS_AFTER_MS = 6_000;
+
+function readCavemanLevel(ctx: ExtensionContext): string | undefined {
+    for (let i = ctx.sessionManager.getEntries().length - 1; i >= 0; i--) {
+        const entry = ctx.sessionManager.getEntries()[i];
+        if (entry.type === "custom" && entry.customType === "caveman-mode") {
+            const data = entry.data as { level?: string } | undefined;
+            return data?.level ?? undefined;
+        }
+    }
+    return undefined;
+}
+
+function modelDisplayShort(modelId: string | undefined): string | undefined {
+    if (!modelId) return undefined;
+    const trimmed = modelId.trim();
+    if (trimmed.length === 0) return undefined;
+    return trimmed;
+}
+
+export default function astroWelcomeExtension(pi: ExtensionAPI): void {
+    let dismissed = false;
+    let timer: ReturnType<typeof setTimeout> | null = null;
+    let unsubscribeInput: (() => void) | null = null;
+    let activeCtx: ExtensionContext | null = null;
+
+    function dismiss(): void {
+        if (dismissed) return;
+        dismissed = true;
+        if (timer !== null) {
+            clearTimeout(timer);
+            timer = null;
+        }
+        if (unsubscribeInput !== null) {
+            try {
+                unsubscribeInput();
+            } catch {
+                /* ignore unsubscribe errors */
+            }
+            unsubscribeInput = null;
+        }
+        try {
+            activeCtx?.ui.setHeader(undefined);
+        } catch {
+            /* ignore header clear errors */
+        }
+        activeCtx = null;
+    }
+
+    pi.on("session_start", async (_event, ctx) => {
+        if (!ctx.hasUI) return;
+        dismissed = false;
+        activeCtx = ctx;
+        const seed = Date.now() & 0xffff_ffff;
+
+        const stats: WelcomeStats = {
+            modelDisplay: modelDisplayShort(ctx.model?.id),
+            contextWindow: ctx.model?.contextWindow,
+            extensionCount: pi.getAllTools().length,
+            cavemanLevel: readCavemanLevel(ctx),
+        };
+
+        ctx.ui.setHeader((_tui, _theme) => ({
+            invalidate() {},
+            render(width: number): string[] {
+                return composeWelcome(width, seed, stats);
+            },
+        }));
+
+        timer = setTimeout(dismiss, DISMISS_AFTER_MS);
+        try {
+            unsubscribeInput = ctx.ui.onTerminalInput(() => {
+                dismiss();
+                return undefined;
+            });
+        } catch {
+            /* terminal input listener not supported in this mode */
+        }
+    });
+
+    pi.on("before_agent_start", async () => {
+        dismiss();
+    });
+}

package/extensions/astro-welcome/messages.test.ts

@@ -0,0 +1,19 @@
+import { describe, expect, it } from "vitest";
+import { MESSAGES, pickMessage } from "./messages.ts";
+
+describe("pickMessage", () => {
+    it("returns one of the known messages", () => {
+        const msg = pickMessage(0);
+        expect(MESSAGES).toContain(msg as typeof MESSAGES[number]);
+    });
+
+    it("is deterministic for the same seed", () => {
+        expect(pickMessage(42)).toBe(pickMessage(42));
+        expect(pickMessage(123_456)).toBe(pickMessage(123_456));
+    });
+
+    it("handles negative seeds", () => {
+        const msg = pickMessage(-7);
+        expect(MESSAGES).toContain(msg as typeof MESSAGES[number]);
+    });
+});

package/extensions/astro-welcome/messages.ts

@@ -0,0 +1,19 @@
+export const MESSAGES = [
+    "Mission control reports you survived another deploy.",
+    "Cosmic radiation suggests today is a good debugging day.",
+    "Houston confirms you have go for prompt submission.",
+    "The void is patient. Take your time — the tokens are not.",
+    "Telemetry shows your last session reached escape velocity.",
+    "Compiler dreams of you. The linter, less so.",
+    "Oxygen at 100%. Caffeine: unmonitored.",
+    "Stardate today. Coils warm. Lockfile: ${'pnpm'} only.",
+    "Approaching the next bug at relativistic speed.",
+    "Warp coils nominal. ESLint: still grumpy.",
+    "All thrusters green. The stack trace is the universe whispering.",
+    "Galactic standard time exceeded. Resume coding.",
+] as const;
+
+export function pickMessage(seed: number): string {
+    const idx = Math.abs(seed) % MESSAGES.length;
+    return MESSAGES[idx];
+}

package/extensions/astro-welcome/stars.ts

@@ -0,0 +1,50 @@
+import { fg, PALETTE, type RGB } from "./colors.ts";
+
+const STAR_GLYPHS = ["·", "·", "·", "✦", "✧", "⋆", "*"];
+const STAR_COLORS: readonly RGB[] = [
+    PALETTE.starDim,
+    PALETTE.starDim,
+    PALETTE.starBright,
+    PALETTE.starGold,
+];
+
+function mulberry32(a: number): () => number {
+    let t = a >>> 0;
+    return () => {
+        t += 0x6d2b79f5;
+        let r = t;
+        r = Math.imul(r ^ (r >>> 15), r | 1);
+        r ^= r + Math.imul(r ^ (r >>> 7), r | 61);
+        return ((r ^ (r >>> 14)) >>> 0) / 4294967296;
+    };
+}
+
+export interface Mask {
+    rows: number;
+    cols: number;
+    isOccupied(row: number, col: number): boolean;
+}
+
+export function renderStarfield(width: number, height: number, seed: number, mask: Mask): string[] {
+    const rng = mulberry32(seed);
+    const lines: string[] = [];
+    const density = 0.06;
+    for (let y = 0; y < height; y++) {
+        let line = "";
+        for (let x = 0; x < width; x++) {
+            if (mask.isOccupied(y, x)) {
+                line += " ";
+                continue;
+            }
+            if (rng() < density) {
+                const glyph = STAR_GLYPHS[Math.floor(rng() * STAR_GLYPHS.length)];
+                const colour = STAR_COLORS[Math.floor(rng() * STAR_COLORS.length)];
+                line += fg(colour, glyph);
+            } else {
+                line += " ";
+            }
+        }
+        lines.push(line);
+    }
+    return lines;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astrofoundry/pi-astro",
-  "version": "0.13.2",
+  "version": "0.14.1",
   "description": "Personal pi customizations (extensions, skills, prompts, themes) for the pi coding agent.",
   "keywords": [
     "pi-package"