@pugi/cli 0.1.0-beta.25 → 0.1.0-beta.27

package/dist/runtime/cli.js

@@ -22,6 +22,7 @@ import { buildRuntimeConfig, fetchPersonaRoster, loadRuntimeConfig, openPugiSess
 import { PUGI_TAGLINE } from '@pugi/personas';
 import { resolveRoster, renderRosterTable } from './commands/roster.js';
 import { runDelegateCommand } from './commands/delegate.js';
+import { runDispatchCommand } from './commands/dispatch.js';
 import { clearApiKey, DEFAULT_API_URL, listStoredCredentials, maskApiKey, normalizeApiUrl, purgeAllCredentials, readCredentialsFile, resolveActiveCredential, storeApiKey, switchActiveAccount, } from '../core/credentials.js';
 import { resolveAndValidateEnvLogin, } from '../core/auth/env-provider.js';
 import { runDeployCommand } from '../commands/deploy.js';
@@ -35,12 +36,19 @@ import { isOnboarded } from '../core/onboarding/marker.js';
 import { runPrivacyCommand } from './commands/privacy.js';
 import { runReport } from './commands/report.js';
 import { runDoctorCommand, defaultHome as defaultDoctorHome } from './commands/doctor.js';
+import { parsePrdCheckArgs, runPrdCheckCommand, } from './commands/prd-check.js';
 import { runStatusCommand, defaultStatusHome, } from './commands/status.js';
 import { runStickersCommand } from './commands/stickers.js';
 import { runRepoMapCommand } from './commands/repo-map.js';
 import { runReleaseNotesCommand, defaultReleaseNotesHome, } from './commands/release-notes.js';
 import { runUndoCommand } from './commands/undo.js';
 import { runCompactCommand } from './commands/compact.js';
+import { runRewindCommand } from './commands/rewind.js';
+import { runSessionsCommand } from './commands/sessions.js';
+// Day 4 ADR-0063: persona-memory operator surface (list / recall / write /
+// forget / sync). The runner is shared by `pugi memory` top-level and the
+// in-REPL `/memory` slash so the two surfaces stay single-sourced.
+import { runMemoryCommand } from './commands/memory.js';
 import { runBudgetCommand } from './commands/budget.js';
 import { BARE_MODE_BANNER, isBareMode, setBareMode, } from '../core/bare-mode/index.js';
 import { runCostCommand } from './commands/cost.js';
@@ -92,6 +100,11 @@ const handlers = {
     config: dispatchConfig,
     cost: dispatchCost,
     delegate: dispatchDelegate,
+    // Leak L10 (2026-05-27): `pugi dispatch list-cache-refs` /
+    // `clear-cache-refs` operate on `.pugi/cache-refs/` — the persisted
+    // prompt-cache inheritance handles for fork-subagent dispatches. The
+    // handler module lives in commands/dispatch.ts so the table stays narrow.
+    dispatch: dispatchSubagentCacheRefs,
     deploy: dispatchDeploy,
     doctor,
     explain: runEngineTask('explain'),
@@ -106,11 +119,20 @@ const handlers = {
     logout,
     lsp: dispatchLsp,
     mcp: dispatchMcp,
+    // ADR-0063 Day 4: `pugi memory list|recall|write|forget|sync`. Routes
+    // to `runMemoryCommand` (admin-api `/api/persona-memory` + offline
+    // queue at `~/.pugi/memory-queue.jsonl`).
+    memory: dispatchMemory,
     patch: dispatchPatch,
     permissions: dispatchPermissions,
     perms: dispatchPermissions,
     plan: dispatchPlan,
     'plan-review': dispatchPlanReview,
+    // Wave 6 (2026-05-27): `pugi prd-check` verifies PRD acceptance
+    // criteria against committed code/tests/docs/commands BEFORE an
+    // operator (or autonomous agent) claims a feature done. Same
+    // handler powers the in-REPL `/prd-check` slash via session.ts.
+    'prd-check': dispatchPrdCheck,
     privacy: dispatchPrivacy,
     // L24 (2026-05-27): `pugi release-notes` shows the bundled CHANGELOG
     // diff between the operator's last-seen version + installed version.
@@ -159,6 +181,11 @@ const handlers = {
     vim: dispatchVim,
     undo: dispatchUndo,
     compact: dispatchCompact,
+    // Leak L9 (2026-05-27): `pugi rewind [N | --to <id>]` rolls the
+    // conversation back to a checkpoint by appending a tombstone marker
+    // to the NDJSON event log. The slash counterpart `/rewind` forwards
+    // to the same runner via session.ts.
+    rewind: dispatchRewind,
     // L19 (2026-05-27): `pugi usage` is an alias of `pugi cost` — same
     // handler, same flags. Operators trained on Claude Code expect either
     // verb to surface the per-model token + USD table.
@@ -343,6 +370,41 @@ async function dispatchPrivacy(args, flags, _session) {
         writeOutput: (payload, text) => writeOutput(flags, payload, text),
     });
 }
+/**
+ * ADR-0063 Day 4 — `pugi memory <sub>` top-level dispatcher.
+ *
+ * Forwards to the shared `runMemoryCommand` runner. Exit codes:
+ *
+ *   - 0 — happy paths (listed / recalled / written / forgot / synced /
+ *         queued_offline / sync_noop / sync_partial)
+ *   - 1 — unauthenticated / feature_disabled / unknown_sub
+ *   - 2 — invalid_args
+ *
+ * `forget_not_found` exits 0 because the operator-visible behaviour
+ * (the memory is gone) matches their intent; the JSON envelope still
+ * carries the `forget_not_found` status flag for scripted callers.
+ */
+async function dispatchMemory(args, flags, _session) {
+    const result = await runMemoryCommand(args, {
+        workspaceRoot: process.cwd(),
+        json: flags.json,
+        writeOutput: (payload, text) => writeOutput(flags, payload, text),
+    });
+    switch (result.status) {
+        case 'unauthenticated':
+        case 'feature_disabled':
+        case 'unknown_sub':
+            process.exitCode = 1;
+            return;
+        case 'invalid_args':
+            process.exitCode = 2;
+            return;
+        default:
+            // 'listed' | 'recalled' | 'written' | 'queued_offline' | 'forgot' |
+            // 'forget_not_found' | 'synced' | 'sync_partial' | 'sync_noop' — exit 0.
+            return;
+    }
+}
 /**
  * Leak L18 (2026-05-27) — `pugi style` top-level dispatcher.
  *
@@ -570,6 +632,31 @@ async function dispatchBudget(args, flags, _session) {
         writeOutput: (payload, text) => writeOutput(flags, payload, text),
     });
 }
+/**
+ * Leak L9 (2026-05-27) — `pugi rewind [N | --to <id>]` rolls the
+ * conversation back to a checkpoint by appending a tombstone marker to
+ * the NDJSON event log. Append-only: events stay durable; `pugi
+ * sessions undo-rewind` reverses the operation. The slash `/rewind`
+ * forwards through this same runner via session.ts.
+ */
+async function dispatchRewind(args, flags, _session) {
+    const result = await runRewindCommand(args, {
+        workspaceRoot: process.cwd(),
+        writeOutput: (payload, text) => writeOutput(flags, payload, text),
+    });
+    if (result.status === 'failed_no_session'
+        || result.status === 'failed_store') {
+        process.exitCode = 1;
+        return;
+    }
+    if (result.status === 'failed_parse') {
+        process.exitCode = 2;
+        return;
+    }
+    if (result.status === 'noop_zero' || result.status === 'noop_empty') {
+        process.exitCode = 2;
+    }
+}
 /**
  * Leak L6 — `pugi permissions [mode] [--persist] [--confirm]`.
  *
@@ -745,6 +832,19 @@ async function dispatchAgents(args, flags, _session) {
         writeOutput: (payload, text) => writeOutput(flags, payload, text),
     });
 }
+/**
+ * Leak L10 (2026-05-27): `pugi dispatch <sub>` — operator-facing
+ * inspection + GC for fork-subagent prompt-cache inherit refs
+ * (.pugi/cache-refs/). Delegates to the standalone runner in
+ * commands/dispatch.ts so the cli.ts table stays under control.
+ */
+async function dispatchSubagentCacheRefs(args, flags, _session) {
+    await runDispatchCommand(args, {
+        workspaceRoot: process.cwd(),
+        json: flags.json,
+        writeOutput: (payload, text) => writeOutput(flags, payload, text),
+    });
+}
 /**
  * `pugi web <url>` — Sprint α6.15 Phase 1 quick-win subcommand.
  *
@@ -1526,6 +1626,17 @@ const COMMAND_HELP_BODIES = {
         'Slugs (Tier 1 alpha 7.5): dev qa pm devops researcher analyst designer',
         'frontend architect. `pugi roster` lists the live set.',
     ],
+    dispatch: [
+        'pugi dispatch <sub> — inspect + GC fork-subagent prompt-cache inherit refs.',
+        '',
+        '  list-cache-refs                        Table of every active ref under .pugi/cache-refs/.',
+        '  clear-cache-refs [--older-than 1h]     Evict refs older than the window (default 24h).',
+        '',
+        'Leak L10 (2026-05-27): when Mira spawns a child via the `agent` tool,',
+        'a prompt-cache handle is persisted so the child loop can request',
+        'parent-context reuse on the wire. These commands surface + clean up',
+        'the persisted refs.',
+    ],
     roster: [
         'pugi roster — list the live Tier 1 personas + roles.',
     ],
@@ -1536,6 +1647,22 @@ const COMMAND_HELP_BODIES = {
         'event log, settings), permission mode, and the capability matrix per',
         'engine adapter. Safe to run anywhere; no network calls.',
     ],
+    'prd-check': [
+        'pugi prd-check <prd-path> | --all   — Wave 6 verified-deliverable gate.',
+        '',
+        'Reads a markdown PRD, parses the acceptance-criteria section, and',
+        'runs verifiers against committed artifacts:',
+        '  file:<path>      fs.existsSync',
+        '  test:<spec>      spec file exists + has ≥1 test()/it() block',
+        '  doc:<path>       doc exists + has > 100 chars',
+        '  command:<name>   CLI registry contains the command',
+        '  route:METHOD /p  best-effort grep of controllers',
+        '',
+        '  --all                   Scan docs/prd/**.md instead of one file.',
+        '  --json                  Emit a structured envelope to stdout.',
+        '',
+        'Exit codes: 0 healthy · 1 failing · 2 unparsed / arg error.',
+    ],
     status: [
         'pugi status — concise session snapshot.',
         '',
@@ -1694,6 +1821,8 @@ async function help(args, flags, _session) {
         'Persona dispatch (α7.5):',
         '  pugi roster                              List the live Tier 1 personas + roles.',
         '  pugi delegate <slug> "<brief>"           Dispatch a brief to one specialist.',
+        '  pugi dispatch list-cache-refs            Inspect fork-subagent prompt-cache inherit refs.',
+        '  pugi dispatch clear-cache-refs           GC stale cache refs (--older-than 1h).',
         '',
         'Plan decomposition (α6.8):',
         '  pugi plan --decompose <idea>   Split a high-level idea into 3-7 components.',
@@ -1757,6 +1886,48 @@ async function doctor(_args, flags, _session) {
         writeOutput: (payload, text) => writeOutput(flags, payload, text),
     });
 }
+/**
+ * `pugi prd-check` — Wave 6 verified-deliverable gate (2026-05-27).
+ *
+ * Reads `docs/prd/<feature>.md` (or any explicit path), parses the
+ * acceptance-criteria section, and runs file / test / doc / command
+ * / route verifiers per criterion. Same handler powers the in-REPL
+ * `/prd-check` slash via session.ts so the verdict is identical
+ * between surfaces.
+ *
+ * The `knownCommands` set is sourced from the same `handlers` map
+ * used by the CLI dispatcher (one source of truth), so a PRD that
+ * mentions `pugi <name>` resolves against the EXACT registry the
+ * shell exposes.
+ *
+ * Exit codes (from reporter.exitCodeFor):
+ *   0 — healthy (every criterion PASS or SKIPPED)
+ *   1 — failing (≥1 FAIL)
+ *   2 — unparsed (PRD has no acceptance section) OR arg error
+ */
+async function dispatchPrdCheck(args, flags, _session) {
+    const parsed = parsePrdCheckArgs(args, { jsonDefault: flags.json });
+    if (!parsed.ok) {
+        writeOutput(flags, { ok: false, error: parsed.error }, parsed.error);
+        process.exitCode = 2;
+        return;
+    }
+    await runPrdCheckCommand({
+        cwd: process.cwd(),
+        ...(parsed.prdPath !== undefined ? { prdPath: parsed.prdPath } : {}),
+        flags: parsed.flags,
+        knownCommands: knownCommandNames(),
+        writeOutput: (payload, text) => writeOutput(flags, payload, text),
+    });
+}
+/**
+ * Snapshot the set of registered CLI command names — used by the
+ * prd-check `command:` verifier so PRD mentions of `pugi <name>`
+ * resolve against the exact same registry the shell exposes.
+ */
+function knownCommandNames() {
+    return new Set(Object.keys(handlers));
+}
 /**
  * `pugi update` — Leak L27 (2026-05-27). Channel-aware npm registry
  * probe + optional shell-out to `npm install -g @pugi/cli@<tag>`.
@@ -3339,6 +3510,25 @@ async function handoff(args, flags, session) {
     writeOutput(flags, bundle, ['Pugi handoff bundle created', `Bundle: ${bundle.path}`].join('\n'));
 }
 async function sessions(args, flags, _session) {
+    // L9 (2026-05-27): `pugi sessions undo-rewind [<session-id>]` rolls
+    // back the latest /rewind by appending an inverse marker. Append-only,
+    // reversible. Falls through to the legacy artifact-based handler when
+    // the sub-command is not recognised.
+    if (args[0] === 'undo-rewind') {
+        const result = await runSessionsCommand(args, {
+            workspaceRoot: process.cwd(),
+            writeOutput: (payload, text) => writeOutput(flags, payload, text),
+        });
+        if (result) {
+            if (result.status === 'failed_no_session' || result.status === 'failed_store') {
+                process.exitCode = 1;
+            }
+            else if (result.status === 'noop_no_rewind') {
+                process.exitCode = 2;
+            }
+            return;
+        }
+    }
     // α6.4: `pugi sessions --local` / `--search "query"` route to the
     // local SessionStore. The default surface stays artifact-based for
     // backward compat — operators who relied on the index.json view get

package/dist/runtime/commands/dispatch.js

@@ -0,0 +1,126 @@
+/**
+ * `pugi dispatch <sub>` — fork-subagent cache-handoff surface (Leak L10 — 2026-05-27).
+ *
+ * Sub-commands:
+ *
+ *   - `pugi dispatch list-cache-refs` — show active cache-inherit refs
+ *     persisted under `.pugi/cache-refs/`. Renders an aligned table or
+ *     JSON depending on `--json`.
+ *
+ *   - `pugi dispatch clear-cache-refs [--older-than 1h] [-v]` — GC stale
+ *     refs. Without `--older-than`, defaults to 24h (the same cutoff
+ *     the REPL boot-time auto-sweep uses). The flag accepts duration
+ *     strings the `parseDuration` helper recognises (`1h`, `30m`,
+ *     `7d`, `500ms`, ...).
+ *
+ * The command lives in its own module (not inline in cli.ts) so the
+ * dispatch table stays narrow and tests can drive it without spinning
+ * up the full CLI.
+ */
+import { cleanupStaleCacheRefs, parseDuration, } from '../../core/dispatch/cache-cleanup.js';
+import { listCacheRefs } from '../../core/dispatch/cache-handoff.js';
+const USAGE = [
+    'Usage:',
+    '  pugi dispatch list-cache-refs',
+    '                                       Show every active subagent cache-inherit',
+    '                                       reference persisted under .pugi/cache-refs/.',
+    '',
+    '  pugi dispatch clear-cache-refs [--older-than <duration>] [-v]',
+    '                                       Evict stale refs. Accepts 500ms / 30s / 5m /',
+    '                                       1h / 7d. Default --older-than 24h.',
+].join('\n');
+export async function runDispatchCommand(args, ctx) {
+    const sub = args[0];
+    if (!sub || sub === '--help' || sub === '-h') {
+        ctx.writeOutput({ command: 'dispatch', usage: USAGE.split('\n') }, USAGE);
+        return;
+    }
+    switch (sub) {
+        case 'list-cache-refs':
+            return runListCacheRefs(ctx);
+        case 'clear-cache-refs':
+            return runClearCacheRefs(args.slice(1), ctx);
+        default:
+            ctx.writeOutput({
+                ok: false,
+                error: `unknown subcommand: ${sub}`,
+                usage: USAGE.split('\n'),
+            }, `pugi dispatch: unknown subcommand '${sub}'\n\n${USAGE}`);
+            process.exitCode = 2;
+            return;
+    }
+}
+function runListCacheRefs(ctx) {
+    const refs = listCacheRefs(ctx.workspaceRoot);
+    if (ctx.json) {
+        ctx.writeOutput({ ok: true, count: refs.length, refs }, '');
+        return;
+    }
+    if (refs.length === 0) {
+        ctx.writeOutput({ ok: true, count: 0, refs: [] }, 'No active cache-inherit refs under .pugi/cache-refs/.');
+        return;
+    }
+    // Aligned column table. Widths derived from the data — no hardcoded
+    // sizes so a long childAgentId does not overflow the layout.
+    const header = ['CHILD AGENT', 'CACHE ID', 'PARENT SESSION', 'CREATED'];
+    const rows = refs.map((r) => [
+        r.childAgentId,
+        r.cacheId,
+        r.parentSessionId,
+        r.createdAt,
+    ]);
+    const widths = header.map((h, i) => Math.max(h.length, ...rows.map((row) => (row[i] ?? '').length)));
+    const lines = [];
+    lines.push(header.map((h, i) => h.padEnd(widths[i] ?? 0)).join('  '));
+    lines.push(widths.map((w) => '-'.repeat(w)).join('  '));
+    for (const row of rows) {
+        lines.push(row.map((cell, i) => (cell ?? '').padEnd(widths[i] ?? 0)).join('  '));
+    }
+    ctx.writeOutput({ ok: true, count: refs.length, refs }, lines.join('\n'));
+}
+function runClearCacheRefs(args, ctx) {
+    let olderThanArg;
+    let verbose = false;
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === '--older-than') {
+            olderThanArg = args[i + 1];
+            i++;
+            continue;
+        }
+        if (arg && arg.startsWith('--older-than=')) {
+            olderThanArg = arg.slice('--older-than='.length);
+            continue;
+        }
+        if (arg === '-v' || arg === '--verbose') {
+            verbose = true;
+            continue;
+        }
+    }
+    // Default 24h matches the REPL boot-time auto-sweep cutoff.
+    const olderThanMs = olderThanArg ? parseDuration(olderThanArg) : 24 * 60 * 60 * 1000;
+    if (olderThanMs === null) {
+        ctx.writeOutput({
+            ok: false,
+            error: `invalid --older-than value: ${olderThanArg ?? '(missing)'}`,
+            usage: USAGE.split('\n'),
+        }, `pugi dispatch clear-cache-refs: invalid --older-than '${olderThanArg ?? '(missing)'}'\n\n${USAGE}`);
+        process.exitCode = 2;
+        return;
+    }
+    const result = cleanupStaleCacheRefs(ctx.workspaceRoot, {
+        olderThanMs,
+        verbose,
+    });
+    const summary = `Removed ${result.removedCount} ref(s) (${result.corruptCount} corrupt), kept ${result.keptCount}.`;
+    ctx.writeOutput({
+        ok: true,
+        olderThanMs,
+        removedCount: result.removedCount,
+        keptCount: result.keptCount,
+        corruptCount: result.corruptCount,
+        removed: result.removed,
+        corrupt: result.corrupt,
+    }, summary);
+}
+//# sourceMappingURL=dispatch.js.map