@productbrain/cli 0.1.0-beta.77 → 0.1.0-beta.7707

package/dist/lib/captureLink.d.ts

@@ -0,0 +1,26 @@
+import type { CoachingResult } from '../formatters/coaching.js';
+import { CLIError } from './errors.js';
+export interface CaptureLinkParams {
+    entryId: string;
+    link: string | undefined;
+    linkType: string | undefined;
+    /** The pre-relation coaching verdict — the post-relation re-eval below overwrites it only
+     *  on a genuinely written relation (fail-open on a re-eval failure keeps this one). */
+    coaching: CoachingResult | null | undefined;
+}
+export interface CaptureLinkResult {
+    actualLinkedTo: string | undefined;
+    actualRelationType: string | undefined;
+    linkTypeRefusal: CLIError | null;
+    coaching: CoachingResult | null | undefined;
+}
+/**
+ * WP-475 E1 fix: the pre-relation verdict predates this relation, so relation-dependent rubric
+ * criteria read falsely-failed; re-run AFTER the relation lands and render THAT verdict.
+ * Fail-open (BR-144): a re-eval failure keeps the pre-relation verdict. WP-688 S4 (TASK-105,
+ * element 11): what was ACTUALLY written — never guessed, never defaulted; `--link` without
+ * `--link-type` is refused with no default, ever, and the refusal is DEFERRED (returned, not
+ * thrown) so the caller can still render the successful capture/version receipt first.
+ */
+export declare function applyCaptureLink(params: CaptureLinkParams): Promise<CaptureLinkResult>;
+//# sourceMappingURL=captureLink.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"captureLink.d.ts","sourceRoot":"","sources":["../../src/lib/captureLink.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAChE,OAAO,EAAE,QAAQ,EAAa,MAAM,aAAa,CAAC;AAGlD,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;IACzB,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAC;IAC7B;2FACuF;IACvF,QAAQ,EAAE,cAAc,GAAG,IAAI,GAAG,SAAS,CAAC;CAC7C;AAED,MAAM,WAAW,iBAAiB;IAChC,cAAc,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC,kBAAkB,EAAE,MAAM,GAAG,SAAS,CAAC;IACvC,eAAe,EAAE,QAAQ,GAAG,IAAI,CAAC;IACjC,QAAQ,EAAE,cAAc,GAAG,IAAI,GAAG,SAAS,CAAC;CAC7C;AAED;;;;;;;GAOG;AACH,wBAAsB,gBAAgB,CAAC,MAAM,EAAE,iBAAiB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAmF5F"}

package/dist/lib/captureLink.js

