@productbrain/cli 0.1.0-beta.5 → 0.1.0-beta.5060

package/dist/lib/client.d.ts

@@ -1,5 +1,90 @@
 /**
  * MCP HTTP client — POST to Convex gateway with Bearer auth.
+ *
+ * TEN-729: Detects sandbox-blocked fetch (Claude Code, Cursor, etc.) and
+ * provides an actionable error instead of the opaque "fetch failed".
+ *
+ * Sandbox proxy support: Node.js fetch (undici) ignores proxy env vars by
+ * default. We detect HTTPS_PROXY and configure a ProxyAgent so pb works in
+ * sandboxed environments (Claude Code, Cursor) without requiring
+ * NODE_OPTIONS="--use-env-proxy".
  */
-export declare function mcpCall<T = unknown>(fn: string, args?: Record<string, unknown>): Promise<T>;
+import type { ValidationErrorDetail } from './kernelEnvelope.js';
+import { CLIError } from './errors.js';
+import { type KernelCallOptions } from './rate-limit.js';
+/** Error thrown by kernelCall/kernelCallWithSession when the server returns a non-OK response. */
+export declare class McpError extends CLIError {
+    details?: ValidationErrorDetail[];
+    /** Present only when code === 'rate-limited' — seconds until the caller may retry. */
+    retryAfterSeconds?: number;
+    constructor(message: string, code?: string, details?: ValidationErrorDetail[], retryAfterSeconds?: number);
+}
+export { resetTouchThrottle, type KernelCallOptions } from './rate-limit.js';
+export type { KernelEnvelope, ValidationErrorDetail } from './kernelEnvelope.js';
+/** Result of validateKey — used by `pb login` to verify a key before saving. */
+export type ValidateKeyResult = {
+    valid: true;
+    workspaceId: string;
+} | {
+    valid: false;
+    error: string;
+};
+/**
+ * Validate an API key against the server before saving it.
+ * Uses `resolveWorkspace` as a lightweight health check — if it returns data, the key works.
+ *
+ * Returns { valid: true, workspaceId } on success.
+ * Returns { valid: false, error } on auth failure (401) or other server error.
+ * Throws on network/timeout errors so the caller can distinguish "bad key" from "can't reach server".
+ *
+ * WP-575: `timeoutMs` now DEFAULTS to `resolveWorkspace`'s declared budget instead of a
+ * local `5000` literal — that literal was the last connector-owned timeout on the gateway
+ * path, and the point of this work package is that no connector gets to pick its own. It
+ * stays an explicit parameter so a caller (or a test) can still override deliberately.
+ * Widening 5s -> the declared 10s costs nothing in the case people actually hit: an
+ * unreachable host fails with ECONNREFUSED/ENOTFOUND immediately, not by timeout. The
+ * timeout only governs a server that ACCEPTS the connection then stalls, where waiting the
+ * route's real declared budget before calling the key invalid is the correct behavior.
+ */
+export declare function validateKey(apiKey: string, siteUrl: string, timeoutMs?: number): Promise<ValidateKeyResult>;
+/** Get a human-friendly spinner label for an MCP function name. */
+export declare function spinnerLabel(fn: string): string;
+/**
+ * POST to the admin gateway (/api/admin) — separate from /api/aki (STD-101, BR-109).
+ * Admin operations are not knowledge operations — they target the operator surface.
+ *
+ * No built-in spinner: callers wrap with withSpinner when appropriate.
+ * Throws CLIError on auth failure or non-OK response.
+ */
+export declare function adminCall(command: string, args?: Record<string, unknown>): Promise<unknown>;
+export declare function kernelCall<T = unknown>(fn: string, args?: Record<string, unknown>, options?: KernelCallOptions): Promise<T>;
+/**
+ * kernelCall variant that returns the full kernel envelope (data + summary + _meta) instead
+ * of stripping to just `data` — mirrors packages/mcp-server/src/client.ts's
+ * `kernelCallEnvelope`. Use when a caller needs `_meta` (e.g. a route-specific additive
+ * flag like chain.shapeAdvisories' `truncated`, WP-571 sweep) without changing `data`'s own
+ * shape — the reason `_meta` exists as a side-channel at all (convex/lib/envelopeContract.ts).
+ */
+export declare function kernelCallEnvelope<T = unknown>(fn: string, args?: Record<string, unknown>, options?: KernelCallOptions): Promise<{
+    data: T;
+    summary?: string;
+    _meta?: {
+        durationMs?: number;
+        truncated?: boolean;
+    };
+}>;
+/**
+ * kernelCall variant for write operations. Callers that need server-side session
+ * validation (e.g. `chain.verifyEntry`) pass `sessionId` in `args` explicitly —
+ * it now travels in the request body, not a header (http.ts never read the old
+ * `X-Agent-Session-Id` header).
+ * All write commands (update, relate, unrelate, capture) should use this.
+ *
+ * After a successful write, fires a non-blocking `agent.touchSession` call to
+ * renew the session TTL — mirroring MCP server behavior (DEC-299, BET-181 Slice 1).
+ * The touch is fire-and-forget: it does not block the write response, and errors
+ * are silently swallowed. No touch is attempted if no session is active or if
+ * the write itself fails.
+ */
+export declare function kernelCallWithSession<T = unknown>(fn: string, args?: Record<string, unknown>, options?: KernelCallOptions): Promise<T>;
 //# sourceMappingURL=client.d.ts.map

