@productbrain/cli 0.1.0-beta.978 → 0.1.0-beta.9791

package/dist/lib/ownerLine.d.ts

@@ -0,0 +1,73 @@
+/**
+ * WP-753 O5b fix round 1 (item 2): the ONE judged core for "how do we say who owns this
+ * entry" — the CLI (packages/cli/src/formatters/entry.ts), MCP
+ * (packages/mcp-server/src/tools/knowledge-helpers.ts), and the browser Rail
+ * (EntryRailPreview.svelte) each held a hand-copied switch over the same states; the
+ * Svelte copy alone drifted with a silent `default:` arm that would print "Owner: unresolved"
+ * for an unhandled kind instead of failing to compile. Pure, no I/O — kernel never imports
+ * convex, so this is a structural five-kind union that convex's `EntryOwnerRead`
+ * (convex/governance/entryOwnershipRead.ts) satisfies exactly, not a copy of it.
+ *
+ * DEC-1793 (RULE-632) deleted the `default`, `overflow` and `unavailable` kinds this union used
+ * to carry: a working record with no ownership row now reads as the plain `none` kind below —
+ * no synthetic Team Lead, no overflow guess.
+ *
+ * DEC-1944 (TASK-614; WP-783): a role or a team is an organisation definition with no
+ * owner of its own; its line says where it lives instead (`placed`, printed `Home: <team>`).
+ *
+ * Surface-specific bits are NOT here, by design — the caller applies them: per-field name
+ * sanitization (CLI/MCP's `sanitizeSingleLineField`), the bold label (MCP), and
+ * whether raw ids are shown at all (browser Rail: never — Rail-Design-Thesis.md:278 forbids
+ * Convex `_id`s as Noise; CLI/MCP: yes, a terminal user pastes them into a repair command).
+ */
+export type OwnerLine = {
+    kind: 'one';
+    team: {
+        name: string;
+    };
+    role: {
+        name: string;
+    };
+} | {
+    kind: 'none';
+} | {
+    kind: 'many';
+    count: number;
+    truncated: boolean;
+} | {
+    kind: 'dangling';
+    teamId: string;
+    roleId: string;
+    team?: {
+        name: string;
+    };
+    role?: {
+        name: string;
+    };
+} | {
+    kind: 'placed';
+    team: {
+        name: string;
+    };
+};
+export interface FormatOwnerLineOptions {
+    /** CLI/MCP keep the raw id for repair commands (default true). The browser Rail passes
+     *  `false` — Convex ids are Noise there, never Signal. */
+    ids?: boolean;
+    /** MCP bolds the leading label (`**Owner:**`, `**Home:**`); CLI and the browser keep it plain (default false). */
+    bold?: boolean;
+}
+/** The owning role and its team as two names, for a surface that shows them apart (the browser
+ *  Rail's role pill with the team beside it, DEC-1932). `null` for every kind but `one`: those keep
+ *  their sentence from `formatOwnerLine`, which builds its `one` sentence from these same names. */
+export declare function ownerLineParts(owner: OwnerLine): {
+    role: string;
+    team: string;
+} | null;
+/** Exhaustive over the five kinds above. The `default:` arm below is not a silent catch-all —
+ *  it assigns the narrowed remainder to a `never`-typed const, so an unhandled kind fails to
+ *  compile HERE regardless of which tsconfig's strictness flags apply at the call site
+ *  (kernel's own tsconfig is red pre-existing, unrelated to this PR, so exhaustiveness cannot
+ *  be left to ride on `noImplicitReturns` alone; WP-753 O5b fix round 3, addendum a). */
+export declare function formatOwnerLine(owner: OwnerLine, options?: FormatOwnerLineOptions): string;
+//# sourceMappingURL=ownerLine.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ownerLine.d.ts","sourceRoot":"","sources":["../../src/lib/ownerLine.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,MAAM,SAAS,GAClB;IAAE,IAAI,EAAE,KAAK,CAAC;IAAC,IAAI,EAAE;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;IAAC,IAAI,EAAE;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE,GAE/D;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAChB;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,OAAO,CAAA;CAAE,GAKnD;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;IAAC,IAAI,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE,GAGtG;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,IAAI,EAAE;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE,CAAC;AAE9C,MAAM,WAAW,sBAAsB;IACtC;8DAC0D;IAC1D,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,kHAAkH;IAClH,IAAI,CAAC,EAAE,OAAO,CAAC;CACf;AAED;;oGAEoG;AACpG,wBAAgB,cAAc,CAAC,KAAK,EAAE,SAAS,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAEtF;AAED;;;;yFAIyF;AACzF,wBAAgB,eAAe,CAAC,KAAK,EAAE,SAAS,EAAE,OAAO,GAAE,sBAA2B,GAAG,MAAM,CAyC9F"}

package/dist/lib/ownerLine.js