@@ -0,0 +1,96 @@
+import { kernelCallWithSession } from './client.js';
+import { CLIError, ErrorCode } from './errors.js';
+import { resolveCreatableRelationTypes } from './legalRelationTypes.js';
+/**
+ * WP-475 E1 fix: the pre-relation verdict predates this relation, so relation-dependent rubric
+ * criteria read falsely-failed; re-run AFTER the relation lands and render THAT verdict.
+ * Fail-open (BR-144): a re-eval failure keeps the pre-relation verdict. WP-688 S4 (TASK-105,
+ * element 11): what was ACTUALLY written — never guessed, never defaulted; `--link` without
+ * `--link-type` is refused with no default, ever, and the refusal is DEFERRED (returned, not
+ * thrown) so the caller can still render the successful capture/version receipt first.
+ */
+export async function applyCaptureLink(params) {
+    const { entryId, link, linkType } = params;
+    let actualLinkedTo;
+    let actualRelationType;
+    let linkTypeRefusal = null;
+    let coaching = params.coaching;
+    if (link === undefined)
+        return { actualLinkedTo, actualRelationType, linkTypeRefusal, coaching };
+    const linkTarget = link.trim();
+    if (!linkTarget) {
+        // bcRUML/bcRpJQ: an empty or whitespace-only --link must not silently no-op.
+        linkTypeRefusal = new CLIError('--link requires a non-empty entry ID.', { code: ErrorCode.VALIDATION_FAILED, category: 'validation', guidance: `${entryId} was captured — only the link was refused. Re-run with a valid --link <entry-id>.` });
+    }
+    else if (!linkType) {
+        // No default, ever (element 11). Legal verbs = the workspace type row's declared valid_relation_types
+        // (matched like loadTypeMap: data.canonical_key, never a guessed entryId), filtered to what `pb relate` can create (bdB5K, cQFZ_).
+        let declaredTypes;
+        let targetMissing = false;
+        try {
+            const [created, target] = await Promise.all([
+                kernelCallWithSession('chain.getEntry', { entryId }),
+                kernelCallWithSession('chain.getEntry', { entryId: linkTarget }),
+            ]);
+            targetMissing = target === null; // bcRUMR: never recommend `pb relate ... <missing-id>`
+            const canonicalKey = created?.canonicalKey;
+            if (canonicalKey) {
+                const typeRows = await kernelCallWithSession('chain.listEntries', { collectionSlug: 'semantic-types' });
+                declaredTypes = resolveCreatableRelationTypes(typeRows, canonicalKey, target?.canonicalKey === 'domain');
+            }
+        }
+        catch {
+            // Advisory read only — a failure here still refuses the link, just without the list.
+        }
+        const verbHint = declaredTypes && declaredTypes.length > 0 ? `Legal relation types for this entry: ${declaredTypes.join(', ')}.` : `No relation types are declared valid for this entry's type.`;
+        linkTypeRefusal = new CLIError(`--link requires --link-type — no default is written. ${verbHint}`, {
+            code: ErrorCode.VALIDATION_FAILED,
+            category: 'validation',
+            guidance: targetMissing
+                ? `${entryId} was captured — the link was refused, and target "${linkTarget}" was not found. Verify the target entry ID.`
+                : `${entryId} was captured — only the link was refused. Re-run: pb relate ${entryId} <verb> ${linkTarget}`,
+        });
+    }
+    else {
+        const relationType = linkType;
+        let relationWritten = false;
+        let relateErr;
+        try {
+            const relateResult = await kernelCallWithSession('chain.createEntryRelation', {
+                fromEntryId: entryId, toEntryId: linkTarget, type: relationType,
+            });
+            // relationId is the ONLY "a row was inserted" marker (relations.ts:94-291) — a proposal diversion or the DEC-1399 auto-link gate return WITHOUT one.
+            relationWritten = Boolean(relateResult?.relationId);
+            if (relationWritten) {
+                actualLinkedTo = linkTarget;
+                actualRelationType = relationType;
+            }
+        }
+        catch (err) { // WP-745 review: a relate-door refusal must not escape uncaught — entryId above was ALREADY written.
+            relateErr = err;
+        }
+        // WP-745 round 3 (PRRT_kwDORS4ils6hz0vD): re-eval runs regardless of relate outcome — un-defers deferLLMSchedule; a refused link must not leave llmStatus:'skipped' forever. Diverted/refused verdicts are still discarded below.
+        try {
+            const reEval = await kernelCallWithSession('quality.evaluateHeuristicAndSchedule', { entryId, context: 'capture' });
+            if (relationWritten && reEval?.verdict)
+                coaching = reEval;
+        }
+        catch {
+            // Advisory — keep the pre-relation verdict rather than fail the capture.
+        }
+        if (relateErr instanceof CLIError && relateErr.code === ErrorCode.NETWORK_TIMEOUT) {
+            // WP-745 round 3 (PRRT_...h0VPP): NETWORK_TIMEOUT is outcome-UNKNOWN, not a refusal (the relate call may have landed server-side) — never buried under a contradictory blind-retry claim.
+            linkTypeRefusal = new CLIError(relateErr.message, { code: relateErr.code, category: relateErr.category, guidance: `${entryId} was captured. The link's outcome is UNKNOWN (not refused) — check before retrying: pb get ${entryId}. ${relateErr.guidance ?? ''}` });
+        }
+        else if (relateErr instanceof CLIError && relateErr.code !== ErrorCode.VALIDATION_FAILED) {
+            // WP-745 round 3 (PRRT_...h0CCc): preserve a real CLIError/McpError's own code/category (auth, rate limit) — only REL-LEGAL-2 VALIDATION (or a non-CLIError) gets the generic "was refused, re-run" guidance below.
+            const guidance = `${entryId} was captured — only the link was refused. Re-run: pb relate ${entryId} <verb> ${linkTarget}`;
+            linkTypeRefusal = new CLIError(relateErr.message, { code: relateErr.code, category: relateErr.category, guidance: relateErr.guidance ? `${guidance} (${relateErr.guidance})` : guidance });
+        }
+        else if (relateErr !== undefined) {
+            linkTypeRefusal = new CLIError(relateErr instanceof Error ? relateErr.message : String(relateErr), { code: ErrorCode.VALIDATION_FAILED, category: 'validation', guidance: `${entryId} was captured — only the link was refused. Re-run: pb relate ${entryId} <verb> ${linkTarget}` });
+        }
+    }
+    return { actualLinkedTo, actualRelationType, linkTypeRefusal, coaching };
+}
+//# sourceMappingURL=captureLink.js.map