package/dist/lib/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/lib/client.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH,wBAAsB,OAAO,CAAC,CAAC,GAAG,OAAO,EACvC,EAAE,EAAE,MAAM,EACV,IAAI,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GACjC,OAAO,CAAC,CAAC,CAAC,CAiBZ"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/lib/client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAUH,OAAO,KAAK,EAAkB,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAIjF,OAAO,EAAE,QAAQ,EAAa,MAAM,aAAa,CAAC;AAGlD,OAAO,EAAkC,KAAK,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAoDzF,kGAAkG;AAClG,qBAAa,QAAS,SAAQ,QAAQ;IACpC,OAAO,CAAC,EAAE,qBAAqB,EAAE,CAAC;IAClC,sFAAsF;IACtF,iBAAiB,CAAC,EAAE,MAAM,CAAC;gBAEf,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,qBAAqB,EAAE,EAAE,iBAAiB,CAAC,EAAE,MAAM;CAe1G;AAID,OAAO,EAAE,kBAAkB,EAAE,KAAK,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAK7E,YAAY,EAAE,cAAc,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAoDjF,gFAAgF;AAChF,MAAM,MAAM,iBAAiB,GACzB;IAAE,KAAK,EAAE,IAAI,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,GACpC;IAAE,KAAK,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAEpC;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,WAAW,CAC/B,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,EACf,SAAS,SAA8C,GACtD,OAAO,CAAC,iBAAiB,CAAC,CAqC5B;AA6BD,mEAAmE;AACnE,wBAAgB,YAAY,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAE/C;AAED;;;;;;GAMG;AACH,wBAAsB,SAAS,CAC7B,OAAO,EAAE,MAAM,EACf,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC7B,OAAO,CAAC,OAAO,CAAC,CAgClB;AASD,wBAAsB,UAAU,CAAC,CAAC,GAAG,OAAO,EAC1C,EAAE,EAAE,MAAM,EACV,IAAI,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,EAClC,OAAO,CAAC,EAAE,iBAAiB,GAC1B,OAAO,CAAC,CAAC,CAAC,CAgCZ;AAED;;;;;;GAMG;AACH,wBAAsB,kBAAkB,CAAC,CAAC,GAAG,OAAO,EAClD,EAAE,EAAE,MAAM,EACV,IAAI,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,EAClC,OAAO,CAAC,EAAE,iBAAiB,GAC1B,OAAO,CAAC;IAAE,IAAI,EAAE,CAAC,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE;QAAE,UAAU,CAAC,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,OAAO,CAAA;KAAE,CAAA;CAAE,CAAC,CA4B9F;AA+BD;;;;;;;;;;;;GAYG;AACH,wBAAsB,qBAAqB,CAAC,CAAC,GAAG,OAAO,EACrD,EAAE,EAAE,MAAM,EACV,IAAI,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,EAClC,OAAO,CAAC,EAAE,iBAAiB,GAC1B,OAAO,CAAC,CAAC,CAAC,CAkDZ"}

package/dist/lib/client.js

@@ -1,21 +1,421 @@
 /**
  * MCP HTTP client — POST to Convex gateway with Bearer auth.
+ *
+ * TEN-729: Detects sandbox-blocked fetch (Claude Code, Cursor, etc.) and
+ * provides an actionable error instead of the opaque "fetch failed".
+ *
+ * Sandbox proxy support: Node.js fetch (undici) ignores proxy env vars by
+ * default. We detect HTTPS_PROXY and configure a ProxyAgent so pb works in
+ * sandboxed environments (Claude Code, Cursor) without requiring
+ * NODE_OPTIONS="--use-env-proxy".
  */
