@pugi/cli 0.1.0-beta.24 → 0.1.0-beta.26

package/dist/core/telemetry/queue.js

@@ -0,0 +1,251 @@
+/**
+ * Telemetry batching queue — Wave 6 BIG TRACK 11 (PR-PUGI-OBSERVABILITY-STACK).
+ *
+ * The emitter (see `emitter.ts`) appends events to an in-memory buffer
+ * and a JSONL spill file. The queue's two-tier strategy:
+ *
+ *   1. In-memory buffer (`MAX_BUFFER`) → flushed every `FLUSH_INTERVAL_MS`
+ *      OR on REPL exit OR when the buffer hits the cap.
+ *   2. JSONL spill (`<repoRoot>/.pugi/telemetry-queue.jsonl`) → drained
+ *      on every flush attempt. Used when the in-memory buffer cannot
+ *      reach the network (offline laptop, admin-api down).
+ *
+ * Failure semantics mirror the `feedback/queue.ts` pattern that landed
+ * in L21:
+ *
+ *   - 200/201/204                → success, drop from spill
+ *   - 404                        → endpoint not deployed yet — keep
+ *   - 5xx / network / abort      → transient — keep + exponential backoff
+ *   - other 4xx                  → permanent — drop (otherwise loop forever)
+ *
+ * The queue is intentionally simple: there are no concurrency primitives
+ * beyond filesystem `O_APPEND`. The CLI is single-process per REPL
+ * session; the JSONL spill survives a crash because every append is
+ * atomic at the OS level for line-sized writes on POSIX (Linux & macOS).
+ *
+ * Privacy:
+ *
+ *   - Events drop into the queue only when telemetry consent ≠ `off`.
+ *     The emitter consults `readTelemetryChoice()` before calling
+ *     `enqueueTelemetry(...)`. This module does NOT re-check — keeping
+ *     the consent gate at the emitter avoids double-decoding and
+ *     centralises the audit point.
+ *
+ *   - The spill file lives under `<repoRoot>/.pugi/` (workspace tier)
+ *     so an operator who deletes the repo also wipes any unfortunate
+ *     events that never made it to the server.
+ */
+import { appendFileSync, existsSync, mkdirSync, readFileSync, writeFileSync, } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { PUGI_CLI_VERSION } from '../../runtime/version.js';
+/** Defaults — tunable via env without redeploy. */
+export const MAX_BUFFER = 50;
+export const FLUSH_INTERVAL_MS = 15_000;
+export const SPILL_FILE_NAME = 'telemetry-queue.jsonl';
+/** Hard cap on the spill file (events, not bytes). Prevents pathologic
+ *  growth on a laptop that is offline for weeks. */
+export const SPILL_MAX_LINES = 5_000;
+/**
+ * Resolve the absolute spill file path. Pure — exposed for spec parity.
+ */
+export function telemetryQueuePath(opts = {}) {
+    const root = opts.repoRoot ?? process.cwd();
+    const name = opts.spillFileName ?? SPILL_FILE_NAME;
+    return resolve(root, '.pugi', name);
+}
+/**
+ * Append one event to the on-disk spill. Atomic at the OS level for
+ * line-sized writes — multiple concurrent appenders never interleave
+ * half-records on POSIX. Caps the file at `SPILL_MAX_LINES` by silently
+ * dropping the OLDEST events (FIFO) on the rare overflow path.
+ */
+export function spillEvent(ev, opts = {}) {
+    const path = telemetryQueuePath(opts);
+    mkdirSync(dirname(path), { recursive: true });
+    const line = `${JSON.stringify(ev)}\n`;
+    // Fast path: append-only. We only check the line count when the file
+    // already exists AND we suspect overflow. Reading + rewriting every
+    // append would dominate the cost.
+    if (existsSync(path)) {
+        const current = readFileSync(path, 'utf8');
+        const lineCount = countLines(current);
+        if (lineCount >= SPILL_MAX_LINES) {
+            // FIFO trim: keep the most-recent SPILL_MAX_LINES/2 events. The
+            // factor 2 amortises the rewrite across many appends.
+            const lines = current.split('\n').filter((l) => l.length > 0);
+            const keep = lines.slice(lines.length - Math.floor(SPILL_MAX_LINES / 2));
+            writeFileSync(path, `${keep.join('\n')}\n${line}`, 'utf8');
+            return;
+        }
+    }
+    appendFileSync(path, line, { encoding: 'utf8', mode: 0o600 });
+}
+/**
+ * Read + parse every spilled event. Returns the events plus a list of
+ * malformed lines (which are dropped silently — we never reject a
+ * parseable line just because an adjacent one is corrupt).
+ */
+export function readSpill(opts = {}) {
+    const path = telemetryQueuePath(opts);
+    if (!existsSync(path))
+        return { events: [], malformed: 0 };
+    const raw = readFileSync(path, 'utf8');
+    if (raw.length === 0)
+        return { events: [], malformed: 0 };
+    const events = [];
+    let malformed = 0;
+    for (const line of raw.split('\n')) {
+        if (line.length === 0)
+            continue;
+        try {
+            const parsed = JSON.parse(line);
+            if (isTelemetryEvent(parsed)) {
+                events.push(parsed);
+            }
+            else {
+                malformed += 1;
+            }
+        }
+        catch {
+            malformed += 1;
+        }
+    }
+    return { events, malformed };
+}
+/**
+ * Atomically rewrite the spill with the given events (the unsubmitted
+ * remainder after a partial-success flush). Writing through a sibling
+ * tempfile + rename keeps the spill consistent across a crash mid-flush.
+ */
+export function rewriteSpill(events, opts = {}) {
+    const path = telemetryQueuePath(opts);
+    mkdirSync(dirname(path), { recursive: true });
+    if (events.length === 0) {
+        // Empty spill — write an empty file so the next read short-circuits.
+        writeFileSync(path, '', { encoding: 'utf8', mode: 0o600 });
+        return;
+    }
+    const body = events.map((e) => JSON.stringify(e)).join('\n');
+    writeFileSync(path, `${body}\n`, { encoding: 'utf8', mode: 0o600 });
+}
+/**
+ * Type guard for inbound spill lines. Keeps the queue robust against a
+ * forward-incompatible event shape (e.g. a future version added a
+ * required field) — anything that fails the guard is treated as
+ * malformed and dropped on parse.
+ */
+export function isTelemetryEvent(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const v = value;
+    return (typeof v.sessionId === 'string'
+        && typeof v.cliVersion === 'string'
+        && typeof v.command === 'string'
+        && typeof v.kind === 'string'
+        && typeof v.ts === 'string');
+}
+/**
+ * Exponential-backoff schedule. Returns the next delay (in ms) given an
+ * attempt counter, capped at `MAX_BACKOFF_MS`. Pure — exposed for tests.
+ *
+ *   attempt 0 → 1s
+ *   attempt 1 → 2s
+ *   attempt 2 → 4s
+ *   attempt 5 → 32s
+ *   attempt 7+ → 60s (cap)
+ */
+export const BACKOFF_BASE_MS = 1000;
+export const MAX_BACKOFF_MS = 60_000;
+export function backoffDelay(attempt) {
+    if (!Number.isFinite(attempt) || attempt < 0)
+        return BACKOFF_BASE_MS;
+    const exp = BACKOFF_BASE_MS * Math.pow(2, Math.floor(attempt));
+    return Math.min(MAX_BACKOFF_MS, exp);
+}
+const DEFAULT_FLUSH_TIMEOUT_MS = 8_000;
+export function telemetryIngestUrl(apiUrl) {
+    const base = apiUrl.replace(/\/+$/u, '');
+    return `${base}/api/pugi/telemetry/event`;
+}
+/**
+ * POST one batch. Same result-variant contract as
+ * `feedback/submitter.submitFeedback`. Never throws.
+ */
+export async function postTelemetryBatch(events, config) {
+    if (events.length === 0) {
+        return { kind: 'ok', httpStatus: 204, accepted: 0, dropped: 0 };
+    }
+    const url = telemetryIngestUrl(config.apiUrl);
+    const fetchImpl = config.fetchImpl ?? fetch;
+    const timeoutMs = config.timeoutMs ?? DEFAULT_FLUSH_TIMEOUT_MS;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        const headers = {
+            'content-type': 'application/json',
+            'user-agent': `pugi-cli/${PUGI_CLI_VERSION}`,
+        };
+        if (config.apiKey)
+            headers['authorization'] = `Bearer ${config.apiKey}`;
+        const res = await fetchImpl(url, {
+            method: 'POST',
+            headers,
+            body: JSON.stringify({ events }),
+            signal: controller.signal,
+        });
+        const status = res.status;
+        if (status >= 200 && status < 300) {
+            let accepted = events.length;
+            let dropped = 0;
+            try {
+                const body = (await res.json());
+                if (typeof body.accepted === 'number')
+                    accepted = body.accepted;
+                if (typeof body.dropped === 'number')
+                    dropped = body.dropped;
+            }
+            catch {
+                // Body absent / not JSON — server still acked 2xx, treat as full success.
+            }
+            return { kind: 'ok', httpStatus: status, accepted, dropped };
+        }
+        if (status === 404) {
+            return {
+                kind: 'transient',
+                reason: 'admin-api /api/pugi/telemetry/event not deployed yet',
+                httpStatus: status,
+            };
+        }
+        if (status >= 500) {
+            return { kind: 'transient', reason: `server error ${status}`, httpStatus: status };
+        }
+        return { kind: 'permanent', reason: `client error ${status}`, httpStatus: status };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return { kind: 'transient', reason: `network: ${message}` };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+// ---------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------
+function countLines(s) {
+    let n = 0;
+    for (let i = 0; i < s.length; i += 1) {
+        if (s.charCodeAt(i) === 10)
+            n += 1;
+    }
+    return n;
+}
+/**
+ * Generate a session id for the REPL boot. UUID v4 — short enough to
+ * grep, long enough to be globally unique across concurrent processes.
+ */
+export function newSessionId() {
+    return randomUUID();
+}
+//# sourceMappingURL=queue.js.map

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';
@@ -37,14 +38,22 @@ import { runReport } from './commands/report.js';
 import { runDoctorCommand, defaultHome as defaultDoctorHome } from './commands/doctor.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';
 import { runShareCommand } from './commands/share.js';
 import { runSkillsCommand } from './commands/skills.js';
+import { runHooksCommand } from './commands/hooks.js';
 import { installDefaultSkills } from '../core/skills/defaults.js';
 import { runAgentsCommand } from './commands/agents.js';
 import { runLspCommand } from './commands/lsp.js';
@@ -90,9 +99,15 @@ 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'),
+    hooks: dispatchHooks,
     fix: runEngineTask('fix'),
     handoff,
     help,
@@ -103,6 +118,10 @@ 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,
@@ -127,6 +146,14 @@ const handlers = {
     skills: dispatchSkills,
     status,
     stickers,
+    // Leak L28 (2026-05-27): `pugi repo-map` walks the source tree,
+    // extracts top-level function / class / interface / type / enum
+    // declarations + JSDoc summaries, caches the result in
+    // `.pugi/repo-map.json`, and renders the compact markdown listing.
+    // Same builder powers the engine boot-time system-prompt injection
+    // — running the CLI command shows the operator EXACTLY what the
+    // engine would see.
+    'repo-map': dispatchRepoMap,
     // Leak L21 (2026-05-27): in-CLI feedback collector. Shares the
     // same handler as the in-REPL `/feedback` slash; the wrapper just
     // routes TTY vs non-TTY before mounting Ink.
@@ -148,6 +175,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.
@@ -332,6 +364,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.
  *
@@ -370,6 +437,31 @@ async function dispatchStyle(args, flags, _session) {
  * The runner returns the code; we attach it to `process.exitCode` so
  * subsequent dispatch wrappers do not clobber it on success.
  */
+/**
+ * Leak L12 (2026-05-27) — `pugi hooks` top-level dispatcher (MVP).
+ *
+ * Two subcommands:
+ *   - `pugi hooks list`   — show configured hooks per event.
+ *   - `pugi hooks doctor` — validate `~/.pugi/hooks-mvp.json`.
+ *
+ * MVP scope: 2 events of 8 (SessionStart + PreToolUse). Remaining 6
+ * events (PostToolUse, UserPromptSubmit, Stop, SubagentStop,
+ * PreCompact, Notification) deferred to fast-follow PR. The runner
+ * pattern established here is reusable for those events without
+ * touching this dispatcher.
+ *
+ * Exit codes:
+ *   0 -> happy path.
+ *   1 -> config present but invalid (doctor only).
+ *   2 -> argument error / unknown subcommand.
+ */
+async function dispatchHooks(args, flags, _session) {
+    const rc = await runHooksCommand(args, {
+        writeOutput: (payload, text) => writeOutput(flags, payload, text),
+    });
+    if (rc !== 0)
+        process.exitCode = rc;
+}
 async function dispatchTheme(args, flags, _session) {
     const rc = await runThemeCommand(args, {
         workspaceRoot: process.cwd(),
@@ -534,6 +626,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]`.
  *
@@ -709,6 +826,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.
  *
@@ -995,6 +1125,10 @@ function parseArgs(argv) {
         // bare invocation only surfaces new sections. Opt-in to force the
         // full bundled changelog к re-render (clears the on-disk marker).
         reset: false,
+        // Leak L28 — `--refresh` for `pugi repo-map`. Default off so a
+        // bare invocation hits the cache when mtime + size match; opt-in
+        // for a cold rebuild from the source tree.
+        refresh: false,
     };
     const args = [];
     // Leak L22: scan for `--bare` BEFORE the early-return short-circuits
@@ -1089,6 +1223,22 @@ function parseArgs(argv) {
             // single consumer today.
             flags.reset = true;
         }
+        else if (arg === '--refresh') {
+            // Leak L28 — `pugi repo-map --refresh` busts the cache and
+            // rebuilds the AST-light summary from a cold scan. Parsed
+            // globally for symmetry with the rest of the flag grammar;
+            // `runRepoMapCommand` is the single consumer today.
+            flags.refresh = true;
+        }
+        else if (arg === '--format=json' || arg === '--format' && argv[index + 1] === 'json') {
+            // Leak L28 — `pugi repo-map --format=json` is a per-command
+            // synonym for the global `--json` flag. The L28 spec calls
+            // out the `--format=json` shape explicitly so we accept it
+            // verbatim and route through the existing JSON envelope.
+            flags.json = true;
+            if (arg === '--format')
+                index += 1;
+        }
         else if (arg === '--decompose') {
             // α6.8 EXTEND PR1: plan-only flag. Other engine commands ignore
             // it. Parsed globally for symmetry with the rest of the flag
@@ -1470,6 +1620,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.',
     ],
@@ -1638,6 +1799,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.',
@@ -1796,6 +1959,27 @@ async function stickers(_args, flags, _session) {
         writeOutput: (payload, text) => writeOutput(flags, payload, text),
     });
 }
+/**
+ * `pugi repo-map` — Leak L28 (2026-05-27). Builds + caches the AST-
+ * light symbol summary of the workspace. The handler is intentionally
+ * thin: argv tail tokens are honoured for `--refresh` symmetry (the
+ * global parser already sets `flags.refresh`, but accepting the flag
+ * positionally lets `pugi repo-map refresh` work too — both forms
+ * land в the same path). Exit code is always 0 (informational).
+ *
+ * The same builder is invoked lazily on engine boot when `--bare` is
+ * not set; running the CLI command shows the operator EXACTLY what
+ * the engine would inject into the system prompt.
+ */
+async function dispatchRepoMap(args, flags, _session) {
+    const refresh = flags.refresh || args.includes('--refresh') || args.includes('refresh');
+    await runRepoMapCommand({
+        cwd: process.cwd(),
+        refresh,
+        json: flags.json,
+        writeOutput: (payload, text) => writeOutput(flags, payload, text),
+    });
+}
 /**
  * `pugi feedback` — Leak L21 (2026-05-27). In-CLI feedback collector.
  *
@@ -3262,6 +3446,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
@@ -4188,6 +4391,19 @@ function runEngineTask(kind) {
                     process.stderr.write(`pugi ${label}: MCP registry shutdown reported error — ${error.message}\n`);
                 });
             }
+            // Leak L15 (2026-05-27) — tear down any LSP servers warmed up
+            // by the post-edit diagnostics cache. The cache is per-process
+            // and survives across multiple tool calls; without this hook a
+            // `pugi code ...` invocation would leak a tsserver process when
+            // the Node host exits. The dynamic import keeps the cache module
+            // out of the cold path for runs that never touch LSP.
+            try {
+                const { stopAllLspClients } = await import('../core/lsp/cache.js');
+                await stopAllLspClients();
+            }
+            catch (error) {
+                process.stderr.write(`pugi ${label}: LSP cache shutdown reported error — ${error.message}\n`);
+            }
         }
     };
 }