@pugi/cli 0.1.0-alpha.7 → 0.1.0-alpha.9

package/dist/core/repl/session.js

@@ -32,6 +32,9 @@ import { evaluateCap, describeVerdict } from './cap-warning.js';
 import { parseSlashCommand } from './slash-commands.js';
 import { webFetchTool } from '../../tools/web-fetch.js';
 import { loadSettings } from '../settings.js';
+import { getJobRegistry } from '../jobs/registry.js';
+import { existsSync, readdirSync, statSync } from 'node:fs';
+import { resolve as resolvePath } from 'node:path';
 const MAX_TRANSCRIPT_ROWS = 500;
 const MAX_RECONNECT_ATTEMPTS = 10;
 const RECONNECT_BASE_MS = 250;
@@ -45,6 +48,18 @@ export class ReplSession {
     reconnectAttempt = 0;
     reconnectTimer;
     closed = false;
+    /**
+     * Last non-trivial step.detail recorded per taskId. The server streams
+     * the persona reply incrementally via `agent.step` events whose
+     * `detail` field carries the cumulative model output. `agent.completed`
+     * arrives last and previously overwrote the visible detail to the
+     * literal string `'shipped'` while the transcript line said only
+     * `shipped.` — the actual reply text was lost. By caching the last
+     * non-trivial detail here, we can flush it into the transcript when
+     * the agent completes so the operator sees what the persona actually
+     * said. CEO wave-2 fix 2026-05-25.
+     */
+    lastStepDetail = new Map();
     constructor(options) {
         this.options = options;
         this.state = {
@@ -81,6 +96,7 @@ export class ReplSession {
             const { sessionId } = await this.options.transport.createSession({
                 apiUrl: this.options.apiUrl,
                 apiKey: this.options.apiKey,
+                workspace: this.options.workspace,
             });
             this.patch({ sessionId, connection: 'connecting' });
             this.openStream();
@@ -122,7 +138,11 @@ export class ReplSession {
                 // UI overlays - no transport interaction.
                 return verdict;
             case 'quit':
-                this.appendSystemLine('Brief it. It ships.');
+                // UI Designer audit 2026-05-25: "Brief it. It ships." is reserved
+                // for identity intro + landing per wave-4 prompt rule. Drop the
+                // tagline drift here; tell the operator what happened and how to
+                // resume.
+                this.appendSystemLine('On watch ended. pugi resume to come back.');
                 return verdict;
             case 'error':
                 this.appendSystemLine(verdict.message);
@@ -139,8 +159,112 @@ export class ReplSession {
                 await this.dispatchWebFetch(verdict.url);
                 return verdict;
             }
+            case 'clear': {
+                this.clearTranscript();
+                return verdict;
+            }
+            case 'version': {
+                this.appendSystemLine(`pugi ${this.options.cliVersion}`);
+                return verdict;
+            }
+            case 'jobs': {
+                await this.dispatchJobs();
+                return verdict;
+            }
+            case 'diff': {
+                this.dispatchDiff();
+                return verdict;
+            }
+            case 'cost': {
+                this.dispatchCost();
+                return verdict;
+            }
+            case 'status': {
+                this.dispatchStatus();
+                return verdict;
+            }
+            case 'stub': {
+                this.appendSystemLine(verdict.message);
+                return verdict;
+            }
         }
     }
+    /**
+     * Reset the conversation transcript. The agent registry stays intact
+     * so the operator can `/clear` to declutter the chat pane without
+     * losing visibility into running dispatches.
+     */
+    clearTranscript() {
+        this.patch({ transcript: [] });
+    }
+    /* ------------- Tier 1 / Tier 2 wired handlers -------------- */
+    async dispatchJobs() {
+        try {
+            const registry = getJobRegistry();
+            const entries = await registry.list();
+            if (entries.length === 0) {
+                this.appendSystemLine('No background jobs tracked.');
+                return;
+            }
+            this.appendSystemLine(`Background jobs (${entries.length}):`);
+            for (const entry of entries) {
+                const id = entry.id.replace(/^pj-/, '').slice(0, 8);
+                const status = entry.status;
+                const cmd = entry.command.length > 48 ? `${entry.command.slice(0, 47)}…` : entry.command;
+                this.appendSystemLine(`  ${id}  ${status.padEnd(10)}  ${cmd}`);
+            }
+        }
+        catch (error) {
+            this.appendSystemLine(`/jobs failed: ${this.errorMessage(error)}`);
+        }
+    }
+    dispatchDiff() {
+        try {
+            const artifactsRoot = resolvePath(process.cwd(), '.pugi', 'artifacts');
+            if (!existsSync(artifactsRoot)) {
+                this.appendSystemLine('No pending diffs (.pugi/artifacts/ not found).');
+                return;
+            }
+            const subdirs = readdirSync(artifactsRoot, { withFileTypes: true })
+                .filter((d) => d.isDirectory())
+                .map((d) => d.name);
+            const diffs = [];
+            for (const name of subdirs) {
+                const candidate = resolvePath(artifactsRoot, name, 'diff.patch');
+                if (existsSync(candidate)) {
+                    const size = statSync(candidate).size;
+                    diffs.push(`  ${name}/diff.patch (${size} bytes)`);
+                }
+            }
+            if (diffs.length === 0) {
+                this.appendSystemLine('No pending diffs.');
+                return;
+            }
+            this.appendSystemLine(`Pending diffs (${diffs.length}):`);
+            for (const line of diffs)
+                this.appendSystemLine(line);
+        }
+        catch (error) {
+            this.appendSystemLine(`/diff failed: ${this.errorMessage(error)}`);
+        }
+    }
+    dispatchCost() {
+        const { tokensDownstreamTotal, agents } = this.state;
+        const active = agents.filter((a) => a.status === 'queued' || a.status === 'thinking').length;
+        const lineTokens = `Tokens this session: ${tokensDownstreamTotal.toLocaleString()} (in+out).`;
+        const lineAgents = `Active dispatches: ${active} of cap.`;
+        this.appendSystemLine(lineTokens);
+        this.appendSystemLine(lineAgents);
+        this.appendSystemLine('Full per-persona budget breakdown lands in α6.5.');
+    }
+    dispatchStatus() {
+        const sessionId = this.state.sessionId ?? '(unbound)';
+        const reach = this.state.connection;
+        this.appendSystemLine(`Backend: ${this.options.apiUrl} (${reach}).`);
+        this.appendSystemLine(`Session: ${sessionId}.`);
+        this.appendSystemLine(`Workspace: ${this.state.workspaceLabel}.`);
+        this.appendSystemLine(`CLI: pugi ${this.state.cliVersion}.`);
+    }
     /**
      * Fetch one URL via the web_fetch tool and inject the resulting
      * Markdown into the transcript as an operator-attributed brief. The
@@ -284,6 +408,20 @@ export class ReplSession {
         switch (event.type) {
             case 'agent.spawned': {
                 const persona = safePersonaName(event.role);
+                // Wave 4 fix 2026-05-25: the roster collapses to one row per
+                // persona slug. The α5.7 reducer pushed a fresh row on every
+                // spawn, so after three turns the bottom panel stacked
+                // "Mira orchestrator shipped" three times. The new contract:
+                //   - If a row already exists for this personaSlug, REUSE it.
+                //     Replace its taskId, reset status to 'queued', clear the
+                //     detail line, restart the duration clock, zero the token
+                //     counters. The persona name + slug + role stay stable
+                //     (they are the row identity).
+                //   - If no row exists yet, push a new one.
+                // Per-task lifecycle (step/tokens/completed/blocked/failed) is
+                // keyed off `taskId` everywhere, so the reused row still folds
+                // the latest task's events correctly.
+                const existing = this.state.agents.find((a) => a.personaSlug === event.personaSlug);
                 const node = {
                     taskId: event.taskId,
                     role: event.role,
@@ -295,7 +433,14 @@ export class ReplSession {
                     tokensIn: 0,
                     tokensOut: 0,
                 };
-                this.patch({ agents: [node, ...this.state.agents] });
+                if (existing) {
+                    this.patch({
+                        agents: this.state.agents.map((a) => a.personaSlug === event.personaSlug ? node : a),
+                    });
+                }
+                else {
+                    this.patch({ agents: [node, ...this.state.agents] });
+                }
                 // The conversation pane already prefixes persona rows with the
                 // persona name in the persona's hue colour. Skip embedding the
                 // name in the body text to avoid the `Marcus Marcus dispatched`
@@ -307,6 +452,12 @@ export class ReplSession {
                 return;
             }
             case 'agent.step': {
+                // Cache the running detail per task so we can surface the
+                // model's actual reply when agent.completed lands (otherwise
+                // the reply disappears under the literal 'shipped' patch).
+                if (event.detail && event.detail.trim().length > 0) {
+                    this.lastStepDetail.set(event.taskId, event.detail);
+                }
                 this.patch({
                     agents: this.state.agents.map((a) => a.taskId === event.taskId
                         ? { ...a, status: 'thinking', detail: event.detail }
@@ -330,18 +481,41 @@ export class ReplSession {
             }
             case 'agent.completed': {
                 const target = this.state.agents.find((a) => a.taskId === event.taskId);
+                const finalDetail = this.lastStepDetail.get(event.taskId);
+                this.lastStepDetail.delete(event.taskId);
                 this.patch({
                     agents: this.state.agents.map((a) => a.taskId === event.taskId
                         ? { ...a, status: 'shipped', detail: 'shipped' }
                         : a),
                 });
                 if (target) {
-                    this.appendPersonaLine(target.personaSlug, 'shipped.');
+                    // If the persona actually produced a reply via incremental
+                    // agent.step events, render that reply in the transcript so
+                    // the operator sees the full answer. The threshold (>4 chars
+                    // + not the queued placeholder) filters out the no-op
+                    // "shipped"/"queued for dispatch" placeholders the dispatcher
+                    // emits before the model speaks. Multi-line replies are
+                    // emitted line by line so the conversation pane wraps each
+                    // sentence on its own row.
+                    if (finalDetail
+                        && finalDetail !== 'queued for dispatch'
+                        && finalDetail.trim().length > 4) {
+                        for (const line of finalDetail.split('\n')) {
+                            const trimmed = line.trim();
+                            if (trimmed.length > 0) {
+                                this.appendPersonaLine(target.personaSlug, trimmed);
+                            }
+                        }
+                    }
+                    else {
+                        this.appendPersonaLine(target.personaSlug, 'shipped.');
+                    }
                 }
                 return;
             }
             case 'agent.blocked': {
                 const target = this.state.agents.find((a) => a.taskId === event.taskId);
+                this.lastStepDetail.delete(event.taskId);
                 this.patch({
                     agents: this.state.agents.map((a) => a.taskId === event.taskId
                         ? { ...a, status: 'blocked', detail: event.detail }
@@ -354,6 +528,7 @@ export class ReplSession {
             }
             case 'agent.failed': {
                 const target = this.state.agents.find((a) => a.taskId === event.taskId);
+                this.lastStepDetail.delete(event.taskId);
                 this.patch({
                     agents: this.state.agents.map((a) => a.taskId === event.taskId
                         ? { ...a, status: 'failed', detail: event.error }

package/dist/core/repl/slash-commands.js

@@ -1,32 +1,99 @@
 /**
- * REPL slash command registry - Sprint α5.7 (ADR-0056 PR-PUGI-CLI-REPL-DEFAULT).
+ * REPL slash command registry — Sprint α5.7, expanded α6.14 wave 2.
  *
- * The REPL input box surfaces a small palette of slash commands that the
- * operator can run from inside a persistent session: dispatch a brief,
- * inspect the agent roster, stop a running persona, open the help
- * overlay, or quit. The registry is intentionally narrow at M1 -
- * complementary surfaces (`/sync`, `/handoff`, `/budget`) ship as proper
- * subcommands in α5.8+ and stay reachable from a non-REPL `pugi
- * <command>` invocation.
+ * The REPL input box surfaces a palette of slash commands the operator
+ * can run from inside a persistent session. The wave-2 expansion (CEO
+ * 2026-05-25) grows the surface from 6 to 20 commands so the `/help`
+ * overlay matches the breadth Claude Code / Codex CLI operators expect.
  *
- * The registry is pure: each entry returns a `SlashCommandResult`
- * describing what the REPL session should do next. The session module
- * owns the side effects (network calls, dispatcher invocation, exit).
- * Keeping the surface pure lets the unit test exercise every shape
- * without standing up an Ink runtime or an Anvil endpoint.
+ * The registry is pure: each `parseSlashCommand` call returns a
+ * `SlashCommandResult` describing what the REPL session should do next.
+ * The session module owns the side effects (network calls, dispatcher
+ * invocation, exit, transcript clear). Keeping the surface pure lets
+ * the unit test exercise every shape without standing up an Ink runtime
+ * or an Anvil endpoint.
+ *
+ * Tiering (per CEO wave-2 spec):
+ *
+ *   Tier 1 — wired against real state (3 + existing 6 = 9 wired):
+ *     brief, agents, stop, help, quit, web, clear, version, jobs.
+ *
+ *   Tier 2 — best-effort wiring against existing surfaces (3):
+ *     diff, cost, status.
+ *
+ *   Tier 3 — deterministic stubs ("coming in αX.Y") (8):
+ *     compact, resume, memory, config, privacy, budget, mcp, undo.
  *
  * Brand voice (brandbook §08): power words `brief / dispatch / stop /
- * agents / quit`. Tagline `Brief it. It ships.` reserved for `/quit`
- * confirmation and `/help` footer - never inline.
+ * agents / quit / shipped`. Tagline `Brief it. It ships.` reserved for
+ * `/quit` confirmation and `/help` footer — never inline.
  */
 import { listRoles } from '../agents/registry.js';
+/**
+ * Deterministic stub copy returned by the Tier 3 commands. Spec'd
+ * inline so the unit test can pin the exact text without poking at
+ * the help overlay. The version tag at the end maps to the sprint we
+ * intend to land the real wiring in.
+ */
+export const SLASH_STUB_MESSAGES = Object.freeze({
+    brief: '',
+    agents: '',
+    stop: '',
+    help: '',
+    quit: '',
+    web: '',
+    clear: '',
+    version: '',
+    jobs: '',
+    diff: '',
+    cost: '',
+    status: '',
+    compact: 'Manual context compaction lands in α6.5.',
+    resume: 'Resume last session lands in α6.4 once SQLite session.db lands.',
+    memory: 'Session memory editor lands in α6.5.',
+    config: 'Run `pugi config list` from a fresh shell for the full surface; in-REPL editor lands in α6.5.',
+    privacy: 'Run `pugi privacy show` from a fresh shell; in-REPL toggle lands in α6.5.',
+    budget: 'Run `pugi budget` from a fresh shell; in-REPL summary lands in α6.5.',
+    mcp: 'Run `pugi config mcp list` from a fresh shell; in-REPL palette lands in α6.5.',
+    undo: 'Run `pugi undo` from a fresh shell; in-REPL undo lands in α6.5.',
+});
 export const SLASH_COMMAND_HELP = Object.freeze([
-    { name: 'brief', args: '<text>', gloss: 'Dispatch a brief to the workforce' },
-    { name: 'agents', args: '', gloss: 'List the on-watch agent roster' },
-    { name: 'stop', args: '<persona>', gloss: 'Stop one agent by persona slug' },
-    { name: 'help', args: '', gloss: 'Show this help overlay' },
-    { name: 'quit', args: '', gloss: 'Exit the REPL (session resumes via pugi resume)' },
-    { name: 'web', args: '<url>', gloss: 'Fetch a URL and brief Pugi on the page' },
+    // Workforce dispatch
+    { name: 'brief', args: '<text>', gloss: 'Dispatch a brief to the workforce', group: 'Workforce dispatch' },
+    { name: 'agents', args: '', gloss: 'List the on-watch agent roster', group: 'Workforce dispatch' },
+    { name: 'stop', args: '<persona>', gloss: 'Stop one agent by persona slug', group: 'Workforce dispatch' },
+    { name: 'jobs', args: '', gloss: 'List background jobs', group: 'Workforce dispatch' },
+    // Session
+    { name: 'clear', args: '', gloss: 'Clear conversation pane', group: 'Session' },
+    { name: 'resume', args: '', gloss: 'Resume last session  (α6.4)', group: 'Session', stub: true },
+    { name: 'compact', args: '', gloss: 'Manual context compaction  (α6.5)', group: 'Session', stub: true },
+    { name: 'memory', args: '', gloss: 'Session memory editor  (α6.5)', group: 'Session', stub: true },
+    // Pugi tools
+    { name: 'web', args: '<url>', gloss: 'Fetch a URL into context', group: 'Pugi tools' },
+    { name: 'diff', args: '', gloss: 'Show pending diff', group: 'Pugi tools' },
+    { name: 'cost', args: '', gloss: 'Token usage + budget', group: 'Pugi tools' },
+    { name: 'status', args: '', gloss: 'Backend + tenant status', group: 'Pugi tools' },
+    // Settings
+    { name: 'config', args: '', gloss: 'Show config', group: 'Settings', stub: true },
+    { name: 'privacy', args: '', gloss: 'Show privacy mode', group: 'Settings', stub: true },
+    { name: 'budget', args: '', gloss: 'Show usage budget', group: 'Settings', stub: true },
+    { name: 'mcp', args: '', gloss: 'List MCP servers', group: 'Settings', stub: true },
+    { name: 'undo', args: '', gloss: 'Undo last write', group: 'Settings', stub: true },
+    // Meta
+    { name: 'help', args: '', gloss: 'Show this help overlay', group: 'Meta' },
+    { name: 'version', args: '', gloss: 'Show CLI version', group: 'Meta' },
+    { name: 'quit', args: '', gloss: 'Exit the REPL', group: 'Meta' },
+]);
+/**
+ * Ordered list of groups. Drives the `/help` overlay sectioning so the
+ * operator reads commands by intent (dispatch first, meta last).
+ */
+export const SLASH_COMMAND_GROUPS = Object.freeze([
+    'Workforce dispatch',
+    'Session',
+    'Pugi tools',
+    'Settings',
+    'Meta',
 ]);
 /**
  * Parse one line of input from the REPL. The contract:
@@ -34,13 +101,15 @@ export const SLASH_COMMAND_HELP = Object.freeze([
  *   - Empty / whitespace-only input returns `noop` with the original
  *     text so the REPL can ignore it without printing anything.
  *   - Input that does not start with `/` is treated as an implicit
- *     `/brief <text>` - the most-common operator action.
+ *     `/brief <text>` — the most-common operator action.
  *   - `/<name> [args]` resolves the name against the registry; unknown
  *     names return `error` so the REPL can render a one-line tip
  *     instead of silently dropping the input.
+ *   - Tier 3 stubs return `{ kind: 'stub', name, message }` so the REPL
+ *     can render the deterministic "coming in αX.Y" copy uniformly.
  *
  * The function never throws. Bad input maps to a structured result the
- * REPL can render - the alternative (throwing from a keystroke handler)
+ * REPL can render — the alternative (throwing from a keystroke handler)
  * would unmount Ink mid-frame.
  */
 export function parseSlashCommand(input) {
@@ -98,6 +167,40 @@ export function parseSlashCommand(input) {
             }
             return { kind: 'web', url: tail };
         }
+        case 'clear':
+        case 'cls': {
+            return { kind: 'clear' };
+        }
+        case 'version':
+        case 'v': {
+            return { kind: 'version' };
+        }
+        case 'jobs': {
+            return { kind: 'jobs' };
+        }
+        case 'diff': {
+            return { kind: 'diff' };
+        }
+        case 'cost': {
+            return { kind: 'cost' };
+        }
+        case 'status': {
+            return { kind: 'status' };
+        }
+        case 'compact':
+        case 'resume':
+        case 'memory':
+        case 'config':
+        case 'privacy':
+        case 'budget':
+        case 'mcp':
+        case 'undo': {
+            return {
+                kind: 'stub',
+                name: name,
+                message: SLASH_STUB_MESSAGES[name],
+            };
+        }
         default: {
             return {
                 kind: 'error',

package/dist/core/repl/workspace-context.js

@@ -0,0 +1,113 @@
+/**
+ * Workspace context resolver — Sprint α6.14 wave 4.
+ *
+ * Reads the operator's cwd and synthesises the workspace bundle the CLI
+ * forwards to admin-api on POST /api/pugi/sessions. Mira's prompt v1.1
+ * consumes the bundle so "what repo is this?" / "а изучи репо…" answers
+ * from the live cwd instead of bouncing back "репо не привязано" (CEO
+ * dogfood 2026-05-25).
+ *
+ * Three fields:
+ *
+ *   - `workspaceCwd`     — absolute path the CLI was launched from.
+ *   - `workspaceSlug`    — a stable short identifier (slugForCwd).
+ *   - `workspaceSummary` — first ~200 chars of `.pugi/PUGI.md` if the
+ *                          repo has one, else the directory basename.
+ *
+ * The helper is pure-ish (reads the filesystem but does not mutate it)
+ * so the production caller in `runtime/cli.ts` can call it eagerly at
+ * REPL launch without touching the network. Tests pass an explicit cwd
+ * + `fs` stub so the resolver stays deterministic.
+ *
+ * Failure mode: any FS error (permission denied, missing PUGI.md,
+ * symlink loop) returns the basename fallback. The CLI never bubbles
+ * the error to the operator — workspace context is a best-effort hint,
+ * not a precondition for opening the session.
+ */
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { basename, resolve as resolvePath } from 'node:path';
+import { slugForCwd } from './history.js';
+/** Cap on the PUGI.md head we forward. Mirrors the admin-api clamp. */
+const PUGI_MD_HEAD_LIMIT = 200;
+/**
+ * Resolve a `ReplWorkspaceContext` from the operator's working directory.
+ * Returns a bundle with at least `workspaceCwd` + `workspaceSlug` +
+ * `workspaceSummary` populated. The summary is the PUGI.md head when
+ * available, else the directory basename.
+ */
+export function resolveWorkspaceContext(cwd) {
+    const normalised = resolvePath(cwd);
+    const slug = slugForCwd(normalised);
+    const summary = readPugiSummary(normalised) ?? basename(normalised) ?? 'workspace';
+    return {
+        workspaceCwd: normalised,
+        workspaceSlug: slug,
+        workspaceSummary: summary,
+    };
+}
+/**
+ * Read the first ~200 chars of `.pugi/PUGI.md` if the file exists. The
+ * project's own description is the highest-signal one-line summary we
+ * can hand to Mira — `pugi init` writes it on workspace creation, and
+ * the operator may have edited it since.
+ *
+ * Returns null on any FS error so the caller falls back to the
+ * basename. We never throw — workspace context is best-effort.
+ */
+function readPugiSummary(cwd) {
+    const candidate = resolvePath(cwd, '.pugi', 'PUGI.md');
+    try {
+        if (!existsSync(candidate))
+            return null;
+        const st = statSync(candidate);
+        if (!st.isFile())
+            return null;
+        // Cap the read at 2 KB — even a malformed PUGI.md will not be
+        // bigger than that's worth on a one-line summary, and capping
+        // bounds the slice cost on a giant file.
+        const raw = readFileSync(candidate, 'utf8').slice(0, 2048);
+        return summariseMarkdown(raw);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Reduce a PUGI.md head to one short summary line: strip the front-
+ * matter and the leading H1 marker, take the first non-empty line,
+ * cap at PUGI_MD_HEAD_LIMIT. Whitespace collapses to single spaces so
+ * the summary survives the admin-api clamp without weird wrap.
+ */
+export function summariseMarkdown(raw) {
+    if (!raw || raw.trim().length === 0)
+        return null;
+    const body = stripFrontmatter(raw);
+    const lines = body.split(/\r?\n/);
+    for (const line of lines) {
+        // Strip leading `#` markers + trim whitespace. A heading like
+        // "# My Project" becomes "My Project".
+        const stripped = line.replace(/^#+\s*/, '').trim();
+        if (stripped.length === 0)
+            continue;
+        const oneLine = stripped.replace(/\s+/g, ' ');
+        return oneLine.length > PUGI_MD_HEAD_LIMIT
+            ? oneLine.slice(0, PUGI_MD_HEAD_LIMIT)
+            : oneLine;
+    }
+    return null;
+}
+/**
+ * Drop a YAML front-matter block (`---\n…\n---`) from the head of a
+ * Markdown file. Mira does not need to see the metadata; the prose body
+ * carries the project description.
+ */
+function stripFrontmatter(raw) {
+    if (!raw.startsWith('---'))
+        return raw;
+    const end = raw.indexOf('\n---', 3);
+    if (end === -1)
+        return raw;
+    const afterFrontmatter = raw.slice(end + 4);
+    return afterFrontmatter.replace(/^\r?\n/, '');
+}
+//# sourceMappingURL=workspace-context.js.map

package/dist/runtime/cli.js

@@ -35,7 +35,7 @@ import { runBudgetCommand } from './commands/budget.js';
  * packages/pugi-sdk/package.json); the publish workflow validates the
  * three are in lockstep.
  */
-const PUGI_CLI_VERSION = '0.1.0-alpha.7';
+const PUGI_CLI_VERSION = '0.1.0-alpha.9';
 const handlers = {
     accounts,
     build: runEngineTask('build_task'),
@@ -169,6 +169,7 @@ export async function runCli(argv) {
                 workspaceLabel: workspaceLabel(process.cwd()),
                 cliVersion: PUGI_CLI_VERSION,
                 updateBanner,
+                skipSplash: flags.noSplash,
             });
             return;
         }
@@ -204,6 +205,7 @@ function parseArgs(argv) {
         noTty: false,
         allowFetch: false,
         noUpdateCheck: false,
+        noSplash: process.env.PUGI_SKIP_SPLASH === '1',
     };
     const args = [];
     // Sprint 2E: `pugi --version` / `-v` are universal install-test conventions
@@ -245,6 +247,9 @@ function parseArgs(argv) {
         else if (arg === '--no-update-check') {
             flags.noUpdateCheck = true;
         }
+        else if (arg === '--no-splash') {
+            flags.noSplash = true;
+        }
         else if (arg.startsWith('--privacy=')) {
             flags.privacy = parsePrivacyMode(arg.slice('--privacy='.length));
         }
@@ -303,6 +308,8 @@ async function help(_args, flags, _session) {
         '                          recording flows, dumb terminals).',
         '  --no-update-check       Silence the REPL startup update banner. Pairs',
         '                          with PUGI_SKIP_UPDATE_BANNER=1.',
+        '  --no-splash             Skip the REPL boot splash. Pairs with',
+        '                          PUGI_SKIP_SPLASH=1.',
         '',
         PUGI_TAGLINE,
         'Execution defaults to local. Use --remote or --web to create a handoff bundle.',

package/dist/tui/input-box.js

@@ -456,7 +456,7 @@ export function InputBox(props) {
         : Math.min(paletteIndex, paletteView.rows.length - 1);
     const divider = '─'.repeat(innerWidth);
     const focusedMatch = search ? search.matches[search.focusedIndex] : undefined;
-    return (_jsxs(Box, { flexDirection: "column", children: [_jsx(Text, { color: "cyan", dimColor: true, children: divider }), _jsx(Box, { borderStyle: "round", borderColor: "cyan", paddingX: 1, flexDirection: "column", children: search ? (_jsxs(Box, { flexDirection: "column", children: [_jsxs(Box, { children: [_jsx(Text, { color: "cyan", children: '(reverse-i-search) ' }), _jsx(Text, { children: `\`${search.query}\`: ` }), _jsx(Text, { color: "yellow", children: focusedMatch ? focusedMatch.brief : '(no match)' })] }), _jsx(Box, { children: _jsx(Text, { dimColor: true, children: `Ctrl+R next  ·  Ctrl+S prev  ·  Enter accept  ·  Esc cancel  ·  ${search.matches.length} match${search.matches.length === 1 ? '' : 'es'}` }) })] })) : (_jsxs(Box, { children: [_jsx(Text, { color: "cyan", children: '› ' }), _jsx(Text, { children: renderLineWithCursor(line, cursor, cursorVisible) })] })) }), line.length > innerWidth - 4 ? (_jsxs(Box, { children: [_jsx(Text, { color: "gray", children: '┊ ' }), _jsx(Text, { dimColor: true, children: 'line wraps - Enter still submits' })] })) : null, _jsx(SlashPalette, { rows: paletteView.rows, focusedIndex: clampedPaletteIndex, totalBeforeLimit: paletteView.totalBeforeLimit }), _jsx(Box, { children: _jsx(Text, { dimColor: true, children: '↑/↓ history  ·  Ctrl+R search  ·  / commands  ·  Enter brief  ·  Esc cancel  ·  Ctrl+C ×2 exit' }) })] }));
+    return (_jsxs(Box, { flexDirection: "column", children: [_jsx(Text, { color: "cyan", dimColor: true, children: divider }), _jsx(Box, { paddingX: 1, flexDirection: "column", children: search ? (_jsxs(Box, { flexDirection: "column", children: [_jsxs(Box, { children: [_jsx(Text, { color: "cyan", children: '(reverse-i-search) ' }), _jsx(Text, { children: `\`${search.query}\`: ` }), _jsx(Text, { color: "yellow", children: focusedMatch ? focusedMatch.brief : '(no match)' })] }), _jsx(Box, { children: _jsx(Text, { dimColor: true, children: `Ctrl+R next  ·  Ctrl+S prev  ·  Enter accept  ·  Esc cancel  ·  ${search.matches.length} match${search.matches.length === 1 ? '' : 'es'}` }) })] })) : (_jsxs(Box, { children: [_jsx(Text, { color: "cyan", children: '› ' }), _jsx(Text, { children: renderLineWithCursor(line, cursor, cursorVisible) })] })) }), _jsx(Text, { color: "cyan", dimColor: true, children: divider }), line.length > innerWidth - 4 ? (_jsxs(Box, { children: [_jsx(Text, { color: "gray", children: '┊ ' }), _jsx(Text, { dimColor: true, children: 'line wraps - Enter still submits' })] })) : null, _jsx(SlashPalette, { rows: paletteView.rows, focusedIndex: clampedPaletteIndex, totalBeforeLimit: paletteView.totalBeforeLimit }), _jsx(Box, { children: _jsx(Text, { dimColor: true, children: '↑/↓ history  ·  Ctrl+R search  ·  / commands  ·  Enter brief  ·  Esc cancel  ·  Ctrl+C ×2 exit' }) })] }));
 }
 /**
  * Render the line with the cursor glyph inserted at `cursor`. The cursor

package/dist/tui/repl-render.js

@@ -19,7 +19,8 @@
 import React from 'react';
 import { render } from 'ink';
 import { Repl } from './repl.js';
-import { ReplSession } from '../core/repl/session.js';
+import { ReplSession, } from '../core/repl/session.js';
+import { resolveWorkspaceContext } from '../core/repl/workspace-context.js';
 /**
  * Mount the REPL and resolve when the user exits via Ctrl+C × 2 or
  * `/quit`. The session is closed (server-side stays alive; resume via
@@ -27,17 +28,27 @@ import { ReplSession } from '../core/repl/session.js';
  */
 export async function renderRepl(options) {
     const transport = createProductionTransport();
+    // Auto-bind the workspace context from process.cwd() so Mira knows
+    // which repo the operator launched the CLI in. The resolver is
+    // best-effort — any FS error falls back to a basename-only summary,
+    // never blocks REPL launch. Wave 4 fix 2026-05-25.
+    const workspace = options.workspace ?? resolveWorkspaceContext(process.cwd());
     const session = new ReplSession({
         apiUrl: options.apiUrl,
         apiKey: options.apiKey,
         workspaceLabel: options.workspaceLabel,
         cliVersion: options.cliVersion,
         transport,
+        workspace,
     });
     // Kick off the connect; the Repl renders the connecting state until
     // the session pushes `connection: 'on_watch'` from the SSE onOpen.
     void session.start();
-    const instance = render(React.createElement(Repl, { session, updateBanner: options.updateBanner ?? null }));
+    const instance = render(React.createElement(Repl, {
+        session,
+        updateBanner: options.updateBanner ?? null,
+        skipSplash: options.skipSplash === true,
+    }));
     try {
         await instance.waitUntilExit();
     }
@@ -50,11 +61,22 @@ export async function renderRepl(options) {
 /* ------------------------------------------------------------------ */
 function createProductionTransport() {
     return {
-        async createSession({ apiUrl, apiKey }) {
+        async createSession({ apiUrl, apiKey, workspace }) {
+            // Forward the workspace bundle in the POST body so admin-api can
+            // surface `<workspace-context>` in Mira's prompt. Older admin-api
+            // builds ignore unknown fields, so this stays forward-compatible.
+            // Wave 4 fix 2026-05-25.
+            const body = {};
+            if (workspace?.workspaceCwd)
+                body.workspaceCwd = workspace.workspaceCwd;
+            if (workspace?.workspaceSlug)
+                body.workspaceSlug = workspace.workspaceSlug;
+            if (workspace?.workspaceSummary)
+                body.workspaceSummary = workspace.workspaceSummary;
             const response = await fetch(joinUrl(apiUrl, '/api/pugi/sessions'), {
                 method: 'POST',
                 headers: jsonHeaders(apiKey),
-                body: JSON.stringify({}),
+                body: JSON.stringify(body),
             });
             const json = await readJson(response);
             const sessionId = json.sessionId;

package/dist/tui/repl-splash-art.js

@@ -0,0 +1,64 @@
+/**
+ * ASCII pug mascot for the REPL boot splash (α6.14 wave 3).
+ *
+ * Hand-crafted at 9 rows × 20 columns to read as a pug at a single
+ * glance — references the cyber-zoo hero glyph in
+ * `apps/clawhost-web/public/brand/hero-pug.png`: blocky pug face with
+ * angular ear flaps on either side of the head, forehead crease,
+ * angular cyan eyes (`◉`), smushed snout, undershot jaw, and a small
+ * cyan circuit chip (`▐■▌`) on the lower-right cheek.
+ *
+ * Separation of art + cyan mask lets the unit test assert structure
+ * (row count, line widths, mask shape, at-least-one cyan pixel per
+ * eye row) without coupling to the Ink renderer. The renderer in
+ * `repl-splash.tsx` splits each row into runs and colors the masked
+ * columns cyan (#3DA9FC, brandbook §05).
+ *
+ * Convention:
+ *   - PUG_MASCOT[i]            = one row of the silhouette
+ *   - PUG_MASCOT_CYAN_MASK[i]  = parallel boolean array, true => that
+ *                                column renders cyan instead of gray
+ *
+ * Both arrays MUST stay the same length and each mask row MUST be the
+ * same length as the corresponding art row. A unit test enforces this.
+ */
+/* eslint-disable no-irregular-whitespace */
+export const PUG_MASCOT = [
+    '   ▄▀▀▀▄▄▄▀▀▀▄    ',
+    '  █▄▄       ▄▄█   ',
+    '  █  ▀▄▄▄▄▄▀  █   ',
+    '  █  ◉     ◉  █   ',
+    '   ▀▄  ▀█▀  ▄▀    ',
+    '     █▀▀▀▀▀█      ',
+    '     █▒▒▒▒▒█ ▐■▌  ',
+    '      ▀▄▄▄▀       ',
+    '        ▀         ',
+];
+/**
+ * Cyan accents are derived from the source characters so the art file
+ * stays the single source of truth. Two glyph classes get colored:
+ *   - `◉`     -> the two cyan eyes on row 3
+ *   - `▐■▌`   -> the cyan chip cluster on row 6 (right cheek)
+ *
+ * Everything else renders gray. The derivation runs at module load,
+ * which keeps the mask trivially auditable from the source array.
+ */
+export const PUG_MASCOT_CYAN_MASK = PUG_MASCOT.map((row) => {
+    const mask = new Array(row.length).fill(false);
+    for (let column = 0; column < row.length; column += 1) {
+        const ch = row.charAt(column);
+        if (ch === '◉' || ch === '▐' || ch === '■' || ch === '▌') {
+            mask[column] = true;
+        }
+    }
+    return mask;
+});
+/**
+ * Pre-computed silhouette dimensions for layout math in the splash
+ * component. The unit test asserts these stay inside the documented
+ * envelope (≤22 chars wide, 9 ≤ rows ≤ 14) so a future edit can not
+ * silently bloat the terminal real estate.
+ */
+export const PUG_MASCOT_MAX_WIDTH = PUG_MASCOT.reduce((max, row) => Math.max(max, row.length), 0);
+export const PUG_MASCOT_HEIGHT = PUG_MASCOT.length;
+//# sourceMappingURL=repl-splash-art.js.map

package/dist/tui/repl-splash.js

@@ -0,0 +1,111 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * REPL boot splash (α6.14 wave 3).
+ *
+ * Rendered on REPL first paint — before the conversation pane, before
+ * any operator input lands. Mirrors the Claude Code / Codex / Gemini
+ * CLI boot-screen aesthetic while staying Pugi-brand-pure:
+ *
+ *   [PUG ASCII]   Pugi.io  v0.1.0-alphaN
+ *                 Plan:      <plan>
+ *                 Model:     <model>
+ *                 Tenant:    <customerId>
+ *                 Workspace: <basename>
+ *
+ *   ─────────────────────────────────────
+ *   Tips for getting started:
+ *     1. Type a brief, the workforce dispatches
+ *     2. /help for slash commands, /web <url> to pull a page
+ *     3. /skills install <name> for Anthropic / OpenClaw skills
+ *
+ * The splash auto-dismisses on:
+ *   - first operator keystroke (the REPL `<Repl />` host owns this and
+ *     calls the `onInteract` callback we expose),
+ *   - 10s idle timeout (built-in, configurable via `skipSplash`),
+ *   - `--no-splash` CLI flag or PUGI_SKIP_SPLASH=1 env (host gates the
+ *     mount entirely; we still respect the `skipSplash` prop as a belt
+ *     so a stray render in a test environment produces nothing).
+ *
+ * Brand voice gate: every visible string here is reviewed against the
+ * forbidden list (`journey / explore / delight / magical / friendly /
+ * AI-powered / pug-tastic`). Power words used: `brief / dispatch /
+ * ship / workforce / sentinel / skills`. No em-dashes; box-drawing
+ * `─` is OK (matches existing REPL header conventions).
+ */
+import { useEffect } from 'react';
+import { Box, Text } from 'ink';
+import { PUG_MASCOT, PUG_MASCOT_CYAN_MASK, PUG_MASCOT_MAX_WIDTH, } from './repl-splash-art.js';
+const DEFAULT_AUTO_DISMISS_MS = 10_000;
+const PLACEHOLDER = '—';
+export function ReplSplash(props) {
+    // Hooks MUST run unconditionally so the React reconciler can keep
+    // its hook order. We branch on `skipSplash` AFTER the effect
+    // declaration; the effect itself bails early when the splash is
+    // suppressed so no stray timer fires in the skip path.
+    useEffect(() => {
+        if (props.skipSplash)
+            return undefined;
+        const ms = props.autoDismissMs ?? DEFAULT_AUTO_DISMISS_MS;
+        const handle = setTimeout(() => {
+            props.onDismiss?.();
+        }, ms);
+        return () => clearTimeout(handle);
+        // Dependency on the onDismiss callback would re-arm the timer on
+        // every parent rerender; the host wraps it in useCallback so
+        // identity is stable for the splash's lifetime.
+    }, [props.autoDismissMs, props.onDismiss, props.skipSplash]);
+    // Belt for stray test renders: when the host already knows the
+    // operator opted out, we still want a render call to produce nothing
+    // visible. The host is the source of truth for mount-or-not; this is
+    // the no-op fallback.
+    if (props.skipSplash) {
+        return null;
+    }
+    return (_jsxs(Box, { flexDirection: "column", paddingX: 1, paddingY: 1, children: [_jsxs(Box, { flexDirection: "row", children: [_jsx(MascotColumn, {}), _jsxs(Box, { flexDirection: "column", marginLeft: 2, marginTop: 1, children: [_jsxs(Box, { children: [_jsx(Text, { bold: true, children: "Pugi" }), _jsx(Text, { bold: true, color: "cyan", children: ".io" }), _jsx(Text, { dimColor: true, children: `  v${props.cliVersion}` })] }), _jsxs(Box, { marginTop: 1, flexDirection: "column", children: [_jsx(HeaderRow, { label: "Plan", value: props.plan ?? PLACEHOLDER }), _jsx(HeaderRow, { label: "Model", value: props.model ?? PLACEHOLDER }), _jsx(HeaderRow, { label: "Tenant", value: props.tenant ?? PLACEHOLDER }), _jsx(HeaderRow, { label: "Workspace", value: props.workspaceLabel })] })] })] }), _jsx(Box, { marginTop: 1, children: _jsx(Text, { dimColor: true, children: '─'.repeat(40) }) }), _jsxs(Box, { marginTop: 1, flexDirection: "column", children: [_jsx(Text, { dimColor: true, children: "Tips for getting started:" }), _jsx(TipRow, { index: 1, text: "Type a brief, the workforce dispatches" }), _jsx(TipRow, { index: 2, text: "/help for slash commands, /web <url> to pull a page" }), _jsx(TipRow, { index: 3, text: "/skills install <name> for Anthropic / OpenClaw skills" })] })] }));
+}
+/**
+ * Renders the multi-line ASCII pug. Each row is split into colored
+ * runs based on `PUG_MASCOT_CYAN_MASK` so the eyes + chip come out
+ * cyan and the body stays gray. Pure render of the static art array;
+ * no IO, no state.
+ */
+function MascotColumn() {
+    return (_jsx(Box, { flexDirection: "column", minWidth: PUG_MASCOT_MAX_WIDTH, children: PUG_MASCOT.map((row, rowIndex) => (_jsx(MascotRow, { row: row, mask: PUG_MASCOT_CYAN_MASK[rowIndex] ?? [] }, rowIndex))) }));
+}
+function MascotRow({ row, mask, }) {
+    // Split the row into contiguous runs of same-color cells so we emit
+    // one <Text> per run instead of one per character. Keeps the Ink
+    // render tree shallow and the snapshot diff readable.
+    const runs = [];
+    let buffer = '';
+    let bufferCyan = false;
+    for (let column = 0; column < row.length; column += 1) {
+        const ch = row.charAt(column);
+        const cyan = mask[column] === true;
+        if (buffer.length === 0) {
+            buffer = ch;
+            bufferCyan = cyan;
+            continue;
+        }
+        if (cyan === bufferCyan) {
+            buffer += ch;
+        }
+        else {
+            runs.push({ text: buffer, cyan: bufferCyan });
+            buffer = ch;
+            bufferCyan = cyan;
+        }
+    }
+    if (buffer.length > 0) {
+        runs.push({ text: buffer, cyan: bufferCyan });
+    }
+    return (_jsx(Text, { children: runs.map((run, runIndex) => run.cyan ? (_jsx(Text, { color: "cyan", children: run.text }, runIndex)) : (_jsx(Text, { color: "gray", children: run.text }, runIndex))) }));
+}
+function HeaderRow({ label, value }) {
+    const padded = `${label}:`.padEnd(11, ' ');
+    return (_jsxs(Text, { children: [_jsx(Text, { dimColor: true, children: padded }), _jsx(Text, { children: value })] }));
+}
+function TipRow({ index, text }) {
+    return (_jsxs(Text, { children: [_jsx(Text, { dimColor: true, children: `  ${index}. ` }), _jsx(Text, { children: text })] }));
+}
+//# sourceMappingURL=repl-splash.js.map

package/dist/tui/repl.js

@@ -23,10 +23,12 @@ import { PUGI_TAGLINE, THE_TEN } from '@pugi/personas';
 import { AgentTree } from './agent-tree.js';
 import { ConversationPane } from './conversation-pane.js';
 import { InputBox } from './input-box.js';
+import { ReplSplash } from './repl-splash.js';
 import { StatusBar } from './status-bar.js';
 import { UpdateBanner } from './update-banner.js';
+import { collectWorkspaceContext } from './workspace-context.js';
 import { slugForCwd } from '../core/repl/history.js';
-import { SLASH_COMMAND_HELP } from '../core/repl/slash-commands.js';
+import { SLASH_COMMAND_HELP, SLASH_COMMAND_GROUPS } from '../core/repl/slash-commands.js';
 const TICK_INTERVAL_MS = 200;
 const PULSE_INTERVAL_MS = 700;
 export function Repl(props) {
@@ -34,6 +36,15 @@ export function Repl(props) {
     const [overlay, setOverlay] = useState('none');
     const [pulsePhase, setPulsePhase] = useState(0);
     const [tickNow, setTickNow] = useState((props.now ?? Date.now)());
+    // α6.14 wave 3: boot splash visible until first input, first
+    // `agent.spawned` event, or 10s idle. The host gates the initial
+    // visibility on `--no-splash` / PUGI_SKIP_SPLASH via `skipSplash`.
+    const [splashVisible, setSplashVisible] = useState(props.skipSplash !== true);
+    const dismissSplash = useCallback(() => setSplashVisible(false), []);
+    // α6.14 wave 3: workspace context snapshot for the status bar. We
+    // read once at mount and freeze; a brand-new PUGI.md or skill is
+    // surfaced on the next REPL boot rather than via a watcher.
+    const workspaceContext = useMemo(() => props.workspaceContext ?? collectWorkspaceContext(process.cwd()), [props.workspaceContext]);
     // Subscribe to session state updates. The session module fires the
     // callback synchronously inside `patch` so we mirror without a
     // batching layer.
@@ -62,9 +73,24 @@ export function Repl(props) {
     useEffect(() => {
         props.onOverlayChange?.(overlay);
     }, [overlay, props]);
+    // α6.14 wave 3: dismiss the boot splash once the first agent spawns
+    // (the operator has clearly engaged the system) or the transcript
+    // gains a row. Mirrors the natural attention shift Claude Code /
+    // Codex / Gemini CLI all do on their boot screens.
+    useEffect(() => {
+        if (!splashVisible)
+            return;
+        if (state.agents.length > 0 || state.transcript.length > 0) {
+            setSplashVisible(false);
+        }
+    }, [splashVisible, state.agents.length, state.transcript.length]);
     const personaNames = useMemo(() => buildPersonaNameMap(), []);
     const { exit } = useApp();
     const handleSubmit = useCallback((line) => {
+        // Dismiss the boot splash on first operator input. Idempotent —
+        // `setSplashVisible(false)` is a no-op once the state already
+        // settled to false (timer fired or `agent.spawned` arrived).
+        setSplashVisible(false);
         // Run async without awaiting - the session module owns the
         // network call, errors land in the transcript automatically.
         void props.session.handleInput(line).then((verdict) => {
@@ -96,11 +122,11 @@ export function Repl(props) {
             setOverlay('none');
         }
     }, { isActive: overlay === 'help' || overlay === 'roster' });
-    return (_jsxs(Box, { flexDirection: "column", paddingX: 1, children: [props.updateBanner ? _jsx(UpdateBanner, { result: props.updateBanner }) : null, _jsx(Header, { state: state }), _jsx(Box, { flexDirection: "column", marginTop: 1, children: overlay === 'help' ? (_jsx(HelpOverlay, {})) : overlay === 'roster' ? (_jsx(RosterOverlay, {})) : overlay === 'farewell' ? (_jsx(FarewellOverlay, {})) : (_jsx(MainArea, { state: state, personaNames: personaNames, nowEpochMs: tickNow })) }), _jsxs(Box, { flexDirection: "column", marginTop: 1, children: [overlay === 'farewell' ? null : (_jsx(InputBox, { onSubmit: handleSubmit, onExit: handleExit, now: props.now, 
+    return (_jsxs(Box, { flexDirection: "column", paddingX: 1, children: [props.updateBanner ? _jsx(UpdateBanner, { result: props.updateBanner }) : null, splashVisible ? (_jsx(ReplSplash, { cliVersion: state.cliVersion, workspaceLabel: state.workspaceLabel, plan: props.splashPlan, model: props.splashModel, tenant: props.splashTenant, onDismiss: dismissSplash })) : null, _jsx(Header, { state: state }), _jsx(Box, { flexDirection: "column", marginTop: 1, children: overlay === 'help' ? (_jsx(HelpOverlay, {})) : overlay === 'roster' ? (_jsx(RosterOverlay, {})) : overlay === 'farewell' ? (_jsx(FarewellOverlay, {})) : (_jsx(MainArea, { state: state, personaNames: personaNames, nowEpochMs: tickNow })) }), _jsxs(Box, { flexDirection: "column", marginTop: 1, children: [overlay === 'farewell' ? null : (_jsx(InputBox, { onSubmit: handleSubmit, onExit: handleExit, now: props.now, 
                         // Slug from process.cwd() (full path) so two workspaces with
                         // the same basename do not share history. state.workspaceLabel
                         // is the basename only. Codex review P2.
-                        workspaceSlug: slugForCwd(process.cwd()) })), _jsx(StatusBar, { connection: state.connection, activeAgentCount: countActive(state), tokensDownstreamTotal: state.tokensDownstreamTotal, briefStartedAtEpochMs: state.briefStartedAtEpochMs, nowEpochMs: tickNow, pulsePhase: pulsePhase })] })] }));
+                        workspaceSlug: slugForCwd(process.cwd()) })), _jsx(StatusBar, { connection: state.connection, activeAgentCount: countActive(state), tokensDownstreamTotal: state.tokensDownstreamTotal, briefStartedAtEpochMs: state.briefStartedAtEpochMs, nowEpochMs: tickNow, pulsePhase: pulsePhase, pugiMdCount: workspaceContext.pugiMdCount, mcpServerCount: workspaceContext.mcpServerCount, skillCount: workspaceContext.skillCount, quotaPct: props.quotaPct })] })] }));
 }
 function Header({ state }) {
     return (_jsxs(Box, { children: [_jsx(Text, { bold: true, children: "Pugi" }), _jsx(Text, { bold: true, color: "cyan", children: ".io" }), _jsx(Text, { dimColor: true, children: `  ·  workspace: ${state.workspaceLabel}  ·  v${state.cliVersion}  ·  ` }), _jsx(Text, { color: "cyan", children: state.connection === 'on_watch' ? 'on watch' : state.connection.replace('_', ' ') })] }));
@@ -114,7 +140,27 @@ function MainArea({ state, personaNames, nowEpochMs, }) {
     return (_jsxs(Box, { flexDirection: "column", children: [_jsx(ConversationPane, { rows: conversationSlice, personaNames: personaNames }), _jsx(Box, { marginTop: 1, children: _jsx(AgentTree, { agents: state.agents, nowEpochMs: nowEpochMs }) })] }));
 }
 function HelpOverlay() {
-    return (_jsxs(Box, { flexDirection: "column", children: [_jsx(Text, { bold: true, children: "Pugi REPL help" }), _jsx(Box, { marginTop: 1, flexDirection: "column", children: SLASH_COMMAND_HELP.map((row) => (_jsxs(Box, { children: [_jsx(Text, { bold: true, color: "cyan", children: `  /${row.name} ${row.args}`.padEnd(22, ' ') }), _jsx(Text, { dimColor: true, children: row.gloss })] }, row.name))) }), _jsx(Box, { marginTop: 1, children: _jsx(Text, { dimColor: true, children: `${PUGI_TAGLINE}` }) }), _jsx(Box, { marginTop: 1, children: _jsx(Text, { dimColor: true, children: 'Press any key to dismiss.' }) })] }));
+    // Group commands by their `group` field so the operator scans the
+    // palette by intent (dispatch → session → tools → settings → meta).
+    // The α6.14 wave-2 expansion grew the surface from 6 to 20 commands;
+    // a flat list would force the operator to read 20 rows top-to-bottom
+    // every time. Grouping cuts perceived complexity dramatically.
+    const grouped = new Map();
+    for (const row of SLASH_COMMAND_HELP) {
+        const list = grouped.get(row.group);
+        if (list) {
+            grouped.set(row.group, [...list, row]);
+        }
+        else {
+            grouped.set(row.group, [row]);
+        }
+    }
+    return (_jsxs(Box, { flexDirection: "column", children: [_jsx(Text, { bold: true, children: "Pugi REPL help" }), SLASH_COMMAND_GROUPS.map((group) => {
+                const rows = grouped.get(group);
+                if (!rows || rows.length === 0)
+                    return null;
+                return (_jsxs(Box, { flexDirection: "column", marginTop: 1, children: [_jsx(Text, { dimColor: true, children: `  -- ${group} --` }), rows.map((row) => (_jsxs(Box, { children: [_jsx(Text, { bold: true, color: "cyan", children: `  /${row.name} ${row.args}`.padEnd(22, ' ') }), _jsx(Text, { dimColor: true, children: row.gloss })] }, row.name)))] }, group));
+            }), _jsx(Box, { marginTop: 1, children: _jsx(Text, { dimColor: true, children: `${PUGI_TAGLINE}` }) }), _jsx(Box, { marginTop: 1, children: _jsx(Text, { dimColor: true, children: 'Press any key to dismiss.' }) })] }));
 }
 function RosterOverlay() {
     return (_jsxs(Box, { flexDirection: "column", children: [_jsx(Text, { bold: true, children: "On-watch roster" }), _jsx(Box, { marginTop: 1, flexDirection: "column", children: THE_TEN.map((persona) => (_jsxs(Box, { children: [_jsx(Text, { bold: true, children: `  ${persona.name.padEnd(10, ' ')}` }), _jsx(Text, { dimColor: true, children: `${persona.role.padEnd(20, ' ')}` }), _jsx(Text, { children: persona.oneLiner })] }, persona.slug))) }), _jsx(Box, { marginTop: 1, children: _jsx(Text, { dimColor: true, children: 'Press any key to dismiss.' }) })] }));
@@ -138,6 +184,15 @@ function applyVerdictSideEffects(verdict, handlers) {
         case 'web':
         case 'error':
         case 'noop':
+        case 'clear':
+        case 'version':
+        case 'jobs':
+        case 'diff':
+        case 'cost':
+        case 'status':
+        case 'stub':
+            // All non-overlay verdicts: the session module already appended
+            // any operator-visible system lines. No further UI side effect.
             return;
     }
 }

package/dist/tui/slash-palette.js

@@ -3,16 +3,21 @@ import { Box, Text } from 'ink';
 import { SLASH_COMMAND_HELP } from '../core/repl/slash-commands.js';
 export const PALETTE_ROW_LIMIT = 8;
 /**
- * Compute the visible palette window for a given input buffer.
+ * Compute the FULL filtered candidate list for a given input buffer.
  * Centralises the "starts-with-slash → filter SLASH_COMMAND_HELP"
  * logic so the input box and the unit test agree on the shape.
  *
+ * Wave 4 fix 2026-05-25: returns the FULL filtered set, not just the
+ * first PALETTE_ROW_LIMIT rows. The palette renderer now windows the
+ * visible slice internally based on `focusedIndex`, so the operator
+ * can scroll past row 7 via ↑/↓ on a long list (e.g. 20 commands when
+ * the buffer is `/`). `totalBeforeLimit` is preserved on the return
+ * shape for backward compatibility but always equals `rows.length`.
+ *
  * Behaviour:
  *   - Empty / non-slash buffer → empty result; palette stays hidden.
  *   - `/` alone → all registry rows (the operator wants to browse).
  *   - `/he` → rows whose name starts with `he` (case-insensitive).
- *   - Capped at PALETTE_ROW_LIMIT; the input box renders a hint when
- *     `totalBeforeLimit > rows.length`.
  */
 export function filterPalette(buffer) {
     if (!buffer.startsWith('/')) {
@@ -31,9 +36,33 @@ export function filterPalette(buffer) {
     const all = prefix.length === 0
         ? SLASH_COMMAND_HELP
         : SLASH_COMMAND_HELP.filter((row) => row.name.toLowerCase().startsWith(prefix));
+    // Defensive copy via spread so callers cannot mutate the registry
+    // through the returned readonly array (TS-only enforcement, but
+    // future refactors might assume the contract).
+    const rows = [...all];
+    return {
+        rows,
+        totalBeforeLimit: rows.length,
+    };
+}
+export function computePaletteWindow(rows, focusedIndex) {
+    const total = rows.length;
+    if (total <= PALETTE_ROW_LIMIT) {
+        return { visible: rows, startIndex: 0, total };
+    }
+    // Sliding window: anchor the start so the focused row stays inside the
+    // PALETTE_ROW_LIMIT span. Clamp at both ends so we never render fewer
+    // than PALETTE_ROW_LIMIT rows when the list is long enough to fill them.
+    let start = focusedIndex - Math.floor(PALETTE_ROW_LIMIT / 2);
+    if (start < 0)
+        start = 0;
+    const maxStart = total - PALETTE_ROW_LIMIT;
+    if (start > maxStart)
+        start = maxStart;
     return {
-        rows: all.slice(0, PALETTE_ROW_LIMIT),
-        totalBeforeLimit: all.length,
+        visible: rows.slice(start, start + PALETTE_ROW_LIMIT),
+        startIndex: start,
+        total,
     };
 }
 /**
@@ -57,13 +86,21 @@ export function completePalette(buffer, rows, focusedIndex) {
 export function SlashPalette(props) {
     if (props.rows.length === 0)
         return null;
-    const total = props.totalBeforeLimit ?? props.rows.length;
-    const overflow = total - props.rows.length;
-    return (_jsxs(Box, { flexDirection: "column", marginTop: 0, paddingLeft: 2, children: [props.rows.map((row, idx) => {
-                const focused = idx === props.focusedIndex;
+    // Wave 4 fix 2026-05-25: compute the visible window so the operator
+    // can scroll past row 7 on long lists. Focus indexes the full rows
+    // array; the window slides to keep the focused row visible.
+    const window = computePaletteWindow(props.rows, props.focusedIndex);
+    const overflow = window.total > PALETTE_ROW_LIMIT;
+    // Indicator value: focused row is 1-based for human display
+    // ("→ 9/20" reads better than "→ 8/20" when the operator is on
+    // the ninth entry).
+    const focusedDisplayIndex = Math.min(window.total, Math.max(1, props.focusedIndex + 1));
+    return (_jsxs(Box, { flexDirection: "column", marginTop: 0, paddingLeft: 2, children: [window.visible.map((row, visibleIdx) => {
+                const absoluteIdx = window.startIndex + visibleIdx;
+                const focused = absoluteIdx === props.focusedIndex;
                 const glyph = focused ? '▸' : '·';
                 const cmd = `/${row.name}${row.args ? ` ${row.args}` : ''}`.padEnd(22, ' ');
                 return (_jsxs(Box, { children: [_jsx(Text, { color: focused ? 'cyan' : 'gray', children: `${glyph} ` }), _jsx(Text, { bold: focused, color: focused ? 'cyan' : undefined, dimColor: !focused, children: cmd }), _jsx(Text, { dimColor: true, children: row.gloss })] }, row.name));
-            }), overflow > 0 ? (_jsx(Box, { children: _jsx(Text, { dimColor: true, children: `  · ${overflow} more (keep typing to narrow)` }) })) : null, _jsx(Box, { children: _jsx(Text, { dimColor: true, children: '  ↑/↓ select  ·  Tab complete  ·  Enter run  ·  Esc close' }) })] }));
+            }), overflow ? (_jsx(Box, { children: _jsx(Text, { dimColor: true, children: `  → ${focusedDisplayIndex}/${window.total}` }) })) : null, _jsx(Box, { children: _jsx(Text, { dimColor: true, children: '  ↑/↓ select  ·  Tab complete  ·  Enter run  ·  Esc close' }) })] }));
 }
 //# sourceMappingURL=slash-palette.js.map

package/dist/tui/status-bar.js

@@ -13,7 +13,20 @@ export function StatusBar(props) {
     const phase = clampPhase(props.pulsePhase);
     const glyph = PULSE_DOTS[Math.min(phase, PULSE_DOTS.length - 1)] ?? PULSE_DOTS[0];
     const status = connectionLabel(props.connection);
-    return (_jsxs(Box, { children: [_jsx(Text, { color: status.color, children: `${glyph ?? '●'} ${status.label}` }), _jsx(Text, { dimColor: true, children: `  ·  ${props.activeAgentCount} agents  ·  ` }), _jsx(Text, { children: `↓ ${tokenLabel} tokens` }), _jsx(Text, { dimColor: true, children: `  ·  ${elapsedLabel}` })] }));
+    return (_jsxs(Box, { flexDirection: "column", children: [_jsxs(Box, { children: [_jsx(Text, { color: status.color, children: `${glyph ?? '●'} ${status.label}` }), _jsx(Text, { dimColor: true, children: `  ·  ${props.activeAgentCount} agents  ·  ` }), _jsx(Text, { children: `↓ ${tokenLabel} tokens` }), _jsx(Text, { dimColor: true, children: `  ·  ${elapsedLabel}` })] }), _jsx(Box, { children: _jsx(Text, { dimColor: true, children: `${formatCount(props.pugiMdCount)} PUGI.md  ·  ${formatCount(props.mcpServerCount)} MCP  ·  ${formatCount(props.skillCount)} skills  ·  ${formatQuota(props.quotaPct)} quota` }) })] }));
+}
+/**
+ * Render a count badge — number if defined, `—` placeholder otherwise.
+ * The placeholder mirrors the splash header convention so the operator
+ * recognises "not yet known" vs "zero" at a glance.
+ */
+function formatCount(value) {
+    return typeof value === 'number' ? value.toString() : '—';
+}
+function formatQuota(pct) {
+    if (typeof pct !== 'number' || Number.isNaN(pct))
+        return '—';
+    return `${Math.round(pct)}%`;
 }
 function connectionLabel(connection) {
     switch (connection) {

package/dist/tui/workspace-context.js

@@ -0,0 +1,105 @@
+/**
+ * Workspace-context badges for the REPL bottom status bar (α6.14
+ * wave 3). Mirrors the Gemini CLI pattern where the operator sees
+ * `N GEMINI.md · N MCP · N skills · N% quota` at a glance.
+ *
+ * Pure-IO helpers: each function reads disk once, swallows every error
+ * (a missing directory is the common case for a fresh workspace), and
+ * returns a count. The REPL host calls these at mount, caches the
+ * result in component state, and passes them to `<StatusBar />`. We
+ * intentionally do NOT refresh on every keystroke — a brand-new
+ * PUGI.md does not appear mid-session often enough to warrant a
+ * watcher.
+ */
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, resolve } from 'node:path';
+/**
+ * Count PUGI.md files in the workspace root. We do NOT walk
+ * subdirectories — a deep grep would burn IO on every REPL boot and
+ * the convention is one root file. Mirrors how Gemini CLI counts
+ * `GEMINI.md` at the project root only.
+ */
+export function countPugiMdFiles(cwd) {
+    try {
+        const entries = readdirSync(cwd, { withFileTypes: true });
+        let count = 0;
+        for (const entry of entries) {
+            if (!entry.isFile())
+                continue;
+            // Case-insensitive so PUGI.md, Pugi.md, pugi.md all count.
+            if (entry.name.toLowerCase() === 'pugi.md')
+                count += 1;
+        }
+        return count;
+    }
+    catch {
+        return 0;
+    }
+}
+/**
+ * Count MCP servers wired into `.pugi/mcp.json` at the workspace root.
+ * Reads the file, parses JSON, returns the `servers` array length when
+ * present. Returns 0 on any failure (file missing, malformed JSON,
+ * wrong shape) — the status bar treats 0 and "error" the same.
+ */
+export function countMcpServers(cwd) {
+    const path = join(cwd, '.pugi', 'mcp.json');
+    if (!existsSync(path))
+        return 0;
+    try {
+        const raw = readFileSync(path, 'utf8');
+        const parsed = JSON.parse(raw);
+        if (parsed && typeof parsed === 'object') {
+            const servers = parsed.servers;
+            if (Array.isArray(servers))
+                return servers.length;
+            // Also support the `{ "<name>": { ... } }` map shape used by
+            // the Anthropic / Claude Code mcp config convention.
+            const entries = Object.keys(parsed);
+            return entries.length;
+        }
+        return 0;
+    }
+    catch {
+        return 0;
+    }
+}
+/**
+ * Count installed skills across the project-local + user-global
+ * directories: `.pugi/skills/` (per-workspace) + `~/.pugi/skills/`
+ * (per-machine). Each immediate subdirectory counts as one skill;
+ * matches the `skill-creator` convention.
+ */
+export function countSkills(cwd, home = homedir()) {
+    const projectDir = resolve(cwd, '.pugi', 'skills');
+    const userDir = resolve(home, '.pugi', 'skills');
+    return countSubdirs(projectDir) + countSubdirs(userDir);
+}
+function countSubdirs(dir) {
+    try {
+        if (!existsSync(dir))
+            return 0;
+        const stat = statSync(dir);
+        if (!stat.isDirectory())
+            return 0;
+        const entries = readdirSync(dir, { withFileTypes: true });
+        let count = 0;
+        for (const entry of entries) {
+            if (entry.isDirectory())
+                count += 1;
+        }
+        return count;
+    }
+    catch {
+        return 0;
+    }
+}
+export function collectWorkspaceContext(cwd, home = homedir()) {
+    return {
+        pugiMdCount: countPugiMdFiles(cwd),
+        mcpServerCount: countMcpServers(cwd),
+        skillCount: countSkills(cwd, home),
+    };
+}
+//# sourceMappingURL=workspace-context.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pugi/cli",
-  "version": "0.1.0-alpha.7",
+  "version": "0.1.0-alpha.9",
   "description": "Pugi CLI — terminal-native software execution system",
   "homepage": "https://pugi.io",
   "repository": {
@@ -47,7 +47,7 @@
     "undici": "^8.3.0",
     "zod": "^3.23.0",
     "@pugi/personas": "0.1.0",
-    "@pugi/sdk": "0.1.0-alpha.7"
+    "@pugi/sdk": "0.1.0-alpha.9"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",