@pugi/cli 0.1.0-beta.2 → 0.1.0-beta.20

package/dist/core/subagents/dispatcher.js

@@ -1,5 +1,5 @@
 /**
- * Subagent dispatcher (Sprint a5.4 — M1 gap remediation D).
+ * Subagent dispatcher (β2 S1 + S4 — 2026-05-26).
  *
  * The dispatcher is the runtime side of the @pugi/sdk subagent contracts.
  * Given a SubagentTask, it:
@@ -7,25 +7,30 @@
  *   1. Resolves the role to a Cyber-Zoo persona via the local registry
  *      (apps/pugi-cli/src/core/agents/registry.ts, which itself sources
  *      @pugi/personas).
- *   2. Classifies isolation per the M1 matrix (see isolationForRole).
+ *   2. Classifies isolation per the matrix (see isolationForRole).
  *   3. Builds the dispatch-time permission overrides (Vera as reviewer
  *      or verifier loses every edit/write/bash class — see
  *      permissionOverridesForRole).
  *   4. Emits subagent.spawned into the session events log.
- *   5. Runs the dispatch (M1: stub returning shipped immediately so the
- *      contract surface is exercisable; M2+ swaps the body for
- *      worktree-isolated execution backed by runEngineLoop).
+ *   5. Drives the dispatch via one of two backends:
+ *      - REAL (β2 S1): when ctx carries an EngineLoopClient, the child
+ *        runs a genuine `runEngineLoop` against Anvil with a per-child
+ *        tools schema gated by the isolation-matrix capability map
+ *        (β2 S4). See `dispatcher-real.ts::runRealDispatch`.
+ *      - STUB (M1 legacy): when no engine client is supplied, the
+ *        dispatcher returns a `shipped` result with zero metrics so
+ *        the legacy `inMemoryDispatcherContext` test path stays green.
+ *        This is the back-compat door for the M1 spec coverage.
  *   6. Emits subagent.completed | blocked | failed into the session
- *      events log.
+ *      events log (real backend emits richer details; stub emits the
+ *      M1-compatible shape).
  *   7. Returns the typed SubagentResult.
  *
- * Why a stub at M1: the contract surface itself, the event emission, the
- * isolation classification, and the permission overrides are real
- * load-bearing pieces — the cabinet UI, audit replay, and triple-review
- * gating all read these events. The model-driven loop that actually
- * spawns a separate Anvil session is alpha-5.7 work (REPL-by-default).
- * The stub returns a shipped result with the correct persona slug + role
- * pair so downstream consumers can wire against the real shape.
+ * Why we kept the stub path: the existing M1 spec coverage exercises
+ * the dispatcher's contract surface (role-to-persona, isolation tier,
+ * permission overrides, event ordering) without any HTTP transport.
+ * β2 must not regress that surface — every existing assertion still
+ * holds for in-memory contexts. The real backend is a strict superset.
  *
  * The dispatcher is the only place that knows the isolation matrix and
  * the permission overrides. Both surfaces are exported so engine adapter
@@ -164,19 +169,51 @@ export function budgetForRole(role, override) {
     };
 }
 /* ------------------------------------------------------------------ */
