@productbrain/cli 0.1.0-beta.1431 → 0.1.0-beta.14316

package/dist/lib/workspaceNotice.js

@@ -0,0 +1,346 @@
+/**
+ * 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`/`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 CWD env files (TEN-1334); neither cascade reads committed `config.json`
+ * siteUrl (TEN-4500). 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). Returns undefined
+ * when no tenant can be named, and the rebound line then says "a different workspace".
+ *
+ * Deliberately UNQUOTED, including the shadowed pin: the rebound line in `style.ts`'s `copy`
+ * is the one place that wraps this whole value in quotes (the same
+ * line 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);
+    if (!label)
+        return undefined;
+    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` (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` (since deleted), `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 CWD env files — a key and its URL as a pair
+ * from the same file, never committed `config.json` siteUrl, TEN-4500) 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

@@ -4,17 +4,11 @@
  * 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
+ * stale labels within a session. 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';
 /**
@@ -28,11 +22,11 @@ export declare function getCachedVocabCtx(cacheKey: string): WorkspaceVocabCtx |
 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`).
+ * Call this when `updateCollectionLabels` mutation succeeds.
  */
 export declare function invalidateVocabCtx(cacheKey: string): void;
 /**
- * Clear all cached entries (useful for testing or `pb handshake --refresh`).
+ * Clear all cached entries (useful for testing).
  */
 export declare function clearVocabCache(): void;
 /**

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

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

package/dist/lib/workspaceVocabCache.js

@@ -4,17 +4,11 @@
  * 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
+ * stale labels within a session. 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).
  */
 const TTL_MS = 5 * 60 * 1000; // 5 minutes
 const STALE_WARN_MS = 4 * 60 * 1000; // warn after 4 minutes (1 minute before expiry)