@@ -0,0 +1,57 @@
+// GENERATED by scripts/generate-mcp-embedded-copies.mjs from kernel/organisationalAuthority/ownerLine.ts.
+// DO NOT EDIT. Run `npm run mcp:embedded-copies` to regenerate.
+// Local runtime copy for the isolated connector build.
+/** The owning role and its team as two names, for a surface that shows them apart (the browser
+ *  Rail's role pill with the team beside it, DEC-1932). `null` for every kind but `one`: those keep
+ *  their sentence from `formatOwnerLine`, which builds its `one` sentence from these same names. */
+export function ownerLineParts(owner) {
+    return owner.kind === 'one' ? { role: owner.role.name, team: owner.team.name } : null;
+}
+/** Exhaustive over the five kinds above. The `default:` arm below is not a silent catch-all —
+ *  it assigns the narrowed remainder to a `never`-typed const, so an unhandled kind fails to
+ *  compile HERE regardless of which tsconfig's strictness flags apply at the call site
+ *  (kernel's own tsconfig is red pre-existing, unrelated to this PR, so exhaustiveness cannot
+ *  be left to ride on `noImplicitReturns` alone; WP-753 O5b fix round 3, addendum a). */
+export function formatOwnerLine(owner, options = {}) {
+    const ids = options.ids ?? true;
+    const word = owner.kind === 'placed' ? 'Home:' : 'Owner:';
+    const label = options.bold ? `**${word}**` : word;
+    switch (owner.kind) {
+        case 'one': {
+            const { role, team } = ownerLineParts(owner);
+            return `${label} ${role} in ${team}`;
+        }
+        case 'none': return `${label} none`;
+        case 'placed': return `${label} ${owner.team.name}`;
+        case 'many': return `${label} conflicting — ${owner.count}${owner.truncated ? '+' : ''} owners recorded`;
+        case 'dangling': {
+            // WP-753 O5b fix round 3, addendum b: lead with whichever name(s) survived —
+            // requiring BOTH team and role names dropped a fetched role name whenever only
+            // the team was gone (or vice versa), silently downgrading to the generic sentence.
+            const named = owner.team && owner.role
+                ? `${owner.role.name} in ${owner.team.name} is archived`
+                : owner.role
+                    ? `role ${owner.role.name} is archived`
+                    : owner.team
+                        ? `team ${owner.team.name} is archived`
+                        : 'the owning team or role is archived';
+            // WP-753 O5b fix round 4 (item 4): one voice for the unresolved state —
+            // "couldn't be resolved", not the earlier "unresolved".
+            return ids ? `${label} couldn't be resolved — ${named} (team ${owner.teamId}, role ${owner.roleId})` : `${label} couldn't be resolved — ${named}`;
+        }
+        default: {
+            // RULE-268 (round 1 review, PR #1180): fail LOUD, never silently render an unhandled
+            // kind's raw object through stripControlChars (which crashed an older globally-
+            // installed CLI live on the preview: `str.replace is not a function`, since the old
+            // `default:` arm returned the non-string `owner` value itself instead of a message).
+            // RULE-632/DEC-1742/CLAUDE.md §13 refuse a wire-compat shim for a shape the write path
+            // no longer produces — an older client hitting a newer server's kind it has never seen
+            // throws with an explicit upgrade instruction instead. The `never` assignment below
+            // still buys compile-time exhaustiveness (a future kind added to `OwnerLine` without a
+            // case here fails to compile HERE, unrelated to this runtime guard).
+            const _exhaustive = owner;
+            throw new Error(`Unknown owner state "${String(owner.kind)}" — this client is older than the server; upgrade @productbrain/cli / @productbrain/mcp`);
+        }
+    }
+}
+//# sourceMappingURL=ownerLine.js.map