-/* Dispatch                                                           */
+/* Real-backend lazy import (memoized)                                */
 /* ------------------------------------------------------------------ */
 /**
- * Spawn a subagent. M1 implementation is a stub that synchronously
- * returns a shipped result so the contract surface is exercised by
- * tests and the cabinet UI. M2+ replaces the body with an Anvil-side
- * dispatch over a per-task worktree (ADR-0057, deferred).
+ * β2a r1 (Backend Architect P1, 2026-05-26): cached lazy-import of
+ * the real dispatch backend. Hoisting the dynamic import to
+ * module scope (instead of running it on every dispatch call) means
+ * the first agent spawn does not pay 50-200ms cold-start latency.
  *
- * The function still emits real subagent.spawned and subagent.completed
- * events; downstream consumers (audit replay, cabinet activity feed,
- * eval harness) cannot tell the stub apart from a real dispatch on the
- * event surface alone, which is the property we want for forward-
- * compatibility testing.
+ * The cache is a Promise so concurrent first-callers share one
+ * import; ESM's own module cache also dedups but the Promise wrapper
+ * lets `prewarmRealDispatch` kick off the import without awaiting.
+ */
+let realDispatchPromise = null;
+function ensureRealDispatch() {
+    if (!realDispatchPromise) {
+        realDispatchPromise = import('./dispatcher-real.js');
+    }
+    return realDispatchPromise;
+}
+/**
+ * β2a r1: pre-warm the real dispatcher's module graph. Called by the
+ * engine adapter (`NativePugiEngineAdapter`) at construction time
+ * when an engine client is wired, so the first `dispatch()` call
+ * with `ctx.engineClient` set returns instantly. Safe to call
+ * multiple times — subsequent calls hit the cached promise.
+ */
+export function prewarmRealDispatch() {
+    return ensureRealDispatch();
+}
+/**
+ * Spawn a subagent. Two backends:
+ *
+ *   - REAL (β2 S1): when `ctx.engineClient` is set, the dispatcher
+ *     spawns a genuine child engine loop. See `dispatcher-real.ts`.
+ *     The child's tool surface is filtered by the isolation matrix
+ *     (β2 S4) so a `researcher` role cannot see `write`/`edit`/`bash`
+ *     in its tools schema and the executor refuses if the model
+ *     fabricates a call.
+ *
+ *   - STUB (M1 legacy): when no engine client is supplied, the
+ *     dispatcher returns a `shipped` result with zero metrics. This
+ *     is the back-compat door for the M1 spec coverage and for
+ *     in-memory consumers that only want to assert the dispatcher's
+ *     CONTRACT surface (role-to-persona, isolation tier, permission
+ *     overrides, event ordering) without standing up Anvil.
  *
  * The function rejects with ZodError when the task fails schema
  * validation. Throwing rather than returning a failed result is the
@@ -186,6 +223,58 @@ export function budgetForRole(role, override) {
  */
 export async function dispatch(task, ctx) {
     const validated = subagentTaskSchema.parse(task);
+    if (ctx.engineClient) {
+        // β2a r1 (Backend Architect P1, 2026-05-26): the lazy import
+        // chain (worktree + engine SDK graph) cost 50-200ms on the FIRST
+        // dispatch call. `ensureRealDispatch` memoizes the promise so the
+        // import happens at most once per process; subsequent dispatches
+        // hit the cached promise instantly. Production callers should
+        // prewarm via `prewarmRealDispatch()` at engine adapter init so
+        // the operator never pays cold-start on the first agent call.
+        const { runRealDispatch } = await ensureRealDispatch();
+        const outcome = await runRealDispatch(validated, {
+            sessionId: ctx.sessionId,
+            workspaceRoot: ctx.workspaceRoot,
+            appendEvent: ctx.appendEvent,
+            ...(ctx.now ? { now: ctx.now } : {}),
+            engineClient: ctx.engineClient,
+            ...(ctx.commandKind ? { commandKind: ctx.commandKind } : {}),
+            ...(ctx.useWorktreeIsolation !== undefined
+                ? { useWorktreeIsolation: ctx.useWorktreeIsolation }
+                : {}),
+            ...(ctx.signal ? { signal: ctx.signal } : {}),
+        });
+        return outcome.result;
+    }
+    return runStubDispatch(validated, ctx);
+}
+/**
+ * Real-backend variant that also surfaces the optional worktree
+ * handle. Callers that need to promote/drop the scratch worktree
+ * (e.g. the REPL `/agent` surface, or the Agent tool dispatcher) use
+ * this entry point.
+ */
+export async function dispatchWithOutcome(task, ctx) {
+    const validated = subagentTaskSchema.parse(task);
+    if (ctx.engineClient) {
+        const { runRealDispatch } = await ensureRealDispatch();
+        return runRealDispatch(validated, {
+            sessionId: ctx.sessionId,
+            workspaceRoot: ctx.workspaceRoot,
+            appendEvent: ctx.appendEvent,
+            ...(ctx.now ? { now: ctx.now } : {}),
+            engineClient: ctx.engineClient,
+            ...(ctx.commandKind ? { commandKind: ctx.commandKind } : {}),
+            ...(ctx.useWorktreeIsolation !== undefined
+                ? { useWorktreeIsolation: ctx.useWorktreeIsolation }
+                : {}),
+            ...(ctx.signal ? { signal: ctx.signal } : {}),
+        });
+    }
+    const result = await runStubDispatch(validated, ctx);
+    return { result };
+}
+async function runStubDispatch(validated, ctx) {
     const persona = getPersonaForRole(validated.role);
     const isolation = isolationForRole(validated.role);
     void budgetForRole(validated.role, validated.budget);
@@ -233,7 +322,7 @@ export async function dispatch(task, ctx) {
     return result;
 }
 function stubSummaryFor(role, personaName) {
-    return `${personaName} (${role}) dispatched: stub returning shipped (M1 contract surface only; real dispatch in alpha-5.7)`;
+    return `${personaName} (${role}) dispatched: in-memory stub backend (no engine client supplied; production callers should pass DispatcherContext.engineClient)`;
 }
 function defaultNow() {
     return new Date().toISOString();

package/dist/core/subagents/index.js

@@ -14,13 +14,26 @@
  * would invite the kind of accidental drift the persona-registry
  * extraction was designed to prevent.
  */
-export { budgetForRole, dispatch, inMemoryDispatcherContext, isolationForRole, permissionOverridesForRole, } from './dispatcher.js';
+export { budgetForRole, dispatch, dispatchWithOutcome, inMemoryDispatcherContext, isolationForRole, permissionOverridesForRole, } from './dispatcher.js';
+/**
+ * β2 S4: per-role capability matrix. Surfaced via the barrel so
+ * engine adapter code, the Agent tool, and tests can introspect a
+ * role's allowed tool set without importing the matrix module
+ * directly.
+ */
+export { allowedToolsForRole, capabilitiesForRole, roleHasToolAccess, ROLE_CAPABILITIES, } from './isolation-matrix.js';
+/**
+ * β2 S1: real-backend entry point. Exposed for callers that want to
+ * drive the dispatch with the worktree handle in scope (e.g. the
+ * Agent tool, the REPL `/agent` surface). Most callers should prefer
+ * the `dispatch()` / `dispatchWithOutcome()` helpers above which
+ * route to this module when ctx.engineClient is set.
+ */
+export { runRealDispatch } from './dispatcher-real.js';
 /**
  * Spawn a subagent from inside the engine adapter loop. Re-exported via
  * the barrel so engine code does not have to import the dispatcher
- * module directly. The actual task_dispatch tool that the model uses
- * to invoke a subagent lands in alpha-5.7 (REPL); for now the helper
- * exists so adapter code has a single seam to wire against.
+ * module directly.
  */
-export { spawnSubagent } from './spawn.js';
+export { spawnSubagent, spawnSubagentWithOutcome } from './spawn.js';
 //# sourceMappingURL=index.js.map

package/dist/core/subagents/isolation-matrix.js

@@ -0,0 +1,213 @@
+const CAP_READ_ONLY = new Set([
+    'read',
+    'task',
+    'skill',
+]);
+const CAP_VERIFIER = new Set([
+    'read',
+    'task',
+    'skill',
+    // β2a r1 (Codex P1, 2026-05-26): verifier previously got the FULL
+    // `bash` capability. The class-aware bash tool defaults to
+    // permission mode `auto`, which permits `write_workspace` class
+    // commands (e.g. `echo x > src/file.ts`, `sed -i`, `rm`). That
+    // silently bypassed the no-edit/no-write contract — a verifier
+    // could mutate the workspace it was meant to read.
+    //
+    // The fix splits bash into two capabilities:
+    //   - `bash`          → full bash (writers only)
+    //   - `bash_read_only` → bash gate that forces read-only classifier
+    //                        mode regardless of operator settings
+    // verifier needs the read-only flavor so test commands (pnpm test,
+    // jest --listFiles, typecheck) still work but a fabricated
+    // `echo x > file.ts` is refused at the executor layer.
+    'bash_read_only',
+]);
+const CAP_WRITER = new Set([
+    'read',
+    'write',
+    'bash',
+    'task',
+    'skill',
+    'ask_user',
+]);
+const CAP_FULL = new Set([
+    'read',
+    'write',
+    'bash',
+    'task',
+    'skill',
+    'ask_user',
+    'web_fetch',
+    'agent',
+]);
+/**
+ * Per-role capability map. Add a new role only when the matching
+ * isolation tier classification in dispatcher.ts agrees with the
+ * capability set here — drift would let a `coder` role get write
+ * privileges with `shared_fs_readonly` isolation, which would mean
+ * the dispatcher emits readonly-isolation events while the child
+ * actually writes. Always touch both files together.
+ */
+export const ROLE_CAPABILITIES = new Map([
+    [
+        'orchestrator',
+        {
+            role: 'orchestrator',
+            capabilities: CAP_FULL,
+            rationale: 'orchestrator (Pugi/Mira) runs in parent context with full toolset; '
+                + 'parent permissions still gate any actual mutation',
+        },
+    ],
+    [
+        'architect',
+        {
+            role: 'architect',
+            capabilities: CAP_READ_ONLY,
+            rationale: 'architect role is read-only by design (analysis + planning, no mutations)',
+        },
+    ],
+    [
+        'coder',
+        {
+            role: 'coder',
+            capabilities: CAP_WRITER,
+            rationale: 'coder role mutates the workspace via write + edit + bash',
+        },
+    ],
+    [
+        'verifier',
+        {
+            role: 'verifier',
+            capabilities: CAP_VERIFIER,
+            rationale: 'verifier role reads workspace + executes verification commands (tests, typecheck) '
+                + 'but never edits the code it is verifying',
+        },
+    ],
+    [
+        'reviewer',
+        {
+            role: 'reviewer',
+            capabilities: CAP_READ_ONLY,
+            rationale: 'reviewer role is read-only by policy (no edits to code under review); '
+                + 'shell is denied because reviewer should not be re-running tests',
+        },
+    ],
+    [
+        'researcher',
+        {
+            role: 'researcher',
+            capabilities: CAP_READ_ONLY,
+            rationale: 'researcher role is read-only (corpus search + summarization)',
+        },
+    ],
+    [
+        'release',
+        {
+            role: 'release',
+            capabilities: CAP_WRITER,
+            rationale: 'release role needs write + bash for changelog edits + version bumps',
+        },
+    ],
+    [
+        'devops',
+        {
+            role: 'devops',
+            capabilities: CAP_WRITER,
+            rationale: 'devops role needs write + bash for infra config + deploy scripts',
+        },
+    ],
+    [
+        'design_qa',
+        {
+            role: 'design_qa',
+            capabilities: CAP_WRITER,
+            rationale: 'design_qa role needs write + bash for UI tweaks + screenshot scripts',
+        },
+    ],
+]);
+/**
+ * Resolve the capability set for a role. Throws when the role is not
+ * registered — the closed SubagentRole union prevents that at compile
+ * time for typed callers, but the runtime guard catches dynamic dispatch
+ * paths (e.g. a tag parsed off Mira's reply text).
+ */
+export function capabilitiesForRole(role) {
+    const entry = ROLE_CAPABILITIES.get(role);
+    if (!entry) {
+        throw new Error(`capabilitiesForRole: unknown role '${role}'`);
+    }
+    return entry;
+}
+/**
+ * Map capability classes → concrete tool names (matches tool-bridge.ts
+ * WIRED_TOOLS). This is the bridge between the policy layer (this file)
+ * and the schema-shaping layer (tool-bridge buildToolsSchema). Keep in
+ * lockstep with WIRED_TOOLS — a new tool added to the bridge should
+ * be classified here so subagents see (or do not see) it consistently.
+ */
+const CAPABILITY_TO_TOOLS = {
+    read: ['read', 'grep', 'glob'],
+    write: ['write', 'edit'],
+    bash: ['bash'],
+    // β2a r1 (2026-05-26): `bash_read_only` maps to the same `bash`
+    // tool name so the model sees only one tool surface. The
+    // dispatcher-real executor wraps the verifier's bash calls with a
+    // forced read-only classifier mode (see `gatedExecutor` in
+    // dispatcher-real.ts) so a `write_workspace`-class command is
+    // rejected before the tool runs even though the capability set
+    // appears to advertise `bash`.
+    bash_read_only: ['bash'],
+    task: ['task_create', 'task_get', 'task_list', 'task_update'],
+    skill: ['skill', 'skills_list'],
+    ask_user: ['ask_user_question'],
+    web_fetch: ['web_fetch'],
+    // Agent tool is the subagent spawn primitive itself (S3). Only the
+    // orchestrator role gets it — child agents cannot recursively spawn
+    // grand-children, which keeps the spawn depth bounded at 1 and the
+    // budget rollup tractable.
+    agent: ['agent'],
+};
+/**
+ * Return the set of tool names a role is allowed to call. Used by the
+ * per-child tool-bridge to shape the OpenAI tools schema AND by the
+ * executor refusal gate.
+ *
+ * The function is pure — same role in, same set out — so the schema
+ * builder can call it from inside `buildToolsSchema`.
+ */
+export function allowedToolsForRole(role) {
+    const caps = capabilitiesForRole(role);
+    const out = new Set();
+    for (const cap of caps.capabilities) {
+        for (const name of CAPABILITY_TO_TOOLS[cap]) {
+            out.add(name);
+        }
+    }
+    return out;
+}
+/**
+ * Predicate: is a tool name reachable by a role under the capability
+ * matrix? Used by the executor's pre-dispatch refusal gate.
+ *
+ * Returns true for orchestrator/full-capability roles and for every
+ * specific tool the role's capability set unlocks; false otherwise.
+ */
+export function roleHasToolAccess(role, toolName) {
+    return allowedToolsForRole(role).has(toolName);
+}
+/**
+ * β2a r1 (Codex P1, 2026-05-26): predicate identifying roles whose
+ * bash access is restricted to read-only classifier mode. Used by
+ * dispatcher-real.ts's gatedExecutor to force-flag bash dispatches as
+ * read-only regardless of the workspace's permission settings.
+ *
+ * A role qualifies when it holds `bash_read_only` but NOT the
+ * full-power `bash` capability — orchestrators (which inherit both
+ * via CAP_FULL) keep full bash access through the regular path.
+ */
+export function bashIsReadOnlyForRole(role) {
+    const caps = capabilitiesForRole(role).capabilities;
+    return caps.has('bash_read_only') && !caps.has('bash');
+}
+//# sourceMappingURL=isolation-matrix.js.map

package/dist/core/subagents/spawn.js

@@ -1,5 +1,5 @@
 import { recordSubagentBlocked, recordSubagentCompleted, recordSubagentFailed, recordSubagentSpawned, recordSubagentToolCall, } from '../session.js';
-import { dispatch } from './dispatcher.js';
+import { dispatch, dispatchWithOutcome, } from './dispatcher.js';
 /**
  * Spawn a subagent under an existing PugiSession. Events are routed
  * through the session module's recorder functions; if the session is
@@ -7,13 +7,28 @@ import { dispatch } from './dispatcher.js';
  * dispatch still runs — the contract is "dispatch always works, audit
  * is best-effort".
  */
-export async function spawnSubagent(task, session) {
-    const ctx = {
+export async function spawnSubagent(task, session, options = {}) {
+    return dispatch(task, buildContext(session, options));
+}
+/**
+ * β2 S1: spawnSubagent variant that surfaces the optional worktree
+ * handle so the caller can wire promote/drop follow-ups.
+ */
+export async function spawnSubagentWithOutcome(task, session, options = {}) {
+    return dispatchWithOutcome(task, buildContext(session, options));
+}
+function buildContext(session, options) {
+    return {
         sessionId: session.id,
         workspaceRoot: session.root,
         appendEvent: (event) => routeEvent(event, session),
+        ...(options.engineClient ? { engineClient: options.engineClient } : {}),
+        ...(options.commandKind ? { commandKind: options.commandKind } : {}),
+        ...(options.useWorktreeIsolation !== undefined
+            ? { useWorktreeIsolation: options.useWorktreeIsolation }
+            : {}),
+        ...(options.signal ? { signal: options.signal } : {}),
     };
-    return dispatch(task, ctx);
 }
 function routeEvent(event, session) {
     if (!isRecord(event))

package/dist/core/transport/version-interceptor.js

@@ -0,0 +1,166 @@
+/**
+ * Pugi CLI ↔ admin-api version handshake — CLI-side interceptor.
+ *
+ * Wraps the engine HTTP transport (and, via the same helpers, any
+ * other `fetch` call the CLI makes to admin-api) so the CLI:
+ *
+ *   1. Sends `X-Pugi-Cli-Version: <installed semver>` on every
+ *      outbound request. The server middleware
+ *      (`apps/admin-api/src/runtime/cli-version.middleware.ts`) reads
+ *      this header and decides whether to honour, soft-warn, or 426.
+ *
+ *   2. Inspects every response for:
+ *      - `X-Pugi-Cli-Upgrade-Recommended` → cache the server's
+ *        recommendation so `UpdateBanner` can compare it against the
+ *        npm-registry poll and show the operator the higher of the two.
+ *      - `X-Pugi-Server-Version` → cache for diagnostics
+ *        (`pugi doctor --json`).
+ *
+ *   3. Throws `PugiCliUpgradeRequiredError` when the server returns
+ *      HTTP 426. The top-level catch in `index.ts` / `runtime/cli.ts`
+ *      renders a clean upgrade banner + `process.exit(1)`.
+ *
+ * # Design: pure helpers, not a callable wrapper
+ *
+ * Wrapping fetch as a higher-order function would require every
+ * transport call site to opt in via `interceptedFetch(...)`. Instead
+ * we expose three small helpers that the existing transport classes
+ * (currently just `AnvilEngineLoopClient`) call inline:
+ *
+ *   - `injectClientVersionHeader(headers)` — adds the X-Pugi-Cli-Version
+ *     entry to an outbound header bag.
+ *   - `inspectVersionResponse(response)` — reads recommended/server
+ *     headers, updates the module cache. Returns void.
+ *   - `assertNotUpgradeRequired(response)` — if status is 426, parses
+ *     the JSON body and throws `PugiCliUpgradeRequiredError`. Returns
+ *     void otherwise.
+ *
+ * That layout keeps the spec tests trivially focused on each branch and
+ * gives future SSE callers (engine-stream EventSource) the same hooks
+ * without touching the fetch wrapper indirection.
+ */
+import { PUGI_CLI_UPGRADE_RECOMMENDED_HEADER, PUGI_CLI_VERSION_HEADER, PUGI_SERVER_VERSION_HEADER, } from '../../runtime/version.js';
+/**
+ * Thrown when admin-api responds with HTTP 426 Upgrade Required. The
+ * top-level CLI catch (see `runtime/cli.ts`) renders this with the
+ * operator-friendly upgrade banner.
+ *
+ * Mirrors the server-side `CliUpgradeRequiredBody` shape; populated
+ * from the response JSON when present and from the request context
+ * (installed version) when the body parse fails.
+ */
+export class PugiCliUpgradeRequiredError extends Error {
+    code = 'cli_upgrade_required';
+    installedVersion;
+    minClientVersion;
+    recommendedVersion;
+    upgradeCommand;
+    upgradeUrl;
+    constructor(details) {
+        super(details.message ??
+            `Pugi CLI ${details.installedVersion} is below the server minimum ${details.minClientVersion}. Upgrade with: ${details.upgradeCommand}`);
+        this.name = 'PugiCliUpgradeRequiredError';
+        this.installedVersion = details.installedVersion;
+        this.minClientVersion = details.minClientVersion;
+        this.recommendedVersion = details.recommendedVersion;
+        this.upgradeCommand = details.upgradeCommand;
+        this.upgradeUrl = details.upgradeUrl;
+    }
+}
+/**
+ * Module-level cache of the most recent server-recommended version.
+ * Read by `UpdateBanner` (via `getCachedServerRecommendation`) when
+ * computing the version it shows the operator. Kept in module scope
+ * (not class state) because both the engine client and the banner live
+ * in different module subtrees and there's no shared service container
+ * to thread DI through.
+ */
+let cachedServerRecommendation = null;
+let cachedServerVersion = null;
+/**
+ * UpdateBanner reads this to merge with its npm-registry poll. Returns
+ * `null` when no Pugi response has been seen yet (very first REPL
+ * launch before the engine has been called).
+ */
+export function getCachedServerRecommendation() {
+    return cachedServerRecommendation;
+}
+/**
+ * `pugi doctor --json` reads this for the server-version diagnostic
+ * field. Returns `null` when no response has been seen yet.
+ */
+export function getCachedServerVersion() {
+    return cachedServerVersion;
+}
+/**
+ * Test seam — reset the cache between specs so cross-test leakage
+ * doesn't make assertions flaky. Not part of the public CLI surface.
+ */
+export function __resetVersionCacheForTests() {
+    cachedServerRecommendation = null;
+    cachedServerVersion = null;
+}
+/**
+ * Mutate an outbound header bag to add the CLI version. Accepts both
+ * the plain-object header shape that `fetch` uses and Headers
+ * instances. Returns the same bag for chaining.
+ *
+ * Header names go in canonical capitalization since some
+ * test/intermediary tools (mitmproxy, charles) display the exact case
+ * the client sent rather than normalising to lowercase.
+ */
+export function injectClientVersionHeader(headers, cliVersion) {
+    if (headers instanceof Headers) {
+        headers.set(PUGI_CLI_VERSION_HEADER, cliVersion);
+        return headers;
+    }
+    headers[PUGI_CLI_VERSION_HEADER] = cliVersion;
+    return headers;
+}
+/**
+ * Inbound-header inspection. Reads `X-Pugi-Cli-Upgrade-Recommended`
+ * and `X-Pugi-Server-Version` from the response and updates the
+ * module-level cache. Caller passes a `headers.get(...)` shim so this
+ * helper stays decoupled from the concrete response type — `Response`,
+ * `undici.Dispatcher.ResponseData`, or a stub in tests.
+ */
+export function inspectVersionResponse(getHeader) {
+    const recommended = getHeader(PUGI_CLI_UPGRADE_RECOMMENDED_HEADER);
+    if (typeof recommended === 'string' && recommended.length > 0) {
+        cachedServerRecommendation = recommended;
+    }
+    const serverVersion = getHeader(PUGI_SERVER_VERSION_HEADER);
+    if (typeof serverVersion === 'string' && serverVersion.length > 0) {
+        cachedServerVersion = serverVersion;
+    }
+}
+/**
+ * If the response is HTTP 426, throw `PugiCliUpgradeRequiredError`.
+ * Otherwise return void. Caller is responsible for already having
+ * read the response body — pass it in so we can parse the
+ * documented JSON shape without consuming the stream a second time.
+ *
+ * `installedFallback` is used when the response body doesn't carry
+ * `installedVersion` (e.g. CDN-injected 426). Should be the CLI's own
+ * PUGI_CLI_VERSION constant.
+ */
+export function assertNotUpgradeRequired(status, bodyText, installedFallback) {
+    if (status !== 426)
+        return;
+    let parsed = {};
+    try {
+        parsed = JSON.parse(bodyText);
+    }
+    catch {
+        // Body wasn't JSON — fall back to constants below.
+    }
+    throw new PugiCliUpgradeRequiredError({
+        installedVersion: parsed.installedVersion ?? installedFallback,
+        minClientVersion: parsed.minClientVersion ?? 'unknown',
+        recommendedVersion: parsed.recommendedVersion ?? 'unknown',
+        upgradeCommand: parsed.upgradeCommand ?? 'npm i -g @pugi/cli@latest',
+        upgradeUrl: parsed.upgradeUrl ?? 'https://www.npmjs.com/package/@pugi/cli',
+        message: parsed.message,
+    });
+}
+//# sourceMappingURL=version-interceptor.js.map

package/dist/index.js

@@ -1,6 +1,34 @@
 #!/usr/bin/env node
 import { runCli } from './runtime/cli.js';
+import { PugiCliUpgradeRequiredError } from './core/transport/version-interceptor.js';
 runCli(process.argv.slice(2)).catch((error) => {
+    // PR-CLI-SERVER-VERSION-HANDSHAKE (#225). When the admin-api returns
+    // 426 Upgrade Required, the engine transport throws a typed
+    // PugiCliUpgradeRequiredError. Render an operator-friendly banner
+    // (vs. the bland `pugi: <message>` default) so the upgrade command
+    // is obvious + copy-pasteable. Plain console.error rather than Ink
+    // here because the error may surface during one-shot commands where
+    // no Ink renderer is mounted (REPL paths catch via runtime/cli.ts).
+    if (error instanceof PugiCliUpgradeRequiredError) {
+        const lines = [
+            '',
+            'Pugi CLI upgrade required',
+            '',
+            `  Your installed version: ${error.installedVersion}`,
+            `  Server requires minimum: ${error.minClientVersion}`,
+            `  Latest recommended:     ${error.recommendedVersion}`,
+            '',
+            `  Upgrade: ${error.upgradeCommand}`,
+            `  Docs:    ${error.upgradeUrl}`,
+            '',
+            '  Until you upgrade, the server will reject your requests.',
+            '  This protects you from silent protocol-drift bugs.',
+            '',
+        ];
+        console.error(lines.join('\n'));
+        process.exitCode = 1;
+        return;
+    }
     const message = error instanceof Error ? error.message : String(error);
     console.error(`pugi: ${message}`);
     process.exitCode = 1;