@productbrain/cli 0.1.0-beta.88 → 0.1.0-beta.8802

package/dist/lib/strip.js

@@ -16,13 +16,60 @@ const STRIP_KEYS = new Set(['_id', '_creationTime']);
  *
  * BET-269: Security baseline — C3 (CLI terminal escaping).
  */
+// Note: the CSI/OSC alternatives MUST precede the bare control-char class. Regex
+// alternation takes the first matching alternative at a given position, not the
+// longest — with the control-char class first, a lone ESC (0x1b, inside \x0b-\x1f)
+// matches and consumes before the longer `\x1b\[...` sequence gets a chance,
+// stripping only the ESC and leaving the rest of the escape sequence (e.g. `[31m`)
+// behind as inert-but-visible text (found via PR #341 review Finding 2 testing).
+// Late-fix consolidation round 1 (PRRT_kwDORS4ils6Y0pz3, P1): the control-char class
+// used to jump \x0b\x0c straight to \x0e-\x1f, deliberately skipping \x0d (carriage
+// return) — but a bare \r moves the terminal cursor to column zero and lets the
+// remaining attacker-controlled text overwrite/spoof the start of the line, so (unlike
+// \t/\n, which carry a legitimate multiline-formatting use) it belongs in the stripped
+// set. \x0b-\x1f is now one contiguous range (still excludes \x09 tab and \x0a newline).
 // eslint-disable-next-line no-control-regex
-const ANSI_AND_CONTROL_RE = /[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]|\x1b\[[0-9;]*[A-Za-z]|\x1b\][^\x07]*\x07|\x1b[^[\]0-9;A-Za-z]?/g;
+const ANSI_AND_CONTROL_RE = /\x1b\[[0-9;]*[A-Za-z]|\x1b\][^\x07]*\x07|\x1b[^[\]0-9;A-Za-z]?|[\x00-\x08\x0b-\x1f\x7f]/g;
 export function stripControlChars(str) {
     if (!str)
         return str;
     return str.replace(ANSI_AND_CONTROL_RE, '');
 }