package/dist/lib/captureLink.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"captureLink.js","sourceRoot":"","sources":["../../src/lib/captureLink.ts"],"names":[],"mappings":"AAOA,OAAO,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAGpD,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAClD,OAAO,EAAE,6BAA6B,EAAE,MAAM,yBAAyB,CAAC;AAkBxE;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAAC,MAAyB;IAC9D,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,GAAG,MAAM,CAAC;IAC3C,IAAI,cAAkC,CAAC;IACvC,IAAI,kBAAsC,CAAC;IAC3C,IAAI,eAAe,GAAoB,IAAI,CAAC;IAC5C,IAAI,QAAQ,GAAG,MAAM,CAAC,QAAQ,CAAC;IAE/B,IAAI,IAAI,KAAK,SAAS;QAAE,OAAO,EAAE,cAAc,EAAE,kBAAkB,EAAE,eAAe,EAAE,QAAQ,EAAE,CAAC;IAEjG,MAAM,UAAU,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC;IAC/B,IAAI,CAAC,UAAU,EAAE,CAAC;QAChB,6EAA6E;QAC7E,eAAe,GAAG,IAAI,QAAQ,CAAC,uCAAuC,EAAE,EAAE,IAAI,EAAE,SAAS,CAAC,iBAAiB,EAAE,QAAQ,EAAE,YAAY,EAAE,QAAQ,EAAE,GAAG,OAAO,mFAAmF,EAAE,CAAC,CAAC;IAClP,CAAC;SAAM,IAAI,CAAC,QAAQ,EAAE,CAAC;QACrB,sGAAsG;QACtG,mIAAmI;QACnI,IAAI,aAAmC,CAAC;QACxC,IAAI,aAAa,GAAG,KAAK,CAAC;QAC1B,IAAI,CAAC;YACH,MAAM,CAAC,OAAO,EAAE,MAAM,CAAC,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC;gBAC1C,qBAAqB,CAAsB,gBAAgB,EAAE,EAAE,OAAO,EAAE,CAAC;gBACzE,qBAAqB,CAAsB,gBAAgB,EAAE,EAAE,OAAO,EAAE,UAAU,EAAE,CAAC;aACtF,CAAC,CAAC;YACH,aAAa,GAAG,MAAM,KAAK,IAAI,CAAC,CAAC,uDAAuD;YACxF,MAAM,YAAY,GAAG,OAAO,EAAE,YAAY,CAAC;YAC3C,IAAI,YAAY,EAAE,CAAC;gBACjB,MAAM,QAAQ,GAAG,MAAM,qBAAqB,CAAiB,mBAAmB,EAAE,EAAE,cAAc,EAAE,gBAAgB,EAAE,CAAC,CAAC;gBACxH,aAAa,GAAG,6BAA6B,CAAC,QAAQ,EAAE,YAAY,EAAE,MAAM,EAAE,YAAY,KAAK,QAAQ,CAAC,CAAC;YAC3G,CAAC;QACH,CAAC;QAAC,MAAM,CAAC;YACP,qFAAqF;QACvF,CAAC;QACD,MAAM,QAAQ,GAAG,aAAa,IAAI,aAAa,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,wCAAwC,aAAa,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,6DAA6D,CAAC;QACjM,eAAe,GAAG,IAAI,QAAQ,CAC5B,wDAAwD,QAAQ,EAAE,EAClE;YACE,IAAI,EAAE,SAAS,CAAC,iBAAiB;YACjC,QAAQ,EAAE,YAAY;YACtB,QAAQ,EAAE,aAAa;gBACrB,CAAC,CAAC,GAAG,OAAO,qDAAqD,UAAU,8CAA8C;gBACzH,CAAC,CAAC,GAAG,OAAO,gEAAgE,OAAO,WAAW,UAAU,EAAE;SAC7G,CACF,CAAC;IACJ,CAAC;SAAM,CAAC;QACN,MAAM,YAAY,GAAG,QAAQ,CAAC;QAC9B,IAAI,eAAe,GAAG,KAAK,CAAC;QAC5B,IAAI,SAAkB,CAAC;QACvB,IAAI,CAAC;YACH,MAAM,YAAY,GAAG,MAAM,qBAAqB,CAAwD,2BAA2B,EAAE;gBACnI,WAAW,EAAE,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,IAAI,EAAE,YAAY;aAChE,CAAC,CAAC;YACH,qJAAqJ;YACrJ,eAAe,GAAG,OAAO,CAAE,YAAoD,EAAE,UAAU,CAAC,CAAC;YAC7F,IAAI,eAAe,EAAE,CAAC;gBACpB,cAAc,GAAG,UAAU,CAAC;gBAC5B,kBAAkB,GAAG,YAAY,CAAC;YACpC,CAAC;QACH,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC,CAAC,qGAAqG;YACnH,SAAS,GAAG,GAAG,CAAC;QAClB,CAAC;QACD,kOAAkO;QAClO,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,MAAM,qBAAqB,CACxC,sCAAsC,EACtC,EAAE,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,CAChC,CAAC;YACF,IAAI,eAAe,IAAI,MAAM,EAAE,OAAO;gBAAE,QAAQ,GAAG,MAAM,CAAC;QAC5D,CAAC;QAAC,MAAM,CAAC;YACP,yEAAyE;QAC3E,CAAC;QACD,IAAI,SAAS,YAAY,QAAQ,IAAI,SAAS,CAAC,IAAI,KAAK,SAAS,CAAC,eAAe,EAAE,CAAC;YAClF,0LAA0L;YAC1L,eAAe,GAAG,IAAI,QAAQ,CAAC,SAAS,CAAC,OAAO,EAAE,EAAE,IAAI,EAAE,SAAS,CAAC,IAAI,EAAE,QAAQ,EAAE,SAAS,CAAC,QAAQ,EAAE,QAAQ,EAAE,GAAG,OAAO,8FAA8F,OAAO,KAAK,SAAS,CAAC,QAAQ,IAAI,EAAE,EAAE,EAAE,CAAC,CAAC;QACtQ,CAAC;aAAM,IAAI,SAAS,YAAY,QAAQ,IAAI,SAAS,CAAC,IAAI,KAAK,SAAS,CAAC,iBAAiB,EAAE,CAAC;YAC3F,oNAAoN;YACpN,MAAM,QAAQ,GAAG,GAAG,OAAO,gEAAgE,OAAO,WAAW,UAAU,EAAE,CAAC;YAC1H,eAAe,GAAG,IAAI,QAAQ,CAAC,SAAS,CAAC,OAAO,EAAE,EAAE,IAAI,EAAE,SAAS,CAAC,IAAI,EAAE,QAAQ,EAAE,SAAS,CAAC,QAAQ,EAAE,QAAQ,EAAE,SAAS,CAAC,QAAQ,CAAC,CAAC,CAAC,GAAG,QAAQ,KAAK,SAAS,CAAC,QAAQ,GAAG,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAC,CAAC;QAC7L,CAAC;aAAM,IAAI,SAAS,KAAK,SAAS,EAAE,CAAC;YACnC,eAAe,GAAG,IAAI,QAAQ,CAAC,SAAS,YAAY,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,SAAS,CAAC,EAAE,EAAE,IAAI,EAAE,SAAS,CAAC,iBAAiB,EAAE,QAAQ,EAAE,YAAY,EAAE,QAAQ,EAAE,GAAG,OAAO,gEAAgE,OAAO,WAAW,UAAU,EAAE,EAAE,CAAC,CAAC;QACxR,CAAC;IACH,CAAC;IAED,OAAO,EAAE,cAAc,EAAE,kBAAkB,EAAE,eAAe,EAAE,QAAQ,EAAE,CAAC;AAC3E,CAAC"}