package/dist/lib/ownerLine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ownerLine.js","sourceRoot":"","sources":["../../src/lib/ownerLine.ts"],"names":[],"mappings":"AAAA,0GAA0G;AAC1G,gEAAgE;AAChE,uDAAuD;AA8CvD;;oGAEoG;AACpG,MAAM,UAAU,cAAc,CAAC,KAAgB;IAC9C,OAAO,KAAK,CAAC,IAAI,KAAK,KAAK,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;AACvF,CAAC;AAED;;;;yFAIyF;AACzF,MAAM,UAAU,eAAe,CAAC,KAAgB,EAAE,UAAkC,EAAE;IACrF,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,IAAI,IAAI,CAAC;IAChC,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,QAAQ,CAAC;IAC1D,MAAM,KAAK,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,IAAI,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC;IAClD,QAAQ,KAAK,CAAC,IAAI,EAAE,CAAC;QACpB,KAAK,KAAK,CAAC,CAAC,CAAC;YACZ,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,GAAG,cAAc,CAAC,KAAK,CAAE,CAAC;YAC9C,OAAO,GAAG,KAAK,IAAI,IAAI,OAAO,IAAI,EAAE,CAAC;QACtC,CAAC;QACD,KAAK,MAAM,CAAC,CAAC,OAAO,GAAG,KAAK,OAAO,CAAC;QACpC,KAAK,QAAQ,CAAC,CAAC,OAAO,GAAG,KAAK,IAAI,KAAK,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;QACpD,KAAK,MAAM,CAAC,CAAC,OAAO,GAAG,KAAK,kBAAkB,KAAK,CAAC,KAAK,GAAG,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,kBAAkB,CAAC;QACzG,KAAK,UAAU,CAAC,CAAC,CAAC;YACjB,6EAA6E;YAC7E,+EAA+E;YAC/E,mFAAmF;YACnF,MAAM,KAAK,GAAG,KAAK,CAAC,IAAI,IAAI,KAAK,CAAC,IAAI;gBACrC,CAAC,CAAC,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,cAAc;gBACxD,CAAC,CAAC,KAAK,CAAC,IAAI;oBACX,CAAC,CAAC,QAAQ,KAAK,CAAC,IAAI,CAAC,IAAI,cAAc;oBACvC,CAAC,CAAC,KAAK,CAAC,IAAI;wBACX,CAAC,CAAC,QAAQ,KAAK,CAAC,IAAI,CAAC,IAAI,cAAc;wBACvC,CAAC,CAAC,qCAAqC,CAAC;YAC3C,wEAAwE;YACxE,wDAAwD;YACxD,OAAO,GAAG,CAAC,CAAC,CAAC,GAAG,KAAK,2BAA2B,KAAK,UAAU,KAAK,CAAC,MAAM,UAAU,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,GAAG,KAAK,2BAA2B,KAAK,EAAE,CAAC;QACnJ,CAAC;QACD,OAAO,CAAC,CAAC,CAAC;YACT,qFAAqF;YACrF,gFAAgF;YAChF,oFAAoF;YACpF,qFAAqF;YACrF,uFAAuF;YACvF,uFAAuF;YACvF,oFAAoF;YACpF,uFAAuF;YACvF,qEAAqE;YACrE,MAAM,WAAW,GAAU,KAAK,CAAC;YACjC,MAAM,IAAI,KAAK,CAAC,wBAAwB,MAAM,CAAE,KAA4B,CAAC,IAAI,CAAC,yFAAyF,CAAC,CAAC;QAC9K,CAAC;IACF,CAAC;AACF,CAAC"}

package/dist/lib/parseFields.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Parse --field key=value pairs into a data object.
+ * Splits on first `=` only to handle values containing `=`.
+ *
+ * Sweep finding #9: `-f`/`--field` is already REPEATABLE at the Commander layer
+ * (index.ts: `(val, prev) => [...prev, val]`) — that is this CLI's existing, documented
+ * convention for a multi-select/array field (e.g. a collection's `tags`,
+ * `type: 'multi-select'` server-side). But this function silently let the LAST occurrence of a
+ * repeated key clobber every earlier one (`data[key] = value` unconditionally), so
+ * `-f tags=a -f tags=b` sent only the string `"b"` — never
+ * an array, and silently dropping `a` besides. The server then rejects a bare string
+ * against an array-typed field ("rejects non-array input"). Fixed by accumulating repeated keys
+ * into an array instead of overwriting — a single-occurrence key (the overwhelming majority of
+ * calls, e.g. the documented `rationale="..."` example) is completely unaffected: no comma
+ * heuristics, no schema round-trip, no behavior change for free text that happens to contain a
+ * comma.
+ */
+export declare function parseFields(fields: string[]): Record<string, unknown>;
+//# sourceMappingURL=parseFields.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"parseFields.d.ts","sourceRoot":"","sources":["../../src/lib/parseFields.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CA4BrE"}

package/dist/lib/parseFields.js

@@ -0,0 +1,49 @@
+import { CLIError, ErrorCode } from './errors.js';
+/**
+ * Parse --field key=value pairs into a data object.
+ * Splits on first `=` only to handle values containing `=`.
+ *
+ * Sweep finding #9: `-f`/`--field` is already REPEATABLE at the Commander layer
+ * (index.ts: `(val, prev) => [...prev, val]`) — that is this CLI's existing, documented
+ * convention for a multi-select/array field (e.g. a collection's `tags`,
+ * `type: 'multi-select'` server-side). But this function silently let the LAST occurrence of a
+ * repeated key clobber every earlier one (`data[key] = value` unconditionally), so
+ * `-f tags=a -f tags=b` sent only the string `"b"` — never
+ * an array, and silently dropping `a` besides. The server then rejects a bare string
+ * against an array-typed field ("rejects non-array input"). Fixed by accumulating repeated keys
+ * into an array instead of overwriting — a single-occurrence key (the overwhelming majority of
+ * calls, e.g. the documented `rationale="..."` example) is completely unaffected: no comma
+ * heuristics, no schema round-trip, no behavior change for free text that happens to contain a
+ * comma.
+ */
+export function parseFields(fields) {
+    const data = {};
+    for (const field of fields) {
+        const eqIndex = field.indexOf('=');
+        if (eqIndex === -1) {
+            throw new CLIError(`Invalid --field format: "${field}". Expected key=value.`, {
+                code: ErrorCode.VALIDATION_FAILED,
+                category: 'validation',
+                guidance: 'Use --field key=value (split on first "=").',
+            });
+        }
+        const key = field.slice(0, eqIndex).trim();
+        const value = field.slice(eqIndex + 1).trim();
+        if (!key) {
+            throw new CLIError(`Invalid --field format: "${field}". Key cannot be empty.`, {
+                code: ErrorCode.VALIDATION_FAILED,
+                category: 'validation',
+                guidance: 'Provide a non-empty key before the "=" sign.',
+            });
+        }
+        if (Object.prototype.hasOwnProperty.call(data, key)) {
+            const existing = data[key];
+            data[key] = Array.isArray(existing) ? [...existing, value] : [existing, value];
+        }
+        else {
+            data[key] = value;
+        }
+    }
+    return data;
+}
+//# sourceMappingURL=parseFields.js.map

