@pugi/cli 0.1.0-beta.5 → 0.1.0-beta.51

package/dist/core/dispatch/cache-cleanup.js

@@ -0,0 +1,197 @@
+/**
+ * Fork-subagent cache-ref cleanup (Leak L10 — 2026-05-27).
+ *
+ * GC pass for `.pugi/cache-refs/`. Two surfaces use this:
+ *
+ *   1. `pugi dispatch clear-cache-refs --older-than <duration>` — operator
+ *      runs this after a long session to evict stale handles. The flag
+ *      accepts an `--older-than` window (e.g. `1h`, `24h`, `7d`); refs
+ *      whose `createdAt` falls outside the window are removed.
+ *
+ *   2. Background sweep on REPL boot — when `cleanupStaleCacheRefs` is
+ *      called on session start with a default 24h window, the dispatcher
+ *      auto-prunes refs left over from crashed processes. Idempotent
+ *      and silent (no logs unless `verbose: true`).
+ *
+ * Design notes:
+ *
+ *   - Cleanup is path-scoped to `.pugi/cache-refs/` only. The function
+ *     refuses to traverse outside that directory; a malicious symlink
+ *     pointing at `~/.ssh/` would not cause damage because we only
+ *     unlink files directly under cacheRefDir().
+ *
+ *   - Cleanup is best-effort. A ref file with a corrupted JSON body
+ *     has no `createdAt` to compare against — the policy is to treat
+ *     such files as "stale" because they cannot be reused anyway.
+ *     They get evicted alongside out-of-window refs.
+ *
+ *   - The function returns a structured summary (counts + paths) so
+ *     the CLI can render a deterministic report (`X refs removed,
+ *     Y refs kept`).
+ */
+import { readdirSync, readFileSync, statSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { cacheRefDir, cacheRefSchema } from './cache-handoff.js';
+const DEFAULT_OLDER_THAN_MS = 24 * 60 * 60 * 1000;
+/**
+ * Sweep `.pugi/cache-refs/` for stale refs.
+ *
+ * Returns a CleanupResult with three buckets:
+ *   - `removed`: refs that were unlinked (either older than window
+ *     OR corrupt + therefore unusable).
+ *   - `kept`:    refs that remain on disk after the sweep.
+ *   - `corrupt`: refs that failed schema validation; these are also
+ *     present in `removed` (the corrupt array is a sub-view for
+ *     diagnostic surfaces).
+ *
+ * The function does not throw on individual file errors — it tracks
+ * the failure (silent skip for unreadable files) and continues so a
+ * single broken ref cannot block the rest of the sweep.
+ */
+export function cleanupStaleCacheRefs(workspaceRoot, options = {}) {
+    const dir = cacheRefDir(workspaceRoot);
+    const now = options.now ?? Date.now;
+    const olderThanMs = options.olderThanMs ?? DEFAULT_OLDER_THAN_MS;
+    const verbose = options.verbose ?? false;
+    const cutoff = now() - olderThanMs;
+    let entries;
+    try {
+        entries = readdirSync(dir).filter((name) => name.endsWith('.json')).sort();
+    }
+    catch {
+        // No directory yet — nothing to clean. Return empty buckets so the
+        // caller's report says "0 refs removed" cleanly.
+        return {
+            removed: [],
+            kept: [],
+            corrupt: [],
+            removedCount: 0,
+            keptCount: 0,
+            corruptCount: 0,
+        };
+    }
+    const removed = [];
+    const kept = [];
+    const corrupt = [];
+    for (const name of entries) {
+        const full = join(dir, name);
+        let raw;
+        try {
+            raw = readFileSync(full, 'utf8');
+        }
+        catch {
+            // Unreadable — treat as corrupt and remove. mtime fallback path
+            // would be unreliable since we already failed to read the file.
+            removed.push(full);
+            corrupt.push(full);
+            tryUnlink(full, verbose);
+            continue;
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch {
+            removed.push(full);
+            corrupt.push(full);
+            tryUnlink(full, verbose);
+            continue;
+        }
+        const validated = cacheRefSchema.safeParse(parsed);
+        if (!validated.success) {
+            removed.push(full);
+            corrupt.push(full);
+            tryUnlink(full, verbose);
+            continue;
+        }
+        const createdAtMs = Date.parse(validated.data.createdAt);
+        // Date.parse returns NaN on invalid strings. Treat as stale.
+        const ageMs = Number.isFinite(createdAtMs)
+            ? createdAtMs
+            : tryStatMtime(full);
+        if (ageMs < cutoff) {
+            removed.push(full);
+            tryUnlink(full, verbose);
+        }
+        else {
+            kept.push(full);
+        }
+    }
+    return {
+        removed,
+        kept,
+        corrupt,
+        removedCount: removed.length,
+        keptCount: kept.length,
+        corruptCount: corrupt.length,
+    };
+}
+/* ------------------------------------------------------------------ */
+/* Duration parsing                                                   */
+/* ------------------------------------------------------------------ */
+/**
+ * Parse a human-readable duration string (e.g. `1h`, `30m`, `7d`) into
+ * milliseconds. Used by the `--older-than` CLI flag handler. Returns
+ * null on parse failure so the CLI can surface a usage error.
+ *
+ * Accepted suffixes:
+ *   - `ms` — milliseconds
+ *   - `s`  — seconds
+ *   - `m`  — minutes
+ *   - `h`  — hours
+ *   - `d`  — days
+ *
+ * A bare number with no suffix is rejected (the CLI requires explicit
+ * units to avoid the "is 60 seconds or 60 minutes?" trap).
+ */
+export function parseDuration(input) {
+    const trimmed = input.trim().toLowerCase();
+    if (!trimmed)
+        return null;
+    const match = trimmed.match(/^([0-9]+(?:\.[0-9]+)?)(ms|s|m|h|d)$/);
+    if (!match)
+        return null;
+    const value = Number(match[1]);
+    if (!Number.isFinite(value) || value < 0)
+        return null;
+    switch (match[2]) {
+        case 'ms':
+            return value;
+        case 's':
+            return value * 1000;
+        case 'm':
+            return value * 60 * 1000;
+        case 'h':
+            return value * 60 * 60 * 1000;
+        case 'd':
+            return value * 24 * 60 * 60 * 1000;
+        default:
+            return null;
+    }
+}
+/* ------------------------------------------------------------------ */
+/* Internals                                                          */
+/* ------------------------------------------------------------------ */
+function tryUnlink(path, verbose) {
+    try {
+        rmSync(path, { force: false });
+        if (verbose) {
+            process.stderr.write(`pugi-cache-cleanup: removed ${path}\n`);
+        }
+    }
+    catch {
+        // Concurrent cleanup raced us. Treat as success — the file is
+        // gone, which is what we wanted.
+    }
+}
+function tryStatMtime(path) {
+    try {
+        return statSync(path).mtimeMs;
+    }
+    catch {
+        // If we can't stat either, treat the ref as ancient so it gets
+        // evicted in the same pass.
+        return 0;
+    }
+}
+//# sourceMappingURL=cache-cleanup.js.map

package/dist/core/dispatch/cache-handoff.js

@@ -0,0 +1,295 @@
+/**
+ * Fork-subagent prompt-cache inheritance (Leak L10 — 2026-05-27).
+ *
+ * Claude Code's leaked sub-agent spawn pattern: when a parent agent
+ * dispatches a child via the Task tool, the child boots with the parent's
+ * prompt cache REFERENCE inherited — not the conversation transcript
+ * verbatim, but a provider-native cache handle that lets the child reuse
+ * the parent's system prompt + cached tool definitions without re-paying
+ * the prompt-prefix tokens on the first turn.
+ *
+ * Anthropic's `cache_control` block in their messages API exposes this
+ * directly via cache breakpoints. OpenAI / xAI / Gemini have similar
+ * primitives at different granularities; the wire payload our Anvil
+ * proxy speaks is provider-agnostic, so we forward a generic
+ * `parent_cache_id` hint and Anvil routes it onto the underlying
+ * provider's cache primitive (or silently drops it if the provider
+ * doesn't support cache inheritance — graceful degrade).
+ *
+ * What this module does:
+ *
+ *   1. `inheritCacheContext(parentSessionId, childAgentId)` —
+ *      synthesises a cache handle for a child dispatch. Persists the
+ *      handle to `.pugi/cache-refs/<child-agent-id>.json` so:
+ *
+ *        a. The child's own boot path can read it (e.g. a child engine
+ *           loop running in a worktree subshell where the in-memory
+ *           DispatcherContext isn't reachable).
+ *        b. `pugi dispatch list-cache-refs` can surface active refs
+ *           for debugging "why is my cache hit rate so low".
+ *        c. `pugi dispatch clear-cache-refs --older-than 1h` can
+ *           garbage-collect stale refs from crashed/killed children.
+ *
+ *   2. `readCacheRef(workspaceRoot, childAgentId)` — child-side read.
+ *      Returns the persisted handle so the child's first engine loop
+ *      turn can include the parent_cache_id hint in its request.
+ *
+ *   3. `cacheHandoffHookForRequest(handle)` — produces the wire payload
+ *      shape that the Anvil bridge can splice into the
+ *      `engineLoopServerRequest` body. Lives here (not in the bridge)
+ *      so the cache-control schema is in one place.
+ *
+ * What this module does NOT do:
+ *
+ *   - It does not replay the parent's conversation transcript into the
+ *     child. That would defeat the cyber-zoo isolation contract
+ *     (`shared_fs_readonly` etc.). The child gets a CACHE HINT — the
+ *     provider may use it to skip re-tokenising shared prompt prefix,
+ *     but the LOGICAL conversation always starts fresh from the child's
+ *     own system prompt + brief.
+ *
+ *   - It does not assume any provider honours the hint. Cache-miss is
+ *     the default path. If Anvil routes the request to a model whose
+ *     provider doesn't expose cache inheritance, the request still
+ *     succeeds — just at full prompt-prefix cost.
+ *
+ *   - It does not rotate or invalidate the parent's cache on the
+ *     parent's side. Parent cache lifecycle is owned by the parent
+ *     engine loop; the child holds a read-only reference.
+ *
+ * Cross-reference:
+ *   - apps/pugi-cli/src/core/subagents/dispatcher-real.ts — where the
+ *     child engine loop is driven; the cache_id from this module is
+ *     forwarded onto Anvil via the `extensions` field of the engine
+ *     loop server request (β2 forward-compat slot).
+ *   - packages/pugi-sdk/src/engine-loop.ts — engineLoopServerRequest
+ *     schema; cache-handoff field is OPTIONAL and additive.
+ *
+ * Leak research §L10 (Claude Code sub-agent spawn fork pattern):
+ * docs/research/2026-05-27-leak-parity-sprint.md (research memo).
+ */
+import { mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { join, resolve as resolvePath } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { z } from 'zod';
+/* ------------------------------------------------------------------ */
+/* Types + schema                                                     */
+/* ------------------------------------------------------------------ */
+/**
+ * Persisted cache reference. The shape is intentionally minimal —
+ * provider-specific cache tokens are opaque strings so the file format
+ * does not couple to any one provider's API.
+ *
+ *   - `cacheId`         — opaque provider hint forwarded to Anvil.
+ *                         Synthesized client-side as `pugi-cache-<uuid>`
+ *                         so the server has a stable correlation key
+ *                         even when the underlying provider's cache
+ *                         object is not yet provisioned.
+ *   - `contextRef`      — logical reference key the parent uses to tag
+ *                         which prompt segments to re-use. Same value
+ *                         as cacheId for the v1 wire (single breakpoint
+ *                         per parent); reserved for future multi-breakpoint
+ *                         schemes (split system + tools + first-user
+ *                         segments).
+ *   - `parentSessionId` — debugging / GC scoping. `list-cache-refs`
+ *                         can group by parent session.
+ *   - `childAgentId`    — the dispatch this ref is scoped to.
+ *   - `createdAt`       — ISO timestamp for `--older-than` cleanup.
+ *   - `schemaVersion`   — pinned to 1; bumped on breaking shape change.
+ */
+export const cacheRefSchema = z.object({
+    schemaVersion: z.literal(1),
+    cacheId: z.string().min(1).max(256),
+    contextRef: z.string().min(1).max(256),
+    parentSessionId: z.string().min(1).max(256),
+    childAgentId: z.string().min(1).max(256),
+    createdAt: z.string().min(1),
+});
+/* ------------------------------------------------------------------ */
+/* Path resolution                                                    */
+/* ------------------------------------------------------------------ */
+/**
+ * Resolve the directory under `.pugi/` where cache refs live. The
+ * directory is created on first write — readers tolerate its absence
+ * (no refs = empty list, not an error).
+ */
+export function cacheRefDir(workspaceRoot) {
+    return resolvePath(workspaceRoot, '.pugi', 'cache-refs');
+}
+function cacheRefPath(workspaceRoot, childAgentId) {
+    // Sanitise the child id — directory traversal via crafted child id
+    // would let a dispatch target write outside the cache-refs dir. The
+    // child id format is owned by spawn.ts (`subagent-<uuid>`) but we
+    // defend in depth.
+    const safe = childAgentId.replace(/[^A-Za-z0-9_-]/g, '_').slice(0, 200);
+    return join(cacheRefDir(workspaceRoot), `${safe}.json`);
+}
+/**
+ * Synthesize a cache handle for a child dispatch and persist it to
+ * `.pugi/cache-refs/<childAgentId>.json`. Returns the in-memory handle
+ * the dispatcher feeds into the Anvil wire request.
+ *
+ * Idempotent: calling twice with the same `childAgentId` overwrites
+ * the existing ref. The dispatcher's `taskId` is a UUID per dispatch,
+ * so collisions are not expected, but the overwrite semantic is safer
+ * than failing — a stale ref from a previous run (e.g. process killed
+ * between spawn and run) should not block a fresh dispatch.
+ */
+export function inheritCacheContext(parentSessionId, childAgentId, options) {
+    if (!parentSessionId) {
+        throw new Error('inheritCacheContext: parentSessionId must be non-empty');
+    }
+    if (!childAgentId) {
+        throw new Error('inheritCacheContext: childAgentId must be non-empty');
+    }
+    const now = options.now ?? defaultNow;
+    const cacheIdFactory = options.cacheIdFactory ?? defaultCacheId;
+    const cacheId = cacheIdFactory();
+    const ref = {
+        schemaVersion: 1,
+        cacheId,
+        contextRef: cacheId,
+        parentSessionId,
+        childAgentId,
+        createdAt: now(),
+    };
+    const dir = cacheRefDir(options.workspaceRoot);
+    mkdirSync(dir, { recursive: true });
+    const path = cacheRefPath(options.workspaceRoot, childAgentId);
+    writeFileSync(path, JSON.stringify(ref, null, 2), 'utf8');
+    return {
+        cacheId: ref.cacheId,
+        contextRef: ref.contextRef,
+        persistedPath: path,
+    };
+}
+/**
+ * Child-side read. Returns null when the ref is missing or malformed
+ * (the child boots without cache inheritance — degrade is silent so a
+ * corrupted ref does not block a dispatch).
+ *
+ * Malformed ref files are NOT auto-deleted by this read path — that's
+ * the cleanup command's job. A failed parse here just returns null so
+ * the dispatch proceeds at full prompt-prefix cost.
+ */
+export function readCacheRef(workspaceRoot, childAgentId) {
+    const path = cacheRefPath(workspaceRoot, childAgentId);
+    let raw;
+    try {
+        raw = readFileSync(path, 'utf8');
+    }
+    catch {
+        return null;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+    const validated = cacheRefSchema.safeParse(parsed);
+    if (!validated.success)
+        return null;
+    return validated.data;
+}
+/**
+ * List every persisted cache ref under `.pugi/cache-refs/`. Used by
+ * `pugi dispatch list-cache-refs` and by GC sweeps in
+ * `cache-cleanup.ts`. Returns refs in deterministic
+ * (filename-ascending) order so the CLI output is stable.
+ *
+ * Malformed ref files are silently skipped — the cleanup command can
+ * surface them via a separate `--show-corrupt` flag if needed.
+ */
+export function listCacheRefs(workspaceRoot) {
+    const dir = cacheRefDir(workspaceRoot);
+    let entries;
+    try {
+        entries = readdirSync(dir).filter((name) => name.endsWith('.json')).sort();
+    }
+    catch {
+        return [];
+    }
+    const refs = [];
+    for (const entry of entries) {
+        const full = join(dir, entry);
+        let raw;
+        try {
+            raw = readFileSync(full, 'utf8');
+        }
+        catch {
+            continue;
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch {
+            continue;
+        }
+        const validated = cacheRefSchema.safeParse(parsed);
+        if (!validated.success)
+            continue;
+        refs.push(validated.data);
+    }
+    return refs;
+}
+/* ------------------------------------------------------------------ */
+/* Wire-format hook                                                   */
+/* ------------------------------------------------------------------ */
+/**
+ * Project the in-memory handle (or persisted ref) onto the wire-format
+ * hint object that the Anvil bridge merges into the engine-loop
+ * request body. Pulled out so callers (dispatcher-real, future bridge
+ * adapters) all speak the same shape.
+ */
+export function cacheHandoffHookForRequest(source) {
+    return {
+        parent_cache_id: source.cacheId,
+        cache_context_ref: source.contextRef,
+    };
+}
+/* ------------------------------------------------------------------ */
+/* Internals                                                          */
+/* ------------------------------------------------------------------ */
+function defaultNow() {
+    return new Date().toISOString();
+}
+function defaultCacheId() {
+    return `pugi-cache-${randomUUID()}`;
+}
+/* ------------------------------------------------------------------ */
+/* Stat helper (used by cache-cleanup.ts)                             */
+/* ------------------------------------------------------------------ */
+/**
+ * Exposed for cache-cleanup.ts so the GC sweep can read mtime without
+ * re-implementing the path-resolution logic. Returns null when the
+ * file is gone (a concurrent cleanup may have raced us — silent miss).
+ */
+export function cacheRefMtime(workspaceRoot, childAgentId) {
+    try {
+        const stat = statSync(cacheRefPath(workspaceRoot, childAgentId));
+        return stat.mtime;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Delete a single cache ref. Returns true when the file existed and
+ * was removed, false when it was already gone. Used by both the
+ * `clear-cache-refs` CLI and by post-dispatch cleanup (a successful
+ * subagent run does not need the cache ref to outlive its dispatch).
+ */
+export function deleteCacheRef(workspaceRoot, childAgentId) {
+    const path = cacheRefPath(workspaceRoot, childAgentId);
+    try {
+        rmSync(path, { force: false });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=cache-handoff.js.map