@productbrain/cli 0.1.0-beta.55 → 0.1.0-beta.5504

package/dist/lib/workspaceNotice.d.ts

@@ -0,0 +1,202 @@
+/**
+ * WP-1 — Loud workspace identity on every Chain write. WP-714 S3 extended this to every
+ * Chain READ too (see `emitEffectiveTenantNotice`'s doc comment below for the read-path wiring).
+ *
+ * Running `pb` from a directory with no repo pin (e.g. `~/`) silently resolves the
+ * GLOBAL profile and writes to whichever Chain that points at — proven live: captures
+ * meant for one workspace landed on another. This module makes every Chain read or write
+ * NAME its target workspace on stderr, and qualifies the line LOUDLY when the binding is an
+ * unpinned fallback (`global`/`default` — no repo pin) so a wrong-Chain call is never
+ * silent. An explicit binding (`local`/`env`) gets a plain, non-alarming line.
+ *
+ * Label source — the PROFILE SLUG only, via `resolveReportedProfile()`: it returns
+ * `missing-pin` when the credential cascade has ALREADY refused (nothing to name — see the
+ * formatter below), and otherwise delegates to `resolveEffectiveProfile()`, whose contract
+ * the rest of this paragraph describes.
+ * Deliberately NOT a workspace-name probe: `resolveEffectiveProfile()` reports the
+ * *configured* pin even when it dangles (TEN-2163), while a probe resolves what
+ * `resolveConfig()` actually binds. On a dangling local pin the two DISAGREE — the
+ * profile says `source='local'` (a plain, reassuring line) while the probe returns the
+ * GLOBAL workspace the write really drifts to. That would print a non-alarming line over
+ * the exact silent-drift this notice exists to expose. One resolution path means the
+ * label and its qualifier can never contradict — and there is no per-write network
+ * round-trip in front of the write.
+ *
+ * Output contract — follows capture.ts's grounding banner (the JSON-safety pattern):
+ *  - The notice is written to STDERR, never stdout, so strict-JSON stdout is byte-for-byte
+ *    unchanged in every mode.
+ *  - There is NO output-mode gate at all (WP-721). Every mode — `--json`, `--quiet`, plain TTY —
+ *    gets the one-line-per-process identity notice. `--json` used to suppress the plain line for
+ *    an explicit binding, which left an agent in a correctly pinned repo with a ZERO-BYTE stderr
+ *    and no tenant signal whatsoever (see `emitEffectiveTenantNotice` below). TEN-3238 had
+ *    already exempted the unpinned-fallback WARNING from that gate; WP-721 removed the gate.
+ *
+ * NOT compared here: the repo-local pin against the globally active `pb` profile (DEC-1632,
+ * TEN-3398/WP-720 — reversing part of WP-714 S3/PR #823). An earlier version of this module
+ * warned on that divergence on every read and write. But the pin exists precisely to OVERRIDE
+ * global, and `pb profile use` reconciles the two by default (`--local`/`--global` are the
+ * opt-in ways to diverge them) — so a divergence is only ever a deliberate act, never drift.
+ * Warning on it forever trained operators to ignore the warning: one global profile and ten
+ * pinned workspaces means nine permanent warnings on entirely correct setups. That comparison
+ * belongs at the POINT OF ACTION instead — `pb profile use --global <name>` says so once, right
+ * when an operator creates the divergence (see `commands/profile.ts`'s `pinnedElsewhere` note) —
+ * never ambiently on every read or write after the fact. The three comparisons that DO still
+ * belong here share one shape pin-vs-global didn't: *the effective tenant is not what your
+ * binding SAYS* — no explicit binding at all (the unpinned-fallback warning below), a credential
+ * silently overriding the binding (`env-key`/`local-key`/`cwd-key`, in the loud set below), or
+ * the binding moving mid-session (`sessionBinding.ts`'s refusal). Pin-vs-global was a different
+ * comparison that got mistaken for one of these.
+ *
+ * SSOT: one pure formatter + one thin emitter — called explicitly from the 7 write-command
+ * files (8 call sites) and once per process from the shared kernel wrapper (`client.ts`'s
+ * `kernelCall`/`kernelCallEnvelope`/`kernelCallWithSession` — TEN-3398/WP-711 follow-up wired
+ * the write path in too, see `emitEffectiveTenantNotice`'s doc comment below) — no per-command
+ * copy-paste.
+ *
+ * `pb admin` is a SEPARATE credential cascade (`adminConfig.ts`'s `resolveAdminConfig`) that
+ * deliberately excludes committed `config.json` siteUrl + CWD env files (TEN-1334) — it can
+ * resolve a different tenant than the cascade above, so it gets its own formatter-reusing
+ * emitter (`emitAdminTenantNotice`/`describeAdminTenantForRefusal` below) rather than sharing
+ * `emitEffectiveTenantNotice`'s guard or resolution path.
+ */
+import { type ReportedProfileSource } from './reportedProfile.js';
+import type { AdminConfigSource } from './adminConfig.js';
+import { assertSessionStillBound } from './sessionBinding.js';
+/** Inputs to the pure notice formatter. */
+export interface EffectiveTenantNoticeInput {
+    /** Effective profile name (the configured pin / identity), or null when unconfigured. */
+    profile: string | null;
+    /** Where that profile came from — see resolveReportedProfile(). */
+    source: ReportedProfileSource;
+}
+/**
+ * Build the one-line target-workspace notice — or null when there is nothing to say.
+ *
+ *  - `none`               → null (not configured: nothing to name, stay silent).
+ *  - `missing-pin`        → null (declared project, no pin: the CLI REFUSES this write, so
+ *                           there is no target workspace to name — and never `→ unknown`).
+ *  - `cwd-key`            → LOUD, unnamed (a dotenv file here picked the Chain — same shape as
+ *                           `env-key`, different file).
+ *  - `env-key`            → LOUD, unnamed (an exported PRODUCTBRAIN_API_KEY picked the Chain;
+ *                           no profile describes it, so the write goes somewhere this process
+ *                           cannot name from config — TEN-3240).
+ *  - `preview`            → named + disposable (a deliberate `npm run pb:preview` binding; the
+ *                           PREVIEW banner already shouts, so this does not shout twice).
+ *  - `global` / `default` → qualified + hint (no repo pin → an unpinned fallback binding).
+ *  - `local` / `env`      → plain (an explicit, intentional binding).
+ *
+ * Pure: no IO. The display label is the profile slug — a single resolution path, so the
+ * label and the qualifier can never contradict each other. DEC-1632/TEN-3398: no longer
+ * compares the pin against the globally active profile — see this module's header comment.
+ */
+export declare function formatEffectiveTenantNotice({ profile, source }: EffectiveTenantNoticeInput): string | null;
+/**
+ * The ONE place a `(profile, source)` pair maps to a human-readable label — no "→" prefix, so
+ * it can be embedded in prose (the tenant notice's base line, and WP-715's session-binding
+ * refusal message) rather than only ever printed as a standalone line. `formatEffectiveTenantNotice`
+ * above is the notice-line caller; `describeCurrentTenant` further down is the prose caller.
+ */
+export declare function describeReportedTenant(profile: string | null, source: ReportedProfileSource): string | null;
+/**
+ * Full prose description of the tenant CURRENTLY IN PLAY, for embedding in a message whose
+ * whole point is naming it — e.g. the session-binding refusal at `sessionBinding.ts` (WP-715).
+ * Unlike `formatEffectiveTenantNotice`, this never drops a shadowed repo pin: it states it explicitly, so
+ * a refusal reading "expected X, found Y" can never render the SAME tenant on both sides (the
+ * bug this closes — `resolveEffectiveProfile().profile` is blind to a credential override, so it
+ * always named the pin even while a foreign key was the one actually in play). Always returns a
+ * string — never null/undefined — so a caller building a "found ..." sentence never has to
+ * supply its own fallback.
+ *
+ * Deliberately UNQUOTED, including the shadowed pin: `sessionBinding.ts`'s
+ * `found "${found}"` template is the one place that wraps this whole value in quotes (the same
+ * template quotes `expected` too), so quoting the pin here as well double-quoted its closing
+ * mark (`...pin "product-brain""`) — cosmetic, but it reads like a typo in the exact message an
+ * agent surfaces to a human. This function owns zero quoting; the template owns all of it.
+ */
+export declare function describeCurrentTenant(profile: string | null, source: ReportedProfileSource): string;
+/**
+ * Live-resolving wrapper for `client.ts`'s `describeCurrent` thunk (WP-715): re-runs
+ * `resolveReportedProfile()` — never `resolveEffectiveProfile()`, which is blind to a
+ * credential override — so a session-binding refusal always names the tenant a call would
+ * actually land in. Kept here, not client.ts, so that call site stays a one-liner.
+ */
+export declare function describeCurrentTenantForRefusal(): string;
+/** Test-only: reset the once-per-process guard between cases (mirrors resetReportedProfileSnapshot). */
+export declare function resetEffectiveTenantNoticeForTests(): void;
+/**
+ * Resolve identity and write the target notice to STDERR — for every Chain read OR write, in
+ * EVERY output mode. WP-714 S3: originally called only from the 8 explicit write call sites;
+ * then ALSO called once per process from `client.ts`'s `kernelCall`/`kernelCallEnvelope` (the
+ * plain, non-session read path), so every read command that reaches the kernel announces too.
+ *
+ * ALSO wired into `kernelCallWithSession` (the write path) directly (TEN-3398 / WP-711
+ * follow-up). This comment used to claim that wiring was unnecessary because "every write
+ * command already calls this explicitly" — that premise was false: a census of every command
+ * module reaching `kernelCallWithSession` found 11 write commands (`accept-policy.ts`,
+ * `audit.ts`, `conflicts.ts`, `direction.ts`, `feedback.ts`, `handshake.ts`, `method.ts`,
+ * `questions.ts`, `rework.ts`, `shape.ts`, `verify.ts`) that never called this at all — a
+ * silent write with no target-workspace line, `chain.verifyEntry` and `rework.report` among
+ * them. A handful of write commands (`capture`/`promote`/`relate`/`restore`/`session`/
+ * `update`, plus the shared `organisationWrite.ts`/`runOrganisationWrite` helper used by
+ * `organisation.ts`/`organisationHierarchy.ts`) still call it explicitly, earlier in their own
+ * flow than any call `kernelCallWithSession` makes (e.g. `update`'s post-write
+ * `chain.getEntry` refresh) — the once-per-process guard makes `kernelCallWithSession`'s own
+ * call a no-op for those, so their output is unchanged bit-for-bit.
+ *
+ * Takes NO output-mode argument (WP-721). It used to take a `json` boolean that suppressed the
+ * plain line for an explicit binding; that parameter existed only to feed the gate, so it went
+ * with the gate rather than lingering as an ignored argument inviting the gate's return. The
+ * full reasoning is at the (now unconditional) emit inside the body — in short: `--json` is how
+ * agents invoke pb, agents are the bulk of both readers and writers, and a one-line-per-process
+ * stderr receipt naming the target Chain is the signal, not the noise. TEN-3238 had already made
+ * the unpinned-fallback WARNING survive `--json` for the same reason; WP-721 finished the job for
+ * the identity line itself. Safe in every mode because the notice goes to STDERR, so strict JSON
+ * on stdout stays byte-for-byte unchanged (and the CLI already writes unconditional stderr
+ * warnings elsewhere, e.g. the preview-scrub misroute in config.ts).
+ *
+ * DEC-1632/TEN-3398: does NOT compare the repo-local pin against the globally active profile —
+ * removed entirely (see this module's header comment). A prior version attached a "differs
+ * from the globally active Chain profile" line here that survived `--json` (WP-714 S3, PR
+ * #823); that line is gone, not just re-gated, because the pin existing to override global was
+ * never a warning-worthy condition in the first place.
+ *
+ * Never throws and does no network IO: a wrong/unreadable config degrades to silence, and
+ * the label comes from `resolveReportedProfile()` — only fast local config reads (no probe)
+ * in front of the call. It is safe to call immediately before any Chain read or write.
+ */
+export declare function emitEffectiveTenantNotice(): Promise<void>;
+/**
+ * `pb admin`'s own identity, as `resolveAdminConfig()` actually resolved it — for
+ * `emitAdminTenantNotice`/`describeAdminTenantForRefusal` below (TEN-3398 / WP-711 follow-up).
+ */
+export interface AdminTenantIdentity {
+    profileName: string | null;
+    source: AdminConfigSource;
+}
+/** Test-only: reset admin's once-per-identity guard between cases. */
+export declare function resetAdminTenantNoticeForTests(): void;
+/**
+ * Resolve identity and write `pb admin`'s target notice to STDERR — once per DISTINCT identity
+ * per process (TEN-3398 / WP-711 follow-up: `adminCall` previously carried no notice at all,
+ * the one gap left after WP-712/WP-714 S3 covered every other kernel path).
+ *
+ * Unlike `emitEffectiveTenantNotice`, this NEVER suppresses under `--json` and has no
+ * "unpinned fallback" vs "explicit binding" distinction: every `pb admin` command can be a
+ * destructive bulk operation (`manage:delete-workspace`, `seed:backfill-starter`), so the
+ * identity line is never noise to cut, in any mode.
+ */
+export declare function emitAdminTenantNotice(admin: AdminTenantIdentity): void;
+/**
+ * Prose description of `pb admin`'s CURRENT tenant, for embedding in the
+ * `assertSessionStillBound` refusal message — mirrors `describeCurrentTenantForRefusal`'s role
+ * on the non-admin path, but resolved off `resolveAdminConfig()`'s own identity rather than
+ * `resolveReportedProfile()`, for the same reason `adminSourceToReportedSource` exists.
+ */
+export declare function describeAdminTenantForRefusal(admin: AdminTenantIdentity): string;
+/**
+ * Announce AND guard one `pb admin` call in a single call (TEN-3398 / WP-711 follow-up) — kept
+ * here, not `client.ts`'s `adminCall` (STD-2/DEC-1504 module-health budget), so `adminCall`
+ * stays a one-liner and this module owns the whole admin-identity story end to end.
+ */
+export declare function guardAdminCall(admin: AdminTenantIdentity, session: Parameters<typeof assertSessionStillBound>[0], fingerprint: string): void;
+//# sourceMappingURL=workspaceNotice.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"workspaceNotice.d.ts","sourceRoot":"","sources":["../../src/lib/workspaceNotice.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4DG;AAEH,OAAO,EAA0B,KAAK,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAE1F,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAC1D,OAAO,EAAE,uBAAuB,EAAE,MAAM,qBAAqB,CAAC;AAE9D,2CAA2C;AAC3C,MAAM,WAAW,0BAA0B;IACzC,yFAAyF;IACzF,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,mEAAmE;IACnE,MAAM,EAAE,qBAAqB,CAAC;CAC/B;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,2BAA2B,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,EAAE,0BAA0B,GAAG,MAAM,GAAG,IAAI,CAG1G;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,EAAE,MAAM,EAAE,qBAAqB,GAAG,MAAM,GAAG,IAAI,CAuB3G;AAmBD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,EAAE,MAAM,EAAE,qBAAqB,GAAG,MAAM,CAInG;AAED;;;;;GAKG;AACH,wBAAgB,+BAA+B,IAAI,MAAM,CAGxD;AAYD,wGAAwG;AACxG,wBAAgB,kCAAkC,IAAI,IAAI,CAEzD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,wBAAsB,yBAAyB,IAAI,OAAO,CAAC,IAAI,CAAC,CAuC/D;AAED;;;GAGG;AACH,MAAM,WAAW,mBAAmB;IAClC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,MAAM,EAAE,iBAAiB,CAAC;CAC3B;AAwCD,sEAAsE;AACtE,wBAAgB,8BAA8B,IAAI,IAAI,CAErD;AAED;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,mBAAmB,GAAG,IAAI,CAStE;AAED;;;;;GAKG;AACH,wBAAgB,6BAA6B,CAAC,KAAK,EAAE,mBAAmB,GAAG,MAAM,CAEhF;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,mBAAmB,EAC1B,OAAO,EAAE,UAAU,CAAC,OAAO,uBAAuB,CAAC,CAAC,CAAC,CAAC,EACtD,WAAW,EAAE,MAAM,GAClB,IAAI,CAGN"}