+// WP-575 (TEN-2917): every gateway call is bounded by the budget DECLARED at the route
+// contract — see ./gatewayTimeout.ts for why a copy, and why the CLI had none before.
+import { latencyBudgetMsForRoute } from '../generated/routeLatencyBudget.generated.js';
+import { gatewayTimeoutError, isTimeoutAbort } from './gatewayTimeout.js';
+// The envelope's shape and how to read one off a Response — including the body-phase budget
+// abort (WP-575 review). Split out under STD-2/DEC-1504; see ./kernelEnvelope.ts's header for
+// why the seam is real and not a line-count dodge.
+import { parseKernelEnvelope, recordLatestFromResponse } from './kernelEnvelope.js';
 import { getConfig } from './config.js';
-export async function mcpCall(fn, args = {}) {
-    const { apiKey, siteUrl } = getConfig();
-    const res = await fetch(`${siteUrl}/api/mcp`, {
-        method: 'POST',
-        headers: {
-            'Content-Type': 'application/json',
-            Authorization: `Bearer ${apiKey}`,
-        },
-        body: JSON.stringify({ fn, args }),
+import { resolveAdminConfig } from './adminConfig.js';
+import { readSession } from './session.js';
+import { CLIError, ErrorCode } from './errors.js';
+import { withSpinner } from './spinner.js';
+import { maybeRetry, shouldTouchSession } from './rate-limit.js';
+/**
+ * Map MCP server error codes to CLIError categories.
+ * Keeps backward compat: McpError.code is still a free string from the server,
+ * but category and guidance are derived for the global error handler.
+ */
+function mcpCodeToCategory(code) {
+    if (!code)
+        return 'internal';
+    if (code.startsWith('AUTH') || code === 'UNAUTHORIZED')
+        return 'auth';
+    if (code === 'VALIDATION_FAILED' ||
+        code === 'QUALITY_GATE_BLOCKED' ||
+        code === 'GROUNDING_GATE_BLOCKED' ||
+        code === 'SEMANTIC_QUALITY_GATE_BLOCKED' ||
+        // WP-485 Slice 2b (FEAT-1370): commitEntry's contradiction gate (dead-but-typed while
+        // DEC-1321 keeps `graduated: false` — see promote.ts's handling) throws this on block.
+        // A 400 the caller fixes by resolving the contradiction, not an internal fault.
+        code === 'CONTRADICTION_BLOCKED' ||
+        // WP-477 / FEAT-1350: both are 400s the caller fixes by changing an argument
+        // (pass the issued cursor verbatim / ask for a smaller numItems) — not internal faults.
+        code === 'CURSOR_QUERY_MISMATCH' ||
+        code === 'PAGE_SPLIT_REQUIRED' ||
+        // TEN-2647: Convex's own arg-validator rejection — a 400 the caller fixes by correcting
+        // the offending argument (missing/unknown/wrong-typed), not an internal fault.
+        code === 'ARGUMENT_VALIDATION_FAILED' ||
+        // WP-494 (TEN-2742): `pb feedback submit` refused because the workspace switched off
+        // agent-submitted feedback — a policy gate, not an internal fault (mirrors the
+        // GATE_BLOCKED family above).
+        code === 'AGENT_FEEDBACK_DISABLED')
+        return 'validation';
+    if (code === 'SESSION_REQUIRED')
+        return 'session';
+    // TEN-656: per-key API quota — a 429 the caller fixes by WAITING, not by changing the
+    // call. Categorized as network so the global handler renders it as retryable, never
+    // as an internal fault.
+    if (code === 'rate-limited')
+        return 'network';
+    return 'internal';
+}
+function normalizeMcpCode(code) {
+    // Convex names the internal protocol condition; the public CLI exposes its
+    // stable, harness-independent error taxonomy to people and agents.
+    // WP-584 S4 review round 1 (P2-3): the WHOLE AUTHZ_* family maps here, not just the one
+    // literal AUTHZ_PERMISSION_DENIED — a narrower match let AUTHZ_INSUFFICIENT_ROLE (BR-227's
+    // own code, convex/http.ts's vendor-gate 403) fall through the `as` cast below and publish
+    // Convex's raw internal code as if it were a real CLI ErrorCodeValue. Mirrors
+    // mcpCodeToCategory's own `code.startsWith('AUTH')` breadth, above.
+    if (code?.startsWith('AUTHZ_'))
+        return ErrorCode.AUTH_DENIED;
+    return code ?? ErrorCode.INTERNAL;
+}
+/** Error thrown by kernelCall/kernelCallWithSession when the server returns a non-OK response. */
+export class McpError extends CLIError {
+    details;
+    /** Present only when code === 'rate-limited' — seconds until the caller may retry. */
+    retryAfterSeconds;
+    constructor(message, code, details, retryAfterSeconds) {
+        super(message, {
+            code: normalizeMcpCode(code),
+            category: mcpCodeToCategory(code),
+            // TEN-656 / TEN-2655: the rate-limit refusal must be agent-legible — say exactly
+            // what to do (wait, then retry unchanged), because autonomous chained runs have
+            // no human to interpret a bare 429.
+            guidance: code === 'rate-limited'
+                ? 'This API key hit its request quota (HTTP 429). Wait the number of seconds in the message (also in the Retry-After header), then retry the same call unchanged — it is safe to retry.'
+                : undefined,
+        });
+        this.name = 'McpError';
+        this.details = details;
+        this.retryAfterSeconds = retryAfterSeconds;
+    }
+}
+// WP-579: the rate-limit retry and touch throttle live in rate-limit.ts — two
+// self-contained policies with their own state, kept out of this module's budget (STD-2).
+export { resetTouchThrottle } from './rate-limit.js';
+// Configure proxy at module load — runs once, before any fetch call.
+// Node.js fetch (undici) ignores HTTPS_PROXY env vars. We detect the proxy
+// and install a ProxyAgent as the global dispatcher so all fetch() calls
+// route through the sandbox proxy automatically.
+try {
+    const _proxy = process.env.https_proxy || process.env.HTTPS_PROXY;
+    if (_proxy) {
+        const { ProxyAgent, setGlobalDispatcher } = await import('undici');
+        setGlobalDispatcher(new ProxyAgent(_proxy));
+    }
+}
+catch {
+    // undici unavailable or proxy config failed — rethrowWithGuidance handles it.
+}
+/** Detect a sandbox/network-blocked fetch and re-throw with guidance. */
+function rethrowWithGuidance(err, siteUrl, 
+// WP-575: the route being called, the budget it was given, and the call's own args, so a
+// budget abort can be reported as itself rather than collapsing into "Could not reach
+// <host>" — and so a dry run is never told its write may have landed (see ./gatewayTimeout.ts).
+route) {
+    const msg = err instanceof Error ? err.message : String(err);
+    // WP-575: a budget abort is not an unreachable host — the connection succeeded, we stopped
+    // waiting, and for a write route the server may have finished. See ./gatewayTimeout.ts.
+    if (route && isTimeoutAbort(err))
+        throw gatewayTimeoutError(route.fn, route.budgetMs, route.args);
+    if (msg === 'fetch failed' || msg.includes('ECONNREFUSED') || msg.includes('ENOTFOUND')) {
+        const host = new URL(siteUrl).hostname;
+        const proxy = process.env.https_proxy || process.env.HTTPS_PROXY;
+        const proxyHint = proxy
+            ? `A proxy is configured (${proxy}) but Node.js fetch() is not using it.\n` +
+                `Fix: set NODE_OPTIONS="--use-env-proxy" in your environment,\n` +
+                `  or re-run with: NODE_OPTIONS="--use-env-proxy" pb <command>`
+            : `If you are running inside an AI code editor sandbox (Claude Code, Cursor, etc.),\n` +
+                `the sandbox may be blocking outbound connections.\n\n` +
+                `Fix: add "${host}" to your sandbox network allowlist.\n` +
+                `  - Claude Code: run /sandbox -> add network host\n` +
+                `  - Or re-run: pb handshake --init (configures sandbox automatically)`;
+        throw new CLIError(`Could not reach ${host}.`, {
+            code: ErrorCode.NETWORK_UNREACHABLE,
+            category: 'network',
+            guidance: proxyHint,
+        });
+    }
+    throw err;
+}
+/**
+ * Validate an API key against the server before saving it.
+ * Uses `resolveWorkspace` as a lightweight health check — if it returns data, the key works.
+ *
+ * Returns { valid: true, workspaceId } on success.
+ * Returns { valid: false, error } on auth failure (401) or other server error.
+ * Throws on network/timeout errors so the caller can distinguish "bad key" from "can't reach server".
+ *
+ * WP-575: `timeoutMs` now DEFAULTS to `resolveWorkspace`'s declared budget instead of a
+ * local `5000` literal — that literal was the last connector-owned timeout on the gateway
+ * path, and the point of this work package is that no connector gets to pick its own. It
+ * stays an explicit parameter so a caller (or a test) can still override deliberately.
+ * Widening 5s -> the declared 10s costs nothing in the case people actually hit: an
+ * unreachable host fails with ECONNREFUSED/ENOTFOUND immediately, not by timeout. The
+ * timeout only governs a server that ACCEPTS the connection then stalls, where waiting the
+ * route's real declared budget before calling the key invalid is the correct behavior.
+ */
+export async function validateKey(apiKey, siteUrl, timeoutMs = latencyBudgetMsForRoute('resolveWorkspace')) {
+    return withSpinner('Validating API key', async () => {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), timeoutMs);
+        try {
+            const res = await fetch(`${siteUrl}/api/aki`, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    Authorization: `Bearer ${apiKey}`,
+                },
+                body: JSON.stringify({ fn: 'resolveWorkspace', args: {} }),
+                signal: controller.signal,
+            });
+            clearTimeout(timer);
+            // Record header BEFORE the 401/403 short-circuit — auth-fail responses still carry the version skew signal.
+            recordLatestFromResponse(res);
+            if (res.status === 401 || res.status === 403) {
+                return { valid: false, error: 'Invalid API key.' };
+            }
+            const envelope = await parseKernelEnvelope(res);
+            if (!res.ok || envelope.ok === false) {
+                return { valid: false, error: envelope.message || envelope.error || `Server error (${res.status})` };
+            }
+            return { valid: true, workspaceId: envelope.data?._id ?? 'unknown' };
+        }
+        catch (err) {
+            clearTimeout(timer);
+            // Re-throw network/timeout errors — caller handles the "offline" case
+            throw err;
+        }
     });