package/dist/lib/parseFields.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"parseFields.js","sourceRoot":"","sources":["../../src/lib/parseFields.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAElD;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,WAAW,CAAC,MAAgB;IAC3C,MAAM,IAAI,GAA4B,EAAE,CAAC;IACzC,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC5B,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;QACnC,IAAI,OAAO,KAAK,CAAC,CAAC,EAAE,CAAC;YACpB,MAAM,IAAI,QAAQ,CAAC,4BAA4B,KAAK,wBAAwB,EAAE;gBAC7E,IAAI,EAAE,SAAS,CAAC,iBAAiB;gBACjC,QAAQ,EAAE,YAAY;gBACtB,QAAQ,EAAE,6CAA6C;aACvD,CAAC,CAAC;QACJ,CAAC;QACD,MAAM,GAAG,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC,IAAI,EAAE,CAAC;QAC3C,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,OAAO,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;QAC9C,IAAI,CAAC,GAAG,EAAE,CAAC;YACV,MAAM,IAAI,QAAQ,CAAC,4BAA4B,KAAK,yBAAyB,EAAE;gBAC9E,IAAI,EAAE,SAAS,CAAC,iBAAiB;gBACjC,QAAQ,EAAE,YAAY;gBACtB,QAAQ,EAAE,8CAA8C;aACxD,CAAC,CAAC;QACJ,CAAC;QACD,IAAI,MAAM,CAAC,SAAS,CAAC,cAAc,CAAC,IAAI,CAAC,IAAI,EAAE,GAAG,CAAC,EAAE,CAAC;YACrD,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC;YAC3B,IAAI,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,QAAQ,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,QAAkB,EAAE,KAAK,CAAC,CAAC;QAC1F,CAAC;aAAM,CAAC;YACP,IAAI,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;QACnB,CAAC;IACF,CAAC;IACD,OAAO,IAAI,CAAC;AACb,CAAC"}

package/dist/lib/pinnedRole.d.ts

@@ -0,0 +1,28 @@
+/**
+ * A folder's default acting role (DEC-1961, TASK-639, WP-809).
+ *
+ * `.productbrain/config.local.json` may carry `role` beside `profile`: the role id (ROL-N) this
+ * folder's sessions act as. `pb session start --role` wins over it. The role binds at session
+ * start (DEC-1715) and only labels attribution; the key never carries it (DEC-1923). The kernel
+ * decides whether the person holds it (RULE-128): a role not held is refused, never swapped for
+ * another (RULE-632). A role id names a role in ONE workspace, so the pin's role is sent only when
+ * the pin's own profile supplies the key; under any other key it is not sent, and that is said.
+ *
+ * A refusal is thrown once and printed once, on stderr; the SessionStart hook pb installs runs
+ * `pb session start 2>&1`, so the agent reads it there (TASK-649, WP-810). Older installs and
+ * machine-level hooks may still discard stderr (TEN-3736). Only role refusals get
+ * this framing: any other failure is rethrown unchanged.
+ */
+import { CLIError } from './errors.js';
+/** The one test for a role refusal; session.ts's stale-preview-key recovery uses it too, so a role refusal is never relabelled. */
+export declare const isRoleRefusal: (err: unknown) => err is CLIError;
+/**
+ * Run a session start with `--role`, else the pin's role. A role refusal under `--role` gains the
+ * reset fix; under the pin it names the pin and its fix. With no role asked for, `multi_role` gains
+ * the folder-pin way to name one, and `no_role` keeps the kernel's fix. Every other failure is
+ * rethrown unchanged.
+ */
+export declare function startWithPinnedRole<O extends {
+    role?: string;
+}>(options: O, json: boolean, start: (options: O) => Promise<void>): Promise<void>;
+//# sourceMappingURL=pinnedRole.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"pinnedRole.d.ts","sourceRoot":"","sources":["../../src/lib/pinnedRole.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAGH,OAAO,EAAE,QAAQ,EAAkC,MAAM,aAAa,CAAC;AAmBvE,mIAAmI;AACnI,eAAO,MAAM,aAAa,GAAI,KAAK,OAAO,KAAG,GAAG,IAAI,QAAkE,CAAC;AAmCvH;;;;;GAKG;AACH,wBAAsB,mBAAmB,CAAC,CAAC,SAAS;IAAE,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,EACnE,OAAO,EAAE,CAAC,EACV,IAAI,EAAE,OAAO,EACb,KAAK,EAAE,CAAC,OAAO,EAAE,CAAC,KAAK,OAAO,CAAC,IAAI,CAAC,GACnC,OAAO,CAAC,IAAI,CAAC,CAwBf"}