package/dist/lib/captureVersion.d.ts

@@ -0,0 +1,38 @@
+import { type CaptureVerdict } from './captureGrounding.js';
+export interface VersionCaptureParams {
+    groundingResult: Extract<CaptureVerdict, {
+        kind: 'version';
+    }>;
+    /** A REAL title only — omit when the capture has none. Never a placeholder (kernel/capture/
+     *  versionWrite.ts's own contract: passing one would rename the target to it). */
+    name?: string;
+    prose: string;
+    /** --field key=value, already parsed. */
+    fields?: Record<string, unknown>;
+    sourceRef?: string;
+    sourceExcerpt?: string;
+    sessionId: string;
+    skipGrounding: boolean;
+    groundingStart: number;
+    groundingElapsed: number;
+}
+export interface VersionCaptureResult {
+    entryId: string;
+    name: string;
+    warnings: string[];
+    normalization: {
+        remapped: Record<string, string>;
+        rejected: string[];
+        accepted: string[];
+    } | null | undefined;
+}
+/**
+ * Runs the version-verdict write. Throws a CLIError on refusal (delegation / organisational-
+ * authority — returned, not thrown, by the door itself; requirePermission's ownership gate
+ * throws directly) or NOT_FOUND (an unresolvable target, e.g. deleted/cross-workspace — fails
+ * closed, no fallback create; a re-run re-decides against the current candidate pool). No
+ * proposal is created on refusal — TEN-3687 already records updateEntry's missing
+ * propose_change branch; C2 does not add a second decision site.
+ */
+export declare function runVersionCapture(params: VersionCaptureParams): Promise<VersionCaptureResult>;
+//# sourceMappingURL=captureVersion.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"captureVersion.d.ts","sourceRoot":"","sources":["../../src/lib/captureVersion.ts"],"names":[],"mappings":"AAcA,OAAO,EAAuB,KAAK,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAEjF,MAAM,WAAW,oBAAoB;IACnC,eAAe,EAAE,OAAO,CAAC,cAAc,EAAE;QAAE,IAAI,EAAE,SAAS,CAAA;KAAE,CAAC,CAAC;IAC9D;sFACkF;IAClF,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,yCAAyC;IACzC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,OAAO,CAAC;IACvB,cAAc,EAAE,MAAM,CAAC;IACvB,gBAAgB,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,aAAa,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QAAC,QAAQ,EAAE,MAAM,EAAE,CAAC;QAAC,QAAQ,EAAE,MAAM,EAAE,CAAA;KAAE,GAAG,IAAI,GAAG,SAAS,CAAC;CAChH;AAwBD;;;;;;;GAOG;AACH,wBAAsB,iBAAiB,CAAC,MAAM,EAAE,oBAAoB,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAyCnG"}

