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

package/dist/lib/versionWrite.d.ts

@@ -0,0 +1,65 @@
+/**
+ * WP-755 C2 (TASK-216, DEC-1717) — the version-write mapping, shared across all three
+ * connectors via the existing embedded-copy generator (kernel/quality/spineVerdictRead.ts's
+ * own precedent — connectors never import kernel/ at runtime; generated copies do. Run
+ * `npm run mcp:embedded-copies` after editing this file). Pure: no Convex, no DB, no
+ * inference. The caller resolves the TARGET entry's prose field key (decisions→'rationale',
+ * glossary→'canonical', assumptions→'belief', else 'description'/'body' —
+ * convex/lib/proseField.ts's resolveProseFieldKey, or each connector's already-fetched
+ * collection profile) and supplies exactly the fields it would have sent to create. Nothing
+ * here infers a schema default, a date, or a full-collection replacement — a version write
+ * only ever touches what the capture explicitly named (contrast the reuse-draft/commit-retry
+ * UPDATE path, which legitimately does a full replacement because it owns the whole draft;
+ * a version write edits someone else's already-accepted entry and must not wipe the rest).
+ */
+export interface VersionWriteCapture {
+    /** The capture's own explicit title, when the caller has a REAL one — omit (undefined)
+     *  otherwise. Never pass a placeholder ('Untitled', ''): a version write must not rename
+     *  the target to a placeholder just because the capture UI had no title yet. */
+    name?: string;
+    /** The capture's prose body, written to the TARGET's own prose field. */
+    prose: string;
+    /** Explicit structured fields the caller parsed (CLI's --field key=value / MCP's `data`
+     *  passthrough) — never schema defaults, never inferred dates. */
+    fields?: Record<string, unknown>;
+}
+export interface VersionWritePatch {
+    name?: string;
+    data: Record<string, unknown>;
+}
+/** Build the `{name?, data}` patch chain.updateEntry / entries.update expects. An empty (or
+ *  whitespace-only) prose body is never written — a capture with no real body text must not
+ *  blank out the target's existing prose field. */
+export declare function buildVersionPatch(params: {
+    capture: VersionWriteCapture;
+    targetProseKey: string;
+}): VersionWritePatch;
+/** The update door's structured refusal shape — the union of every branch that can produce
+ *  one (delegation, organisational-authority, coherency). Fields are all optional because no
+ *  single branch sets every one; render only what is present, never assume a shape. */
+export interface VersionWriteRefusal {
+    code?: string;
+    reason?: string;
+    category?: string;
+    requiredAction?: string;
+    disposition?: string;
+    overridable?: boolean;
+    mode?: string;
+    routes?: Record<string, unknown>;
+}
+export type VersionWriteOutcome = {
+    ok: true;
+    id: string;
+} | {
+    ok: false;
+    refusal: VersionWriteRefusal;
+};
+/**
+ * Read chain.updateEntry's (or api.entries.update's) return. A refusal is signalled by
+ * RETURN VALUE (`{outcome:'refused', refusal}`) for delegation and organisational-authority
+ * denials — NOT always a throw (only the ownership/stratum gate, requirePermission, throws).
+ * A caller that reads `.id` without checking `outcome` first silently renders
+ * "Saved as a new version of undefined" on a refused write that returned 200.
+ */
+export declare function readVersionWriteOutcome(result: unknown): VersionWriteOutcome;
+//# sourceMappingURL=versionWrite.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"versionWrite.d.ts","sourceRoot":"","sources":["../../src/lib/versionWrite.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;GAaG;AAEH,MAAM,WAAW,mBAAmB;IACnC;;oFAEgF;IAChF,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,yEAAyE;IACzE,KAAK,EAAE,MAAM,CAAC;IACd;sEACkE;IAClE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACjC;AAED,MAAM,WAAW,iBAAiB;IACjC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC9B;AAED;;mDAEmD;AACnD,wBAAgB,iBAAiB,CAAC,MAAM,EAAE;IACzC,OAAO,EAAE,mBAAmB,CAAC;IAC7B,cAAc,EAAE,MAAM,CAAC;CACvB,GAAG,iBAAiB,CAKpB;AAED;;uFAEuF;AACvF,MAAM,WAAW,mBAAmB;IACnC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACjC;AAED,MAAM,MAAM,mBAAmB,GAC5B;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,GACxB;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,OAAO,EAAE,mBAAmB,CAAA;CAAE,CAAC;AAE/C;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,OAAO,GAAG,mBAAmB,CAW5E"}