-    const json = (await res.json());
-    if (!res.ok || json.error) {
-        throw new Error(json.error ?? res.statusText);
+}
+/**
+ * Map MCP function names to human-friendly spinner labels.
+ * Unknown functions get a generic fallback.
+ */
+const SPINNER_LABELS = {
+    orient: 'Loading workspace overview',
+    'entries.get': 'Loading entry',
+    'entries.search': 'Searching entries',
+    'entries.create': 'Creating entry',
+    'entries.update': 'Updating entry',
+    'capture-quick': 'Capturing to Chain',
+    'propose-capture': 'Preparing capture',
+    'commit-entry': 'Committing entry',
+    'agent.startSession': 'Starting session',
+    'agent.closeSession': 'Closing session',
+    'agent.touchSession': 'Refreshing session',
+    resolveWorkspace: 'Resolving workspace',
+    'onboarding.chat': 'Thinking',
+    context: 'Loading context',
+    'entries.relate': 'Creating relation',
+    'entries.unrelate': 'Removing relation',
+    constellation: 'Loading constellation',
+    'conflicts.list': 'Loading open conflicts',
+    'conflicts.resolve': 'Recording verdict',
+    'conflicts.summary': 'Loading precision summary',
+};
+/** Get a human-friendly spinner label for an MCP function name. */
+export function spinnerLabel(fn) {
+    return SPINNER_LABELS[fn] || `Loading ${fn.replace(/\./g, ' ')}`;
+}
+/**
+ * POST to the admin gateway (/api/admin) — separate from /api/aki (STD-101, BR-109).
+ * Admin operations are not knowledge operations — they target the operator surface.
+ *
+ * No built-in spinner: callers wrap with withSpinner when appropriate.
+ * Throws CLIError on auth failure or non-OK response.
+ */
+export async function adminCall(command, args) {
+    const { apiKey, siteUrl } = resolveAdminConfig();
+    // WP-575 deliberately leaves /api/admin UNBOUNDED (PR #533 review, Codex P2 — an earlier
+    // round bounded it and that was the regression). Admin commands are long-running BULK
+    // operations (`manage:delete-workspace` cascading 100-row batches, `seed:backfill-starter`
+    // across workspaces) and are NOT in the route registry, so the fail-safe "widest" fallback
+    // is a real number for a route the contract describes and a guess for one it doesn't —
+    // an arbitrary ceiling on a destructive operation that can abort it mid-flight, which is
+    // worse than the hang it would prevent. (That fallback is whatever
+    // WIDEST_ROUTE_LATENCY_BUDGET_MS happens to be — today 330_000, since it spans the override
+    // table too — which is the point: a number that MOVES when an unrelated route's override
+    // changes is not a budget for this surface.) It needs its own MEASURED budget: follow-up work.
+    let res;
+    try {
+        res = await fetch(`${siteUrl}/api/admin`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                Authorization: `Bearer ${apiKey}`,
+            },
+            body: JSON.stringify({ command, args }),
+        });
+    }
+    catch (err) {
+        rethrowWithGuidance(err, siteUrl);
+    }
+    const response = (await res.json().catch(() => ({})));
+    if (response.ok === false || (!res.ok && response.ok == null)) {
+        throw new McpError((response.message ?? response.error ?? res.statusText) || 'Admin request failed', response.code);
+    }
+    return response.data;
+}
+/**
+ * Connector identity for the gateway's context.served shared seam (DEC-1207). Sent as the
+ * `x-pb-source` header on gateway calls so the server-side emit can attribute this connector;
+ * the gateway defaults to `api` if it is ever absent.
+ */
+const PB_TELEMETRY_SOURCE = 'cli';
+export async function kernelCall(fn, args = {}, options) {
+    const { apiKey, siteUrl } = getConfig();
+    const label = spinnerLabel(fn);
+    const budgetMs = latencyBudgetMsForRoute(fn);
+    // Spinner OUTSIDE the retry: withSpinner reports a terminal `— failed` line on any throw,
+    // so a spinner per attempt would paint up to MAX_RATE_LIMIT_RETRIES false failures for a
+    // call that ultimately succeeds, then sit silent through each Retry-After wait.
+    return withSpinner(label, () => maybeRetry(async () => {
+        let res;
+        try {
+            res = await fetch(`${siteUrl}/api/aki`, {
+                method: 'POST',
+                signal: AbortSignal.timeout(budgetMs),
+                headers: {
+                    'Content-Type': 'application/json',
+                    Authorization: `Bearer ${apiKey}`,
+                    // DEC-1207: attribute this connector for the gateway's context.served seam.
+                    'x-pb-source': PB_TELEMETRY_SOURCE,
+                },
+                body: JSON.stringify({ fn, args }),
+            });
+        }
+        catch (err) {
+            rethrowWithGuidance(err, siteUrl, { fn, budgetMs, args });
+        }
+        const envelope = await parseKernelEnvelope(res, { fn, budgetMs, args });
+        if (!res.ok || envelope.ok === false) {
+            throw new McpError(envelope.message || envelope.error || res.statusText, envelope.code, envelope.details, envelope.retryAfterSeconds);
+        }
+        return envelope.data;
+    }, options));
+}
+/**
+ * kernelCall variant that returns the full kernel envelope (data + summary + _meta) instead
+ * of stripping to just `data` — mirrors packages/mcp-server/src/client.ts's
+ * `kernelCallEnvelope`. Use when a caller needs `_meta` (e.g. a route-specific additive
+ * flag like chain.shapeAdvisories' `truncated`, WP-571 sweep) without changing `data`'s own
+ * shape — the reason `_meta` exists as a side-channel at all (convex/lib/envelopeContract.ts).
+ */
+export async function kernelCallEnvelope(fn, args = {}, options) {
+    const { apiKey, siteUrl } = getConfig();
+    const label = spinnerLabel(fn);
+    const budgetMs = latencyBudgetMsForRoute(fn);
+    return withSpinner(label, () => maybeRetry(async () => {
+        let res;
+        try {
+            res = await fetch(`${siteUrl}/api/aki`, {
+                method: 'POST',
+                signal: AbortSignal.timeout(budgetMs),
+                headers: {
+                    'Content-Type': 'application/json',
+                    Authorization: `Bearer ${apiKey}`,
+                    'x-pb-source': PB_TELEMETRY_SOURCE,
+                },
+                body: JSON.stringify({ fn, args }),
+            });
+        }
+        catch (err) {
+            rethrowWithGuidance(err, siteUrl, { fn, budgetMs, args });
+        }
+        const envelope = await parseKernelEnvelope(res, { fn, budgetMs, args });
+        if (!res.ok || envelope.ok === false) {
+            throw new McpError(envelope.message || envelope.error || res.statusText, envelope.code, envelope.details, envelope.retryAfterSeconds);
+        }
+        return { data: envelope.data, summary: envelope.summary, _meta: envelope._meta };
+    }, options));
+}
+/**
+ * Raw fetch to the gateway — no spinner, swallows errors.
+ * Used for fire-and-forget operations (e.g. session touch) where visible feedback is noise.
+ */
+async function mcpFetchRaw(fn, args, apiKey, siteUrl) {
+    try {
+        await fetch(`${siteUrl}/api/aki`, {
+            method: 'POST',
+            // WP-575: fire-and-forget still gets the declared budget. Errors are swallowed either
+            // way, so this is not about the message — it is about not leaving a socket and a
+            // pending promise open indefinitely on a stuck backend behind an already-returned
+            // command. "Best-effort" was never meant to mean "unbounded".
+            signal: AbortSignal.timeout(latencyBudgetMsForRoute(fn)),
+            headers: {
+                'Content-Type': 'application/json',
+                Authorization: `Bearer ${apiKey}`,
+            },
+            body: JSON.stringify({ fn, args }),
+        });
+    }
+    catch {
+        // Best-effort — silently swallow all errors
+    }
+}
+/**
+ * kernelCall variant for write operations. Callers that need server-side session
+ * validation (e.g. `chain.verifyEntry`) pass `sessionId` in `args` explicitly —
+ * it now travels in the request body, not a header (http.ts never read the old
+ * `X-Agent-Session-Id` header).
+ * All write commands (update, relate, unrelate, capture) should use this.
+ *
+ * After a successful write, fires a non-blocking `agent.touchSession` call to
+ * renew the session TTL — mirroring MCP server behavior (DEC-299, BET-181 Slice 1).
+ * The touch is fire-and-forget: it does not block the write response, and errors
+ * are silently swallowed. No touch is attempted if no session is active or if
+ * the write itself fails.
+ */
+export async function kernelCallWithSession(fn, args = {}, options) {
+    const { apiKey, siteUrl } = getConfig();
+    const session = readSession();
+    const label = spinnerLabel(fn);
+    const headers = {
+        'Content-Type': 'application/json',
+        Authorization: `Bearer ${apiKey}`,
+        // DEC-1207: attribute this connector for the gateway's context.served seam.
+        'x-pb-source': PB_TELEMETRY_SOURCE,
+    };
+    // WP-575 + WP-579 compose deliberately: the budget is derived ONCE per route, but the
+    // AbortSignal is created inside the retried callback, so each 429 retry attempt gets its
+    // own full budget rather than sharing one deadline across all attempts.
+    const budgetMs = latencyBudgetMsForRoute(fn);
+    const result = await withSpinner(label, () => maybeRetry(async () => {
+        let res;
+        try {
+            res = await fetch(`${siteUrl}/api/aki`, {
+                method: 'POST',
+                signal: AbortSignal.timeout(budgetMs),
+                headers,
+                body: JSON.stringify({ fn, args }),
+            });
+        }
+        catch (err) {
+            rethrowWithGuidance(err, siteUrl, { fn, budgetMs, args });
+        }
+        const envelope = await parseKernelEnvelope(res, { fn, budgetMs, args });
+        if (!res.ok || envelope.ok === false) {
+            throw new McpError(envelope.message || envelope.error || res.statusText, envelope.code, envelope.details, envelope.retryAfterSeconds);
+        }
+        return envelope.data;
+    }, options));
+    // Fire-and-forget session touch — best-effort, never blocks the write response.
+    // Uses mcpFetchRaw (not kernelCall) to avoid recursion and suppress the visible spinner
+    // that would appear if kernelCall were used here (background ops are silent noise).
+    // TEN-2923: throttled to match the server's own no-op window (shouldTouchSession) — a
+    // touch inside that window would just burn quota on a call the server already discards.
+    // WP-688 S2a review fix (thread bb1oj): `skipSessionTouch` opts a --dry-run-style caller
+    // out entirely — the door itself may not write, but this touch is a REAL session-row
+    // patch, and "no write" must mean none, not "none except telemetry".
+    if (!options?.skipSessionTouch && session?.sessionId && shouldTouchSession(session.sessionId)) {
+        void mcpFetchRaw('agent.touchSession', { sessionId: session.sessionId }, apiKey, siteUrl);
     }
-    return json.data;
+    return result;
 }
 //# sourceMappingURL=client.js.map