package/dist/lib/pinnedRole.js

@@ -0,0 +1,105 @@
+/**
+ * A folder's default acting role (DEC-1961, TASK-639, WP-809).
+ *
+ * `.productbrain/config.local.json` may carry `role` beside `profile`: the role id (ROL-N) this
+ * folder's sessions act as. `pb session start --role` wins over it. The role binds at session
+ * start (DEC-1715) and only labels attribution; the key never carries it (DEC-1923). The kernel
+ * decides whether the person holds it (RULE-128): a role not held is refused, never swapped for
+ * another (RULE-632). A role id names a role in ONE workspace, so the pin's role is sent only when
+ * the pin's own profile supplies the key; under any other key it is not sent, and that is said.
+ *
+ * A refusal is thrown once and printed once, on stderr; the SessionStart hook pb installs runs
+ * `pb session start 2>&1`, so the agent reads it there (TASK-649, WP-810). Older installs and
+ * machine-level hooks may still discard stderr (TEN-3736). Only role refusals get
+ * this framing: any other failure is rethrown unchanged.
+ */
+import { readLocalProjectConfig } from './config.js';
+import { CLIError, ErrorCode } from './errors.js';
+import { resolveReportedProfile } from './reportedProfile.js';
+import { describeReportedTenant } from './workspaceNotice.js';
+const PIN = '.productbrain/config.local.json';
+const ROLE_SWITCH_FIX = 'If this conversation already has a session bound to another role, run `pb session close`, ' +
+    'then `pb session reset --force`, then start again.';
+const PINNED_ROLE_FIX = `Fix: put a role id you hold in the "role" field of ${PIN}, or remove the field. ${ROLE_SWITCH_FIX}`;
+/**
+ * The kernel's role refusals at session start. VALIDATION_FAILED counts only because a role was
+ * sent: on this path it comes from the role reference (an unknown id, or a record that is not a role).
+ */
+const ROLE_REFUSALS = new Set([
+    ErrorCode.ROLE_NOT_OWNER, ErrorCode.NO_ROLE, ErrorCode.MULTI_ROLE, ErrorCode.ROLE_SWITCH_REFUSED, ErrorCode.VALIDATION_FAILED,
+]);
+/** The one test for a role refusal; session.ts's stale-preview-key recovery uses it too, so a role refusal is never relabelled. */
+export const isRoleRefusal = (err) => err instanceof CLIError && ROLE_REFUSALS.has(err.code);
+/** The same refusal, same message and code, with one more line of guidance. */
+function withGuidance(err, extra) {
+    return new CLIError(err.message, {
+        code: err.code, category: err.category, authority: err.authority,
+        guidance: [err.guidance, extra].filter(Boolean).join('\n'),
+    });
+}
+/** A role refusal while the pin's role was in play: names the pin. Keeps the kernel's code. */
+function pinnedRoleRefusal(role, err) {
+    // JSON.stringify quotes the hand-written value and escapes any control character in it.
+    return new CLIError(`This folder pins role ${JSON.stringify(role)} in ${PIN}, and the session did not start: ${err.message}`, {
+        code: err.code, category: err.category, authority: err.authority,
+        guidance: [err.guidance, PINNED_ROLE_FIX].filter(Boolean).join('\n'),
+    });
+}
+/**
+ * The pin's role, when it applies: only when the pin's own profile supplies the key. Under an
+ * exported key, a preview binding or any other source, it is not sent, and one line says why.
+ */
+function pinnedRoleInPlay(json) {
+    const pin = readLocalProjectConfig();
+    if (!pin?.role && !pin?.roleMalformed)
+        return { malformed: false };
+    const { profile, source } = resolveReportedProfile();
+    if (source !== 'local') {
+        const line = `folder role ${pin.role ?? '(not a role id)'} not applied: the key comes from ${describeReportedTenant(profile, source) ?? source}\n`;
+        (json ? process.stderr : process.stdout).write(line);
+        return { malformed: false };
+    }
+    return { role: pin.role, malformed: pin.roleMalformed === true };
+}
+/**
+ * Run a session start with `--role`, else the pin's role. A role refusal under `--role` gains the
+ * reset fix; under the pin it names the pin and its fix. With no role asked for, `multi_role` gains
+ * the folder-pin way to name one, and `no_role` keeps the kernel's fix. Every other failure is
+ * rethrown unchanged.
+ */
+export async function startWithPinnedRole(options, json, start) {
+    if (options.role) {
+        try {
+            return await start(options);
+        }
+        catch (err) {
+            throw isRoleRefusal(err) ? withGuidance(err, ROLE_SWITCH_FIX) : err;
+        }
+    }
+    const { role, malformed } = pinnedRoleInPlay(json);
+    if (malformed) {
+        throw new CLIError(`The "role" field in ${PIN} is not a role id (ROL- followed by a number), so the session did not start.`, {
+            code: ErrorCode.CONFIG_INVALID, category: 'config', guidance: PINNED_ROLE_FIX,
+        });
+    }
+    if (!role) {
+        try {
+            return await start(options);
+        }
+        catch (err) {
+            if (err instanceof CLIError && err.code === ErrorCode.MULTI_ROLE) {
+                throw withGuidance(err, `Or name this folder's role once: add "role": "<ROLE-ID>" to ${PIN}.`);
+            }
+            throw err;
+        }
+    }
+    try {
+        await start({ ...options, role });
+    }
+    catch (err) {
+        if (isRoleRefusal(err))
+            throw pinnedRoleRefusal(role, err);
+        throw err;
+    }
+}
+//# sourceMappingURL=pinnedRole.js.map