+/** Round 4 (quiet-sweep item 1): stripControlChars deliberately excludes `\x0a` (newline) —
+ *  legitimate for multiline text, but a field rendered as ONE terminal line (a digest bullet,
+ *  a formatted label) must never let an embedded `\n`/`\r`/`\t` inject extra, unprefixed
+ *  lines. Collapses every whitespace run to a single space, after stripping control chars —
+ *  the same `stripControlChars(v).replace(/\s+/g, ' ').trim()` idiom already duplicated across
+ *  this package's formatters (shape.ts, conflicts.ts, direction.ts, feedback.ts, questions.ts,
+ *  sessionNotices.ts); centralized here as the shared, single-line-safe sanitizer. */
+export function sanitizeSingleLineField(str) {
+    return stripControlChars(str).replace(/\s+/g, ' ').trim();
+}
+const FILESYSTEM_PATH_ESCAPES = { '\t': '\\t', '\n': '\\n', '\r': '\\r' };
+/**
+ * Round 15 (Codex P2, PR #912/#916): reversibly escape control chars/non-printables in a
+ * filesystem-derived identifier (a path or filename) for terminal display. Unlike
+ * `sanitizeSingleLineField` — which DELETES control chars and COLLAPSES whitespace runs, fine
+ * for a Chain-entry label but lossy for a filename a user is told to go find and remove — this
+ * escapes each unsafe byte as `\t`/`\n`/`\r` or `\xNN`, byte-for-byte recoverable, and leaves
+ * ordinary spaces untouched so e.g. "safe  name.mdc" and "safe name.mdc" still render distinctly.
+ */
+export function renderFilesystemPath(value) {
+    let out = '';
+    for (const ch of value) {
+        const code = ch.codePointAt(0) ?? 0;
+        if (FILESYSTEM_PATH_ESCAPES[ch]) {
+            out += FILESYSTEM_PATH_ESCAPES[ch];
+        }
+        else if (code < 0x20 || code === 0x7f) {
+            out += `\\x${code.toString(16).padStart(2, '0')}`;
+        }
+        else {
+            out += ch;
+        }
+    }
+    return out;
+}
 export function stripConvexInternals(data) {
     if (Array.isArray(data)) {
         return data.map((item) => stripConvexInternals(item));

package/dist/lib/strip.js.map

@@ -1 +1 @@
-{"version":3,"file":"strip.js","sourceRoot":"","sources":["../../src/lib/strip.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,MAAM,UAAU,GAAG,IAAI,GAAG,CAAC,CAAC,KAAK,EAAE,eAAe,CAAC,CAAC,CAAC;AAErD;;;;;;;GAOG;AACH,4CAA4C;AAC5C,MAAM,mBAAmB,GAAG,kGAAkG,CAAC;AAE/H,MAAM,UAAU,iBAAiB,CAAC,GAAW;IAC3C,IAAI,CAAC,GAAG;QAAE,OAAO,GAAG,CAAC;IACrB,OAAO,GAAG,CAAC,OAAO,CAAC,mBAAmB,EAAE,EAAE,CAAC,CAAC;AAC9C,CAAC;AAED,MAAM,UAAU,oBAAoB,CAAI,IAAO;IAC7C,IAAI,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;QACxB,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,oBAAoB,CAAC,IAAI,CAAC,CAAiB,CAAC;IACxE,CAAC;IAED,IAAI,IAAI,KAAK,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ,EAAE,CAAC;QAC9C,MAAM,MAAM,GAA4B,EAAE,CAAC;QAC3C,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,IAA+B,CAAC,EAAE,CAAC;YAC3E,IAAI,UAAU,CAAC,GAAG,CAAC,GAAG,CAAC;gBAAE,SAAS;YAClC,MAAM,CAAC,GAAG,CAAC,GAAG,oBAAoB,CAAC,KAAK,CAAC,CAAC;QAC5C,CAAC;QACD,OAAO,MAAsB,CAAC;IAChC,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC"}
+{"version":3,"file":"strip.js","sourceRoot":"","sources":["../../src/lib/strip.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,MAAM,UAAU,GAAG,IAAI,GAAG,CAAC,CAAC,KAAK,EAAE,eAAe,CAAC,CAAC,CAAC;AAErD;;;;;;;GAOG;AACH,iFAAiF;AACjF,gFAAgF;AAChF,mFAAmF;AACnF,6EAA6E;AAC7E,mFAAmF;AACnF,iFAAiF;AACjF,qFAAqF;AACrF,oFAAoF;AACpF,gFAAgF;AAChF,uFAAuF;AACvF,uFAAuF;AACvF,yFAAyF;AACzF,4CAA4C;AAC5C,MAAM,mBAAmB,GAAG,0FAA0F,CAAC;AAEvH,MAAM,UAAU,iBAAiB,CAAC,GAAW;IAC3C,IAAI,CAAC,GAAG;QAAE,OAAO,GAAG,CAAC;IACrB,OAAO,GAAG,CAAC,OAAO,CAAC,mBAAmB,EAAE,EAAE,CAAC,CAAC;AAC9C,CAAC;AAED;;;;;;sFAMsF;AACtF,MAAM,UAAU,uBAAuB,CAAC,GAAW;IACjD,OAAO,iBAAiB,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC;AAC5D,CAAC;AAED,MAAM,uBAAuB,GAA2B,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC;AAElG;;;;;;;GAOG;AACH,MAAM,UAAU,oBAAoB,CAAC,KAAa;IAChD,IAAI,GAAG,GAAG,EAAE,CAAC;IACb,KAAK,MAAM,EAAE,IAAI,KAAK,EAAE,CAAC;QACvB,MAAM,IAAI,GAAG,EAAE,CAAC,WAAW,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;QACpC,IAAI,uBAAuB,CAAC,EAAE,CAAC,EAAE,CAAC;YAChC,GAAG,IAAI,uBAAuB,CAAC,EAAE,CAAC,CAAC;QACrC,CAAC;aAAM,IAAI,IAAI,GAAG,IAAI,IAAI,IAAI,KAAK,IAAI,EAAE,CAAC;YACxC,GAAG,IAAI,MAAM,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CAAC;QACpD,CAAC;aAAM,CAAC;YACN,GAAG,IAAI,EAAE,CAAC;QACZ,CAAC;IACH,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,MAAM,UAAU,oBAAoB,CAAI,IAAO;IAC7C,IAAI,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;QACxB,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,oBAAoB,CAAC,IAAI,CAAC,CAAiB,CAAC;IACxE,CAAC;IAED,IAAI,IAAI,KAAK,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ,EAAE,CAAC;QAC9C,MAAM,MAAM,GAA4B,EAAE,CAAC;QAC3C,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,IAA+B,CAAC,EAAE,CAAC;YAC3E,IAAI,UAAU,CAAC,GAAG,CAAC,GAAG,CAAC;gBAAE,SAAS;YAClC,MAAM,CAAC,GAAG,CAAC,GAAG,oBAAoB,CAAC,KAAK,CAAC,CAAC;QAC5C,CAAC;QACD,OAAO,MAAsB,CAAC;IAChC,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/lib/style.d.ts

@@ -8,6 +8,7 @@
  * All color output respects NO_COLOR env (https://no-color.org/) and TTY detection.
  * Quiet mode suppresses banners, hints, and progress — only essential results show.
  */
+import { type DeploymentTier } from './deployment.js';
 /** Returns true if the terminal supports color output. */
 export declare function supportsColor(): boolean;
 export declare const green: (s: string) => string;
@@ -65,17 +66,22 @@ export declare function heading(text: string): string;
  */
 export declare function formatCheck(status: 'pass' | 'fail' | 'warn', label: string, detail: string): string;
 /**
- * Print an environment-aware admin banner. Suppressed in quiet mode.
+ * Colored deployment-tier tag — shared by `adminBanner` and any other surface (e.g. `pb profile
+ * create`'s receipt, WP-744 / 1e-B) that needs to name which tier a resolved host classifies as.
  *
  * Labels:
  * - [DEV] — localhost loopback
  * - [DEV·CLOUD] — known Convex Development (Cloud) deployment
  * - [PROD] — known production gateway / prod Convex deployment
  * - [CLOUD] — other remote URL (unknown tier)
+ */
+export declare function deploymentBadge(tier: DeploymentTier): string;
+/**
+ * Print an environment-aware admin banner. Suppressed in quiet mode.
  *
  * Format: "⚡ pb admin — [ENV] <host>"
  */
-export declare function adminBanner(siteUrl: string): void;
+export declare function adminBanner(siteUrl: string, profileLabel?: string): void;
 /**
  * Prompt for confirmation before a destructive admin operation (remote deployments).
  *

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

@@ -1 +1 @@
-{"version":3,"file":"style.d.ts","sourceRoot":"","sources":["../../src/lib/style.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAUH,0DAA0D;AAC1D,wBAAgB,aAAa,IAAI,OAAO,CAEvC;AAMD,eAAO,MAAM,KAAK,GAAI,GAAG,MAAM,KAAG,MAAuD,CAAC;AAC1F,eAAO,MAAM,GAAG,GAAI,GAAG,MAAM,KAAG,MAAuD,CAAC;AACxF,eAAO,MAAM,MAAM,GAAI,GAAG,MAAM,KAAG,MAAuD,CAAC;AAC3F,eAAO,MAAM,IAAI,GAAI,GAAG,MAAM,KAAG,MAAuD,CAAC;AACzF,eAAO,MAAM,OAAO,GAAI,GAAG,MAAM,KAAG,MAAuD,CAAC;AAC5F,eAAO,MAAM,IAAI,GAAI,GAAG,MAAM,KAAG,MAAuD,CAAC;AACzF,eAAO,MAAM,GAAG,GAAI,GAAG,MAAM,KAAG,MAAsD,CAAC;AACvF,eAAO,MAAM,IAAI,GAAI,GAAG,MAAM,KAAG,MAAsD,CAAC;AAMxF,eAAO,MAAM,KAAK;;;;;;CAMR,CAAC;AAMX,eAAO,MAAM,IAAI;;;;;;;;;;;;;gCAkBI,MAAM;sCACA,MAAM;CACvB,CAAC;AAMX;;;GAGG;AACH,wBAAgB,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAG1C;AAED;;;GAGG;AACH,wBAAgB,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAGvC;AAED;;GAEG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAG3C;AAED;;GAEG;AACH,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE5C;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CASnG;AAMD;;;;;;;;;;GAUG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAoBjD;AAED;;;;;;;;;GASG;AACH,wBAAsB,iBAAiB,CAAC,OAAO,EAAE;IAC/C,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,OAAO,CAAC;IACtB,6EAA6E;IAC7E,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,GAAG,OAAO,CAAC,OAAO,CAAC,CASnB"}
+{"version":3,"file":"style.d.ts","sourceRoot":"","sources":["../../src/lib/style.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAqC,KAAK,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAQzF,0DAA0D;AAC1D,wBAAgB,aAAa,IAAI,OAAO,CAEvC;AAMD,eAAO,MAAM,KAAK,GAAI,GAAG,MAAM,KAAG,MAAuD,CAAC;AAC1F,eAAO,MAAM,GAAG,GAAI,GAAG,MAAM,KAAG,MAAuD,CAAC;AACxF,eAAO,MAAM,MAAM,GAAI,GAAG,MAAM,KAAG,MAAuD,CAAC;AAC3F,eAAO,MAAM,IAAI,GAAI,GAAG,MAAM,KAAG,MAAuD,CAAC;AACzF,eAAO,MAAM,OAAO,GAAI,GAAG,MAAM,KAAG,MAAuD,CAAC;AAC5F,eAAO,MAAM,IAAI,GAAI,GAAG,MAAM,KAAG,MAAuD,CAAC;AACzF,eAAO,MAAM,GAAG,GAAI,GAAG,MAAM,KAAG,MAAsD,CAAC;AACvF,eAAO,MAAM,IAAI,GAAI,GAAG,MAAM,KAAG,MAAsD,CAAC;AAMxF,eAAO,MAAM,KAAK;;;;;;CAMR,CAAC;AAMX,eAAO,MAAM,IAAI;;;;;;;;;;;;;gCAkBI,MAAM;sCACA,MAAM;CACvB,CAAC;AAMX;;;GAGG;AACH,wBAAgB,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAG1C;AAED;;;GAGG;AACH,wBAAgB,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAGvC;AAED;;GAEG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAG3C;AAED;;GAEG;AACH,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE5C;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CASnG;AAMD;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,cAAc,GAAG,MAAM,CAW5D;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAWxE;AAED;;;;;;;;;GASG;AACH,wBAAsB,iBAAiB,CAAC,OAAO,EAAE;IAC/C,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,OAAO,CAAC;IACtB,6EAA6E;IAC7E,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,GAAG,OAAO,CAAC,OAAO,CAAC,CASnB"}

package/dist/lib/style.js

@@ -113,36 +113,43 @@ export function formatCheck(status, label, detail) {
 // Admin UX framework (WP-312 S2, FEAT-972)
 // ---------------------------------------------------------------------------
 /**
- * Print an environment-aware admin banner. Suppressed in quiet mode.
+ * Colored deployment-tier tag — shared by `adminBanner` and any other surface (e.g. `pb profile
+ * create`'s receipt, WP-744 / 1e-B) that needs to name which tier a resolved host classifies as.
  *
  * Labels:
  * - [DEV] — localhost loopback
  * - [DEV·CLOUD] — known Convex Development (Cloud) deployment
  * - [PROD] — known production gateway / prod Convex deployment
  * - [CLOUD] — other remote URL (unknown tier)
- *
- * Format: "⚡ pb admin — [ENV] <host>"
  */
-export function adminBanner(siteUrl) {
-    if (isQuietMode())
-        return;
-    const host = parseHostname(siteUrl);
-    const tier = classifyDeployment(siteUrl);
-    let envTag;
+export function deploymentBadge(tier) {
     switch (tier) {
         case 'local':
-            envTag = green('[DEV]');
-            break;
+            return green('[DEV]');
         case 'prod':
-            envTag = red('[PROD]');
-            break;
+            return red('[PROD]');
         case 'dev-cloud':
-            envTag = cyan('[DEV·CLOUD]');
-            break;
+            return cyan('[DEV·CLOUD]');
         default:
-            envTag = yellow('[CLOUD]');
+            return yellow('[CLOUD]');
     }
-    process.stdout.write(`\n${bold(`\u26A1 pb admin`)} ${dim('\u2014')} ${envTag} ${dim(host)}\n\n`);
+}
+/**
+ * Print an environment-aware admin banner. Suppressed in quiet mode.
+ *
+ * Format: "⚡ pb admin — [ENV] <host>"
+ */
+export function adminBanner(siteUrl, profileLabel) {
+    if (isQuietMode())
+        return;
+    const host = parseHostname(siteUrl);
+    const envTag = deploymentBadge(classifyDeployment(siteUrl));
+    // WP-681: name WHICH credential resolved the target, not just the tier - the env tag alone
+    // never told you which of possibly several profiles put you there (the live-reproduced bug
+    // this closes: `pb admin run` silently resolving the operator's global profile - often prod -
+    // even inside a repo explicitly pinned to a dev-scoped one).
+    const profileSuffix = profileLabel ? ` ${dim(`(profile: ${profileLabel})`)}` : '';
+    process.stdout.write(`\n${bold(`\u26A1 pb admin`)} ${dim('\u2014')} ${envTag} ${dim(host)}${profileSuffix}\n\n`);
 }
 /**
  * Prompt for confirmation before a destructive admin operation (remote deployments).

package/dist/lib/style.js.map

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

package/dist/lib/tokenConstants.d.ts

@@ -9,6 +9,8 @@
 export declare const API_KEY_PREFIX = "pb_sk_";
 /** Prefix for short-lived connect tokens (15-min, single-use). */
 export declare const CONNECT_TOKEN_PREFIX = "pb_ct_";
+/** Prefix for preview-only admin proof-bridge tokens (≤24h, workspace-pinned; WP-459). */
+export declare const PREVIEW_ADMIN_TOKEN_PREFIX = "pb_pat_";
 /**
  * Length of the random hex component in generated API keys.
  * 32 hex chars = 128-bit entropy.

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

@@ -1 +1 @@
-{"version":3,"file":"tokenConstants.d.ts","sourceRoot":"","sources":["../../src/lib/tokenConstants.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,qDAAqD;AACrD,eAAO,MAAM,cAAc,WAAW,CAAC;AAEvC,kEAAkE;AAClE,eAAO,MAAM,oBAAoB,WAAW,CAAC;AAE7C;;;GAGG;AACH,eAAO,MAAM,kBAAkB,KAAK,CAAC"}
+{"version":3,"file":"tokenConstants.d.ts","sourceRoot":"","sources":["../../src/lib/tokenConstants.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,qDAAqD;AACrD,eAAO,MAAM,cAAc,WAAW,CAAC;AAEvC,kEAAkE;AAClE,eAAO,MAAM,oBAAoB,WAAW,CAAC;AAE7C,0FAA0F;AAC1F,eAAO,MAAM,0BAA0B,YAAY,CAAC;AAEpD;;;GAGG;AACH,eAAO,MAAM,kBAAkB,KAAK,CAAC"}

package/dist/lib/tokenConstants.js

@@ -9,6 +9,8 @@
 export const API_KEY_PREFIX = 'pb_sk_';
 /** Prefix for short-lived connect tokens (15-min, single-use). */
 export const CONNECT_TOKEN_PREFIX = 'pb_ct_';
+/** Prefix for preview-only admin proof-bridge tokens (≤24h, workspace-pinned; WP-459). */
+export const PREVIEW_ADMIN_TOKEN_PREFIX = 'pb_pat_';
 /**
  * Length of the random hex component in generated API keys.
  * 32 hex chars = 128-bit entropy.

package/dist/lib/tokenConstants.js.map

@@ -1 +1 @@
-{"version":3,"file":"tokenConstants.js","sourceRoot":"","sources":["../../src/lib/tokenConstants.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,qDAAqD;AACrD,MAAM,CAAC,MAAM,cAAc,GAAG,QAAQ,CAAC;AAEvC,kEAAkE;AAClE,MAAM,CAAC,MAAM,oBAAoB,GAAG,QAAQ,CAAC;AAE7C;;;GAGG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,EAAE,CAAC"}
+{"version":3,"file":"tokenConstants.js","sourceRoot":"","sources":["../../src/lib/tokenConstants.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,qDAAqD;AACrD,MAAM,CAAC,MAAM,cAAc,GAAG,QAAQ,CAAC;AAEvC,kEAAkE;AAClE,MAAM,CAAC,MAAM,oBAAoB,GAAG,QAAQ,CAAC;AAE7C,0FAA0F;AAC1F,MAAM,CAAC,MAAM,0BAA0B,GAAG,SAAS,CAAC;AAEpD;;;GAGG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,EAAE,CAAC"}

package/dist/lib/update-check.d.ts

@@ -5,17 +5,52 @@
  * a one-line notification when a newer version is available.
  *
  * Rules:
- *   - Non-blocking: check fires async, never delays the command
- *   - 24h cache at ~/.config/productbrain/update-check.json
+ *   - Synchronous: reads cache only, never awaits network, never delays the command
+ *   - Multi-source cache at ~/.config/productbrain/update-check.json:
+ *     server header is authoritative within 48h; npm is an isNewer-gated fallback
  *   - Silent on any error (network down, registry unreachable, etc.)
- *   - JSON mode: suppress notification entirely
+ *   - JSON/agent mode: notice goes to stderr (stdout stays bare JSON), throttled once per session
  *   - Does NOT use undici/fetch directly; uses Node.js built-in https
  */
 /**
- * Prints one line to stderr if a newer version is available.
- * The check is always non-blocking: it fires async and is not awaited by the caller.
- *
- * Call once per human-initiated command, just before the command action runs.
+ * Emit `cli.version_skew.detected` at most once per process when a strictly newer
+ * version has been observed. Exported so callers (e.g. doctor's freshness check)
+ * can fire it from their own discovery path while sharing the dedup guard.
+ */
+export declare function reportVersionSkewIfNew(latest: string | null, current?: string): void;
+/**
+ * Hot-path resolution from cache only — NEVER fetches. The **newest** in-window source wins: the
+ * server header is preferred only when it is actually the highest version, so a server that lags
+ * npm (its committed `cliVersion.ts` value trails the run-numbered npm publish — see TEN-2199) can
+ * no longer mask a newer npm latest. Returns the best available value even when every source is
+ * stale ("better than nothing"), because the hot path (checkForUpdate) cannot block on a refresh.
+ */
+export declare function resolveCachedLatest(): string | null;
+/** @deprecated use resolveCachedLatest. Kept for callers migrating. */
+export declare function readCachedLatestVersion(): string | null;
+/** Clear the post-upgrade sentinel and stale update cache on next CLI startup. */
+export declare function clearPendingUpgradeCache(): void;
+/** Written after a successful self-upgrade so the next CLI process drops stale cache. */
+export declare function writeUpgradePendingSentinel(installedVersion?: string): void;
+/** Test-only: reset module-level per-process guards so each test starts clean. */
+export declare function _resetProcessGuardsForTest(): void;
+/**
+ * Compare two semver strings. Returns true if `b` is strictly newer than `a`.
+ * Handles standard x.y.z and x.y.z-beta.N formats (numeric comparison per part).
+ */
+export declare function isNewer(current: string, latest: string): boolean;
+/** Record the server-supplied latest version (authoritative source). */
+export declare function recordServerLatest(latestVersion: string | null): void;
+/** Record an npm-resolved latest version — gated so it never stores <= installed. */
+export declare function recordNpmLatest(latestVersion: string | null, currentVersion: string): void;
+/** LIVE resolve — fetches npm and records it (gated). Call ONLY from doctor/upgrade, never the hot path. */
+export declare function resolveLatestVersion(currentVersion?: string): Promise<string | null>;
+/**
+ * Synchronously prints at most one update line. Reads cache only — never fetches.
+ * Reaches agents (JSON mode) on stderr; stdout stays bare JSON. Throttled once per
+ * session (agent) / once per UTC day (human TTY) via O_EXCL markers. Never throws.
+ * NOTE: a session with no authenticated server call writes no cache and fires no
+ * notice; `pb doctor` live-resolves as the backstop. DEC-2.
  */
 export declare function checkForUpdate(currentVersion: string): void;
 //# sourceMappingURL=update-check.d.ts.map

package/dist/lib/update-check.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"update-check.d.ts","sourceRoot":"","sources":["../../src/lib/update-check.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAuGH;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,cAAc,EAAE,MAAM,GAAG,IAAI,CA0B3D"}
+{"version":3,"file":"update-check.d.ts","sourceRoot":"","sources":["../../src/lib/update-check.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAyCH;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAQpF;AA+BD;;;;;;GAMG;AACH,wBAAgB,mBAAmB,IAAI,MAAM,GAAG,IAAI,CAUnD;AAYD,uEAAuE;AACvE,wBAAgB,uBAAuB,IAAI,MAAM,GAAG,IAAI,CAEvD;AAMD,kFAAkF;AAClF,wBAAgB,wBAAwB,IAAI,IAAI,CAU/C;AAED,yFAAyF;AACzF,wBAAgB,2BAA2B,CAAC,gBAAgB,CAAC,EAAE,MAAM,GAAG,IAAI,CAK3E;AAED,kFAAkF;AAClF,wBAAgB,0BAA0B,IAAI,IAAI,CAIjD;AA2BD;;;GAGG;AACH,wBAAgB,OAAO,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAuBhE;AAED,wEAAwE;AACxE,wBAAgB,kBAAkB,CAAC,aAAa,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAMrE;AAED,qFAAqF;AACrF,wBAAgB,eAAe,CAAC,aAAa,EAAE,MAAM,GAAG,IAAI,EAAE,cAAc,EAAE,MAAM,GAAG,IAAI,CAM1F;AAED,4GAA4G;AAC5G,wBAAsB,oBAAoB,CAAC,cAAc,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAmB1F;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,cAAc,EAAE,MAAM,GAAG,IAAI,CAiB3D"}

package/dist/lib/update-check.js

@@ -5,55 +5,172 @@
  * a one-line notification when a newer version is available.
  *
  * Rules:
- *   - Non-blocking: check fires async, never delays the command
- *   - 24h cache at ~/.config/productbrain/update-check.json
+ *   - Synchronous: reads cache only, never awaits network, never delays the command
+ *   - Multi-source cache at ~/.config/productbrain/update-check.json:
+ *     server header is authoritative within 48h; npm is an isNewer-gated fallback
  *   - Silent on any error (network down, registry unreachable, etc.)
- *   - JSON mode: suppress notification entirely
+ *   - JSON/agent mode: notice goes to stderr (stdout stays bare JSON), throttled once per session
  *   - Does NOT use undici/fetch directly; uses Node.js built-in https
  */
-import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'node:fs';
+import { readFileSync, writeFileSync, mkdirSync, existsSync, unlinkSync } from 'node:fs';
 import { request } from 'node:https';
 import { homedir } from 'node:os';
-import { join } from 'node:path';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { isJsonMode } from './runner.js';
 import { dim, yellow } from './style.js';
+import { claimNotice } from './notice-marker.js';
+import { trackEvent } from './telemetry.js';
 const PKG_NAME = '@productbrain/cli';
-const CACHE_TTL_MS = 24 * 60 * 60 * 1000; // 24 hours
+const SERVER_FRESHNESS_MS = 48 * 60 * 60 * 1000;
+// npm fallback freshness — mirrors the single-source 24h cache TTL that existed before the
+// multi-source split, so a cached npm value is revalidated daily instead of served forever.
+const NPM_FRESHNESS_MS = 24 * 60 * 60 * 1000;
 const CONFIG_DIR = join(homedir(), '.config', 'productbrain');
 const CACHE_PATH = join(CONFIG_DIR, 'update-check.json');
-/** Read the cached latest version if it is still fresh (< 24h). */
-function readCache() {
+const UPGRADE_PENDING_PATH = join(CONFIG_DIR, 'upgrade-pending');
+const NPM_BETA_URL = `https://registry.npmjs.org/${PKG_NAME}/beta`;
+const CHANNEL_RANK = { alpha: -3, beta: -2, rc: -1 };
+let pendingUpgradeClearedThisProcess = false;
+let versionSkewReportedThisProcess = false;
+let cachedRunningCliVersion;
+/** Read the running CLI version from the package's package.json (cached after first read). */
+function readRunningCliVersion() {
+    if (cachedRunningCliVersion !== undefined)
+        return cachedRunningCliVersion;
+    try {
+        const here = dirname(fileURLToPath(import.meta.url));
+        const pkgPath = join(here, '..', '..', 'package.json');
+        const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
+        cachedRunningCliVersion = pkg.version ?? null;
+    }
+    catch {
+        cachedRunningCliVersion = null;
+    }
+    return cachedRunningCliVersion;
+}
+/**
+ * Emit `cli.version_skew.detected` at most once per process when a strictly newer
+ * version has been observed. Exported so callers (e.g. doctor's freshness check)
+ * can fire it from their own discovery path while sharing the dedup guard.
+ */
+export function reportVersionSkewIfNew(latest, current) {
+    if (versionSkewReportedThisProcess)
+        return;
+    if (!latest)
+        return;
+    const running = current ?? readRunningCliVersion();
+    if (!running)
+        return;
+    if (!isNewer(running, latest))
+        return;
+    versionSkewReportedThisProcess = true;
+    trackEvent('cli.version_skew.detected', { current: running, latest });
+}
+function readCacheFile() {
     try {
         if (!existsSync(CACHE_PATH))
-            return null;
-        const raw = readFileSync(CACHE_PATH, 'utf8');
-        const entry = JSON.parse(raw);
-        if (Date.now() - entry.checkedAt < CACHE_TTL_MS) {
-            return entry.latestVersion;
-        }
+            return {};
+        return JSON.parse(readFileSync(CACHE_PATH, 'utf8'));
     }
     catch {
-        // Corrupt or missing cache — treat as cold
+        return {};
     }
-    return null;
 }
-/** Write a cache entry with the resolved latest version. */
-function writeCache(latestVersion) {
+function writeCacheFile(cache) {
     try {
         mkdirSync(CONFIG_DIR, { recursive: true });
-        const entry = { checkedAt: Date.now(), latestVersion };
-        writeFileSync(CACHE_PATH, JSON.stringify(entry), 'utf8');
+        writeFileSync(CACHE_PATH, JSON.stringify(cache), 'utf8');
+    }
+    catch { /* non-fatal */ }
+}
+/** Return the newest (highest by semver) of the supplied values, ignoring null/undefined. */
+function newestOf(...values) {
+    let best = null;
+    for (const v of values) {
+        if (!v)
+            continue;
+        if (best === null || isNewer(best, v))
+            best = v;
+    }
+    return best;
+}
+/**
+ * Hot-path resolution from cache only — NEVER fetches. The **newest** in-window source wins: the
+ * server header is preferred only when it is actually the highest version, so a server that lags
+ * npm (its committed `cliVersion.ts` value trails the run-numbered npm publish — see TEN-2199) can
+ * no longer mask a newer npm latest. Returns the best available value even when every source is
+ * stale ("better than nothing"), because the hot path (checkForUpdate) cannot block on a refresh.
+ */
+export function resolveCachedLatest() {
+    if (isVersionCheckDisabled())
+        return null;
+    const cache = readCacheFile();
+    const now = Date.now();
+    const serverFresh = cache.server && now - cache.server.recordedAt < SERVER_FRESHNESS_MS ? cache.server.value : null;
+    // Hot path: an npm value is usable even when stale ("better than nothing"); the live resolver
+    // (resolveLatestVersion) is the one that enforces the npm freshness window and re-fetches.
+    const best = newestOf(serverFresh, cache.npm?.value);
+    if (best !== null)
+        return best;
+    return cache.server?.value ?? null; // stale server (>48h) as last resort — better than nothing
+}
+/** The in-window value from each source (null when the source is absent or past its freshness window). */
+function readFreshSources() {
+    const cache = readCacheFile();
+    const now = Date.now();
+    return {
+        server: cache.server && now - cache.server.recordedAt < SERVER_FRESHNESS_MS ? cache.server.value : null,
+        npm: cache.npm && now - cache.npm.recordedAt < NPM_FRESHNESS_MS ? cache.npm.value : null,
+    };
+}
+/** @deprecated use resolveCachedLatest. Kept for callers migrating. */
+export function readCachedLatestVersion() {
+    return resolveCachedLatest();
+}
+function isVersionCheckDisabled() {
+    return process.env.PB_NO_VERSION_CHECK === '1';
+}
+/** Clear the post-upgrade sentinel and stale update cache on next CLI startup. */
+export function clearPendingUpgradeCache() {
+    if (pendingUpgradeClearedThisProcess)
+        return;
+    pendingUpgradeClearedThisProcess = true;
+    try {
+        if (!existsSync(UPGRADE_PENDING_PATH))
+            return;
+        try {
+            unlinkSync(UPGRADE_PENDING_PATH);
+        }
+        catch { /* non-fatal */ }
+        try {
+            if (existsSync(CACHE_PATH))
+                unlinkSync(CACHE_PATH);
+        }
+        catch { /* non-fatal */ }
     }
     catch {
-        // Cache write failure is non-fatal
+        // Sentinel cleanup must never block CLI startup.
     }
 }
+/** Written after a successful self-upgrade so the next CLI process drops stale cache. */
+export function writeUpgradePendingSentinel(installedVersion) {
+    try {
+        mkdirSync(CONFIG_DIR, { recursive: true });
+        writeFileSync(UPGRADE_PENDING_PATH, JSON.stringify({ upgradedAt: Date.now(), version: installedVersion ?? null /* version: concrete installed version, recorded for post-upgrade diagnostics/future "upgraded to X" notice */ }), 'utf8');
+    }
+    catch { /* non-fatal — update checks recover via cache TTL */ }
+}
+/** Test-only: reset module-level per-process guards so each test starts clean. */
+export function _resetProcessGuardsForTest() {
+    pendingUpgradeClearedThisProcess = false;
+    versionSkewReportedThisProcess = false;
+    cachedRunningCliVersion = undefined;
+}
 /** Fetch latest version from npm registry. Returns null on any error. */
 function fetchLatestVersion() {
     return new Promise((resolve) => {
-        // Use beta dist-tag — package publishes with --tag beta; /latest is pinned to beta.1
-        const url = `https://registry.npmjs.org/${PKG_NAME}/beta`;
-        const req = request(url, { method: 'GET', headers: { 'Accept': 'application/json' } }, (res) => {
+        const req = request(NPM_BETA_URL, { method: 'GET', headers: { 'Accept': 'application/json' } }, (res) => {
             let body = '';
             res.on('data', (chunk) => { body += chunk.toString(); });
             res.on('end', () => {
@@ -79,21 +196,19 @@ function fetchLatestVersion() {
  * Compare two semver strings. Returns true if `b` is strictly newer than `a`.
  * Handles standard x.y.z and x.y.z-beta.N formats (numeric comparison per part).
  */
-function isNewer(current, latest) {
+export function isNewer(current, latest) {
     if (current === latest)
         return false;
     const parseVersion = (v) => {
-        // Strip leading 'v'
         const clean = v.replace(/^v/, '');
-        // Split on '-' to handle pre-release like '0.1.0-beta.70'
         const [release, pre] = clean.split('-');
         const parts = (release ?? '').split('.').map((n) => parseInt(n, 10) || 0);
-        // Append pre-release numeric tag as a negative offset so pre < release
-        if (pre !== undefined) {
-            const preNum = parseInt(pre.replace(/\D+/, ''), 10) || 0;
-            parts.push(-1e6 + preNum);
-        }
-        return parts;
+        if (pre === undefined)
+            return [...parts, 0, 0];
+        const match = pre.match(/^([a-zA-Z]+)\.?(\d+)?/);
+        const channel = match?.[1]?.toLowerCase() ?? '';
+        const preNum = match?.[2] ? parseInt(match[2], 10) : 0;
+        return [...parts, CHANNEL_RANK[channel] ?? -4, Number.isFinite(preNum) ? preNum : 0];
     };
     const a = parseVersion(current);
     const b = parseVersion(latest);
@@ -108,38 +223,74 @@ function isNewer(current, latest) {
     }
     return false;
 }
+/** Record the server-supplied latest version (authoritative source). */
+export function recordServerLatest(latestVersion) {
+    if (isVersionCheckDisabled() || !latestVersion)
+        return;
+    const cache = readCacheFile();
+    cache.server = { value: latestVersion, recordedAt: Date.now() };
+    writeCacheFile(cache);
+    reportVersionSkewIfNew(latestVersion);
+}
+/** Record an npm-resolved latest version — gated so it never stores <= installed. */
+export function recordNpmLatest(latestVersion, currentVersion) {
+    if (isVersionCheckDisabled() || !latestVersion)
+        return;
+    if (!isNewer(currentVersion, latestVersion))
+        return;
+    const cache = readCacheFile();
+    cache.npm = { value: latestVersion, recordedAt: Date.now() };
+    writeCacheFile(cache);
+}
+/** LIVE resolve — fetches npm and records it (gated). Call ONLY from doctor/upgrade, never the hot path. */
+export async function resolveLatestVersion(currentVersion) {
+    if (isVersionCheckDisabled())
+        return null;
+    const fresh = readFreshSources();
+    // Skip the network ONLY when npm itself is within its freshness window. A fresh server header
+    // alone cannot prove npm isn't newer (the hot path never populates npm, and the server's committed
+    // cliVersion.ts value structurally trails the run-numbered npm publish — TEN-2199), so a
+    // server-only cache MUST trigger a live npm fetch or the lagging server would mask the true latest.
+    if (fresh.npm !== null)
+        return newestOf(fresh.server, fresh.npm);
+    const fetched = await fetchLatestVersion();
+    if (fetched !== null) {
+        // The live registry is ground truth. Record only when strictly newer (the cache never stores a
+        // value <= installed), but compare against any fresh server header so a genuinely-newer server
+        // still wins. A successful fetch REPLACES a stale npm entry rather than falling back to it.
+        if (currentVersion)
+            recordNpmLatest(fetched, currentVersion);
+        return newestOf(fresh.server, fetched);
+    }
+    // Fetch failed (offline / registry unreachable): fall back to any cached value — better than
+    // nothing, and the documented `pb doctor` offline backstop.
+    return resolveCachedLatest();
+}
 /**
- * Prints one line to stderr if a newer version is available.
- * The check is always non-blocking: it fires async and is not awaited by the caller.
- *
- * Call once per human-initiated command, just before the command action runs.
+ * Synchronously prints at most one update line. Reads cache only — never fetches.
+ * Reaches agents (JSON mode) on stderr; stdout stays bare JSON. Throttled once per
+ * session (agent) / once per UTC day (human TTY) via O_EXCL markers. Never throws.
+ * NOTE: a session with no authenticated server call writes no cache and fires no
+ * notice; `pb doctor` live-resolves as the backstop. DEC-2.
  */
 export function checkForUpdate(currentVersion) {
-    // Suppress in JSON/agent mode
-    if (isJsonMode())
+    clearPendingUpgradeCache();
+    if (isVersionCheckDisabled())
         return;
-    // Fire-and-forget: result is printed after command output via process.nextTick trick
-    void (async () => {
-        try {
-            // Try cache first
-            let latest = readCache();
-            if (latest === null) {
-                latest = await fetchLatestVersion();
-                if (latest)
-                    writeCache(latest);
-            }
-            if (!latest)
-                return;
-            if (!isNewer(currentVersion, latest))
-                return;
-            // Print after current command output (nextTick ensures we don't interleave)
-            process.nextTick(() => {
-                process.stderr.write(`\n${yellow('Update available:')} ${dim(currentVersion)} → ${latest}  ${dim('run')} pb upgrade ${dim('to update')}\n`);
-            });
-        }
-        catch {
-            // Never surface update-check errors to the user
-        }
-    })();
+    try {
+        const latest = resolveCachedLatest();
+        if (!latest || !isNewer(currentVersion, latest))
+            return;
+        reportVersionSkewIfNew(latest, currentVersion);
+        const channel = isJsonMode() ? 'agent' : 'human';
+        if (!claimNotice(channel))
+            return;
+        const line = `${yellow('pb:')} update available — you're on ${dim(currentVersion)}, latest is ${latest}. ` +
+            `Recommended: tell your operator and run ${dim('pb upgrade')}.\n`;
+        process.stderr.write('\n' + line);
+    }
+    catch {
+        // Advisory notice — never block or crash a command.
+    }
 }
 //# sourceMappingURL=update-check.js.map