@pugi/cli 0.1.0-beta.1 → 0.1.0-beta.100

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

@@ -1,10 +1,10 @@
 /**
- * REPL slash command registry - Sprint α5.7, expanded α6.14 wave 2.
+ * REPL slash command registry - Sprint , expanded wave 2.
  *
  * 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.
+ *) grows the surface from 6 to 20 commands so the `/help`
+ * overlay matches the breadth the upstream tool / peer CLI operators expect.
  *
  * The registry is pure: each `parseSlashCommand` call returns a
  * `SlashCommandResult` describing what the REPL session should do next.
@@ -15,20 +15,21 @@
  *
  * 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 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 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.
+ *  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 / shipped`. Tagline `Brief it. It ships.` reserved for
  * `/quit` confirmation and `/help` footer - never inline.
  */
 import { listRoles } from '../agents/registry.js';
+import { PERMISSION_MODES, parsePermissionMode, } from '../permissions/index.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
@@ -38,44 +39,76 @@ import { listRoles } from '../agents/registry.js';
  * silently appear here with empty placeholders.
  */
 export const SLASH_STUB_MESSAGES = Object.freeze({
-    compact: 'Manual context compaction lands in α6.5b.',
-    memory: 'Session memory editor lands in α6.5b.',
-    config: 'Run `pugi config list` from a fresh shell for the full surface; in-REPL editor lands in α6.5.',
+    // /compact graduated from stub. The session
+    // module now owns the summariser round-trip + boundary marker append
+    // via `dispatchCompact`. Keep the type record exhaustive so a future
+    // stub addition cannot silently overlap the wired set.
+    memory: 'Session memory editor lands in .',
+    config: 'Run `pugi config list` from a fresh shell for the full surface; in-REPL editor lands in .',
     // alpha 6.13: /privacy graduated from stub; nothing reads this at
     // runtime but the type record stays exhaustive.
     privacy: '',
-    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.',
+    budget: 'Run `pugi budget` from a fresh shell; in-REPL summary lands in .',
+    // β4 Sl7 : /mcp graduated from stub to a real handler
+    // that forwards to `runMcpCommand`. Stub message removed from the
+    // exhaustive record so the type narrows correctly.
+    //
+    // final : /undo graduated from stub to a real
+    // handler that forwards to `runUndoCommand` (Aider walk-back —
+    // single-step revert of the last mutating tool result, with
+    // mtime+hash external-modification gate). Stub message removed.
 });
 export const SLASH_COMMAND_HELP = Object.freeze([
     // 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: 'delegate', args: '<slug> <brief>', gloss: 'Dispatch a brief to one Tier 1 specialist ', 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' },
-    { name: 'ask', args: '<question>', gloss: 'Surface a yes/no modal locally (α6.3 forcing question)', group: 'Workforce dispatch' },
+    { name: 'jobs', args: '[--watch]', gloss: 'List background jobs + agent-progress; --watch mounts the live Ink TUI', group: 'Workforce dispatch' },
+    { name: 'cancel', args: '[<id> | all]', gloss: 'Halt active dispatch by id ', group: 'Workforce dispatch' },
+    { name: 'ask', args: '<question>', gloss: 'Surface a yes/no modal locally ', group: 'Workforce dispatch' },
     // Session
     { name: 'clear', args: '', gloss: 'Clear conversation pane', group: 'Session' },
     { name: 'resume', args: '', gloss: 'Pick a stored session to restore', group: 'Session' },
     { name: 'context', args: '', gloss: 'Show three-tier context summary (Tier 0 skeleton + Tier 1 working set)', group: 'Session' },
-    { name: 'compact', args: '', gloss: 'Manual context compaction  (α6.5b)', group: 'Session', stub: true },
-    { name: 'memory', args: '', gloss: 'Session memory editor  (α6.5b)', group: 'Session', stub: true },
+    { name: 'compact', args: '[--force]', gloss: 'Summarise older turns into a boundary marker . --force bypasses the noop-empty guard', group: 'Session' },
+    { name: 'rewind', args: '[N | --to <id>]', gloss: 'Roll the conversation back to a checkpoint ', group: 'Session' },
+    { name: 'memory', args: '', gloss: 'Session memory editor ', group: 'Session', stub: true },
+    { name: 'init', args: '', gloss: 'Scaffold .pugi/ in the current workspace (β1 Sl11)', group: 'Session' },
     // 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' },
+    { name: 'cost', args: '', gloss: 'Session token + USD totals + last 5 turn breakdown', group: 'Pugi tools' },
+    { name: 'quota', args: '', gloss: 'Plan tier + monthly usage caps (sync / review / engine)', group: 'Pugi tools' },
+    { name: 'status', args: '', gloss: 'Session snapshot — id · cwd · mode · tokens · dispatches · auth', group: 'Pugi tools' },
     { name: 'consensus', args: '[ref]', gloss: '3-model consensus review (codex · claude · deepseek)', group: 'Pugi tools' },
+    { name: 'repo-map', args: '[refresh]', gloss: 'AST-light symbol summary of the workspace ', group: 'Pugi tools' },
+    { name: 'codegraph-status', args: '[--install|--reindex|--offer]', gloss: 'Codegraph MCP — install state, index age, symbol count, refresh CTA ', group: 'Pugi tools' },
     // Settings
     { name: 'config', args: '', gloss: 'Show config', group: 'Settings', stub: true },
     { name: 'privacy', args: '', gloss: 'Show privacy mode + contract', group: 'Settings' },
+    { name: 'permissions', args: '[mode] [--persist]', gloss: 'Show or flip permission mode (default / acceptEdits / plan / auto / dontAsk / bypassPermissions) (also: /plan, Shift+Tab cycle)', group: 'Settings' },
+    { name: 'plan', args: '[--back | --persist] [<prompt>]', gloss: 'Switch to plan mode (read-only). Same as /permissions plan, slicker UX.', group: 'Settings' },
+    { name: 'model', args: '[<slug>]', gloss: 'Show or select the active model. Bare /model lists tier-gated options', group: 'Settings' },
     { 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 },
+    { name: 'mcp', args: '[sub]', gloss: 'MCP servers — list / trust / deny / install / serve / perms', group: 'Settings' },
+    { name: 'style', args: '[name] [--persist|--reset|--list]', gloss: 'Output-style preset (default / terse / explanatory / russian-formal / casual)', group: 'Settings' },
+    { name: 'theme', args: '[name] [--persist|--reset|--list]', gloss: 'TUI color palette (default / dark / light / colorblind)', group: 'Settings' },
+    { name: 'onboarding', args: '[--reset|--non-interactive]', gloss: 'First-run wizard — auth / mode / style / MCP / telemetry ', group: 'Settings' },
+    { name: 'vim', args: '[on|off|status]', gloss: 'Toggle vim-style modal editing in the input buffer ', group: 'Settings' },
+    { name: 'undo', args: '', gloss: 'Revert the last successful write / edit / multi_edit (Aider walk-back, )', group: 'Settings' },
+    { name: 'redo', args: '', gloss: 'Reapply the most recent /undo (LIFO stack, cleanup)', group: 'Settings' },
     // Meta
     { name: 'help', args: '', gloss: 'Show this help overlay', group: 'Meta' },
     { name: 'version', args: '', gloss: 'Show CLI version', group: 'Meta' },
+    { name: 'doctor', args: '', gloss: 'Environment health report (auth · API · Node · disk · MCP · …)', group: 'Meta' },
+    { name: 'prd-check', args: '<prd-path | --all | --session> [--json]', gloss: 'Verify PRD against code (default) or session work (--session, final)', group: 'Meta' },
+    { name: 'chain', args: '<new|status|next|show|export|list> [...args]', gloss: 'Artifact chain — PRD → ADR → mindmap → ER → sequence → tests → code ', group: 'Meta' },
+    { name: 'stickers', args: '', gloss: 'show Pugi brand stickers (gimmick)', group: 'Meta' },
+    { name: 'feedback', args: '', gloss: 'file a bug / feature / general comment without leaving the REPL', group: 'Meta' },
+    { name: 'share', args: '[--gist|--pugi] [--redact] [--preview]', gloss: 'Export session transcript to gist / pugi.io ', group: 'Meta' },
+    { name: 'release-notes', args: '[--reset]', gloss: 'Show changelog diff since last upgrade ', group: 'Meta' },
+    { name: 'update', args: '[--check|--apply [--yes]] [--channel <name>]', gloss: 'Check for / apply CLI update on stable / beta / canary ', group: 'Meta' },
     { name: 'quit', args: '', gloss: 'Exit the REPL', group: 'Meta' },
 ]);
 /**
@@ -92,20 +125,88 @@ export const SLASH_COMMAND_GROUPS = Object.freeze([
 /**
  * Parse one line of input from the REPL. The contract:
  *
- *   - 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.
- *   - `/<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.
+ *  - 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.
+ *  - `/<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)
  * would unmount Ink mid-frame.
  */