package/dist/lib/pinnedRole.js.map

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

package/dist/lib/platformGlossary.d.ts

@@ -0,0 +1,19 @@
+/**
+ * The platform's glossary: four governance words every workspace shares, served from code (TEN-4475,
+ * DEC-1949, DEC-1947). No workspace stores them and no team edits them; a team adds its own terms
+ * as glossary entries, and those are listed after these. A platform term has no entry id.
+ *
+ * Readers: the Cortex Glossary page (src/lib/glossary/platformTerms.ts), the build context
+ * (convex/agentKnowledge/intelligence.ts), pb search, and the MCP entries search and terminology
+ * resource through generated copies (scripts/generate-mcp-embedded-copies.mjs). Zero imports, so
+ * the generator copies it verbatim.
+ */
+export interface PlatformGlossaryTerm {
+    name: string;
+    definition: string;
+}
+export declare const PLATFORM_GLOSSARY_TERMS: readonly PlatformGlossaryTerm[];
+/** The platform terms a free-text search names: every query word (case-insensitive) appears in the
+ *  term's name. Queries shorter than two characters match nothing, like the entry search. */
+export declare function matchPlatformGlossaryTerms(query: string): PlatformGlossaryTerm[];
+//# sourceMappingURL=platformGlossary.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"platformGlossary.d.ts","sourceRoot":"","sources":["../../src/lib/platformGlossary.ts"],"names":[],"mappings":"AAIA;;;;;;;;;GASG;AAEH,MAAM,WAAW,oBAAoB;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;CACnB;AAED,eAAO,MAAM,uBAAuB,EAAE,SAAS,oBAAoB,EAKlE,CAAC;AAEF;6FAC6F;AAC7F,wBAAgB,0BAA0B,CAAC,KAAK,EAAE,MAAM,GAAG,oBAAoB,EAAE,CAOhF"}

package/dist/lib/platformGlossary.js

@@ -0,0 +1,21 @@
+// GENERATED by scripts/generate-mcp-embedded-copies.mjs from kernel/governance/platformGlossary.ts.
+// DO NOT EDIT. Run `npm run mcp:embedded-copies` to regenerate.
+// Local runtime copy for the isolated connector build.
+export const PLATFORM_GLOSSARY_TERMS = [
+    { name: 'Team', definition: 'A group of people and agents working toward one purpose; its roles own its decisions, rules and work.' },
+    { name: 'Team Lead', definition: 'The role accountable for a team\'s purpose; it decides anything that belongs to a role nobody holds.' },
+    { name: 'Role', definition: 'A named set of responsibilities a person holds; whoever sits in it decides and accepts the entries it owns.' },
+    { name: 'Tension', definition: 'A gap someone notices between how things are and how they should be; linking one to an entry is how you say you disagree with it.' },
+];
+/** The platform terms a free-text search names: every query word (case-insensitive) appears in the
+ *  term's name. Queries shorter than two characters match nothing, like the entry search. */
+export function matchPlatformGlossaryTerms(query) {
+    const words = query.toLowerCase().split(/\s+/).filter(Boolean);
+    if (query.trim().length < 2 || words.length === 0)
+        return [];
+    return PLATFORM_GLOSSARY_TERMS.filter((term) => {
+        const name = term.name.toLowerCase();
+        return words.every((word) => name.includes(word));
+    });
+}
+//# sourceMappingURL=platformGlossary.js.map

package/dist/lib/platformGlossary.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"platformGlossary.js","sourceRoot":"","sources":["../../src/lib/platformGlossary.ts"],"names":[],"mappings":"AAAA,oGAAoG;AACpG,gEAAgE;AAChE,uDAAuD;AAkBvD,MAAM,CAAC,MAAM,uBAAuB,GAAoC;IACvE,EAAE,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,uGAAuG,EAAE;IACrI,EAAE,IAAI,EAAE,WAAW,EAAE,UAAU,EAAE,sGAAsG,EAAE;IACzI,EAAE,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,6GAA6G,EAAE;IAC3I,EAAE,IAAI,EAAE,SAAS,EAAE,UAAU,EAAE,mIAAmI,EAAE;CACpK,CAAC;AAEF;6FAC6F;AAC7F,MAAM,UAAU,0BAA0B,CAAC,KAAa;IACvD,MAAM,KAAK,GAAG,KAAK,CAAC,WAAW,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IAC/D,IAAI,KAAK,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IAC7D,OAAO,uBAAuB,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE;QAC9C,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC;QACrC,OAAO,KAAK,CAAC,KAAK,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC;IACnD,CAAC,CAAC,CAAC;AACJ,CAAC"}