package/dist/lib/captureVersion.js

@@ -0,0 +1,73 @@
+import { kernelCallWithSession } from './client.js';
+import { CLIError, ErrorCode } from './errors.js';
+import { buildVersionPatch, readVersionWriteOutcome } from './versionWrite.js';
+import { highestVerdictScore } from './captureGrounding.js';
+/** The TARGET entry's collection prose key — never the CAPTURE's chosen collection (decide()
+ *  matches across every collection, so the target can be in a different one). chain.updateEntry
+ *  merges `data` verbatim; it does not remap a write onto the target's real field the way
+ *  createEntry's own TEN-1258 remap does for a brand-new entry — this resolution is the only
+ *  thing standing between a captured prose body and the wrong field. Fail-open to 'description'
+ *  only when the fetch itself fails, same posture as capture.ts's own WHY-contract fetch. */
+async function resolveTargetProseKey(collectionSlug) {
+    try {
+        const contract = await kernelCallWithSession('chain.getCollectionFields', { slug: collectionSlug });
+        return contract?.descriptionFieldKey ?? 'description';
+    }
+    catch {
+        return 'description';
+    }
+}
+function refusalGuidance(refusal) {
+    return refusal.requiredAction ?? 'Route this change to the accountable role, or run `pb get <id>` to see the entry\'s current state.';
+}
+/**
+ * Runs the version-verdict write. Throws a CLIError on refusal (delegation / organisational-
+ * authority — returned, not thrown, by the door itself; requirePermission's ownership gate
+ * throws directly) or NOT_FOUND (an unresolvable target, e.g. deleted/cross-workspace — fails
+ * closed, no fallback create; a re-run re-decides against the current candidate pool). No
+ * proposal is created on refusal — TEN-3687 already records updateEntry's missing
+ * propose_change branch; C2 does not add a second decision site.
+ */
+export async function runVersionCapture(params) {
+    const { groundingResult, name, prose, fields, sourceRef, sourceExcerpt, sessionId, skipGrounding, groundingStart, groundingElapsed } = params;
+    const targetProseKey = await resolveTargetProseKey(groundingResult.collectionSlug);
+    const patch = buildVersionPatch({ capture: { name, prose, fields }, targetProseKey });
+    const rawResult = await kernelCallWithSession('chain.updateEntry', {
+        entryId: groundingResult.entryId,
+        ...patch,
+        autoPublish: true,
+        changeNote: 'Captured as a new version via CLI',
+        changedBy: `agent:${sessionId}`,
+        ...(sourceRef ? { sourceRef } : {}),
+        ...(sourceExcerpt ? { sourceExcerpt } : {}),
+    });
+    // WP-319 S3 / STD-155: same observability this verdict would have fed via the create path's
+    // own recordGroundingOutcome call — fires regardless of write outcome, matching that call's
+    // own best-effort, never-blocks posture.
+    if (!skipGrounding && groundingStart > 0) {
+        void kernelCallWithSession('chain.recordGroundingOutcome', {
+            surface: 'cli',
+            promptShown: false,
+            highestRatio: highestVerdictScore(groundingResult),
+            hadGovernance: false,
+            grounding_ms: groundingElapsed,
+        }, { retryOnRateLimit: false }).catch(() => undefined);
+    }
+    const outcome = readVersionWriteOutcome(rawResult);
+    if (!outcome.ok) {
+        const authorityRefusal = outcome.refusal.category === 'auth';
+        throw new CLIError(outcome.refusal.reason ?? `Version write on ${groundingResult.entryId} was refused.`, {
+            code: authorityRefusal ? ErrorCode.AUTH_DENIED : ErrorCode.VALIDATION_FAILED,
+            category: authorityRefusal ? 'auth' : 'validation',
+            guidance: refusalGuidance(outcome.refusal),
+        });
+    }
+    const typed = rawResult;
+    return {
+        entryId: groundingResult.entryId,
+        name: groundingResult.name,
+        warnings: typed.warnings ?? [],
+        normalization: typed.normalization,
+    };
+}
+//# sourceMappingURL=captureVersion.js.map