package/dist/lib/versionWrite.js

@@ -0,0 +1,32 @@
+// GENERATED by scripts/generate-mcp-embedded-copies.mjs from kernel/capture/versionWrite.ts.
+// DO NOT EDIT. Run `npm run mcp:embedded-copies` to regenerate.
+// Local runtime copy for the isolated connector build.
+/** Build the `{name?, data}` patch chain.updateEntry / entries.update expects. An empty (or
+ *  whitespace-only) prose body is never written — a capture with no real body text must not
+ *  blank out the target's existing prose field. */
+export function buildVersionPatch(params) {
+    const { capture, targetProseKey } = params;
+    const data = { ...(capture.fields ?? {}) };
+    if (capture.prose.trim())
+        data[targetProseKey] = capture.prose;
+    return capture.name ? { name: capture.name, data } : { data };
+}
+/**
+ * Read chain.updateEntry's (or api.entries.update's) return. A refusal is signalled by
+ * RETURN VALUE (`{outcome:'refused', refusal}`) for delegation and organisational-authority
+ * denials — NOT always a throw (only the ownership/stratum gate, requirePermission, throws).
+ * A caller that reads `.id` without checking `outcome` first silently renders
+ * "Saved as a new version of undefined" on a refused write that returned 200.
+ */
+export function readVersionWriteOutcome(result) {
+    if (result && typeof result === 'object' && result.outcome === 'refused') {
+        const rawRefusal = result.refusal;
+        const refusal = rawRefusal && typeof rawRefusal === 'object' ? rawRefusal : { reason: 'The workspace refused this update.' };
+        return { ok: false, refusal };
+    }
+    if (result && typeof result === 'object' && typeof result.id === 'string') {
+        return { ok: true, id: result.id };
+    }
+    return { ok: false, refusal: { reason: 'The workspace refused this update.' } };
+}
+//# sourceMappingURL=versionWrite.js.map

package/dist/lib/versionWrite.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"versionWrite.js","sourceRoot":"","sources":["../../src/lib/versionWrite.ts"],"names":[],"mappings":"AAAA,6FAA6F;AAC7F,gEAAgE;AAChE,uDAAuD;AAkCvD;;mDAEmD;AACnD,MAAM,UAAU,iBAAiB,CAAC,MAGjC;IACA,MAAM,EAAE,OAAO,EAAE,cAAc,EAAE,GAAG,MAAM,CAAC;IAC3C,MAAM,IAAI,GAA4B,EAAE,GAAG,CAAC,OAAO,CAAC,MAAM,IAAI,EAAE,CAAC,EAAE,CAAC;IACpE,IAAI,OAAO,CAAC,KAAK,CAAC,IAAI,EAAE;QAAE,IAAI,CAAC,cAAc,CAAC,GAAG,OAAO,CAAC,KAAK,CAAC;IAC/D,OAAO,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,OAAO,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC;AAC/D,CAAC;AAoBD;;;;;;GAMG;AACH,MAAM,UAAU,uBAAuB,CAAC,MAAe;IACtD,IAAI,MAAM,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAK,MAAgC,CAAC,OAAO,KAAK,SAAS,EAAE,CAAC;QACrG,MAAM,UAAU,GAAI,MAAgC,CAAC,OAAO,CAAC;QAC7D,MAAM,OAAO,GACZ,UAAU,IAAI,OAAO,UAAU,KAAK,QAAQ,CAAC,CAAC,CAAE,UAAkC,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,oCAAoC,EAAE,CAAC;QACvI,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC;IAC/B,CAAC;IACD,IAAI,MAAM,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,OAAQ,MAA2B,CAAC,EAAE,KAAK,QAAQ,EAAE,CAAC;QACjG,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,EAAE,EAAG,MAAyB,CAAC,EAAE,EAAE,CAAC;IACxD,CAAC;IACD,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE,MAAM,EAAE,oCAAoC,EAAE,EAAE,CAAC;AACjF,CAAC"}