+/**
+ * Pugi backlog : parse the artifact-store subcommands
+ * of `/plan`. Kept module-local because the legacy mode-toggle parser
+ * already owns the `case 'plan':` branch — this helper is the
+ * dispatch tail when the first arg is `show / list / diff / prune`.
+ *
+ * Argument grammar:
+ *  /plan show <planId>
+ *  /plan list [<taskId>]
+ *  /plan diff <planId> [<otherId>]
+ *  /plan prune [<maxAgeDays>]
+ *
+ * Validation:
+ *  - `planId` is required for show + diff; surfaced as a structured
+ *    error verdict when missing so the REPL renders one line of
+ *    guidance instead of falling through to the mode-toggle path.
+ *  - `maxAgeDays` is parsed as a positive integer; missing leaves the
+ *    core module's default in place. Negative / NaN inputs become
+ *    errors so the operator does not silently wipe their plan store.
+ */
+function parsePlanArtifactSubcommand(op, rest) {
+    if (op === 'show') {
+        const planId = rest[0];
+        if (!planId) {
+            return {
+                kind: 'error',
+                message: '/plan show <plan-id> — plan-id is required.',
+            };
+        }
+        return { kind: 'plan-artifact', sub: { op: 'show', planId } };
+    }
+    if (op === 'list') {
+        const taskId = rest[0];
+        return {
+            kind: 'plan-artifact',
+            sub: taskId ? { op: 'list', taskId } : { op: 'list' },
+        };
+    }
+    if (op === 'diff') {
+        const planId = rest[0];
+        if (!planId) {
+            return {
+                kind: 'error',
+                message: '/plan diff <plan-id> [<other-id>] — plan-id is required.',
+            };
+        }
+        const otherId = rest[1];
+        return {
+            kind: 'plan-artifact',
+            sub: otherId
+                ? { op: 'diff', planId, otherId }
+                : { op: 'diff', planId },
+        };
+    }
+    // prune
+    const raw = rest[0];
+    if (raw === undefined) {
+        return { kind: 'plan-artifact', sub: { op: 'prune' } };
+    }
+    const parsed = Number(raw);
+    if (!Number.isFinite(parsed) || parsed <= 0 || !Number.isInteger(parsed)) {
+        return {
+            kind: 'error',
+            message: `/plan prune [<days>] — expected positive integer, got '${raw}'.`,
+        };
+    }
+    return { kind: 'plan-artifact', sub: { op: 'prune', maxAgeDays: parsed } };
+}
 export function parseSlashCommand(input) {
     const trimmed = input.trim();
     if (trimmed.length === 0) {
@@ -135,6 +236,38 @@ export function parseSlashCommand(input) {
         case 'roster': {
             return { kind: 'roster' };
         }
+        case 'delegate': {
+            // tail must start with the persona slug followed by the brief.
+            // Slug accepts only the closed-set lowercase ASCII pattern the
+            // server-side persona registry enforces; anything else surfaces
+            // as a usage error so the operator sees the typo before the
+            // round-trip.
+            const innerSpace = tail.indexOf(' ');
+            if (innerSpace === -1 || innerSpace === 0) {
+                return {
+                    kind: 'error',
+                    message: 'Usage: /delegate <slug> <one-sentence brief>',
+                };
+            }
+            const persona = tail.slice(0, innerSpace).toLowerCase();
+            const brief = tail.slice(innerSpace + 1).trim();
+            // Pattern intentionally mirrors server-side PUGI_DELEGATE_REGEX in
+            // sessions.controller.ts (^[a-z]+$). Keeping them lockstep means
+            // the REPL surfaces typos locally instead of round-tripping a 4xx.
+            if (!/^[a-z]+$/.test(persona)) {
+                return {
+                    kind: 'error',
+                    message: `/delegate slug must be lowercase ASCII (a-z only); got '${persona}'`,
+                };
+            }
+            if (brief.length === 0) {
+                return {
+                    kind: 'error',
+                    message: 'Usage: /delegate <slug> <one-sentence brief>',
+                };
+            }
+            return { kind: 'delegate', persona, brief };
+        }
         case 'stop':
         case 'kill': {
             if (tail.length === 0) {
@@ -170,7 +303,87 @@ export function parseSlashCommand(input) {
             return { kind: 'version' };
         }
         case 'jobs': {
-            return { kind: 'jobs' };
+            // cleanup : tokenise the tail so the slash
+            // can route `--watch` к the live Ink TUI (same renderer as
+            // `pugi jobs --watch`). Unknown tokens fall through silently —
+            // the slash surface is intentionally minimal vs. the shell
+            // command (which supports list/status/tail/kill subcommands
+            // through `runJobsCommand`).
+            const tokens = tail.length === 0 ? [] : tail.split(/\s+/).filter((s) => s.length > 0);
+            const watch = tokens.includes('--watch') || tokens.includes('-w') || tokens[0] === 'watch';
+            return { kind: 'jobs', watch };
+        }
+        case 'cancel':
+        case 'halt': {
+            // small-CC-parity batch :
+            //
+            //  /cancel             -> list active dispatches
+            //  /cancel all         -> halt every running dispatch
+            //  /cancel <id>        -> halt one (id may be a prefix; runner
+            //                          does startsWith lookup)
+            //
+            // The `halt` alias matches operator muscle memory from systemd /
+            // brand voice (`stop` is already taken by /stop <persona>; cancel
+            // is dispatch-id-keyed, stop is persona-keyed). Unknown extra
+            // tokens are tolerated — the runner reads only the first.
+            const trimmedTail = tail.trim();
+            if (trimmedTail.length === 0) {
+                return { kind: 'cancel', mode: 'list', dispatchId: '' };
+            }
+            const firstToken = trimmedTail.split(/\s+/)[0].toLowerCase();
+            if (firstToken === 'all' || firstToken === '*') {
+                return { kind: 'cancel', mode: 'all', dispatchId: 'all' };
+            }
+            // Defensive: dispatch ids are filename-safe per the
+            // `validateAgentProgress` agentId regex (`[a-zA-Z0-9_-]+`).
+            // Reject anything outside that range with a usage tip so the
+            // operator sees the typo before the round-trip.
+            if (!/^[A-Za-z0-9_-]+$/.test(firstToken)) {
+                return {
+                    kind: 'error',
+                    message: `/cancel: invalid dispatch id '${firstToken}'. Use letters / digits / '-' / '_' only.`,
+                };
+            }
+            return { kind: 'cancel', mode: 'one', dispatchId: firstToken };
+        }
+        case 'servers': {
+            // PR H (2026-06-05): operator-facing server kill. Customer
+            // can't terminate `server_start`-launched processes from inside
+            // the REPL — `/stop <persona>` halts a persona agent, not the
+            // server. Surface the existing `.pugi/runs/srv-*/server.json`
+            // meta as a first-class list + dispatch к `dispatchServerStop`.
+            //
+            //  /servers                     → list
+            //  /servers stop <runId|pid|all>→ kill one or all
+            const trimmed = tail.trim();
+            if (trimmed.length === 0) {
+                return { kind: 'servers', mode: 'list', target: '' };
+            }
+            const tokens = trimmed.split(/\s+/);
+            const verb = tokens[0].toLowerCase();
+            if (verb !== 'stop' && verb !== 'kill') {
+                return {
+                    kind: 'error',
+                    message: `Usage: /servers [stop <runId|pid|all>]`,
+                };
+            }
+            const target = tokens[1]?.toLowerCase() ?? '';
+            if (target.length === 0) {
+                return {
+                    kind: 'error',
+                    message: `Usage: /servers stop <runId|pid|all>`,
+                };
+            }
+            // Defensive: validate target shape. Run ids look like `srv-<uuid>`,
+            // pids are positive integers, `all` is the literal token. Reject
+            // anything else with the usage tip.
+            if (target !== 'all' && !/^srv-[\w-]+$/.test(target) && !/^\d+$/.test(target)) {
+                return {
+                    kind: 'error',
+                    message: `/servers stop: target must be 'all', a run id (srv-...), or a numeric pid; got '${target}'.`,
+                };
+            }
+            return { kind: 'servers', mode: 'stop', target };
         }
         case 'ask': {
             if (tail.length === 0) {
@@ -181,9 +394,19 @@ export function parseSlashCommand(input) {
         case 'diff': {
             return { kind: 'diff' };
         }
-        case 'cost': {
+        case 'cost':
+        case 'usage': {
+            // L19 : `/usage` is an alias of `/cost` per the cost-
+            // command spec. The previous mapping routed `/usage` to the
+            // network-backed `/quota` surface, but operators trained on Claude
+            // Code expect `/usage` to surface the per-model token breakdown
+            // (same shape as `/cost`). `/quota` remains the canonical name
+            // for the tier + monthly-cap fetch.
             return { kind: 'cost' };
         }
+        case 'quota': {
+            return { kind: 'quota' };
+        }
         case 'status': {
             return { kind: 'status' };
         }
@@ -195,14 +418,14 @@ export function parseSlashCommand(input) {
             return { kind: 'consensus', ref: tail };
         }
         case 'resume': {
-            // α6.4: wired against the local SessionStore. The REPL session
+            // : wired against the local SessionStore. The REPL session
             // owns the picker UI (Ink select over the 10 most recent rows)
             // so the slash-command layer stays UI-agnostic.
             return { kind: 'resume' };
         }
         case 'context':
         case 'ctx': {
-            // α6.5: surface Tier 0 + Tier 1 status. The session module
+            // : surface Tier 0 + Tier 1 status. The session module
             // renders the summary as system lines so the operator can see
             // skeleton size + working-set utilisation at a glance.
             return { kind: 'context' };
@@ -215,12 +438,321 @@ export function parseSlashCommand(input) {
             // device flow + audit identity are wired correctly).
             return { kind: 'privacy' };
         }
-        case 'compact':
+        case 'permissions':
+        case 'perms': {
+            // : `/permissions [mode] [--persist] [--confirm]`.
+            //
+            // Argument grammar (single line, no quoting):
+            //  /permissions                                       -> show + table
+            //  /permissions default|acceptEdits|plan|auto|dontAsk -> flip mode
+            //  /permissions bypassPermissions --confirm           -> flip to
+            //                                    bypassPermissions (refused
+            //                                    без --confirm — safety)
+            //  /permissions <mode> --persist -> also write to ~/.pugi/config.json
+            //
+            // aliases (`ask`, `allow`, `bypass`) are accepted и mapped to
+            // their canonical names via `parsePermissionMode`.
+            const tokens = tail.length === 0 ? [] : tail.split(/\s+/).filter((s) => s.length > 0);
+            if (tokens.length === 0) {
+                return { kind: 'permissions', persist: false, confirmBypass: false };
+            }
+            const headRaw = tokens[0] ?? '';
+            const mode = parsePermissionMode(headRaw);
+            if (!mode) {
+                const modeList = [...PERMISSION_MODES].join('|');
+                return {
+                    kind: 'error',
+                    message: `Usage: /permissions [${modeList}] [--persist] [--confirm]; unknown mode '${headRaw}'`,
+                };
+            }
+            const flags = tokens.slice(1);
+            let persist = false;
+            let confirmBypass = false;
+            for (const flag of flags) {
+                if (flag === '--persist') {
+                    persist = true;
+                }
+                else if (flag === '--confirm') {
+                    confirmBypass = true;
+                }
+                else {
+                    return {
+                        kind: 'error',
+                        message: `/permissions: unknown flag '${flag}' (allowed: --persist, --confirm)`,
+                    };
+                }
+            }
+            return { kind: 'permissions', mode, persist, confirmBypass };
+        }
+        case 'init': {
+            // β1 Sl11: surface the init flow inside the REPL. Tail args
+            // are ignored — the init handler is parameterless today; `pugi
+            // init --no-defaults` is the CLI surface for skipping bundled
+            // skills.
+            return { kind: 'init' };
+        }
+        case 'plan': {
+            // `/plan [--back | --persist] [<prompt>]`.
+            //
+            // Argument grammar (single line, no quoting):
+            //  /plan                          -> enter plan mode + banner
+            //  /plan --back                   -> restore previous mode
+            //  /plan --persist                -> enter + write global config
+            //  /plan <prompt...>              -> enter + run one-shot engine
+            //  /plan --auto-back <prompt...>  -> enter + run + restore mode
+            //
+            // The parser pulls the flags off the head of the tail; whatever
+            // remains is the prompt. `--back` + a non-empty prompt and
+            // `--back` + `--auto-back` are both refused as `error` because
+            // they conflict at the verb level.
+            //
+            // Pugi backlog : when the FIRST token of the
+            // tail is one of the artifact subcommands (`show / list / diff /
+            // prune`), the parser hands off to the plan-as-FILE surface
+            // instead of the mode-toggle. This keeps both feature sets under
+            // one `/plan` namespace without overloading the verb table.
+            const tokens = tail.length === 0 ? [] : tail.split(/\s+/).filter((s) => s.length > 0);
+            const head = tokens[0];
+            if (head === 'show' || head === 'list' || head === 'diff' || head === 'prune') {
+                return parsePlanArtifactSubcommand(head, tokens.slice(1));
+            }
+            let back = false;
+            let persist = false;
+            let autoBack = false;
+            const promptTokens = [];
+            for (const token of tokens) {
+                if (token === '--back') {
+                    back = true;
+                }
+                else if (token === '--persist') {
+                    persist = true;
+                }
+                else if (token === '--auto-back') {
+                    autoBack = true;
+                }
+                else {
+                    promptTokens.push(token);
+                }
+            }
+            const prompt = promptTokens.join(' ');
+            if (back && prompt.length > 0) {
+                return {
+                    kind: 'error',
+                    message: '/plan --back does not accept a prompt; revert first, then dispatch.',
+                };
+            }
+            if (back && autoBack) {
+                return {
+                    kind: 'error',
+                    message: '/plan --back and --auto-back cannot be combined.',
+                };
+            }
+            return { kind: 'plan', back, persist, autoBack, prompt };
+        }
+        case 'model': {
+            // BT 8 (the upstream tool parity): `/model [<slug>]`. Bare form
+            // prints the tier-gated model menu + current selection; with a
+            // slug it flips workspace selection. Slug grammar (loose): alnum
+            // + dash + dot + slash. Anything outside that range becomes an
+            // error verdict so the operator sees a clear message instead of a
+            // silent no-op. Whitespace inside the tail = multiple tokens = we
+            // take the first; the help gloss documents single-slug usage.
+            const trimmedTail = tail.trim();
+            if (trimmedTail.length === 0) {
+                return { kind: 'model', slug: undefined };
+            }
+            const firstToken = trimmedTail.split(/\s+/)[0] ?? '';
+            if (!/^[A-Za-z0-9][A-Za-z0-9._\-\/]{0,63}$/.test(firstToken)) {
+                return {
+                    kind: 'error',
+                    message: `/model: invalid slug '${firstToken}'. Use letters / digits / '-' / '.' / '/' only.`,
+                };
+            }
+            return { kind: 'model', slug: firstToken };
+        }
+        case 'mcp': {
+            // β4 Sl7: tokenize the tail. Empty tail -> `list` (matches CLI).
+            // Quoting / shell-escapes are NOT supported — the slash surface is
+            // intentionally simple; complex installs (env vars, multi-word
+            // args) go through `pugi mcp install` from a fresh shell.
+            const tokens = tail.length === 0 ? [] : tail.split(/\s+/).filter((s) => s.length > 0);
+            return { kind: 'mcp', args: tokens };
+        }
+        case 'style':
+        case 'output-style': {
+            // forward the tokenized tail unchanged so
+            // the slash + top-level CLI surfaces share one parser inside
+            // `runStyleCommand`. Quoting / multi-word args are not used (the
+            // preset slugs are single tokens by contract).
+            const tokens = tail.length === 0 ? [] : tail.split(/\s+/).filter((s) => s.length > 0);
+            return { kind: 'style', args: tokens };
+        }
+        case 'theme':
+        case 'palette':
+        case 'colors': {
+            // forward the tokenized tail unchanged so
+            // the slash + top-level `pugi theme` surfaces share one parser
+            // inside `runThemeCommand`. Aliases `/palette` and `/colors`
+            // exist because the leak-landscape audit found operators reach
+            // for either word interchangeably — same surface, same handler.
+            const tokens = tail.length === 0 ? [] : tail.split(/\s+/).filter((s) => s.length > 0);
+            return { kind: 'theme', args: tokens };
+        }
+        case 'onboarding':
+        case 'onboard':
+        case 'setup': {
+            // forward the tokenized tail unchanged.
+            // The slash always routes through the non-interactive snapshot
+            // path (the REPL already owns the Ink tree); the runner picks
+            // it up from `ctx.interactive = false` in the session
+            // dispatcher.
+            const tokens = tail.length === 0 ? [] : tail.split(/\s+/).filter((s) => s.length > 0);
+            return { kind: 'onboarding', args: tokens };
+        }
+        case 'vim': {
+            // forward the tokenized tail unchanged so
+            // the slash + top-level CLI surfaces share one parser inside
+            // `runVimCommand`. Subcommands are single tokens (on / off /
+            // status); a bare `/vim` toggles.
+            const tokens = tail.length === 0 ? [] : tail.split(/\s+/).filter((s) => s.length > 0);
+            return { kind: 'vim', args: tokens };
+        }
+        case 'doctor':
+        case 'health': {
+            // L17 : run the probe sweep inline. Tail is ignored —
+            // the doctor command has no operator-facing arguments (every
+            // probe runs unconditionally; per-probe disable lives on the CLI
+            // shell surface, not the slash one).
+            return { kind: 'doctor' };
+        }
+        case 'prd-check':
+        case 'prdcheck': {
+            // : tokenise the tail and forward verbatim
+            // so the slash + shell surfaces share one `parsePrdCheckArgs`.
+            // Supports `<prd-path>`, `--all`, and `--json`.
+            const tokens = tail.length === 0 ? [] : tail.split(/\s+/).filter((s) => s.length > 0);
+            return { kind: 'prd-check', args: tokens };
+        }
+        case 'chain': {
+            // : forward the tokenized argv to
+            // `runChainCommand` via the session module. Subcommands are
+            // single tokens (new / status / next / show / export / list);
+            // the `new` subcommand accepts the intent as the joined tail so
+            // operators can write `/chain new add auth flow` без quoting.
+            const tokens = tail.length === 0 ? [] : tail.split(/\s+/).filter((s) => s.length > 0);
+            return { kind: 'chain', args: tokens };
+        }
+        case 'codegraph-status':
+        case 'codegraph': {
+            // BT 9 Phase 2 : forward the tokenized argv
+            // to `runCodegraphStatusCommand`. Flags handled by the runner:
+            //  --install — merge codegraph into .pugi/mcp.json (accept)
+            //  --reindex — stamp lastIndexedAt + hint runtime to refresh
+            //  --offer  — surface the install prompt even after a decline
+            // `/codegraph` is the short alias; same handler.
+            const tokens = tail.length === 0 ? [] : tail.split(/\s+/).filter((s) => s.length > 0);
+            return { kind: 'codegraph-status', args: tokens };
+        }
+        case 'compact': {
+            // graduated from stub. The session module
+            // owns the summariser round-trip. BT 8: `--force` overrides
+            // the noop-empty guard. Unknown flags fall through silently per
+            // the existing tail-tolerance behaviour (operators wanting a
+            // per-session compact run `pugi compact --session <id>` from a
+            // fresh shell).
+            const tokens = tail.length === 0 ? [] : tail.split(/\s+/).filter((s) => s.length > 0);
+            const force = tokens.some((t) => t === '--force' || t === '-f');
+            return { kind: 'compact', force };
+        }
+        case 'rewind': {
+            // `/rewind [N | --to <id>]`. Tokenize the
+            // tail unchanged so `runRewindCommand` (in `runtime/commands/
+            // rewind.ts`) handles every mode (picker / turns / to-event)
+            // through one parser. The slash + top-level CLI surfaces stay
+            // single-sourced — same separation as `/compact`.
+            const tokens = tail.length === 0 ? [] : tail.split(/\s+/).filter((s) => s.length > 0);
+            return { kind: 'rewind', args: tokens };
+        }
+        case 'stickers': {
+            // brand-personality gimmick. Tail args
+            // are ignored — the surface is intentionally parameterless. The
+            // session module delegates to the shared `runStickersCommand`
+            // so the slash + top-level paths stay single-sourced.
+            return { kind: 'stickers' };
+        }
+        case 'feedback': {
+            // in-CLI feedback collector. The wizard
+            // collects category/rating/comment/context/confirm interactively
+            // so the slash surface is parameterless. Tail args are reserved
+            // for a future `--message=...` quick-path; today they are
+            // accepted but ignored so the operator-level UX matches
+            // the upstream tool's `/feedback`.
+            return { kind: 'feedback' };
+        }
+        case 'share': {
+            // forward the tokenized arg list verbatim
+            // so the session module (which owns the network + readline
+            // affordances) can hand them to runShareCommand. Defaults: no
+            // tokens means "auto-pick target + prompt for confirmation".
+            const tokens = tail.length === 0 ? [] : tail.split(/\s+/).filter((s) => s.length > 0);
+            return { kind: 'share', args: tokens };
+        }
+        case 'repo-map':
+        case 'repomap': {
+            // build + show the AST-light symbol
+            // summary. Accepts `refresh` as a positional или `--refresh`
+            // flag so muscle memory from both shells lands the same way.
+            const tokens = tail.length === 0 ? [] : tail.split(/\s+/).filter((s) => s.length > 0);
+            const refresh = tokens.includes('--refresh') || tokens.includes('refresh') || tokens.includes('-r');
+            return { kind: 'repo-map', refresh };
+        }
+        case 'release-notes':
+        case 'releasenotes':
+        case 'changelog': {
+            // changelog diff between last-seen +
+            // installed CLI version. Tail args are tokenized so `--reset`
+            // can flip the marker-clear bit; no other flags are honoured —
+            // the surface mirrors the CLI top-level's intentional minimalism.
+            // `changelog` alias matches operator muscle memory from npm /
+            // cargo / brew, all of which ship `changelog` subcommands.
+            const tokens = tail.length === 0 ? [] : tail.split(/\s+/).filter((s) => s.length > 0);
+            const reset = tokens.includes('--reset') || tokens.includes('-r');
+            return { kind: 'release-notes', reset };
+        }
+        case 'update': {
+            // forward the tokenized argv to the
+            // session module which delegates to `runUpdateCommand`. The
+            // dispatcher owns argv validation (unknown channel / flag) so
+            // the slash parser stays as thin as the rest of the surface.
+            // The slash form does NOT support `--apply` because spawning
+            // `npm install -g` from inside a running REPL session would
+            // corrupt the operator's running binary — the dispatcher treats
+            // `--apply` from a slash as a non-interactive offer (probe +
+            // install command, no shell-out). Top-level `pugi update --apply`
+            // remains the recommended path for the actual install.
+            const tokens = tail.length === 0 ? [] : tail.split(/\s+/).filter((s) => s.length > 0);
+            return { kind: 'update', args: tokens };
+        }
+        case 'undo': {
+            // final : graduated from stub. Tail args are
+            // ignored — `runUndoCommand` is parameterless (single-step revert
+            // of the most recent successful mutating tool result). Multiple
+            // undos = stack of single-step undos. `/redo` is the counterpart
+            // — operators ping-pong через undo/redo on the
+            // event-log stack without re-running the underlying tool.
+            return { kind: 'undo' };
+        }
+        case 'redo': {
+            // cleanup : counterpart к /undo. Tail args
+            // are ignored — `runRedoCommand` is parameterless. Each /redo
+            // pops one entry from the LIFO undo stack (the runner tracks
+            // which undos have already been consumed by previous redos so
+            // double-/redo is a noop, not a double-write).
+            return { kind: 'redo' };
+        }
         case 'memory':
         case 'config':
-        case 'budget':
-        case 'mcp':
-        case 'undo': {
+        case 'budget': {
             const stubName = name;
             return {
                 kind: 'stub',