@productbrain/cli 0.1.0-beta.14 → 0.1.0-beta.14010

package/dist/lib/errors.d.ts

@@ -0,0 +1,153 @@
+/**
+ * CLIError — structured error taxonomy for the Product Brain CLI.
+ *
+ * WP-302 Slice 0: Error Taxonomy + Commander Migration.
+ * WP-302 Slice 2: Profile error codes added.
+ * Every CLI error carries a machine-readable code, category, and actionable guidance.
+ * The global error handler in index.ts formats these for JSON or human output.
+ */
+/** Error categories — groups of related failure modes. */
+export type ErrorCategory = 'auth' | 'network' | 'config' | 'validation' | 'session' | 'profile' | 'internal';
+/** Known error codes — extend as new failure modes are discovered. */
+export declare const ErrorCode: {
+    readonly AUTH_MISSING: "AUTH_MISSING";
+    readonly AUTH_INVALID: "AUTH_INVALID";
+    readonly AUTH_DENIED: "AUTH_DENIED";
+    readonly NETWORK_UNREACHABLE: "NETWORK_UNREACHABLE";
+    readonly NETWORK_TIMEOUT: "NETWORK_TIMEOUT";
+    readonly CONFIG_MISSING: "CONFIG_MISSING";
+    readonly CONFIG_INVALID: "CONFIG_INVALID";
+    readonly SESSION_REQUIRED: "SESSION_REQUIRED";
+    /** Session close blocked: drafts not yet accepted remain (TEN-2370). Non-zero exit unless --force. */
+    readonly LOOP_UNFINISHED: "LOOP_UNFINISHED";
+    readonly SESSION_ORPHANED: "SESSION_ORPHANED";
+    readonly SESSION_EXPIRED: "SESSION_EXPIRED";
+    readonly SESSION_CLOSED: "SESSION_CLOSED";
+    /** A write that needs orientation, sent before `pb orient --task`. */
+    readonly ORIENTATION_REQUIRED: "ORIENTATION_REQUIRED";
+    readonly VALIDATION_FAILED: "VALIDATION_FAILED";
+    /** The referenced resource does not exist — mirrors convex/lib/errors.ts's ErrorCodes.NOT_FOUND (WP-753 V2, TASK-203 round 3 NIT). */
+    readonly NOT_FOUND: "NOT_FOUND";
+    /** Kernel / MCP quality gate (e.g. verify-before-commit). */
+    readonly QUALITY_GATE_BLOCKED: "QUALITY_GATE_BLOCKED";
+    /**
+     * Grounding gate refused a draft→active promotion (WP-455 E3 / WP-475 E2):
+     * verify the entry (pb verify <ID>); there is no override (TASK-617).
+     */
+    readonly GROUNDING_GATE_BLOCKED: "GROUNDING_GATE_BLOCKED";
+    /**
+     * Semantic quality gate refused a draft→active promotion on a gated
+     * collection (WP-475 E4 / DEC-1345): fix each unchecked line of the returned checklist
+     * (TASK-590) — or, when the verdict was missing/stale,
+     * retry once the scheduled fresh judgment lands. No override route.
+     */
+    readonly SEMANTIC_QUALITY_GATE_BLOCKED: "SEMANTIC_QUALITY_GATE_BLOCKED";
+    /**
+     * Strategy-singleton cardinality guard refused a draft→active promotion (WP-586 D1): the
+     * workspace already has a live strategy row and this collection allows only one. TASK-273
+     * (C1c, thread 5): newly reachable as a THROWN code — acceptEntryCore's own soft-return
+     * refusal (agentKnowledge/entries.ts / chainCore.ts's commit-then-accept doors) is now
+     * translated to this canonical code instead of a generic VALIDATION_FAILED, so the E2 lesson
+     * (an unregistered code surfaces as an opaque 500) doesn't repeat for a third gate.
+     */
+    readonly STRATEGY_SINGLETON_BLOCKED: "STRATEGY_SINGLETON_BLOCKED";
+    /**
+     * A `paginationOpts.cursor` was not issued by that exact query — undecodable, or minted for a
+     * different query shape. Pass the previous page's `continueCursor` back verbatim, or `null`
+     * to restart. Never silently reset: a reset re-walks rows already handled.
+     */
+    readonly CURSOR_QUERY_MISMATCH: "CURSOR_QUERY_MISMATCH";
+    /**
+     * Convex could not return a complete page even after a bounded halve-and-retry
+     * (dormant server-side since TEN-2877). Retry with a smaller
+     * `paginationOpts.numItems`. Never downgraded to a silent short page — resuming from an
+     * incomplete page's cursor would SKIP rows.
+     */
+    readonly PAGE_SPLIT_REQUIRED: "PAGE_SPLIT_REQUIRED";
+    /**
+     * Convex's OWN argument validator rejected the call shape — a required arg missing,
+     * an unknown extra arg, or a wrong-typed arg (TEN-2647). Fix the offending argument
+     * named in the message; never retry an unchanged call. A 400, not an internal fault.
+     * Mirror of convex/lib/errors.ts ErrorCodes.ARGUMENT_VALIDATION_FAILED.
+     */
+    readonly ARGUMENT_VALIDATION_FAILED: "ARGUMENT_VALIDATION_FAILED";
+    /**
+     * Agent-submitted product feedback is switched off for this workspace
+     * (WP-494 / TEN-2742): `pb feedback submit` hits this when
+     * `productFeedbackPolicy.agentSubmissions` is off. Not a bug — an admin or
+     * owner disabled it; the message names the setting and the re-enable path.
+     * Mirror of convex/lib/errors.ts ErrorCodes.AGENT_FEEDBACK_DISABLED.
+     */
+    readonly AGENT_FEEDBACK_DISABLED: "AGENT_FEEDBACK_DISABLED";
+    /**
+     * Per-key API quota exceeded (TEN-656). Mirror of convex/lib/errors.ts
+     * ErrorCodes.RATE_LIMITED. Retryable — the caller waits `retryAfterSeconds`
+     * (on McpError) then retries the same call unchanged.
+     */
+    readonly RATE_LIMITED: "rate-limited";
+    readonly PROFILE_NOT_FOUND: "PROFILE_NOT_FOUND";
+    readonly PROFILE_ALREADY_EXISTS: "PROFILE_ALREADY_EXISTS";
+    readonly PROFILE_IS_ACTIVE: "PROFILE_IS_ACTIVE";
+    readonly PROFILE_IS_LAST: "PROFILE_IS_LAST";
+    readonly PROFILE_NAME_INVALID: "PROFILE_NAME_INVALID";
+    /**
+     * `PB_PROFILE` names a profile that already exists, so `pb connect` would overwrite another
+     * key (TEN-2851, TASK-638). Refused before the token is redeemed; the escape hatch is a free
+     * name or no PB_PROFILE at all.
+     */
+    readonly PROFILE_CREDENTIALS_CONFLICT: "PROFILE_CREDENTIALS_CONFLICT";
+    readonly NO_ROLE: "no_role";
+    readonly MULTI_ROLE: "multi_role";
+    readonly ROLE_NOT_OWNER: "role_not_owner";
+    readonly ROLE_SWITCH_REFUSED: "role_switch_refused";
+    readonly NON_INTERACTIVE: "NON_INTERACTIVE";
+    readonly UPGRADE_FAILED: "UPGRADE_FAILED";
+    readonly INTERNAL: "INTERNAL";
+};
+export type ErrorCodeValue = (typeof ErrorCode)[keyof typeof ErrorCode];
+export declare const isEndedSessionCode: (code?: string) => boolean;
+/**
+ * Structured CLI error with machine-readable fields.
+ *
+ * Usage:
+ *   throw new CLIError('No API key configured', {
+ *     code: ErrorCode.AUTH_MISSING,
+ *     category: 'auth',
+ *     guidance: 'Run `pb login` to configure your API key.',
+ *   });
+ */
+export declare class CLIError extends Error {
+    readonly code: ErrorCodeValue;
+    readonly category: ErrorCategory;
+    readonly guidance?: string;
+    /** An authority refusal's structured guidance (who decides), in the JSON error output. */
+    readonly authority?: {
+        requiredAction?: string;
+        routeTarget?: unknown;
+    };
+    /** TASK-1408 (DEC-2495): a seat route timed out, so the seat may be open; the session-start hook reads it. */
+    readonly seatMayBeOpen?: true;
+    constructor(message: string, options?: {
+        code?: ErrorCodeValue;
+        category?: ErrorCategory;
+        guidance?: string;
+        authority?: {
+            requiredAction?: string;
+            routeTarget?: unknown;
+        };
+        seatMayBeOpen?: true;
+    });
+    /** Serialize for JSON error output. */
+    toJSON(): {
+        error: string;
+        code: string;
+        category: string;
+        guidance?: string;
+        authority?: {
+            requiredAction?: string;
+            routeTarget?: unknown;
+        };
+        seatMayBeOpen?: true;
+    };
+}
+//# sourceMappingURL=errors.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/lib/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,0DAA0D;AAC1D,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,SAAS,GAAG,QAAQ,GAAG,YAAY,GAAG,SAAS,GAAG,SAAS,GAAG,UAAU,CAAC;AAE9G,sEAAsE;AACtE,eAAO,MAAM,SAAS;;;;;;;;;IAapB,sGAAsG;;;;;IAMtG,sEAAsE;;;IAItE,sIAAsI;;IAEtI,6DAA6D;;IAE7D;;;OAGG;;IAEH;;;;;OAKG;;IAEH;;;;;;;OAOG;;IAEH;;;;OAIG;;IAEH;;;;;OAKG;;IAEH;;;;;OAKG;;IAEH;;;;;;OAMG;;IAEH;;;;OAIG;;;;;;;IAQH;;;;OAIG;;;;;;;;;CAaK,CAAC;AAEX,MAAM,MAAM,cAAc,GAAG,CAAC,OAAO,SAAS,CAAC,CAAC,MAAM,OAAO,SAAS,CAAC,CAAC;AAIxE,eAAO,MAAM,kBAAkB,GAAI,OAAO,MAAM,KAAG,OAA8D,CAAC;AAElH;;;;;;;;;GASG;AACH,qBAAa,QAAS,SAAQ,KAAK;IACjC,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC;IAC9B,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC;IACjC,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,0FAA0F;IAC1F,QAAQ,CAAC,SAAS,CAAC,EAAE;QAAE,cAAc,CAAC,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC;IACxE,8GAA8G;IAC9G,QAAQ,CAAC,aAAa,CAAC,EAAE,IAAI,CAAC;gBAG5B,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE;QACR,IAAI,CAAC,EAAE,cAAc,CAAC;QACtB,QAAQ,CAAC,EAAE,aAAa,CAAC;QACzB,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,SAAS,CAAC,EAAE;YAAE,cAAc,CAAC,EAAE,MAAM,CAAC;YAAC,WAAW,CAAC,EAAE,OAAO,CAAA;SAAE,CAAC;QAC/D,aAAa,CAAC,EAAE,IAAI,CAAC;KACtB;IAWH,uCAAuC;IACvC,MAAM,IAAI;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE;YAAE,cAAc,CAAC,EAAE,MAAM,CAAC;YAAC,WAAW,CAAC,EAAE,OAAO,CAAA;SAAE,CAAC;QAAC,aAAa,CAAC,EAAE,IAAI,CAAA;KAAE;CAUrK"}