package/dist/lib/workspace-probe.d.ts

@@ -8,6 +8,9 @@
 /**
  * Attempt to detect workspace connectivity via a lightweight API call.
  * Returns workspace info on success, null on any failure.
+ *
+ * Uses resolveWorkspace (registered in http.ts) rather than orient, which is
+ * not exposed on the HTTP gateway — orient is MCP-server-only.
  */
 export declare function probeWorkspace(): Promise<{
     name: string;

package/dist/lib/workspace-probe.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"workspace-probe.d.ts","sourceRoot":"","sources":["../../src/lib/workspace-probe.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH;;;GAGG;AACH,wBAAsB,cAAc,IAAI,OAAO,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAAC,CAuB5F"}
+{"version":3,"file":"workspace-probe.d.ts","sourceRoot":"","sources":["../../src/lib/workspace-probe.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH;;;;;;GAMG;AACH,wBAAsB,cAAc,IAAI,OAAO,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAAC,CAQ5F"}

package/dist/lib/workspace-probe.js

@@ -9,22 +9,16 @@ import { kernelCall } from './client.js';
 /**
  * Attempt to detect workspace connectivity via a lightweight API call.
  * Returns workspace info on success, null on any failure.
+ *
+ * Uses resolveWorkspace (registered in http.ts) rather than orient, which is
+ * not exposed on the HTTP gateway — orient is MCP-server-only.
  */
 export async function probeWorkspace() {
     try {
-        const result = await kernelCall('orient', { brief: true });
-        const name = result?.workspace?.name || 'unknown';
-        // Sum entry counts from orient sections if available
-        let entryCount;
-        if (result?.sections) {
-            entryCount = result.sections.reduce((sum, s) => {
-                if (s.counts) {
-                    return sum + Object.values(s.counts).reduce((a, b) => a + (b || 0), 0);
-                }
-                return sum;
-            }, 0);
-        }
-        return { name, entryCount };
+        const result = await kernelCall('resolveWorkspace', {});
+        if (!result)
+            return null;
+        return { name: result.name || 'unknown' };
     }
     catch {
         return null;

package/dist/lib/workspace-probe.js.map

@@ -1 +1 @@
-{"version":3,"file":"workspace-probe.js","sourceRoot":"","sources":["../../src/lib/workspace-probe.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc;IAClC,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,MAAM,UAAU,CAI5B,QAAQ,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;QAE9B,MAAM,IAAI,GAAG,MAAM,EAAE,SAAS,EAAE,IAAI,IAAI,SAAS,CAAC;QAClD,qDAAqD;QACrD,IAAI,UAA8B,CAAC;QACnC,IAAI,MAAM,EAAE,QAAQ,EAAE,CAAC;YACrB,UAAU,GAAG,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,CAAC,EAAE,EAAE;gBAC7C,IAAI,CAAC,CAAC,MAAM,EAAE,CAAC;oBACb,OAAO,GAAG,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;gBACzE,CAAC;gBACD,OAAO,GAAG,CAAC;YACb,CAAC,EAAE,CAAC,CAAC,CAAC;QACR,CAAC;QACD,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,CAAC;IAC9B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC"}
+{"version":3,"file":"workspace-probe.js","sourceRoot":"","sources":["../../src/lib/workspace-probe.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc;IAClC,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,MAAM,UAAU,CAA0C,kBAAkB,EAAE,EAAE,CAAC,CAAC;QACjG,IAAI,CAAC,MAAM;YAAE,OAAO,IAAI,CAAC;QACzB,OAAO,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,IAAI,SAAS,EAAE,CAAC;IAC5C,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC"}

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"}