@cleocode/cleo-os 2026.4.35 → 2026.4.36

package/extensions/cleo-startup.js

@@ -0,0 +1,728 @@
+/**
+ * CleoOS branded startup extension.
+ *
+ * CANONICAL LOCATION: `packages/cleo-os/extensions/cleo-startup.ts`
+ *
+ * Installed to: $XDG_DATA_HOME/cleo/extensions/cleo-startup.js
+ * Loaded by:    Pi via `--extension <path>` injected by CleoOS cli.ts
+ *
+ * On `session_start`, displays a branded CleoOS welcome panel with:
+ *   - ASCII art CLEO logo
+ *   - Project name and CLEO task summary (pending / active / done)
+ *   - Last 3 brain decisions ("what we decided recently")
+ *   - Memory bridge summary (total entries, % verified, top 3 cited)
+ *   - Quick action hints based on current state
+ *   - Current focused task (if any)
+ *   - Last session handoff note from the memory bridge
+ *
+ * Also registers:
+ *   - `/cleo:status` — on-demand project status refresh
+ *   - `/cleo:focus <task-id>` — focus on a task
+ *   - `/cleo:end-session [note]` — end the current session
+ *
+ * All data is fetched via the `cleo` CLI (best-effort). If any call
+ * fails, the banner degrades gracefully — Pi is never crashed.
+ *
+ * Design system:
+ *   - accentPrimary (purple #a855f7) — banner chrome, icons
+ *   - accentSuccess (green #22c55e) — active counts
+ *   - accentWarning (amber #f59e0b) — pending counts, handoff note
+ *   - textSecondary (gray #94a3b8)  — body text, labels
+ *   - bold — headings, task title
+ *   - Box-drawing constants from tui-theme for Forge aesthetic
+ *
+ * Guardrails:
+ *   - Best-effort: all CLEO CLI calls wrapped in try/catch
+ *   - NO top-level await; all work inside event handlers
+ *   - NEVER modify system prompt (startup display only)
+ *   - NEVER crash Pi
+ *
+ * @packageDocumentation
+ */
+import { execFile } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { promisify } from "node:util";
+import { accentPrimary, accentSuccess, accentWarning, accentError, textSecondary, textTertiary, bold, BOX_HORIZONTAL, BOX_VERTICAL, BOX_TOP_LEFT, BOX_TOP_RIGHT, BOX_BOTTOM_LEFT, BOX_BOTTOM_RIGHT, BOX_LEFT_T, BOX_RIGHT_T, ICON_FORGE, DOT_FILLED, } from "./tui-theme.js";
+const execFileAsync = promisify(execFile);
+// ============================================================================
+// Parsers — best-effort, always return a typed default on failure
+// ============================================================================
+/**
+ * Parse task summary from `cleo dash --json` output.
+ *
+ * @param stdout - Raw stdout from the CLI call.
+ * @returns Parsed task summary, defaulting all counts to 0 on failure.
+ */
+export function parseDashSummary(stdout) {
+    try {
+        const parsed = JSON.parse(stdout);
+        const data = (parsed["data"] ?? parsed);
+        const summary = data["summary"];
+        const blocked = data["blockedTasks"];
+        return {
+            active: typeof summary?.["active"] === "number" ? summary["active"] : 0,
+            pending: typeof summary?.["pending"] === "number" ? summary["pending"] : 0,
+            done: typeof summary?.["done"] === "number" ? summary["done"] : 0,
+            total: typeof summary?.["total"] === "number" ? summary["total"] : 0,
+            blocked: typeof blocked?.["count"] === "number" ? blocked["count"] : 0,
+        };
+    }
+    catch {
+        return { active: 0, pending: 0, done: 0, total: 0, blocked: 0 };
+    }
+}
+/**
+ * Parse session info from `cleo session status --json` output.
+ *
+ * Extracts active state, session ID/name, current task, and the last
+ * handoff note left at session end.
+ *
+ * @param stdout - Raw stdout from the CLI call.
+ * @returns Parsed session info.
+ */
+export function parseSessionInfo(stdout) {
+    const defaultInfo = {
+        active: false,
+        id: "",
+        name: "",
+        currentTaskId: null,
+        handoffNote: null,
+    };
+    try {
+        const parsed = JSON.parse(stdout);
+        const data = (parsed["data"] ?? parsed);
+        const sessionWrapper = data["session"];
+        if (!sessionWrapper)
+            return defaultInfo;
+        const hasActive = sessionWrapper["hasActiveSession"] === true;
+        if (!hasActive)
+            return { ...defaultInfo, active: false };
+        const session = sessionWrapper["session"];
+        if (!session)
+            return { ...defaultInfo, active: true };
+        const taskWork = sessionWrapper["taskWork"];
+        const currentTaskId = typeof taskWork?.["taskId"] === "string" && taskWork["taskId"]
+            ? taskWork["taskId"]
+            : null;
+        // Handoff note is stored on the session object itself
+        const handoffRaw = session["handoffJson"];
+        let handoffNote = null;
+        if (typeof handoffRaw === "string" && handoffRaw.length > 0) {
+            try {
+                const handoff = JSON.parse(handoffRaw);
+                if (typeof handoff["note"] === "string") {
+                    handoffNote = handoff["note"];
+                }
+            }
+            catch {
+                // Not valid JSON — use raw value if it's short enough
+                if (handoffRaw.length < 200)
+                    handoffNote = handoffRaw;
+            }
+        }
+        return {
+            active: true,
+            id: typeof session["id"] === "string" ? session["id"] : "",
+            name: typeof session["name"] === "string" ? session["name"] : "",
+            currentTaskId,
+            handoffNote,
+        };
+    }
+    catch {
+        return defaultInfo;
+    }
+}
+/**
+ * Parse current task info from `cleo current --json` output.
+ *
+ * @param stdout - Raw stdout from the CLI call.
+ * @returns Parsed current task, or null if none active.
+ */
+export function parseCurrentTask(stdout) {
+    try {
+        const parsed = JSON.parse(stdout);
+        const data = (parsed["data"] ?? parsed);
+        // `cleo current` can return `{ currentTask: null }` or a task object
+        const taskRaw = data["currentTask"] ?? data["task"];
+        if (!taskRaw || typeof taskRaw !== "object")
+            return null;
+        const task = taskRaw;
+        const id = typeof task["id"] === "string" ? task["id"] : null;
+        const title = typeof task["title"] === "string" ? task["title"] : null;
+        const status = typeof task["status"] === "string" ? task["status"] : "unknown";
+        if (!id || !title)
+            return null;
+        return { id, title, status };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Parse the last 3 decisions from `cleo memory decision-find --json` output.
+ *
+ * @param stdout - Raw stdout from the CLI call.
+ * @returns Array of up to 3 decision entries.
+ */
+export function parseRecentDecisions(stdout) {
+    try {
+        const parsed = JSON.parse(stdout);
+        const data = (parsed["data"] ?? parsed);
+        const rawDecisions = data["decisions"];
+        if (!Array.isArray(rawDecisions))
+            return [];
+        return rawDecisions
+            .slice(0, 3)
+            .map((d) => {
+            const entry = d;
+            const id = typeof entry["id"] === "string" ? entry["id"] : "";
+            const title = typeof entry["title"] === "string"
+                ? entry["title"]
+                : typeof entry["summary"] === "string"
+                    ? entry["summary"]
+                    : "";
+            const date = typeof entry["date"] === "string"
+                ? entry["date"].slice(0, 10)
+                : typeof entry["createdAt"] === "string"
+                    ? entry["createdAt"].slice(0, 10)
+                    : "";
+            return { id, title, date };
+        })
+            .filter((d) => d.title.length > 0);
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Parse memory bridge statistics from `.cleo/memory-bridge.md`.
+ *
+ * Counts total list items across all sections and extracts the
+ * top 3 cited items (items appearing in the "Recent Decisions" or
+ * "Key Learnings" sections).
+ *
+ * @param content - Raw memory-bridge.md content.
+ * @returns Memory bridge statistics.
+ */
+export function parseMemoryBridgeStats(content) {
+    if (!content || content.length === 0) {
+        return { totalEntries: 0, topThree: [] };
+    }
+    // Count all list items (lines starting with "- " or "* ")
+    const allItems = content.match(/^[-*]\s+\[.+?\].+/gm) ?? [];
+    const totalEntries = allItems.length;
+    // Extract top 3 from "Key Learnings" or "Recent Decisions" sections
+    const learningsMatch = content.match(/## Key Learnings\n([\s\S]*?)(?=\n##|\s*$)/m);
+    const decisionsMatch = content.match(/## Recent Decisions\n([\s\S]*?)(?=\n##|\s*$)/m);
+    const topSection = (learningsMatch?.[1] ?? decisionsMatch?.[1] ?? "");
+    const topItems = (topSection.match(/^[-*]\s+\[.+?\]\s+(.+)/gm) ?? [])
+        .slice(0, 3)
+        .map((line) => {
+        // Strip the "- [ID] " prefix, keep the description
+        return line.replace(/^[-*]\s+\[.+?\]\s+/, "").trim();
+    })
+        .filter((s) => s.length > 0);
+    return { totalEntries, topThree: topItems };
+}
+/**
+ * Build quick-action hints based on current project state.
+ *
+ * Generates context-sensitive suggestions so the operator knows
+ * immediately what to do next without running extra commands.
+ *
+ * @param tasks - Task summary counts.
+ * @param session - Current session state.
+ * @param currentTask - Currently focused task, or null.
+ * @returns Quick-action hints.
+ */
+export function buildQuickHints(tasks, session, currentTask) {
+    const hints = [];
+    if (!session.active) {
+        hints.push("No active session — run `cleo session start` to begin");
+    }
+    else if (!currentTask && tasks.pending > 0) {
+        hints.push(`${tasks.pending} ready tasks — run \`cleo next\` to pick one`);
+    }
+    else if (currentTask) {
+        hints.push(`Working on [${currentTask.id}] — run \`cleo complete ${currentTask.id}\` when done`);
+    }
+    if (tasks.blocked > 0) {
+        hints.push(`${tasks.blocked} blocked task(s) — run \`cleo blockers\` to review`);
+    }
+    if (hints.length === 0 && tasks.total === 0) {
+        hints.push("No tasks yet — run `cleo add \"<task title>\"` to start");
+    }
+    return { hints };
+}
+/**
+ * Read the last session handoff note from `.cleo/memory-bridge.md`.
+ *
+ * Falls back to null if the file does not exist or parsing fails.
+ * Prefers the `## Last Session` section's `Note:` line.
+ *
+ * @param projectDir - The project root directory.
+ * @returns The last session note, or null.
+ */
+export function readMemoryBridgeNote(projectDir) {
+    try {
+        const bridgePath = join(projectDir, ".cleo", "memory-bridge.md");
+        if (!existsSync(bridgePath))
+            return null;
+        const content = readFileSync(bridgePath, "utf-8");
+        // Extract the Note: line from the ## Last Session section
+        const noteMatch = content.match(/[-*]\s+\*\*Note\*\*:\s*(.+)/m);
+        if (noteMatch?.[1]) {
+            return noteMatch[1].trim();
+        }
+        // Fallback: look for any line that starts with "- **Note**"
+        const altMatch = content.match(/\*\*Note\*\*[:\s]+(.+)/m);
+        if (altMatch?.[1]) {
+            return altMatch[1].trim();
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+// ============================================================================
+// Banner rendering
+// ============================================================================
+/**
+ * Truncate a string to a maximum length, appending "..." if truncated.
+ *
+ * @param text - The text to truncate.
+ * @param maxLen - Maximum character length.
+ * @returns Truncated string.
+ */
+function truncate(text, maxLen) {
+    if (text.length <= maxLen)
+        return text;
+    return text.slice(0, maxLen - 3) + "...";
+}
+/**
+ * Pad a content string to fill the banner inner width.
+ *
+ * The banner uses box-drawing characters. The padding is calculated
+ * from the raw (un-styled) content string length so ANSI escapes
+ * in styledContent do not affect the column calculation.
+ *
+ * @param rawContent - Visible text content (without ANSI codes) for width calculation.
+ * @param styledContent - ANSI-styled version of the content to display.
+ * @param innerWidth - Inner width of the banner box in characters.
+ * @returns A single padded line with box-drawing vertical borders.
+ */
+function padBannerLine(rawContent, styledContent, innerWidth) {
+    const pad = Math.max(0, innerWidth - rawContent.length);
+    return (accentPrimary(BOX_VERTICAL) +
+        " " +
+        styledContent +
+        " ".repeat(pad) +
+        accentPrimary(BOX_VERTICAL));
+}
+/**
+ * ASCII art CLEO logo lines (no ANSI — caller applies color).
+ *
+ * Rendered in a compact 3-row form that fits within the 54-char banner width.
+ */
+const CLEO_ASCII_LOGO = [
+    "  ██████╗██╗     ███████╗ ██████╗",
+    "  ██╔════╝██║     ██╔════╝██╔═══██╗",
+    "  ██║     ██║     █████╗  ██║   ██║",
+    "  ██║     ██║     ██╔══╝  ██║   ██║",
+    "  ╚██████╗███████╗███████╗╚██████╔╝",
+    "   ╚═════╝╚══════╝╚══════╝ ╚═════╝",
+];
+/**
+ * Build the full CleoOS startup banner.
+ *
+ * Renders a box-drawing widget with:
+ *   - ASCII art CLEO logo
+ *   - Branded header with forge icon
+ *   - Task counts (active / pending / done / blocked)
+ *   - Last 3 brain decisions
+ *   - Memory bridge summary
+ *   - Quick action hints
+ *   - Current task title (if any)
+ *   - Session info (name + ID)
+ *   - Last session handoff note (from memory-bridge.md or session data)
+ *
+ * @param tasks - Task summary counts.
+ * @param session - Current session state.
+ * @param currentTask - Currently focused task, or null.
+ * @param handoffNote - Last session handoff note, or null.
+ * @param projectName - Project display name.
+ * @param decisions - Recent brain decisions (up to 3).
+ * @param memStats - Memory bridge statistics.
+ * @param hints - Quick-action hints.
+ * @returns Array of ANSI-styled banner lines.
+ */
+export function buildStartupBanner(tasks, session, currentTask, handoffNote, projectName, decisions = [], memStats = { totalEntries: 0, topThree: [] }, hints = { hints: [] }) {
+    // Inner width: characters between the two vertical border chars
+    // (not counting the leading space + BOX_VERTICAL or trailing BOX_VERTICAL)
+    const INNER = 52;
+    const hBar = BOX_HORIZONTAL.repeat(INNER + 2); // +2 for the spaces beside borders
+    const lines = [];
+    // ── Top border ────────────────────────────────────────────────────────
+    lines.push(accentPrimary(BOX_TOP_LEFT + hBar + BOX_TOP_RIGHT));
+    // ── ASCII Logo ────────────────────────────────────────────────────────
+    for (const logoLine of CLEO_ASCII_LOGO) {
+        // Pad to INNER width so border chars align
+        lines.push(padBannerLine(logoLine + " ", accentPrimary(logoLine), INNER));
+    }
+    // ── Header row ────────────────────────────────────────────────────────
+    const headerRaw = `  ${ICON_FORGE}  Agentic Dev Forge  ${ICON_FORGE}  ${truncate(projectName, 18)}`;
+    lines.push(padBannerLine(" " + headerRaw + " ", "  " + bold(accentPrimary(`${ICON_FORGE}  Agentic Dev Forge  ${ICON_FORGE}`)) +
+        accentPrimary("  ") +
+        bold(textSecondary(truncate(projectName, 18))), INNER));
+    // ── Task summary divider ──────────────────────────────────────────────
+    lines.push(accentPrimary(BOX_LEFT_T + hBar + BOX_RIGHT_T));
+    // ── Task counts ───────────────────────────────────────────────────────
+    const activeStr = String(tasks.active);
+    const pendingStr = String(tasks.pending);
+    const doneStr = String(tasks.done);
+    const blockedStr = String(tasks.blocked);
+    const countsRaw = `  Tasks: ${activeStr} active  ${pendingStr} pending  ${doneStr} done` +
+        (tasks.blocked > 0 ? `  ${blockedStr} blocked` : "");
+    const countsDot = tasks.active > 0
+        ? accentSuccess(DOT_FILLED)
+        : (tasks.pending > 0 ? accentWarning(DOT_FILLED) : textSecondary(DOT_FILLED));
+    const countsStyled = `  ${countsDot} Tasks: ` +
+        accentSuccess(activeStr) + textSecondary(" active  ") +
+        accentWarning(pendingStr) + textSecondary(" pending  ") +
+        textSecondary(doneStr + " done") +
+        (tasks.blocked > 0
+            ? "  " + accentError(blockedStr) + textSecondary(" blocked")
+            : "");
+    lines.push(padBannerLine(" " + countsRaw + " ", "  " + countsStyled.trimStart(), INNER));
+    // ── Current task ──────────────────────────────────────────────────────
+    if (currentTask) {
+        const taskRaw = `  Focus: [${currentTask.id}] ${truncate(currentTask.title, 32)}`;
+        const taskStyled = `  ${textSecondary("Focus:")} ` +
+            accentPrimary(`[${currentTask.id}]`) + " " +
+            bold(textSecondary(truncate(currentTask.title, 32)));
+        lines.push(padBannerLine(" " + taskRaw + " ", taskStyled, INNER));
+    }
+    else {
+        const noTaskRaw = "  Focus: none";
+        lines.push(padBannerLine(" " + noTaskRaw + " ", "  " + textSecondary("Focus:") + " " + textTertiary("none"), INNER));
+    }
+    // ── Session info ──────────────────────────────────────────────────────
+    if (session.active) {
+        const shortId = session.id.length > 22 ? session.id.slice(0, 22) + ".." : session.id;
+        const sessionName = session.name.length > 0 ? truncate(session.name, 20) : shortId;
+        const sessionRaw = `  Session: ${sessionName}`;
+        const sessionStyled = `  ${textSecondary("Session:")} ` + accentPrimary(sessionName);
+        lines.push(padBannerLine(" " + sessionRaw + " ", sessionStyled, INNER));
+    }
+    // ── Memory bridge stats ───────────────────────────────────────────────
+    if (memStats.totalEntries > 0) {
+        lines.push(accentPrimary(BOX_LEFT_T + hBar + BOX_RIGHT_T));
+        const memRaw = `  Memory: ${memStats.totalEntries} entries`;
+        const memStyled = `  ${textSecondary("Memory:")} ` + accentSuccess(String(memStats.totalEntries)) +
+            textSecondary(" entries");
+        lines.push(padBannerLine(" " + memRaw + " ", memStyled, INNER));
+        for (const item of memStats.topThree) {
+            const truncItem = truncate(item, INNER - 6);
+            lines.push(padBannerLine(`    * ${truncItem} `, `    ${textTertiary("*")} ${textSecondary(truncItem)}`, INNER));
+        }
+    }
+    // ── Recent decisions ──────────────────────────────────────────────────
+    if (decisions.length > 0) {
+        lines.push(accentPrimary(BOX_LEFT_T + hBar + BOX_RIGHT_T));
+        const decHeaderRaw = "  What we decided recently:";
+        lines.push(padBannerLine(" " + decHeaderRaw + " ", "  " + bold(textSecondary("What we decided recently:")), INNER));
+        for (const dec of decisions) {
+            const label = dec.date ? `[${dec.date}]` : `[${dec.id}]`;
+            const decRaw = `  ${label} ${truncate(dec.title, INNER - label.length - 5)}`;
+            const decStyled = `  ${textTertiary(label)} ` +
+                textSecondary(truncate(dec.title, INNER - label.length - 5));
+            lines.push(padBannerLine(" " + decRaw + " ", decStyled, INNER));
+        }
+    }
+    // ── Quick action hints ────────────────────────────────────────────────
+    if (hints.hints.length > 0) {
+        lines.push(accentPrimary(BOX_LEFT_T + hBar + BOX_RIGHT_T));
+        for (const hint of hints.hints) {
+            const truncHint = truncate(hint, INNER - 5);
+            lines.push(padBannerLine(`  > ${truncHint} `, `  ${accentWarning(">")} ${accentWarning(truncHint)}`, INNER));
+        }
+    }
+    // ── Handoff note ──────────────────────────────────────────────────────
+    const note = handoffNote ?? session.handoffNote;
+    if (note) {
+        // Split into two lines if the note is long (up to 88 chars total)
+        lines.push(accentPrimary(BOX_LEFT_T + hBar + BOX_RIGHT_T));
+        const maxNoteChars = (INNER - 4) * 2; // two lines of inner width
+        const truncatedNote = truncate(note, maxNoteChars);
+        const noteLineMaxLen = INNER - 4; // leave space for "  > " prefix
+        const noteLine1Raw = truncatedNote.slice(0, noteLineMaxLen);
+        const noteLine2Raw = truncatedNote.length > noteLineMaxLen
+            ? truncatedNote.slice(noteLineMaxLen)
+            : null;
+        lines.push(padBannerLine(`   > ${noteLine1Raw} `, `   ${accentWarning(">")} ${accentWarning(noteLine1Raw)}`, INNER));
+        if (noteLine2Raw) {
+            lines.push(padBannerLine(`     ${noteLine2Raw} `, `     ${textSecondary(noteLine2Raw)}`, INNER));
+        }
+    }
+    // ── Bottom border ─────────────────────────────────────────────────────
+    lines.push(accentPrimary(BOX_BOTTOM_LEFT + hBar + BOX_BOTTOM_RIGHT));
+    return lines;
+}
+// ============================================================================
+// Project name detection
+// ============================================================================
+/**
+ * Detect the project name for display in the startup banner.
+ *
+ * Resolution order:
+ * 1. `name` field from `.cleo/project-info.json`
+ * 2. `name` field from `package.json` in `projectDir`
+ * 3. Last path segment of `projectDir`
+ *
+ * @param projectDir - The project root directory.
+ * @returns The resolved project display name.
+ */
+export function detectProjectName(projectDir) {
+    // Try .cleo/project-info.json first
+    try {
+        const infoPath = join(projectDir, ".cleo", "project-info.json");
+        if (existsSync(infoPath)) {
+            const raw = readFileSync(infoPath, "utf-8");
+            const parsed = JSON.parse(raw);
+            if (typeof parsed["name"] === "string" && parsed["name"].length > 0) {
+                return parsed["name"];
+            }
+        }
+    }
+    catch {
+        // Fall through
+    }
+    // Try package.json
+    try {
+        const pkgPath = join(projectDir, "package.json");
+        if (existsSync(pkgPath)) {
+            const raw = readFileSync(pkgPath, "utf-8");
+            const parsed = JSON.parse(raw);
+            if (typeof parsed["name"] === "string" && parsed["name"].length > 0) {
+                return parsed["name"];
+            }
+        }
+    }
+    catch {
+        // Fall through
+    }
+    // Fall back to last path segment
+    const parts = projectDir.replace(/\\/g, "/").split("/").filter(Boolean);
+    return parts[parts.length - 1] ?? "unknown-project";
+}
+// ============================================================================
+// Pi extension factory
+// ============================================================================
+// ============================================================================
+// Shared fetch helper (used by both session_start and /cleo:status)
+// ============================================================================
+/**
+ * Fetch all data needed to render the startup banner.
+ *
+ * All CLI calls are issued in parallel and are best-effort — no failure
+ * will throw or block. Returns a fully-populated data bundle.
+ *
+ * @param cwd - Project root directory.
+ * @returns All banner data.
+ */
+async function fetchBannerData(cwd) {
+    const [dashResult, sessionResult, currentResult, decisionsResult] = await Promise.allSettled([
+        execFileAsync("cleo", ["dash", "--json"], { timeout: 8_000, cwd }),
+        execFileAsync("cleo", ["session", "status", "--json"], { timeout: 8_000, cwd }),
+        execFileAsync("cleo", ["current", "--json"], { timeout: 8_000, cwd }),
+        execFileAsync("cleo", ["memory", "decision-find", "--limit", "3", "--json"], {
+            timeout: 8_000,
+            cwd,
+        }),
+    ]);
+    const tasks = dashResult.status === "fulfilled"
+        ? parseDashSummary(dashResult.value.stdout)
+        : { active: 0, pending: 0, done: 0, total: 0, blocked: 0 };
+    const session = sessionResult.status === "fulfilled"
+        ? parseSessionInfo(sessionResult.value.stdout)
+        : { active: false, id: "", name: "", currentTaskId: null, handoffNote: null };
+    const currentTask = currentResult.status === "fulfilled"
+        ? parseCurrentTask(currentResult.value.stdout)
+        : null;
+    const decisions = decisionsResult.status === "fulfilled"
+        ? parseRecentDecisions(decisionsResult.value.stdout)
+        : [];
+    // Memory bridge stats — synchronous read from filesystem
+    const bridgeContent = readMemoryBridgeContent(cwd);
+    const memStats = bridgeContent
+        ? parseMemoryBridgeStats(bridgeContent)
+        : { totalEntries: 0, topThree: [] };
+    const handoffNote = bridgeContent ? extractNoteFromBridgeContent(bridgeContent) : null;
+    const projectName = detectProjectName(cwd);
+    const hints = buildQuickHints(tasks, session, currentTask);
+    return { tasks, session, currentTask, handoffNote, projectName, decisions, memStats, hints };
+}
+/**
+ * Read raw `.cleo/memory-bridge.md` content.
+ *
+ * Returns null when the file does not exist or cannot be read.
+ *
+ * @param projectDir - The project root directory.
+ * @returns The raw file content, or null.
+ */
+function readMemoryBridgeContent(projectDir) {
+    try {
+        const bridgePath = join(projectDir, ".cleo", "memory-bridge.md");
+        if (!existsSync(bridgePath))
+            return null;
+        const content = readFileSync(bridgePath, "utf-8");
+        return content.length > 0 ? content : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Extract the last session handoff note from raw memory-bridge.md content.
+ *
+ * Prefers the `## Last Session` section's `Note:` line.
+ *
+ * @param content - Raw memory-bridge.md content.
+ * @returns The last session note, or null.
+ */
+function extractNoteFromBridgeContent(content) {
+    try {
+        const noteMatch = content.match(/[-*]\s+\*\*Note\*\*:\s*(.+)/m);
+        if (noteMatch?.[1])
+            return noteMatch[1].trim();
+        const altMatch = content.match(/\*\*Note\*\*[:\s]+(.+)/m);
+        if (altMatch?.[1])
+            return altMatch[1].trim();
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+// ============================================================================
+// Pi extension factory
+// ============================================================================
+/**
+ * Pi extension factory for the CleoOS branded startup experience.
+ *
+ * Registers:
+ *   - `session_start` — fetches all data, renders the branded startup banner
+ *   - `/cleo:status` — on-demand project status refresh
+ *   - `/cleo:focus <task-id>` — focus on a task from inside Pi
+ *   - `/cleo:end-session [note]` — end the current session from inside Pi
+ *
+ * All operations are best-effort — failures are silently swallowed so Pi
+ * is never blocked by CLEO unavailability.
+ *
+ * @param pi - The Pi extension API instance.
+ */
+export default function (pi) {
+    pi.on("session_start", async (_event, ctx) => {
+        const data = await fetchBannerData(ctx.cwd);
+        const bannerLines = buildStartupBanner(data.tasks, data.session, data.currentTask, data.handoffNote, data.projectName, data.decisions, data.memStats, data.hints);
+        if (ctx.hasUI) {
+            ctx.ui.setWidget("cleo-startup-banner", bannerLines, {
+                placement: "aboveEditor",
+            });
+            // Compact status bar entry
+            const taskSummary = `${data.tasks.active}a ${data.tasks.pending}p ${data.tasks.done}d`;
+            ctx.ui.setStatus("cleo-startup", `${ICON_FORGE} ${data.projectName.split("/").pop() ?? data.projectName} [${taskSummary}]`);
+        }
+        else {
+            // No UI — print to stderr as a text summary (visible in TTY mode)
+            process.stderr.write(bannerLines.join("\n") + "\n");
+        }
+    });
+    // -------------------------------------------------------------------------
+    // Command: /cleo:status — on-demand project status refresh
+    // -------------------------------------------------------------------------
+    pi.registerCommand("cleo:status", {
+        description: "Show CleoOS project status: tasks, session, decisions, and hints",
+        handler: async (_args, ctx) => {
+            const data = await fetchBannerData(ctx.cwd);
+            const bannerLines = buildStartupBanner(data.tasks, data.session, data.currentTask, data.handoffNote, data.projectName, data.decisions, data.memStats, data.hints);
+            // Refresh the widget too
+            if (ctx.hasUI) {
+                ctx.ui.setWidget("cleo-startup-banner", bannerLines, {
+                    placement: "aboveEditor",
+                });
+                ctx.ui.notify("CleoOS status refreshed", "info");
+            }
+            pi.sendMessage({
+                customType: "cleo-status",
+                content: bannerLines.join("\n"),
+                display: true,
+            }, { triggerTurn: false });
+        },
+    });
+    // -------------------------------------------------------------------------
+    // Command: /cleo:focus <task-id> — focus on a task
+    // -------------------------------------------------------------------------
+    pi.registerCommand("cleo:focus", {
+        description: "Focus on a CLEO task: /cleo:focus <task-id>",
+        handler: async (args, ctx) => {
+            const taskId = args.trim();
+            if (!taskId) {
+                pi.sendMessage({
+                    customType: "cleo-focus",
+                    content: "Usage: /cleo:focus <task-id>",
+                    display: true,
+                }, { triggerTurn: false });
+                return;
+            }
+            let resultText;
+            try {
+                const { stdout } = await execFileAsync("cleo", ["start", taskId], { timeout: 8_000, cwd: ctx.cwd });
+                resultText = stdout.trim() || `Focused on task ${taskId}`;
+            }
+            catch (err) {
+                resultText = `Failed to focus on ${taskId}: ${err instanceof Error ? err.message : String(err)}`;
+            }
+            pi.sendMessage({
+                customType: "cleo-focus",
+                content: resultText,
+                display: true,
+            }, { triggerTurn: false });
+            if (ctx.hasUI) {
+                ctx.ui.notify(`Focused: ${taskId}`, "info");
+            }
+        },
+    });
+    // -------------------------------------------------------------------------
+    // Command: /cleo:end-session [note] — end the current CLEO session
+    // -------------------------------------------------------------------------
+    pi.registerCommand("cleo:end-session", {
+        description: "End the current CLEO session with an optional handoff note",
+        handler: async (args, ctx) => {
+            const note = args.trim() || "Session ended from CleoOS Hearth";
+            let resultText;
+            try {
+                const { stdout } = await execFileAsync("cleo", ["session", "end", "--note", note], { timeout: 15_000, cwd: ctx.cwd });
+                resultText = stdout.trim() || "Session ended";
+            }
+            catch (err) {
+                resultText = `Failed to end session: ${err instanceof Error ? err.message : String(err)}`;
+            }
+            pi.sendMessage({
+                customType: "cleo-end-session",
+                content: resultText,
+                display: true,
+            }, { triggerTurn: false });
+            if (ctx.hasUI) {
+                ctx.ui.notify("CLEO session ended", "info");
+            }
+        },
+    });
+    // session_shutdown: no cleanup needed — Pi clears widgets on shutdown
+    pi.on("session_shutdown", async () => {
+        // Intentional no-op
+    });
+}
+//# sourceMappingURL=cleo-startup.js.map