package/dist/lib/errors.js

@@ -0,0 +1,158 @@
+/**
+ * CLIError — structured error taxonomy for the Product Brain CLI.
+ *
+ * WP-302 Slice 0: Error Taxonomy + Commander Migration.
+ * WP-302 Slice 2: Profile error codes added.
+ * Every CLI error carries a machine-readable code, category, and actionable guidance.
+ * The global error handler in index.ts formats these for JSON or human output.
+ */
+/** Known error codes — extend as new failure modes are discovered. */
+export const ErrorCode = {
+    // Auth
+    AUTH_MISSING: 'AUTH_MISSING',
+    AUTH_INVALID: 'AUTH_INVALID',
+    AUTH_DENIED: 'AUTH_DENIED',
+    // Network
+    NETWORK_UNREACHABLE: 'NETWORK_UNREACHABLE',
+    NETWORK_TIMEOUT: 'NETWORK_TIMEOUT',
+    // Config
+    CONFIG_MISSING: 'CONFIG_MISSING',
+    CONFIG_INVALID: 'CONFIG_INVALID',
+    // Session
+    SESSION_REQUIRED: 'SESSION_REQUIRED',
+    /** Session close blocked: drafts not yet accepted remain (TEN-2370). Non-zero exit unless --force. */
+    LOOP_UNFINISHED: 'LOOP_UNFINISHED',
+    // The session door's codes (kernel/sessions/sessionState.ts), each checked against the kernel's so a rename fails typecheck.
+    SESSION_ORPHANED: 'SESSION_ORPHANED',
+    SESSION_EXPIRED: 'SESSION_EXPIRED',
+    SESSION_CLOSED: 'SESSION_CLOSED',
+    /** A write that needs orientation, sent before `pb orient --task`. */
+    ORIENTATION_REQUIRED: 'ORIENTATION_REQUIRED',
+    // Validation
+    VALIDATION_FAILED: 'VALIDATION_FAILED',
+    /** The referenced resource does not exist — mirrors convex/lib/errors.ts's ErrorCodes.NOT_FOUND (WP-753 V2, TASK-203 round 3 NIT). */
+    NOT_FOUND: 'NOT_FOUND',
+    /** Kernel / MCP quality gate (e.g. verify-before-commit). */
+    QUALITY_GATE_BLOCKED: 'QUALITY_GATE_BLOCKED',
+    /**
+     * Grounding gate refused a draft→active promotion (WP-455 E3 / WP-475 E2):
+     * verify the entry (pb verify <ID>); there is no override (TASK-617).
+     */
+    GROUNDING_GATE_BLOCKED: 'GROUNDING_GATE_BLOCKED',
+    /**
+     * Semantic quality gate refused a draft→active promotion on a gated
+     * collection (WP-475 E4 / DEC-1345): fix each unchecked line of the returned checklist
+     * (TASK-590) — or, when the verdict was missing/stale,
+     * retry once the scheduled fresh judgment lands. No override route.
+     */
+    SEMANTIC_QUALITY_GATE_BLOCKED: 'SEMANTIC_QUALITY_GATE_BLOCKED',
+    /**
+     * Strategy-singleton cardinality guard refused a draft→active promotion (WP-586 D1): the
+     * workspace already has a live strategy row and this collection allows only one. TASK-273
+     * (C1c, thread 5): newly reachable as a THROWN code — acceptEntryCore's own soft-return
+     * refusal (agentKnowledge/entries.ts / chainCore.ts's commit-then-accept doors) is now
+     * translated to this canonical code instead of a generic VALIDATION_FAILED, so the E2 lesson
+     * (an unregistered code surfaces as an opaque 500) doesn't repeat for a third gate.
+     */
+    STRATEGY_SINGLETON_BLOCKED: 'STRATEGY_SINGLETON_BLOCKED',
+    /**
+     * A `paginationOpts.cursor` was not issued by that exact query — undecodable, or minted for a
+     * different query shape. Pass the previous page's `continueCursor` back verbatim, or `null`
+     * to restart. Never silently reset: a reset re-walks rows already handled.
+     */
+    CURSOR_QUERY_MISMATCH: 'CURSOR_QUERY_MISMATCH',
+    /**
+     * Convex could not return a complete page even after a bounded halve-and-retry
+     * (dormant server-side since TEN-2877). Retry with a smaller
+     * `paginationOpts.numItems`. Never downgraded to a silent short page — resuming from an
+     * incomplete page's cursor would SKIP rows.
+     */
+    PAGE_SPLIT_REQUIRED: 'PAGE_SPLIT_REQUIRED',
+    /**
+     * Convex's OWN argument validator rejected the call shape — a required arg missing,
+     * an unknown extra arg, or a wrong-typed arg (TEN-2647). Fix the offending argument
+     * named in the message; never retry an unchanged call. A 400, not an internal fault.
+     * Mirror of convex/lib/errors.ts ErrorCodes.ARGUMENT_VALIDATION_FAILED.
+     */
+    ARGUMENT_VALIDATION_FAILED: 'ARGUMENT_VALIDATION_FAILED',
+    /**
+     * Agent-submitted product feedback is switched off for this workspace
+     * (WP-494 / TEN-2742): `pb feedback submit` hits this when
+     * `productFeedbackPolicy.agentSubmissions` is off. Not a bug — an admin or
+     * owner disabled it; the message names the setting and the re-enable path.
+     * Mirror of convex/lib/errors.ts ErrorCodes.AGENT_FEEDBACK_DISABLED.
+     */
+    AGENT_FEEDBACK_DISABLED: 'AGENT_FEEDBACK_DISABLED',
+    /**
+     * Per-key API quota exceeded (TEN-656). Mirror of convex/lib/errors.ts
+     * ErrorCodes.RATE_LIMITED. Retryable — the caller waits `retryAfterSeconds`
+     * (on McpError) then retries the same call unchanged.
+     */
+    RATE_LIMITED: 'rate-limited',
+    // Profile (WP-302 S2)
+    PROFILE_NOT_FOUND: 'PROFILE_NOT_FOUND',
+    PROFILE_ALREADY_EXISTS: 'PROFILE_ALREADY_EXISTS',
+    PROFILE_IS_ACTIVE: 'PROFILE_IS_ACTIVE',
+    PROFILE_IS_LAST: 'PROFILE_IS_LAST',
+    PROFILE_NAME_INVALID: 'PROFILE_NAME_INVALID',
+    /**
+     * `PB_PROFILE` names a profile that already exists, so `pb connect` would overwrite another
+     * key (TEN-2851, TASK-638). Refused before the token is redeemed; the escape hatch is a free
+     * name or no PB_PROFILE at all.
+     */
+    PROFILE_CREDENTIALS_CONFLICT: 'PROFILE_CREDENTIALS_CONFLICT',
+    // Acting-role refusals the kernel sends at session start (convex/governance/actingRole.ts,
+    // convex/intelligence/startSessionCore.ts), forwarded with their code (TASK-639).
+    NO_ROLE: 'no_role',
+    MULTI_ROLE: 'multi_role',
+    ROLE_NOT_OWNER: 'role_not_owner',
+    ROLE_SWITCH_REFUSED: 'role_switch_refused',
+    // Interactive
+    NON_INTERACTIVE: 'NON_INTERACTIVE',
+    // Internal
+    UPGRADE_FAILED: 'UPGRADE_FAILED',
+    INTERNAL: 'INTERNAL',
+};
+/** The codes for a session that has ended: the marker that names it is closed, so the next `pb session start` resumes linked. */
+const ENDED_SESSION_CODES = new Set([ErrorCode.SESSION_ORPHANED, ErrorCode.SESSION_EXPIRED, ErrorCode.SESSION_CLOSED]);
+export const isEndedSessionCode = (code) => code !== undefined && ENDED_SESSION_CODES.has(code);
+/**
+ * Structured CLI error with machine-readable fields.
+ *
+ * Usage:
+ *   throw new CLIError('No API key configured', {
+ *     code: ErrorCode.AUTH_MISSING,
+ *     category: 'auth',
+ *     guidance: 'Run `pb login` to configure your API key.',
+ *   });
+ */
+export class CLIError extends Error {
+    code;
+    category;
+    guidance;
+    /** An authority refusal's structured guidance (who decides), in the JSON error output. */
+    authority;
+    /** TASK-1408 (DEC-2495): a seat route timed out, so the seat may be open; the session-start hook reads it. */
+    seatMayBeOpen;
+    constructor(message, options) {
+        super(message);
+        this.name = 'CLIError';
+        this.code = options?.code ?? ErrorCode.INTERNAL;
+        this.category = options?.category ?? 'internal';
+        this.guidance = options?.guidance;
+        this.authority = options?.authority;
+        this.seatMayBeOpen = options?.seatMayBeOpen;
+    }
+    /** Serialize for JSON error output. */
+    toJSON() {
+        return {
+            error: this.message,
+            code: this.code,
+            category: this.category,
+            ...(this.guidance ? { guidance: this.guidance } : {}),
+            ...(this.authority ? { authority: this.authority } : {}),
+            ...(this.seatMayBeOpen ? { seatMayBeOpen: true } : {}),
+        };
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/lib/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/lib/errors.ts"],"names":[],"mappings":"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"}

package/dist/lib/format.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Shared formatting utilities for the CLI.
+ * Single source of truth for display helpers used across commands.
+ */
+/**
+ * Format an ISO timestamp into a human-friendly elapsed string.
+ * e.g. "just now", "5m ago", "3h ago", "2d ago"
+ */
+export declare function formatElapsed(isoDate: string): string;
+//# sourceMappingURL=format.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"format.d.ts","sourceRoot":"","sources":["../../src/lib/format.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;GAGG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAarD"}

package/dist/lib/format.js

@@ -0,0 +1,27 @@
+/**
+ * Shared formatting utilities for the CLI.
+ * Single source of truth for display helpers used across commands.
+ */
+/**
+ * Format an ISO timestamp into a human-friendly elapsed string.
+ * e.g. "just now", "5m ago", "3h ago", "2d ago"
+ */
+export function formatElapsed(isoDate) {
+    try {
+        const ms = Date.now() - new Date(isoDate).getTime();
+        const minutes = Math.floor(ms / 60000);
+        if (minutes < 1)
+            return 'just now';
+        if (minutes < 60)
+            return `${minutes}m ago`;
+        const hours = Math.floor(minutes / 60);
+        if (hours < 24)
+            return `${hours}h ago`;
+        const days = Math.floor(hours / 24);
+        return `${days}d ago`;
+    }
+    catch {
+        return 'unknown';
+    }
+}
+//# sourceMappingURL=format.js.map

package/dist/lib/format.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"format.js","sourceRoot":"","sources":["../../src/lib/format.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;GAGG;AACH,MAAM,UAAU,aAAa,CAAC,OAAe;IAC3C,IAAI,CAAC;QACH,MAAM,EAAE,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,IAAI,CAAC,OAAO,CAAC,CAAC,OAAO,EAAE,CAAC;QACpD,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,EAAE,GAAG,KAAK,CAAC,CAAC;QACvC,IAAI,OAAO,GAAG,CAAC;YAAE,OAAO,UAAU,CAAC;QACnC,IAAI,OAAO,GAAG,EAAE;YAAE,OAAO,GAAG,OAAO,OAAO,CAAC;QAC3C,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,GAAG,EAAE,CAAC,CAAC;QACvC,IAAI,KAAK,GAAG,EAAE;YAAE,OAAO,GAAG,KAAK,OAAO,CAAC;QACvC,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,GAAG,EAAE,CAAC,CAAC;QACpC,OAAO,GAAG,IAAI,OAAO,CAAC;IACxB,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC"}

package/dist/lib/gatewayTimeout.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Gateway latency-budget aborts on the CLI — WP-575 (TEN-2917, TEN-1126).
+ *
+ * Before this, `./client.ts` set NO timeout on any gateway call: the same missing-declaration
+ * defect as MCP's blanket 10s constant, in the opposite direction (hang forever instead of
+ * give up too early). Both now derive their budget from the route contract; this module owns
+ * what to SAY when one is hit.
+ *
+ * Split out of client.ts at the 500-LOC ratchet's insistence (STD-2 / DEC-1504), and the
+ * ratchet read it correctly: "how do we explain a timeout, and is it safe to retry" is a
+ * decision with its own reason to change, separate from how a request is sent.
+ *
+ * The budget itself is DECLARED once at the route contract
+ * (packages/kernel-client/src/routeLatencyBudget.ts) and reaches this connector as a
+ * drift-checked generated copy. A runtime value import from @productbrain/kernel-client is
+ * impossible here — it is a devDependency and this package is PUBLISHED, so the specifier
+ * would be unresolvable in dist/ for every installed user.
+ */
+import { CLIError } from './errors.js';
+/**
+ * Does this route mutate state?
+ *
+ * Read off the route contract's own Convex function type — `mutation` and `action` can write,
+ * `query` cannot — never inferred from the route's NAME. This decides whether the user is told
+ * a timed-out call may have landed, so an UNKNOWN route fails safe to `true`: telling someone
+ * "nothing was written" when something was is the worse error, and it is the one that invites
+ * a duplicating retry.
+ */
+export declare function routeMayMutate(fn: string): boolean;
+/**
+ * Was this call a DRY RUN? (PR #533 review, Codex P2)
+ *
+ * `preview: true` is a gateway-wide contract meaning "run every validation, write nothing" —
+ * every registered route accepting it returns before its first write (the routes are
+ * enumerated with line citations in the mcp-server twin of this function,
+ * packages/mcp-server/src/gatewaySeam.ts).
+ *
+ * MIRRORED, NOT SHARED, and deliberately so: a runtime value import from
+ * @productbrain/kernel-client is impossible in both connectors (see this module's header for
+ * the CLI's reason, DEC-701 for mcp-server's), and this derivation needs no route data, so
+ * routing it through the generated-copy pipeline would buy codegen machinery for two
+ * three-line functions. What must not drift is the ANSWER — pinned by a parity test asserting
+ * both connectors classify the same (fn, args) identically.
+ */
+export declare function isDryRunCall(args: unknown): boolean;
+/**
+ * Could a timed-out call have LANDED A WRITE?
+ *
+ * The route's type answers "can this route write at all"; the call's own arguments answer
+ * "was this particular call asking it to". `pb capture` never sends `preview: true` today and
+ * says so loudly (../commands/capture.ts:445-450), so the CLI has no live defect here — but
+ * the two connectors holding DIFFERENT answers to the same question is the exact failure mode
+ * WP-575 exists to remove, so the derivation is kept identical on both sides rather than added
+ * only where a bug was observed.
+ */
+export declare function mayHaveLandedOnTimeout(fn: string, args: unknown): boolean;
+/**
+ * Did this throw come from the budget signal firing?
+ *
+ * `AbortSignal.timeout` rejects with a DOMException named "TimeoutError", but an abort that
+ * lands while the response BODY is streaming can surface as "AbortError" instead, depending on
+ * where in undici the signal is observed. Matching only the first name left that case falling
+ * through `parseKernelEnvelope`'s lenient branch into an empty envelope — which a 200 status
+ * then reads as SUCCESS with `undefined` data, the exact false-completion this work package
+ * exists to remove, surviving in the one phase it was fixed for.
+ *
+ * Accepting both is also what the mcp-server twin already does
+ * (`throwClassifiedGatewayFailure`, packages/mcp-server/src/gatewaySeam.ts), and the two
+ * connectors disagreeing about what a budget abort IS is the same defect class as them
+ * disagreeing about how long a route may take.
+ *
+ * Safe to widen because of WHERE this is consulted: both call sites are guarded on a `route`
+ * being present (./client.ts and ./kernelEnvelope.ts), and `route` is supplied only for the
+ * gateway fetches that carry `AbortSignal.timeout(budgetMs)`. On those paths there is no other
+ * abort to confuse this with — the caller-driven `controller.abort()` surfaces
+ * (`/api/admin`, proof-run, connect) never pass a route and never reach here.
+ */
+export declare function isTimeoutAbort(err: unknown): boolean;
+/**
+ * The error a budget abort deserves.
+ *
+ * A budget abort is NOT an unreachable host. The connection succeeded; we stopped waiting.
+ * Reporting "could not reach" would be a false statement about the server AND would imply
+ * nothing ran — but for a write route the server may well have finished. Say what is actually
+ * known, and name the one action that resolves it.
+ */
+export declare function gatewayTimeoutError(fn: string, budgetMs: number, args?: unknown): CLIError;
+//# sourceMappingURL=gatewayTimeout.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"gatewayTimeout.d.ts","sourceRoot":"","sources":["../../src/lib/gatewayTimeout.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,OAAO,EAAE,QAAQ,EAAa,MAAM,aAAa,CAAC;AAOlD;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAGlD;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAEnD;AAED;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,OAAO,CAEzE;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAGpD;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,QAAQ,CAsB1F"}

package/dist/lib/gatewayTimeout.js

@@ -0,0 +1,124 @@
+/**
+ * Gateway latency-budget aborts on the CLI — WP-575 (TEN-2917, TEN-1126).
+ *
+ * Before this, `./client.ts` set NO timeout on any gateway call: the same missing-declaration
+ * defect as MCP's blanket 10s constant, in the opposite direction (hang forever instead of
+ * give up too early). Both now derive their budget from the route contract; this module owns
+ * what to SAY when one is hit.
+ *
+ * Split out of client.ts at the 500-LOC ratchet's insistence (STD-2 / DEC-1504), and the
+ * ratchet read it correctly: "how do we explain a timeout, and is it safe to retry" is a
+ * decision with its own reason to change, separate from how a request is sent.
+ *
+ * The budget itself is DECLARED once at the route contract
+ * (packages/kernel-client/src/routeLatencyBudget.ts) and reaches this connector as a
+ * drift-checked generated copy. A runtime value import from @productbrain/kernel-client is
+ * impossible here — it is a devDependency and this package is PUBLISHED, so the specifier
+ * would be unresolvable in dist/ for every installed user.
+ */
+import { CLIError, ErrorCode } from './errors.js';
+import { ROUTE_TYPE_BY_NAME } from '../generated/routeLatencyBudget.generated.js';
+import { seatMayBeOpenLine } from './sessionStartCommands.js';
+/** TASK-1408 (DEC-2495): the seat routes; a timed-out seat is checked by rerunning the start, never by a search. */
+const SEAT_ROUTES = new Set(['agent.startSession', 'agent.resumeSession']);
+/**
+ * Does this route mutate state?
+ *
+ * Read off the route contract's own Convex function type — `mutation` and `action` can write,
+ * `query` cannot — never inferred from the route's NAME. This decides whether the user is told
+ * a timed-out call may have landed, so an UNKNOWN route fails safe to `true`: telling someone
+ * "nothing was written" when something was is the worse error, and it is the one that invites
+ * a duplicating retry.
+ */
+export function routeMayMutate(fn) {
+    const type = ROUTE_TYPE_BY_NAME[fn];
+    return type === undefined || type !== 'query';
+}
+/**
+ * Was this call a DRY RUN? (PR #533 review, Codex P2)
+ *
+ * `preview: true` is a gateway-wide contract meaning "run every validation, write nothing" —
+ * every registered route accepting it returns before its first write (the routes are
+ * enumerated with line citations in the mcp-server twin of this function,
+ * packages/mcp-server/src/gatewaySeam.ts).
+ *
+ * MIRRORED, NOT SHARED, and deliberately so: a runtime value import from
+ * @productbrain/kernel-client is impossible in both connectors (see this module's header for
+ * the CLI's reason, DEC-701 for mcp-server's), and this derivation needs no route data, so
+ * routing it through the generated-copy pipeline would buy codegen machinery for two
+ * three-line functions. What must not drift is the ANSWER — pinned by a parity test asserting
+ * both connectors classify the same (fn, args) identically.
+ */
+export function isDryRunCall(args) {
+    return args?.preview === true;
+}
+/**
+ * Could a timed-out call have LANDED A WRITE?
+ *
+ * The route's type answers "can this route write at all"; the call's own arguments answer
+ * "was this particular call asking it to". `pb capture` never sends `preview: true` today and
+ * says so loudly (../commands/capture.ts:445-450), so the CLI has no live defect here — but
+ * the two connectors holding DIFFERENT answers to the same question is the exact failure mode
+ * WP-575 exists to remove, so the derivation is kept identical on both sides rather than added
+ * only where a bug was observed.
+ */
+export function mayHaveLandedOnTimeout(fn, args) {
+    return routeMayMutate(fn) && !isDryRunCall(args);
+}
+/**
+ * Did this throw come from the budget signal firing?
+ *
+ * `AbortSignal.timeout` rejects with a DOMException named "TimeoutError", but an abort that
+ * lands while the response BODY is streaming can surface as "AbortError" instead, depending on
+ * where in undici the signal is observed. Matching only the first name left that case falling
+ * through `parseKernelEnvelope`'s lenient branch into an empty envelope — which a 200 status
+ * then reads as SUCCESS with `undefined` data, the exact false-completion this work package
+ * exists to remove, surviving in the one phase it was fixed for.
+ *
+ * Accepting both is also what the mcp-server twin already does
+ * (`throwClassifiedGatewayFailure`, packages/mcp-server/src/gatewaySeam.ts), and the two
+ * connectors disagreeing about what a budget abort IS is the same defect class as them
+ * disagreeing about how long a route may take.
+ *
+ * Safe to widen because of WHERE this is consulted: both call sites are guarded on a `route`
+ * being present (./client.ts and ./kernelEnvelope.ts), and `route` is supplied only for the
+ * gateway fetches that carry `AbortSignal.timeout(budgetMs)`. On those paths there is no other
+ * abort to confuse this with — the caller-driven `controller.abort()` surfaces
+ * (`/api/admin`, proof-run, connect) never pass a route and never reach here.
+ */
+export function isTimeoutAbort(err) {
+    const name = err?.name;
+    return name === 'TimeoutError' || name === 'AbortError';
+}
+/**
+ * The error a budget abort deserves.
+ *
+ * A budget abort is NOT an unreachable host. The connection succeeded; we stopped waiting.
+ * Reporting "could not reach" would be a false statement about the server AND would imply
+ * nothing ran — but for a write route the server may well have finished. Say what is actually
+ * known, and name the one action that resolves it.
+ */
+export function gatewayTimeoutError(fn, budgetMs, args) {
+    return new CLIError(`"${fn}" exceeded its ${budgetMs}ms latency budget.`, {
+        // PR #533 review (Copilot + Codex, same finding independently): this was
+        // NETWORK_UNREACHABLE, which contradicted the very distinction this module exists to
+        // make — the host WAS reachable. The taxonomy already had the right code and nothing
+        // used it. A caller branching on the code (retry policy, error reporting) would have
+        // been told "unreachable" about a server that answered the connection.
+        code: ErrorCode.NETWORK_TIMEOUT,
+        category: 'network',
+        ...(SEAT_ROUTES.has(fn) ? { seatMayBeOpen: true } : {}), // the hook names the open seat only for these
+        guidance: SEAT_ROUTES.has(fn)
+            ? seatMayBeOpenLine(String(args?.conversationId ?? '<conversation>'))
+            : mayHaveLandedOnTimeout(fn, args)
+                ? `The server was reachable — this client stopped waiting, so the operation may have\n` +
+                    `COMPLETED anyway. Check before retrying (a blind retry can duplicate the write):\n` +
+                    `  pb search "<what you were writing>"   # or: pb get <ID>`
+                : isDryRunCall(args)
+                    ? `The server was reachable but did not respond in time. This was a preview, so\n` +
+                        `nothing was written — safe to retry.`
+                    : `The server was reachable but did not respond in time. This is a read, so nothing\n` +
+                        `was written — safe to retry.`,
+    });
+}
+//# sourceMappingURL=gatewayTimeout.js.map

package/dist/lib/gatewayTimeout.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gatewayTimeout.js","sourceRoot":"","sources":["../../src/lib/gatewayTimeout.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAClD,OAAO,EAAE,kBAAkB,EAAE,MAAM,8CAA8C,CAAC;AAClF,OAAO,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AAE9D,oHAAoH;AACpH,MAAM,WAAW,GAAG,IAAI,GAAG,CAAC,CAAC,oBAAoB,EAAE,qBAAqB,CAAC,CAAC,CAAC;AAE3E;;;;;;;;GAQG;AACH,MAAM,UAAU,cAAc,CAAC,EAAU;IACvC,MAAM,IAAI,GAAG,kBAAkB,CAAC,EAAE,CAAC,CAAC;IACpC,OAAO,IAAI,KAAK,SAAS,IAAI,IAAI,KAAK,OAAO,CAAC;AAChD,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,YAAY,CAAC,IAAa;IACxC,OAAQ,IAAiD,EAAE,OAAO,KAAK,IAAI,CAAC;AAC9E,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,sBAAsB,CAAC,EAAU,EAAE,IAAa;IAC9D,OAAO,cAAc,CAAC,EAAE,CAAC,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC;AACnD,CAAC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,UAAU,cAAc,CAAC,GAAY;IACzC,MAAM,IAAI,GAAI,GAA4C,EAAE,IAAI,CAAC;IACjE,OAAO,IAAI,KAAK,cAAc,IAAI,IAAI,KAAK,YAAY,CAAC;AAC1D,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,mBAAmB,CAAC,EAAU,EAAE,QAAgB,EAAE,IAAc;IAC9E,OAAO,IAAI,QAAQ,CAAC,IAAI,EAAE,kBAAkB,QAAQ,oBAAoB,EAAE;QACxE,yEAAyE;QACzE,qFAAqF;QACrF,qFAAqF;QACrF,qFAAqF;QACrF,uEAAuE;QACvE,IAAI,EAAE,SAAS,CAAC,eAAe;QAC/B,QAAQ,EAAE,SAAS;QACnB,GAAG,CAAC,WAAW,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,aAAa,EAAE,IAAa,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,8CAA8C;QAChH,QAAQ,EAAE,WAAW,CAAC,GAAG,CAAC,EAAE,CAAC;YAC3B,CAAC,CAAC,iBAAiB,CAAC,MAAM,CAAE,IAAiD,EAAE,cAAc,IAAI,gBAAgB,CAAC,CAAC;YACnH,CAAC,CAAC,sBAAsB,CAAC,EAAE,EAAE,IAAI,CAAC;gBAClC,CAAC,CAAC,qFAAqF;oBACrF,oFAAoF;oBACpF,2DAA2D;gBAC7D,CAAC,CAAC,YAAY,CAAC,IAAI,CAAC;oBAClB,CAAC,CAAC,gFAAgF;wBAChF,sCAAsC;oBACxC,CAAC,CAAC,oFAAoF;wBACpF,8BAA8B;KACrC,CAAC,CAAC;AACL,CAAC"}

package/dist/lib/gitEnvLeakKeysParity.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=gitEnvLeakKeysParity.test.d.ts.map

package/dist/lib/gitEnvLeakKeysParity.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gitEnvLeakKeysParity.test.d.ts","sourceRoot":"","sources":["../../src/lib/gitEnvLeakKeysParity.test.ts"],"names":[],"mappings":""}