package/dist/lib/previewBanner.d.ts

@@ -0,0 +1,9 @@
+import type { Command } from 'commander';
+/**
+ * Print a loud PREVIEW banner to stderr when pb is bound to a throwaway preview.
+ *
+ * This is intentionally synchronous and never throws: it must not disrupt command
+ * execution, JSON stdout, or the root command lifecycle.
+ */
+export declare function printPreviewBanner(actionCommand: Command): void;
+//# sourceMappingURL=previewBanner.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"previewBanner.d.ts","sourceRoot":"","sources":["../../src/lib/previewBanner.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAiBzC;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,aAAa,EAAE,OAAO,GAAG,IAAI,CAiB/D"}

package/dist/lib/previewBanner.js

@@ -0,0 +1,37 @@
+import { getPreviewBinding } from './config.js';
+import { bold, yellow } from './style.js';
+/** Top-level Chain-write commands that need the throwaway-writes advisory. */
+const PREVIEW_WRITE_COMMANDS = new Set([
+    'capture',
+    'update',
+    'verify',
+    'promote',
+    'relate',
+    'unrelate',
+    'ingest',
+    'accept',
+    'reject',
+]);
+/**
+ * Print a loud PREVIEW banner to stderr when pb is bound to a throwaway preview.
+ *
+ * This is intentionally synchronous and never throws: it must not disrupt command
+ * execution, JSON stdout, or the root command lifecycle.
+ */
+export function printPreviewBanner(actionCommand) {
+    try {
+        const binding = getPreviewBinding();
+        if (!binding)
+            return;
+        const name = binding.workspaceName ?? 'preview';
+        process.stderr.write(yellow(bold(`⚠ PREVIEW ${name} — writes are throwaway. npm run pb:real to return to the real Chain`)) + '\n');
+        const isTopLevel = actionCommand.parent?.name() === 'pb';
+        if (isTopLevel && PREVIEW_WRITE_COMMANDS.has(actionCommand.name())) {
+            process.stderr.write('  → real learnings belong in the real Chain. Switch back with: npm run pb:real\n');
+        }
+    }
+    catch {
+        // Never let the banner crash the CLI.
+    }
+}
+//# sourceMappingURL=previewBanner.js.map

package/dist/lib/previewBanner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"previewBanner.js","sourceRoot":"","sources":["../../src/lib/previewBanner.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAE1C,8EAA8E;AAC9E,MAAM,sBAAsB,GAAG,IAAI,GAAG,CAAC;IACrC,SAAS;IACT,QAAQ;IACR,QAAQ;IACR,SAAS;IACT,QAAQ;IACR,UAAU;IACV,QAAQ;IACR,QAAQ;IACR,QAAQ;CACT,CAAC,CAAC;AAEH;;;;;GAKG;AACH,MAAM,UAAU,kBAAkB,CAAC,aAAsB;IACvD,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,iBAAiB,EAAE,CAAC;QACpC,IAAI,CAAC,OAAO;YAAE,OAAO;QACrB,MAAM,IAAI,GAAG,OAAO,CAAC,aAAa,IAAI,SAAS,CAAC;QAChD,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,MAAM,CAAC,IAAI,CAAC,aAAa,IAAI,sEAAsE,CAAC,CAAC,GAAG,IAAI,CAC7G,CAAC;QACF,MAAM,UAAU,GAAG,aAAa,CAAC,MAAM,EAAE,IAAI,EAAE,KAAK,IAAI,CAAC;QACzD,IAAI,UAAU,IAAI,sBAAsB,CAAC,GAAG,CAAC,aAAa,CAAC,IAAI,EAAE,CAAC,EAAE,CAAC;YACnE,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,kFAAkF,CACnF,CAAC;QACJ,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,sCAAsC;IACxC,CAAC;AACH,CAAC"}

package/dist/lib/productbrain-files.d.ts