package/dist/lib/captureVersion.js.map

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

package/dist/lib/client.d.ts

@@ -1,29 +1,26 @@
 /**
  * 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".
+ * 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".
+ * 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".
  */
+import type { ValidationErrorDetail } from './kernelEnvelope.js';
 import { CLIError } from './errors.js';
-/** Structured field-level detail from a VALIDATION_FAILED response. */
-export interface ValidationErrorDetail {
-    fieldKey: string;
-    fieldLabel: string;
-    invalidValue: unknown;
-    validOptions?: string[];
-    errorType: 'type_mismatch' | 'invalid_option' | 'required';
-    message: string;
-}
+import { type KernelCallOptions } from './rate-limit.js';
+export declare function isPerEntryAuthorizationRefusal(code?: string): boolean;
 /** Error thrown by kernelCall/kernelCallWithSession when the server returns a non-OK response. */
 export declare class McpError extends CLIError {
     details?: ValidationErrorDetail[];
-    constructor(message: string, code?: string, 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;
@@ -39,6 +36,15 @@ export type ValidateKeyResult = {
  * 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. */
@@ -51,16 +57,37 @@ export declare function spinnerLabel(fn: string): string;
  * 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>): Promise<T>;
+export declare function kernelCall<T = unknown>(fn: string, args?: Record<string, unknown>, options?: KernelCallOptions): Promise<T>;
 /**
- * kernelCall variant that injects X-Agent-Session-Id header for write operations.
+ * 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.
  *
+ * WP-711/712: the binding guard lives in the shared fetchKernelEnvelope. TEN-3398 (follow-up)
+ * added the effective-tenant notice here too, alongside the post-write session-touch below.
+ *
  * 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>): Promise<T>;
+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;;;;;;;;;;GAUG;AAIH,OAAO,EAAE,QAAQ,EAAa,MAAM,aAAa,CAAC;AAIlD,uEAAuE;AACvE,MAAM,WAAW,qBAAqB;IACpC,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,OAAO,CAAC;IACtB,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,SAAS,EAAE,eAAe,GAAG,gBAAgB,GAAG,UAAU,CAAC;IAC3D,OAAO,EAAE,MAAM,CAAC;CACjB;AAeD,kGAAkG;AAClG,qBAAa,QAAS,SAAQ,QAAQ;IACpC,OAAO,CAAC,EAAE,qBAAqB,EAAE,CAAC;gBAEtB,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,qBAAqB,EAAE;CAQ9E;AAwCD,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;;;;;;;GAOG;AACH,wBAAsB,WAAW,CAC/B,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,EACf,SAAS,SAAO,GACf,OAAO,CAAC,iBAAiB,CAAC,CAmC5B;AA0BD,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,CAsBlB;AAED,wBAAsB,UAAU,CAAC,CAAC,GAAG,OAAO,EAC1C,EAAE,EAAE,MAAM,EACV,IAAI,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GACjC,OAAO,CAAC,CAAC,CAAC,CAyBZ;AA0BD;;;;;;;;;GASG;AACH,wBAAsB,qBAAqB,CAAC,CAAC,GAAG,OAAO,EACrD,EAAE,EAAE,MAAM,EACV,IAAI,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GACjC,OAAO,CAAC,CAAC,CAAC,CAwCZ"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/lib/client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAWH,OAAO,KAAK,EAAkB,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAMjF,OAAO,EAAE,QAAQ,EAAa,MAAM,aAAa,CAAC;AAGlD,OAAO,EAAkC,KAAK,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAoBzF,wBAAgB,8BAA8B,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAErE;AAkCD,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;CAc1G;AAGD,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,CAoClB;AAqFD,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,CAIZ;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,CAI9F;AA+BD;;;;;;;;;;;;;;;GAeG;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,CA8BZ"}