package/dist/lib/client.js.map

@@ -1 +1 @@
-{"version":3,"file":"client.js","sourceRoot":"","sources":["../../src/lib/client.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAExC,MAAM,CAAC,KAAK,UAAU,OAAO,CAC3B,EAAU,EACV,OAAgC,EAAE;IAElC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,SAAS,EAAE,CAAC;IAExC,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,GAAG,OAAO,UAAU,EAAE;QAC5C,MAAM,EAAE,MAAM;QACd,OAAO,EAAE;YACP,cAAc,EAAE,kBAAkB;YAClC,aAAa,EAAE,UAAU,MAAM,EAAE;SAClC;QACD,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC;KACnC,CAAC,CAAC;IAEH,MAAM,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAAiC,CAAC;IAChE,IAAI,CAAC,GAAG,CAAC,EAAE,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;QAC1B,MAAM,IAAI,KAAK,CAAC,IAAI,CAAC,KAAK,IAAI,GAAG,CAAC,UAAU,CAAC,CAAC;IAChD,CAAC;IACD,OAAO,IAAI,CAAC,IAAS,CAAC;AACxB,CAAC"}
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../../src/lib/client.ts"],"names":[],"mappings":"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"}

package/dist/lib/collectionRegistry.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Runtime collection registry — fetches from chain.listCollections via kernelCall
+ * and memoizes per process invocation (module-scope singleton).
+ *
+ * Fails open to a build-time SEED snapshot (mirrors PREFIX_TO_COLLECTION in
+ * capture.ts) so CLI commands continue to work even when the backend is
+ * unreachable or chain.listCollections is unavailable.
+ *
+ * FEAT-885 / TEN-1406: Replaces hardcoded PREFIX_TO_COLLECTION + datedCollections
+ * constants with runtime-derived data.  BR-108: CLI cannot import from convex/,
+ * so registry uses kernelCall (HTTP gateway).
+ */
+export interface CollectionMeta {
+    slug: string;
+    idPrefix?: string;
+    classificationCheck?: string;
+    classificationSignals?: string[];
+    navGroup?: string;
+    governed?: boolean;
+    governanceFunction?: string;
+}
+/**
+ * SEED — the OFFLINE FAIL-OPEN FALLBACK only (WP-480 S2, TEN-2219).
+ * The online path derives from `chain.listCollections` (getCollections below);
+ * this snapshot exists solely so CLI commands keep working when the backend is
+ * unreachable. It therefore only needs day-zero accuracy, and is content-pinned
+ * against the canonical day-zero seed truth —
+ * `convex/lib/seedClassificationRegistry.ts` on the {slug, idPrefix} projection
+ * (see src/__tests__/collection-registry-seed-drift.test.ts). Two carve-outs
+ * have no canonical counterpart and are excluded from the pin:
+ *   - `work-packages → BET` (BET-230 rename backward compat; canonical maps only WP).
+ *   - `objectives → KEY` (P1 review PRRT_kwDORS4ils6cUz6M, WP-686 S6): the canonical
+ *     registry flipped `objectives`'s idPrefix from KEY to OBJ in place (S5, TASK-91)
+ *     rather than adding a parallel row, so there is no canonical KEY entry to pin
+ *     against — but a version-skewed CLI running OFFLINE (this SEED's only use case)
+ *     against a workspace whose live `collections.idPrefix` is still KEY (prod's own
+ *     id-rewrite is a deferred, founder-run operation per
+ *     docs/migration-deferrals/wp686_key_to_obj_prefix_rewrite.md — it has not
+ *     necessarily run yet) still needs `pb capture "KEY: ..."` to route to
+ *     `objectives`, same reasoning as the BET alias above.
+ */
+export declare const SEED: CollectionMeta[];
+/**
+ * Fetch all collections for the current workspace.
+ * Module-scope memoized — calls kernelCall once per process, then returns
+ * the cached result.  Fails open to SEED on any error.
+ */
+export declare function getCollections(): Promise<CollectionMeta[]>;
+/**
+ * Build a prefix → collection slug map from the runtime registry.
+ * Falls back to SEED-derived map on failure.
+ */
+export declare function getPrefixToCollection(): Promise<Record<string, string>>;
+/**
+ * Returns slugs of collections that accept a date field during capture.
+ * Derived from classificationCheck presence when available (a non-empty
+ * classificationCheck indicates the collection is content-dated).
+ * Falls back to a hardcoded seed set when field metadata is absent.
+ */
+export declare function getDatedCollections(): Promise<Set<string>>;
+//# sourceMappingURL=collectionRegistry.d.ts.map

package/dist/lib/collectionRegistry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"collectionRegistry.d.ts","sourceRoot":"","sources":["../../src/lib/collectionRegistry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAIH,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,qBAAqB,CAAC,EAAE,MAAM,EAAE,CAAC;IACjC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,IAAI,EAAE,cAAc,EAiChC,CAAC;AAgBF;;;;GAIG;AACH,wBAAsB,cAAc,IAAI,OAAO,CAAC,cAAc,EAAE,CAAC,CAiBhE;AAED;;;GAGG;AACH,wBAAsB,qBAAqB,IAAI,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAO7E;AAED;;;;;GAKG;AACH,wBAAsB,mBAAmB,IAAI,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAWhE"}