@@ -0,0 +1,108 @@
+/**
+ * The .productbrain file-contract brain (WP-471 / WP-3, DEC-1382 / DEC-1383).
+ * Pure classification + gitignore exposure logic; all I/O is injected so the
+ * core is deterministic and testable. Git ignore-status is a cross-check, not
+ * the primary classifier — classification comes from DESCRIPTORS (what pb
+ * writes); only a present-but-undescribed entry falls back to ignore-status.
+ */
+/** What a .productbrain path IS — drives display grouping AND gitignore expectation. */
+export type FileKind = 'pb-secret' | 'pb-owned' | 'committed' | 'local';
+/** gitignore expectation → drives the exposure warning + --fix. */
+export type GitignoreRule = 'must' | 'should' | 'no';
+/** A declared pb write-target. Descriptors NEVER declare 'committed' (that is the residual). */
+export interface FileDescriptor {
+    /** Path relative to .productbrain/ (a dir ends with '/'). */
+    pattern: string;
+    kind: Exclude<FileKind, 'committed'>;
+    /** "what writes this" — human answer. */
+    writer: string;
+    /** "when" — human trigger. */
+    when: string;
+    gitignore: GitignoreRule;
+    /** FUTURE headroom (skill/hook/playbook packages); ships no machinery now. */
+    portable?: boolean;
+}
+export interface ClassifiedFile {
+    path: string;
+    kind: FileKind;
+    writer: string;
+    when: string;
+    present: boolean;
+    gitignored: boolean | null;
+    exposed: boolean;
+}
+/** The pb-owned write-targets. Annotation of what pb writes — NOT the per-repo file list. */
+export declare const DESCRIPTORS: FileDescriptor[];
+export interface ClassifyDeps {
+    /** Entries present directly under .productbrain/ (dirs suffixed with '/'). */
+    presentEntries: string[];
+    /** Is `.productbrain/<entry>` gitignored? null when git is unavailable. */
+    isIgnored: (relUnderRepo: string) => boolean | null;
+}
+/**
+ * Classify the full contract: every descriptor (present or absent) plus any
+ * present-but-undescribed entry. Pure — no fs/git here.
+ */
+export declare function classifyTree(deps: ClassifyDeps): ClassifiedFile[];
+/**
+ * Resolve the .productbrain root. Prefer a git toplevel that carries a .productbrain
+ * (isToplevel=true — the only root safe for --fix writes). Else the config-anchored root
+ * (lib/config.ts:73; isToplevel=false — findProjectRoot can walk ABOVE the git toplevel, so
+ * --fix must refuse). Else null → not a pb project. `git` = git reachable. Never throws.
+ */
+export declare function resolvePbRoot(cwd?: string): {
+    root: string | null;
+    git: boolean;
+    isToplevel: boolean;
+};
+export { makeGitTrackedChecker } from './projectConfig.js';
+/** Entries directly under <root>/.productbrain; dirs suffixed with '/'. [] if absent. */
+export declare function listProductbrainEntries(root: string): string[];
+/**
+ * Per-path git ignore-status checker. Uses execFileSync (argv array, NO shell) so a
+ * malicious .productbrain filename like `$(...)` is passed to git literally, never evaluated.
+ * `git check-ignore <path>` exits 0 when ignored (composing ALL .gitignore files), exit 1 when
+ * not — a non-zero exit is NOT an error here. Git unavailable (ENOENT / status 128) → null. Never throws.
+ */
+export declare function makeGitIgnoreChecker(root: string): (rel: string) => boolean | null;
+export interface Exposure {
+    path: string;
+    kind: FileKind;
+    severity: 'high' | 'mild';
+}
+/** Present must/should descriptors that are not gitignored → exposures. */
+export declare function detectExposures(rows: ClassifiedFile[]): Exposure[];
+/** .gitignore lines for must/should descriptors not currently ignored (preemptive). */
+export declare function planGitignoreLines(rows: ClassifiedFile[]): string[];
+/**
+ * Git-ignore what `pb connect` just wrote under `<folder>/.productbrain/` (TEN-2598, TASK-641): the
+ * DESCRIPTORS rows `pb connect` writes, through the same applyGitignoreFix `pb files --fix` uses.
+ * The line goes in the git toplevel's .gitignore WITH the folder's prefix — the pin lives in the
+ * connected folder, and a root `.productbrain/x` line does not cover a subfolder's `.productbrain`.
+ * Outside git nothing is written. `stillExposed` names a path git still does not ignore (tracked,
+ * a negation rule wins, or the write failed — then `writeError` says so) — the caller warns. Never
+ * throws: the profile and pin are already written, so a .gitignore problem must not abort connect.
+ */
+export declare function sealConnectWrites(folder: string): {
+    git: boolean;
+    added: string[];
+    stillExposed: string[];
+    writeError?: string;
+};
+/**
+ * A path as a gitignore line that matches only itself: `\ [ ] * ?` are glob syntax anywhere, a
+ * leading `!`/`#` is a negation/comment, and trailing spaces are dropped — each is `\`-escaped.
+ */
+export declare function gitignoreLiteral(path: string): string;
+/** Idempotent append to <root>/.gitignore. dryRun → compute only. A line already present is
+ * skipped, never duplicated. A path that stays exposed despite its line — a negation rule
+ * (root-anchored, or a lower-level .productbrain/.gitignore git gives precedence, overriding it)
+ * — is NOT out-appended here (that only grows the file unboundedly and can't beat a nested file);
+ * the caller re-probes git after the write and reports any such path via stillExposed. */
+export declare function applyGitignoreFix(root: string, lines: string[], opts: {
+    dryRun: boolean;
+}): {
+    added: string[];
+    skipped: string[];
+};
+//# sourceMappingURL=productbrain-files.d.ts.map

package/dist/lib/productbrain-files.d.ts.map

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