@@ -47,13 +41,13 @@ export function setCachedVocabCtx(cacheKey, ctx) {
 }
 /**
  * Explicitly invalidate a cached vocab context by cacheKey.
- * Call this when `updateCollectionLabels` mutation succeeds (e.g. after `pb handshake`).
+ * Call this when `updateCollectionLabels` mutation succeeds.
  */
 export function invalidateVocabCtx(cacheKey) {
     cache.delete(cacheKey);
 }
 /**
- * Clear all cached entries (useful for testing or `pb handshake --refresh`).
+ * Clear all cached entries (useful for testing).
  */
 export function clearVocabCache() {
     cache.clear();

package/dist/lib/workspaceVocabCache.js.map

@@ -1 +1 @@
-{"version":3,"file":"workspaceVocabCache.js","sourceRoot":"","sources":["../../src/lib/workspaceVocabCache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAUH,MAAM,MAAM,GAAG,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC,YAAY;AAC1C,MAAM,aAAa,GAAG,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC,gDAAgD;AAErF,0FAA0F;AAC1F,MAAM,KAAK,GAAG,IAAI,GAAG,EAAsB,CAAC;AAE5C;;;GAGG;AACH,MAAM,UAAU,iBAAiB,CAAC,QAAgB;IAChD,MAAM,KAAK,GAAG,KAAK,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IAClC,IAAI,CAAC,KAAK;QAAE,OAAO,IAAI,CAAC;IACxB,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IACvB,IAAI,GAAG,IAAI,KAAK,CAAC,SAAS,EAAE,CAAC;QAC3B,KAAK,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;QACvB,OAAO,IAAI,CAAC;IACd,CAAC;IACD,IAAI,GAAG,GAAG,CAAC,KAAK,CAAC,SAAS,GAAG,MAAM,CAAC,IAAI,aAAa,EAAE,CAAC;QACtD,8EAA8E;QAC9E,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,wFAAwF,CACzF,CAAC;IACJ,CAAC;IACD,OAAO,KAAK,CAAC,GAAG,CAAC;AACnB,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,iBAAiB,CAAC,QAAgB,EAAE,GAAsB;IACxE,KAAK,CAAC,GAAG,CAAC,QAAQ,EAAE,EAAE,GAAG,EAAE,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,MAAM,EAAE,CAAC,CAAC;AAC/D,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,kBAAkB,CAAC,QAAgB;IACjD,KAAK,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;AACzB,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,eAAe;IAC7B,KAAK,CAAC,KAAK,EAAE,CAAC;AAChB,CAAC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,QAAgB,EAChB,OAAgD;IAEhD,MAAM,MAAM,GAAG,iBAAiB,CAAC,QAAQ,CAAC,CAAC;IAC3C,IAAI,MAAM;QAAE,OAAO,MAAM,CAAC;IAE1B,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,MAAM,OAAO,EAAE,CAAC;QAC5B,IAAI,GAAG,EAAE,CAAC;YACR,iBAAiB,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC;YACjC,OAAO,GAAG,CAAC;QACb,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,sEAAsE;IACxE,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC"}
+{"version":3,"file":"workspaceVocabCache.js","sourceRoot":"","sources":["../../src/lib/workspaceVocabCache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAUH,MAAM,MAAM,GAAG,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC,YAAY;AAC1C,MAAM,aAAa,GAAG,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC,gDAAgD;AAErF,0FAA0F;AAC1F,MAAM,KAAK,GAAG,IAAI,GAAG,EAAsB,CAAC;AAE5C;;;GAGG;AACH,MAAM,UAAU,iBAAiB,CAAC,QAAgB;IAChD,MAAM,KAAK,GAAG,KAAK,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IAClC,IAAI,CAAC,KAAK;QAAE,OAAO,IAAI,CAAC;IACxB,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IACvB,IAAI,GAAG,IAAI,KAAK,CAAC,SAAS,EAAE,CAAC;QAC3B,KAAK,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;QACvB,OAAO,IAAI,CAAC;IACd,CAAC;IACD,IAAI,GAAG,GAAG,CAAC,KAAK,CAAC,SAAS,GAAG,MAAM,CAAC,IAAI,aAAa,EAAE,CAAC;QACtD,8EAA8E;QAC9E,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,wFAAwF,CACzF,CAAC;IACJ,CAAC;IACD,OAAO,KAAK,CAAC,GAAG,CAAC;AACnB,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,iBAAiB,CAAC,QAAgB,EAAE,GAAsB;IACxE,KAAK,CAAC,GAAG,CAAC,QAAQ,EAAE,EAAE,GAAG,EAAE,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,MAAM,EAAE,CAAC,CAAC;AAC/D,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,kBAAkB,CAAC,QAAgB;IACjD,KAAK,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;AACzB,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,eAAe;IAC7B,KAAK,CAAC,KAAK,EAAE,CAAC;AAChB,CAAC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,QAAgB,EAChB,OAAgD;IAEhD,MAAM,MAAM,GAAG,iBAAiB,CAAC,QAAQ,CAAC,CAAC;IAC3C,IAAI,MAAM;QAAE,OAAO,MAAM,CAAC;IAE1B,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,MAAM,OAAO,EAAE,CAAC;QAC5B,IAAI,GAAG,EAAE,CAAC;YACR,iBAAiB,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC;YACjC,OAAO,GAAG,CAAC;QACb,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,sEAAsE;IACxE,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC"}

package/dist/registerEntryCommands.d.ts

@@ -0,0 +1,18 @@
+/**
+ * `pb entry propose|accept|discard|resolve` — the entry-lifecycle verbs, noun-scoped per
+ * DEC-1574 (WP-640 S4). Split out of index.ts (STD-2/DEC-1504: index.ts is
+ * grandfathered over-budget and shrink-only) — same "own every command group in
+ * its own file" split index.ts's other multi-command surfaces would benefit from.
+ *
+ * `propose` is a discoverable alias over the SAME draft-creating door `pb capture`
+ * already uses (DEC-1583: capturing creates a draft, which IS the propose act —
+ * both roads lead to one draft door; capture is NOT renamed or removed). `accept`
+ * is `pb promote`'s exact server route (chain.commitEntry) under its new name —
+ * pure rename, zero behavior change. `discard` and `resolve` are the two
+ * category verbs over `pb update --status archived` (TASK-400): the verb decides Discarded or Past;
+ * the optional `--reason` is free text recorded in the history note (DEC-1814), never a data field.
+ */
+import type { Command } from 'commander';
+export declare function registerEntryCommands(program: Command): void;
+export declare function registerRelateCommands(program: Command): void;
+//# sourceMappingURL=registerEntryCommands.d.ts.map

package/dist/registerEntryCommands.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registerEntryCommands.d.ts","sourceRoot":"","sources":["../src/registerEntryCommands.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAezC,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAsH5D;AAOD,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAkB7D"}

package/dist/registerEntryCommands.js

@@ -0,0 +1,146 @@
+import { runCapture } from './commands/capture.js';
+import { runEntryAccept } from './commands/entryAccept.js';
+import { runEntryDiscard, runEntryResolve } from './commands/entryDiscardResolve.js';
+import { runEntryOwn } from './commands/entryOwn.js';
+import { runEntryReplace } from './commands/entryReplace.js';
+import { runEntryPreflight } from './commands/entryPreflight.js';
+import { runEntryTick } from './commands/entryTick.js';
+import { runRelate, runUnrelate } from './commands/relate.js';
+import { SPINE_RUNG_LINES } from './lib/checklist.js';
+import { ENTRY_BODY_HELP, ENTRY_NAME_HELP } from './lib/limits.js';
+/** TASK-1026 (WP-862, RULE-664): the spine's links, worded once by rungLine, printed under relate and preflight help. */
+const SPINE_LINKS_HELP = `\nEach level links to the one above:\n${SPINE_RUNG_LINES.map((line) => `  ${line}`).join('\n')}\n`;
+export function registerEntryCommands(program) {
+    const entryCmd = program
+        .command('entry')
+        .description('Entry-lifecycle commands (propose | accept | replace | discard | resolve | tick)');
+    entryCmd
+        .command('preflight')
+        .description('Read structural requirements before composing an entry; saves nothing')
+        .requiredOption('-c, --collection <slug>', 'Collection to inspect')
+        .option('--canonical-key <key>', 'Explicit semantic type')
+        .option('-l, --link <type:entry-id>', 'Selected context (repeatable); e.g. validates:<entry-id>', (value, previous) => [...previous, value], [])
+        .option('-t, --link-type <type>', 'Type for any --link supplied as a bare entry ID')
+        .addHelpText('after', SPINE_LINKS_HELP)
+        .action(runEntryPreflight);
+    entryCmd
+        .command('propose [text...]')
+        .description('Propose (capture) a new draft entry — same draft door as `pb capture`')
+        .option('-n, --name <name>', `${ENTRY_NAME_HELP} Left out, it is the first sentence of the text.`)
+        .option('-d, --description <desc>', `${ENTRY_BODY_HELP} Left out, it is the whole text.`)
+        .option('-c, --collection <slug>', 'Explicit collection (skip auto-classification)')
+        .option('-f, --field <key=value>', 'Set a data field (repeatable; checklist: -f doneWhen="a" -f doneWhen="b", one item per flag)', (val, prev) => [...prev, val], [])
+        .option('-l, --link <entry-id>', 'Link to an existing entry by id or name (repeatable; pairs with the -t in the same position)', (val, prev) => [...prev, val], [])
+        .option('-t, --link-type <relation-type>', 'Relation type for the -l in the same position; one per --link, no default', (val, prev) => [...prev, val], [])
+        .option('--source-ref <ref>', 'Source reference URI')
+        .option('--source-excerpt <text>', 'Verbatim source excerpt')
+        .option('--draft', 'Force the entry to draft regardless of workspace governance mode')
+        .option('--json', 'Output machine-readable JSON (deprecated: use global --json flag)')
+        // WP-640 SWEEP (#653 review): `propose` is advertised as the same draft door as
+        // `pb capture` (DEC-1583), but this rung-2 ownership option was never registered or
+        // forwarded here — an ownership-scoped propose hit "unknown option" instead of reaching
+        // runCapture. Mirrors index.ts's `capture` registration exactly.
+        // WP-753 O1b (DEC-1715): --owner-team is deleted — an unnamed create resolves a default
+        // owner itself (the session's acting role, else the nearest Team Lead); --owner-role
+        // survives as the explicit override, its team the one you hold the role in (root first, else the shallowest).
+        .option('--owner-role <entry-id>', 'Existing Role entry ID to create AS OWNER of (you must hold it, and its team is the one you hold it in: root first, else the shallowest)')
+        .option('--team <team-ref>', 'For a role: the team it is born in. For a team: its parent. Defaults to the root team')
+        .action(async (textParts = [], opts) => {
+        const text = textParts.join(' ').trim();
+        if (!text && !opts.name) {
+            entryCmd.commands.find((c) => c.name() === 'propose')?.help();
+            return;
+        }
+        await runCapture({
+            text: text || opts.name || '', name: opts.name, description: opts.description, collection: opts.collection,
+            field: opts.field, link: opts.link, linkType: opts.linkType, sourceRef: opts.sourceRef, sourceExcerpt: opts.sourceExcerpt,
+            draft: opts.draft, json: opts.json,
+            ownerRole: opts.ownerRole, team: opts.team,
+        });
+    });
+    entryCmd
+        .command('accept <entry-ids...>')
+        .description('Accept one or more draft entries onto the Chain. Batch: a single failure does not abort the rest.')
+        .option('-m, --message <text>', 'Note recorded with the accept (applied to every entry in the batch)')
+        .option('--override-reason <text>', 'Why it stands alone, at least 12 characters, or why a text passes after its checklist failed. Your name is kept with it.')
+        .option('--acknowledge <response>', 'Answer why it stands alone: linked | accepted-fix | diverged')
+        .option('--ack-entry <entry-id>', 'Authorizing entry for --acknowledge linked / accepted-fix')
+        .option('--ack-reason <text>', 'Why you diverge, at least 12 characters; required with --acknowledge diverged')
+        .option('--replaces <entry-id>', 'The accepted entry this one replaces: it is archived and what hangs on it moves here')
+        .option('--reason <text>', 'With --replaces: why it is replaced, one line of at most 200 characters (required)')
+        .action(async (entryIds, opts) => {
+        const { message, overrideReason, acknowledge, ackEntry, ackReason, replaces, reason } = opts;
+        await runEntryAccept({ entryIds, message, overrideReason, acknowledge, ackEntry, ackReason, replaces, reason });
+    });
+    // TASK-1095 (DEC-2006): the agent's replace door; the reason is required and the kernel refuses without one.
+    entryCmd
+        .command('replace <old-id> <new-id>')
+        .description('Replace an accepted entry with another accepted one of its kind: the old one is archived and reads Replaced by the new one')
+        .option('--reason <text>', 'Why it is replaced, in one sentence (required)')
+        .action(async (oldEntryId, newEntryId, opts) => {
+        await runEntryReplace({ oldEntryId, newEntryId, reason: opts.reason });
+    });
+    entryCmd
+        .command('discard <entry-id>')
+        .description('Discard a draft or current entry: it moves to the collection\'s Discarded word')
+        .option('--reason <text>', 'Free text recorded in the history note')
+        .option('--note <text>', 'Change note for history')
+        .action(async (entryId, opts) => {
+        await runEntryDiscard({ entryId, reason: opts.reason, note: opts.note });
+    });
+    entryCmd
+        .command('resolve <entry-id>')
+        .description('Resolve a current entry: it moves to the collection\'s Past archive word')
+        .option('--reason <text>', 'Why, recorded in the history note; required to resolve an accepted decision or rule')
+        .option('--note <text>', 'Change note for history')
+        .action(async (entryId, opts) => {
+        await runEntryResolve({ entryId, reason: opts.reason, note: opts.note });
+    });
+    // TASK-382 (WP-770 K4): ticking a Done-when item records who/when and mints no version.
+    entryCmd
+        .command('tick <entry-id> <item-id>')
+        .description('Tick a Done-when item — records who and when, not an edit (the role that owns the record; the Team Lead only when it has no owner)')
+        .option('--undo', 'Untick the item instead')
+        .action(async (entryId, itemId, opts) => {
+        await runEntryTick({ entryId, itemId, undo: opts.undo });
+    });
+    // DEC-1710: the retired `pb organisation work own` re-homed under the entry noun — same
+    // judged door (organisation.setOwnership), no `own`'s `unown` sibling (an entry is never
+    // unowned; reassignment is the only way ownership changes).
+    entryCmd
+        .command('own [entry-id]')
+        .description('Assign an entry to one exact team and role, or move every open item a role owns to another role\n'
+        + 'Example: pb entry own --from-role <role-id> --to-role <role-id> --dry-run')
+        .option('--team <team-id>', 'With an entry id: the team')
+        .option('--role <role-id>', 'With an entry id: the role')
+        .option('--from-role <role-id>', 'Move every open item this role owns, each checked; past items stay as history')
+        .option('--to-role <role-id>', 'With --from-role: the receiving role; without it, the nearest Team Lead of the role\'s home team')
+        .option('--dry-run', 'With --from-role: list the role\'s open items, 200 a page, and change nothing')
+        .option('--page <n>', 'With --dry-run: the page to list, from 1')
+        .action(async (entryId, opts) => {
+        await runEntryOwn(entryId, opts);
+    });
+}
+// --- Relate / Unrelate commands (TEN-704) — moved from index.ts (WP-688 S2a): index.ts is
+// grandfathered shrink-only (STD-2/DEC-1504), and this file already owns the "own every command
+// group in its own file" registrar pattern. `relate`/`unrelate` stay TOP-LEVEL commands (not
+// nested under `entry`) — this is a file-location move for LOC budget, not a DEC-1574 rename.
+export function registerRelateCommands(program) {
+    program
+        .command('relate <from-id> <type> <to-id>')
+        .description('Add a typed relation between two entries (requires active session)')
+        .option('--if-missing', 'Only create relation if it does not already exist')
+        .option('--dry-run', 'Preview the write (advisories, wouldBlock) without creating the relation')
+        .option('--move', 'Move the entry: the new part_of replaces the one it already hangs on, in one write')
+        .addHelpText('after', SPINE_LINKS_HELP)
+        .action(async (fromId, type, toId, opts) => {
+        await runRelate({ fromId, type, toId, ifMissing: opts.ifMissing, dryRun: opts.dryRun, move: opts.move });
+    });
+    program
+        .command('unrelate <from-id> <type> <to-id>')
+        .description('Remove a typed relation between two entries (requires active session)')
+        .action(async (fromId, type, toId) => {
+        await runUnrelate({ fromId, type, toId });
+    });
+}
+//# sourceMappingURL=registerEntryCommands.js.map

package/dist/registerEntryCommands.js.map

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