package/dist/lib/workspaceNotice.js

@@ -0,0 +1,345 @@
+/**
+ * WP-1 — Loud workspace identity on every Chain write. WP-714 S3 extended this to every
+ * Chain READ too (see `emitEffectiveTenantNotice`'s doc comment below for the read-path wiring).
+ *
+ * Running `pb` from a directory with no repo pin (e.g. `~/`) silently resolves the
+ * GLOBAL profile and writes to whichever Chain that points at — proven live: captures
+ * meant for one workspace landed on another. This module makes every Chain read or write
+ * NAME its target workspace on stderr, and qualifies the line LOUDLY when the binding is an
+ * unpinned fallback (`global`/`default` — no repo pin) so a wrong-Chain call is never
+ * silent. An explicit binding (`local`/`env`) gets a plain, non-alarming line.
+ *
+ * Label source — the PROFILE SLUG only, via `resolveReportedProfile()`: it returns
+ * `missing-pin` when the credential cascade has ALREADY refused (nothing to name — see the
+ * formatter below), and otherwise delegates to `resolveEffectiveProfile()`, whose contract
+ * the rest of this paragraph describes.
+ * Deliberately NOT a workspace-name probe: `resolveEffectiveProfile()` reports the
+ * *configured* pin even when it dangles (TEN-2163), while a probe resolves what
+ * `resolveConfig()` actually binds. On a dangling local pin the two DISAGREE — the
+ * profile says `source='local'` (a plain, reassuring line) while the probe returns the
+ * GLOBAL workspace the write really drifts to. That would print a non-alarming line over
+ * the exact silent-drift this notice exists to expose. One resolution path means the
+ * label and its qualifier can never contradict — and there is no per-write network
+ * round-trip in front of the write.
+ *
+ * Output contract — follows capture.ts's grounding banner (the JSON-safety pattern):
+ *  - The notice is written to STDERR, never stdout, so strict-JSON stdout is byte-for-byte
+ *    unchanged in every mode.
+ *  - There is NO output-mode gate at all (WP-721). Every mode — `--json`, `--quiet`, plain TTY —
+ *    gets the one-line-per-process identity notice. `--json` used to suppress the plain line for
+ *    an explicit binding, which left an agent in a correctly pinned repo with a ZERO-BYTE stderr
+ *    and no tenant signal whatsoever (see `emitEffectiveTenantNotice` below). TEN-3238 had
+ *    already exempted the unpinned-fallback WARNING from that gate; WP-721 removed the gate.
+ *
+ * NOT compared here: the repo-local pin against the globally active `pb` profile (DEC-1632,
+ * TEN-3398/WP-720 — reversing part of WP-714 S3/PR #823). An earlier version of this module
+ * warned on that divergence on every read and write. But the pin exists precisely to OVERRIDE
+ * global, and `pb profile use` reconciles the two by default (`--local`/`--global` are the
+ * opt-in ways to diverge them) — so a divergence is only ever a deliberate act, never drift.
+ * Warning on it forever trained operators to ignore the warning: one global profile and ten
+ * pinned workspaces means nine permanent warnings on entirely correct setups. That comparison
+ * belongs at the POINT OF ACTION instead — `pb profile use --global <name>` says so once, right
+ * when an operator creates the divergence (see `commands/profile.ts`'s `pinnedElsewhere` note) —
+ * never ambiently on every read or write after the fact. The three comparisons that DO still
+ * belong here share one shape pin-vs-global didn't: *the effective tenant is not what your
+ * binding SAYS* — no explicit binding at all (the unpinned-fallback warning below), a credential
+ * silently overriding the binding (`env-key`/`local-key`/`cwd-key`, in the loud set below), or
+ * the binding moving mid-session (`sessionBinding.ts`'s refusal). Pin-vs-global was a different
+ * comparison that got mistaken for one of these.
+ *
+ * SSOT: one pure formatter + one thin emitter — called explicitly from the 7 write-command
+ * files (8 call sites) and once per process from the shared kernel wrapper (`client.ts`'s
+ * `kernelCall`/`kernelCallEnvelope`/`kernelCallWithSession` — TEN-3398/WP-711 follow-up wired
+ * the write path in too, see `emitEffectiveTenantNotice`'s doc comment below) — no per-command
+ * copy-paste.
+ *
+ * `pb admin` is a SEPARATE credential cascade (`adminConfig.ts`'s `resolveAdminConfig`) that
+ * deliberately excludes committed `config.json` siteUrl + CWD env files (TEN-1334) — it can
+ * resolve a different tenant than the cascade above, so it gets its own formatter-reusing
+ * emitter (`emitAdminTenantNotice`/`describeAdminTenantForRefusal` below) rather than sharing
+ * `emitEffectiveTenantNotice`'s guard or resolution path.
+ */
+import { resolveReportedProfile } from './reportedProfile.js';
+import { readLocalProjectConfig } from './projectConfig.js';
+import { assertSessionStillBound } from './sessionBinding.js';
+/**
+ * Build the one-line target-workspace notice — or null when there is nothing to say.
+ *
+ *  - `none`               → null (not configured: nothing to name, stay silent).
+ *  - `missing-pin`        → null (declared project, no pin: the CLI REFUSES this write, so
+ *                           there is no target workspace to name — and never `→ unknown`).
+ *  - `cwd-key`            → LOUD, unnamed (a dotenv file here picked the Chain — same shape as
+ *                           `env-key`, different file).
+ *  - `env-key`            → LOUD, unnamed (an exported PRODUCTBRAIN_API_KEY picked the Chain;
+ *                           no profile describes it, so the write goes somewhere this process
+ *                           cannot name from config — TEN-3240).
+ *  - `preview`            → named + disposable (a deliberate `npm run pb:preview` binding; the
+ *                           PREVIEW banner already shouts, so this does not shout twice).
+ *  - `global` / `default` → qualified + hint (no repo pin → an unpinned fallback binding).
+ *  - `local` / `env`      → plain (an explicit, intentional binding).
+ *
+ * Pure: no IO. The display label is the profile slug — a single resolution path, so the
+ * label and the qualifier can never contradict each other. DEC-1632/TEN-3398: no longer
+ * compares the pin against the globally active profile — see this module's header comment.
+ */
+export function formatEffectiveTenantNotice({ profile, source }) {
+    const label = describeReportedTenant(profile, source);
+    return label ? `→ ${label}` : null;
+}
+/**
+ * The ONE place a `(profile, source)` pair maps to a human-readable label — no "→" prefix, so
+ * it can be embedded in prose (the tenant notice's base line, and WP-715's session-binding
+ * refusal message) rather than only ever printed as a standalone line. `formatEffectiveTenantNotice`
+ * above is the notice-line caller; `describeCurrentTenant` further down is the prose caller.
+ */
+export function describeReportedTenant(profile, source) {
+    if (source === 'none' || source === 'missing-pin')
+        return null;
+    // Deliberately NOT "unknown": that reads as "a workspace whose name we failed to look up".
+    // Here there is no name to look up — the credential itself chose the Chain, so the honest
+    // line names the credential and the repair (TEN-3240).
+    if (source === 'env-key') {
+        return 'unnamed workspace (PRODUCTBRAIN_API_KEY — the exported key picks the Chain, not a profile)';
+    }
+    if (source === 'cwd-key') {
+        return 'unnamed workspace (a dotenv file in this directory picks the Chain, not a profile)';
+    }
+    if (source === 'local-key') {
+        return 'unnamed workspace (config.local.json binds a credential directly, not a profile)';
+    }
+    const name = profile?.trim() || 'unknown';
+    // Deliberate and disposable: the operator ran `npm run pb:preview`, and index.ts already prints
+    // a loud PREVIEW banner on every command — so this names the workspace without a second alarm.
+    if (source === 'preview')
+        return `${name} (throwaway preview — \`npm run pb:real\` to go back)`;
+    if (source === 'global' || source === 'default') {
+        return `${name} (global default — run from your project dir to use its workspace)`;
+    }
+    // 'local' | 'env' — an explicit, intentional binding.
+    return name;
+}
+/**
+ * The repo-local PIN a direct-credential binding overrides, when the repo declares one (WP-715).
+ * Meaningful only for the three sources where a `config.local.json` `profile` field can still be
+ * PRESENT while this process does not actually use it — a direct apiKey/env/dotenv binding
+ * outranks it (DEC-1607). Mirrors `whoami.ts`'s `shadowedPin` (previously computed ad hoc,
+ * env-key only, in that one command); generalized here to the whole outranking family so any
+ * caller naming the current tenant can state a shadowed pin rather than silently drop it.
+ */
+function resolveShadowedPin(source) {
+    if (source !== 'env-key' && source !== 'cwd-key' && source !== 'local-key')
+        return null;
+    try {
+        return readLocalProjectConfig()?.profile?.trim() || null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Full prose description of the tenant CURRENTLY IN PLAY, for embedding in a message whose
+ * whole point is naming it — e.g. the session-binding refusal at `sessionBinding.ts` (WP-715).
+ * Unlike `formatEffectiveTenantNotice`, this never drops a shadowed repo pin: it states it explicitly, so
+ * a refusal reading "expected X, found Y" can never render the SAME tenant on both sides (the
+ * bug this closes — `resolveEffectiveProfile().profile` is blind to a credential override, so it
+ * always named the pin even while a foreign key was the one actually in play). Always returns a
+ * string — never null/undefined — so a caller building a "found ..." sentence never has to
+ * supply its own fallback.
+ *
+ * Deliberately UNQUOTED, including the shadowed pin: `sessionBinding.ts`'s
+ * `found "${found}"` template is the one place that wraps this whole value in quotes (the same
+ * template quotes `expected` too), so quoting the pin here as well double-quoted its closing
+ * mark (`...pin "product-brain""`) — cosmetic, but it reads like a typo in the exact message an
+ * agent surfaces to a human. This function owns zero quoting; the template owns all of it.
+ */
+export function describeCurrentTenant(profile, source) {
+    const label = describeReportedTenant(profile, source) ?? 'a different, unrecorded workspace';
+    const shadowedPin = resolveShadowedPin(source);
+    return shadowedPin ? `${label}, shadowing pin ${shadowedPin}` : label;
+}
+/**
+ * Live-resolving wrapper for `client.ts`'s `describeCurrent` thunk (WP-715): re-runs
+ * `resolveReportedProfile()` — never `resolveEffectiveProfile()`, which is blind to a
+ * credential override — so a session-binding refusal always names the tenant a call would
+ * actually land in. Kept here, not client.ts, so that call site stays a one-liner.
+ */
+export function describeCurrentTenantForRefusal() {
+    const { profile, source } = resolveReportedProfile();
+    return describeCurrentTenant(profile, source);
+}
+/**
+ * Once-per-PROCESS guard (WP-714 S3). A `pb` invocation is one process, so this is really
+ * "once per command" — but a single command can reach this function many times (`pb orient`
+ * alone makes three separate `kernelCall`s). Set on the FIRST call regardless of outcome
+ * (silent 'none'/'missing-pin', json-suppressed, or an actual print): the resolved identity
+ * cannot change mid-process, so re-attempting on later calls would only ever repeat the same
+ * verdict — or, for a printed notice, repeat the same line.
+ */
+let hasAttemptedEffectiveTenantNotice = false;
+/** Test-only: reset the once-per-process guard between cases (mirrors resetReportedProfileSnapshot). */
+export function resetEffectiveTenantNoticeForTests() {
+    hasAttemptedEffectiveTenantNotice = false;
+}
+/**
+ * Resolve identity and write the target notice to STDERR — for every Chain read OR write, in
+ * EVERY output mode. WP-714 S3: originally called only from the 8 explicit write call sites;
+ * then ALSO called once per process from `client.ts`'s `kernelCall`/`kernelCallEnvelope` (the
+ * plain, non-session read path), so every read command that reaches the kernel announces too.
+ *
+ * ALSO wired into `kernelCallWithSession` (the write path) directly (TEN-3398 / WP-711
+ * follow-up). This comment used to claim that wiring was unnecessary because "every write
+ * command already calls this explicitly" — that premise was false: a census of every command
+ * module reaching `kernelCallWithSession` found 11 write commands (`accept-policy.ts`,
+ * `audit.ts`, `conflicts.ts`, `direction.ts`, `feedback.ts`, `handshake.ts`, `method.ts`,
+ * `questions.ts`, `rework.ts`, `shape.ts`, `verify.ts`) that never called this at all — a
+ * silent write with no target-workspace line, `chain.verifyEntry` and `rework.report` among
+ * them. A handful of write commands (`capture`/`promote`/`relate`/`restore`/`session`/
+ * `update`, plus the shared `organisationWrite.ts`/`runOrganisationWrite` helper used by
+ * `organisation.ts`/`organisationHierarchy.ts`) still call it explicitly, earlier in their own
+ * flow than any call `kernelCallWithSession` makes (e.g. `update`'s post-write
+ * `chain.getEntry` refresh) — the once-per-process guard makes `kernelCallWithSession`'s own
+ * call a no-op for those, so their output is unchanged bit-for-bit.
+ *
+ * Takes NO output-mode argument (WP-721). It used to take a `json` boolean that suppressed the
+ * plain line for an explicit binding; that parameter existed only to feed the gate, so it went
+ * with the gate rather than lingering as an ignored argument inviting the gate's return. The
+ * full reasoning is at the (now unconditional) emit inside the body — in short: `--json` is how
+ * agents invoke pb, agents are the bulk of both readers and writers, and a one-line-per-process
+ * stderr receipt naming the target Chain is the signal, not the noise. TEN-3238 had already made
+ * the unpinned-fallback WARNING survive `--json` for the same reason; WP-721 finished the job for
+ * the identity line itself. Safe in every mode because the notice goes to STDERR, so strict JSON
+ * on stdout stays byte-for-byte unchanged (and the CLI already writes unconditional stderr
+ * warnings elsewhere, e.g. the preview-scrub misroute in config.ts).
+ *
+ * DEC-1632/TEN-3398: does NOT compare the repo-local pin against the globally active profile —
+ * removed entirely (see this module's header comment). A prior version attached a "differs
+ * from the globally active Chain profile" line here that survived `--json` (WP-714 S3, PR
+ * #823); that line is gone, not just re-gated, because the pin existing to override global was
+ * never a warning-worthy condition in the first place.
+ *
+ * Never throws and does no network IO: a wrong/unreadable config degrades to silence, and
+ * the label comes from `resolveReportedProfile()` — only fast local config reads (no probe)
+ * in front of the call. It is safe to call immediately before any Chain read or write.
+ */
+export async function emitEffectiveTenantNotice() {
+    if (hasAttemptedEffectiveTenantNotice)
+        return;
+    hasAttemptedEffectiveTenantNotice = true;
+    let profile = null;
+    let source = 'none';
+    try {
+        ({ profile, source } = resolveReportedProfile());
+    }
+    catch {
+        return; // unreadable/racing config — say nothing rather than crash a read or write.
+    }
+    if (source === 'none' || source === 'missing-pin')
+        return;
+    // WP-721: NO `json` gate. The identity line is emitted in every mode, for every source that
+    // has a tenant to name — an explicit `local`/`env` pin included. The loud QUALIFIER for the
+    // unpinned-fallback family still differs (`describeReportedTenant` owns it, unchanged); what
+    // no longer differs is whether an agent is told anything at all.
+    //
+    // The removed gate was justified as "the plain line carries no warning, so it is pure noise in
+    // agent logs". That reasoning does not survive the shape of the thing: this is ONE line per
+    // PROCESS (the `hasAttemptedEffectiveTenantNotice` guard above), on STDERR, naming the tenant a
+    // read or write is about to touch. For an agent that is not noise — it is the receipt for the
+    // exact safety property this module exists to provide, and WP-715 states the standard outright:
+    // "Agents are the primary consumers of the pb CLI and invoke it with --json. A guard that
+    // renders only in human TTY output is, for the bulk of real usage, not shipped."
+    //
+    // The gate went unnoticed because a SECOND line — the pin-vs-global disagreement NOTICE — used
+    // to survive `--json` and happened to carry the tenant name. DEC-1632 removed that comparison
+    // (correctly: a pin exists to override global, so a divergence is deliberate, and warning on it
+    // forever is fatigue), and with it the last thing an agent saw. Proven live on
+    // `@productbrain/cli@0.1.0-beta.5421`: `pb get WP-711 --json 2>err` left `err` at ZERO BYTES in
+    // a correctly pinned repo. DEC-1632's fatigue argument was about a WARNING that fires on
+    // correct setups, never about a single identity line — so restoring this line does NOT
+    // reintroduce that comparison, and must not: see this module's header comment.
+    //
+    // Safe in every mode for the same reason the unpinned-fallback warning already was (TEN-3238):
+    // it goes to STDERR, so strict JSON on stdout stays byte-for-byte unchanged.
+    const notice = formatEffectiveTenantNotice({ profile, source });
+    if (notice)
+        process.stderr.write(notice + '\n');
+}
+/**
+ * Map `resolveAdminConfig()`'s `AdminConfigSource` onto the read/write notice's
+ * `ReportedProfileSource` vocabulary, so `pb admin` reuses the SAME formatter and label rules
+ * (`formatEffectiveTenantNotice`/`describeReportedTenant`) instead of a parallel copy. This is
+ * deliberately NOT a call to `resolveReportedProfile()` — that walks a DIFFERENT cascade
+ * (`config.ts`'s `resolveConfig`, which DOES read committed `config.json` siteUrl + CWD env
+ * files) and can disagree with what `resolveAdminConfig()` actually resolved, which would name
+ * a tenant this admin call is not actually about to use. `'legacy'` (the nameless
+ * `~/.config/productbrain/.env` fallback) has no direct analog in `ReportedProfileSource` — it
+ * maps to `'default'`, the closest existing "implicit, no deliberate per-repo pin" qualifier.
+ */
+function adminSourceToReportedSource(source) {
+    switch (source) {
+        case 'env': return 'env-key';
+        case 'local-profile': return 'local';
+        case 'global-profile': return 'global';
+        case 'legacy': return 'default';
+    }
+}
+/** Admin's own once-per-process guard — separate from `hasAttemptedEffectiveTenantNotice`
+ * above, because `resolveAdminConfig()`'s cascade is a different resolution than the one that
+ * guard's notice announces.
+ *
+ * Keyed by IDENTITY (`source:profileName`), not a single boolean (TEN-3398 follow-up,
+ * `admin/probe.ts`): `pb admin probe --env prod --env dev` resolves TWO genuinely different
+ * named-profile identities in one process, by design (the whole point is comparing them side
+ * by side) — a single shared flag would announce the first and silently swallow the second,
+ * hiding exactly which tenant the comparison's second half hit. A Set still gives every OTHER
+ * admin command (one identity resolved once via `resolveAdminConfig()`, called through
+ * `adminCall` any number of times) the same "announce once" behavior a boolean gave, since
+ * repeat calls carry the identical key. */
+const announcedAdminTenantKeys = new Set();
+function adminIdentityKey(admin) {
+    return `${admin.source}:${admin.profileName ?? ''}`;
+}
+/** Test-only: reset admin's once-per-identity guard between cases. */
+export function resetAdminTenantNoticeForTests() {
+    announcedAdminTenantKeys.clear();
+}
+/**
+ * Resolve identity and write `pb admin`'s target notice to STDERR — once per DISTINCT identity
+ * per process (TEN-3398 / WP-711 follow-up: `adminCall` previously carried no notice at all,
+ * the one gap left after WP-712/WP-714 S3 covered every other kernel path).
+ *
+ * Unlike `emitEffectiveTenantNotice`, this NEVER suppresses under `--json` and has no
+ * "unpinned fallback" vs "explicit binding" distinction: every `pb admin` command can be a
+ * destructive bulk operation (`manage:delete-workspace`, `seed:backfill-starter`), so the
+ * identity line is never noise to cut, in any mode.
+ */
+export function emitAdminTenantNotice(admin) {
+    const key = adminIdentityKey(admin);
+    if (announcedAdminTenantKeys.has(key))
+        return;
+    announcedAdminTenantKeys.add(key);
+    const notice = formatEffectiveTenantNotice({
+        profile: admin.profileName,
+        source: adminSourceToReportedSource(admin.source),
+    });
+    if (notice)
+        process.stderr.write(notice + '\n');
+}
+/**
+ * Prose description of `pb admin`'s CURRENT tenant, for embedding in the
+ * `assertSessionStillBound` refusal message — mirrors `describeCurrentTenantForRefusal`'s role
+ * on the non-admin path, but resolved off `resolveAdminConfig()`'s own identity rather than
+ * `resolveReportedProfile()`, for the same reason `adminSourceToReportedSource` exists.
+ */
+export function describeAdminTenantForRefusal(admin) {
+    return describeCurrentTenant(admin.profileName, adminSourceToReportedSource(admin.source));
+}
+/**
+ * Announce AND guard one `pb admin` call in a single call (TEN-3398 / WP-711 follow-up) — kept
+ * here, not `client.ts`'s `adminCall` (STD-2/DEC-1504 module-health budget), so `adminCall`
+ * stays a one-liner and this module owns the whole admin-identity story end to end.
+ */
+export function guardAdminCall(admin, session, fingerprint) {
+    emitAdminTenantNotice(admin);
+    assertSessionStillBound(session, fingerprint, () => describeAdminTenantForRefusal(admin));
+}
+//# sourceMappingURL=workspaceNotice.js.map

package/dist/lib/workspaceNotice.js.map

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

package/dist/lib/workspaceVocabCache.d.ts

@@ -0,0 +1,60 @@
+/**
+ * 5-minute TTL cache for workspace vocabulary context (WP-436 S2).
+ *
+ * Purpose (R2 mitigation): the CLI resolves vocabulary labels on every invocation.
+ * Without a cache, each `pb orient` / `pb get` / `pb capture` would call
+ * `chain.getVocabulary` — adding a Convex round-trip overhead and risking
+ * handshake-time staleness. A 5-min TTL short-circuits repeat calls within
+ * a typical session while staying fresh enough that label changes land quickly.
+ *
+ * PAT-230: the cache holds WorkspaceVocabCtx (pure data, no Convex imports here).
+ * DEC-1021: only Axis 2 (collectionLabels) lives here; Axis 1 (displayNames) is untouched.
+ *
+ * S4 note: when Cortex UI builds its `vocabularyStore`, it should mirror this
+ * contract — a keyed map by workspaceId with an expiresAt field (Cortex has
+ * direct access to workspaceId; the CLI uses apiKey as a 1:1 surrogate, since
+ * the HTTP gateway server-side injects workspaceId from authResult per
+ * convex/http.ts:675).
+ */
+import type { WorkspaceVocabCtx } from './canonicalRefs.js';
+/**
+ * Get a cached WorkspaceVocabCtx by cacheKey, or null if expired/missing.
+ * Prints a staleness warning when the entry is older than STALE_WARN_MS.
+ */
+export declare function getCachedVocabCtx(cacheKey: string): WorkspaceVocabCtx | null;
+/**
+ * Store a WorkspaceVocabCtx under cacheKey with a 5-min TTL.
+ */
+export declare function setCachedVocabCtx(cacheKey: string, ctx: WorkspaceVocabCtx): void;
+/**
+ * Explicitly invalidate a cached vocab context by cacheKey.
+ * Call this when `updateCollectionLabels` mutation succeeds (e.g. after `pb handshake`).
+ */
+export declare function invalidateVocabCtx(cacheKey: string): void;
+/**
+ * Clear all cached entries (useful for testing or `pb handshake --refresh`).
+ */
+export declare function clearVocabCache(): void;
+/**
+ * Get the cached vocab context, or fetch it via the provided async fetcher on cache miss.
+ *
+ * Usage pattern at CLI command sites:
+ * ```ts
+ * const vocabCtx = await getOrFetchVocabCtx(config.apiKey, async () => {
+ *   type VocabResult = { collectionLabels?: Record<string, unknown> };
+ *   const vocab = await kernelCall<VocabResult>('chain.getVocabulary', {});
+ *   return vocab?.collectionLabels
+ *     ? { collectionLabels: vocab.collectionLabels as WorkspaceVocabCtx['collectionLabels'] }
+ *     : null;
+ * });
+ * ```
+ *
+ * - `cacheKey`: use the API key as a surrogate for cacheKey (1:1 mapping at CLI layer).
+ * - `fetcher`: async function that resolves the vocab ctx; returns null on failure to signal
+ *   "don't cache, fall back to resolver literal". Fetcher errors are swallowed — vocabulary
+ *   labels are advisory (PAT-230 / fail-open principle).
+ *
+ * Returns WorkspaceVocabCtx on cache hit or successful fetch; undefined on error/null fetcher result.
+ */
+export declare function getOrFetchVocabCtx(cacheKey: string, fetcher: () => Promise<WorkspaceVocabCtx | null>): Promise<WorkspaceVocabCtx | undefined>;
+//# sourceMappingURL=workspaceVocabCache.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"workspaceVocabCache.d.ts","sourceRoot":"","sources":["../../src/lib/workspaceVocabCache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAc5D;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,iBAAiB,GAAG,IAAI,CAe5E;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,iBAAiB,GAAG,IAAI,CAEhF;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAEzD;AAED;;GAEG;AACH,wBAAgB,eAAe,IAAI,IAAI,CAEtC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,kBAAkB,CACtC,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAAC,GAC/C,OAAO,CAAC,iBAAiB,GAAG,SAAS,CAAC,CAcxC"}