@productbrain/cli 0.1.0-beta.47 → 0.1.0-beta.4721

package/dist/lib/profiles.js

@@ -16,7 +16,16 @@ const ACTIVE_PROFILE_PATH = resolve(HOME_CONFIG_DIR, 'active-profile');
 const LEGACY_ENV_PATH = resolve(HOME_CONFIG_DIR, '.env');
 /** Profile name validation: lowercase alphanumeric + hyphens, 1-32 chars. */
 const PROFILE_NAME_RE = /^[a-z0-9][a-z0-9-]{0,31}$/;
-function validateProfileName(name) {
+/**
+ * Validate a profile name — lowercase alphanumeric + hyphens, 1-32 chars, no path
+ * separators. Exported so any caller that resolves a path from an UNTRUSTED name
+ * (e.g. `PB_PROFILE`) before it reaches a `createProfile`/`useProfile`/`deleteProfile`
+ * write can validate at the point of first path resolution, not only at the eventual
+ * write (TEN-2851 Copilot review: connect.ts's read-before-write called
+ * `resolveNamedProfileConfig()` — which resolves a path but never validated — before
+ * name validation ever ran).
+ */
+export function validateProfileName(name) {
     if (!PROFILE_NAME_RE.test(name)) {
         throw new CLIError(`Invalid profile name "${name}". Must be 1-32 chars, lowercase alphanumeric + hyphens, starting with alphanumeric.`, { code: ErrorCode.PROFILE_NAME_INVALID, category: 'profile' });
     }
@@ -49,16 +58,24 @@ function readProfileFile(path) {
 /**
  * Auto-migrate legacy ~/.config/productbrain/.env to profiles/default.env.
  * Only runs if legacy file exists AND no profiles directory exists.
+ * If profiles already exist, silently removes the legacy .env (TEN-1343) — so any caller
+ * that might CREATE the profiles dir before this runs (e.g. `pb connect`'s named-profile
+ * create path) must call this FIRST, or the legacy file is deleted, unmigrated (Codex
+ * review, WP-628 P1).
  */
-function autoMigrate() {
-    if (existsSync(PROFILES_DIR))
+export function autoMigrate() {
+    if (existsSync(PROFILES_DIR)) {
+        if (existsSync(LEGACY_ENV_PATH))
+            unlinkSync(LEGACY_ENV_PATH);
         return false;
+    }
     if (!existsSync(LEGACY_ENV_PATH))
         return false;
     mkdirSync(PROFILES_DIR, { recursive: true });
     const content = readFileSync(LEGACY_ENV_PATH, 'utf8');
     writeFileSync(profilePath('default'), content, { mode: 0o600 });
     writeFileSync(ACTIVE_PROFILE_PATH, 'default', { mode: 0o600 });
+    unlinkSync(LEGACY_ENV_PATH);
     return true;
 }
 /** List all profile names (sorted). */
@@ -71,12 +88,8 @@ export function listProfiles() {
         .map((f) => f.replace(/\.env$/, ''))
         .sort();
 }
-/** Get the active profile name. */
-export function getActiveProfile() {
-    // PB_PROFILE env var takes precedence
-    const envProfile = process.env.PB_PROFILE?.trim();
-    if (envProfile)
-        return envProfile;
+/** Read the global active-profile file only (ignores PB_PROFILE). */
+export function getGlobalActiveProfile() {
     if (existsSync(ACTIVE_PROFILE_PATH)) {
         const name = readFileSync(ACTIVE_PROFILE_PATH, 'utf8').trim();
         if (name)
@@ -84,12 +97,24 @@ export function getActiveProfile() {
     }
     return null;
 }
-/** Create a new profile. */
-export function createProfile(name, apiKey, siteUrl) {
+/** Get the active profile name (PB_PROFILE env wins, then the global file). */
+export function getActiveProfile() {
+    const envProfile = process.env.PB_PROFILE?.trim();
+    if (envProfile)
+        return envProfile;
+    return getGlobalActiveProfile();
+}
+/**
+ * Create a new profile.
+ *
+ * TEN-2851: refuses to overwrite an existing profile file by default — a caller wanting to
+ * replace an occupied profile's credentials must pass `{ overwrite: true }` explicitly (the
+ * act stays deliberate at every call site, never a silent side-effect of a name collision).
+ * `pb connect`'s clobber gate (connect.ts saveKeyAsProfile) is the one caller that passes it,
+ * and only after an explicit interactive confirm.
+ */
+export function createProfile(name, apiKey, siteUrl, opts) {
     validateProfileName(name);
-    if (existsSync(profilePath(name))) {
-        throw new CLIError(`Profile "${name}" already exists.`, { code: ErrorCode.PROFILE_ALREADY_EXISTS, category: 'profile' });
-    }
     mkdirSync(PROFILES_DIR, { recursive: true });
     const lines = [
         `# Product Brain CLI profile: ${name}`,
@@ -99,9 +124,36 @@ export function createProfile(name, apiKey, siteUrl) {
         lines.push(`CONVEX_SITE_URL=${siteUrl}`);
     }
     lines.push('');
-    writeFileSync(profilePath(name), lines.join('\n'), { mode: 0o600 });
-    // If this is the first profile, make it active
-    if (!existsSync(ACTIVE_PROFILE_PATH)) {
+    const content = lines.join('\n');
+    // TEN-2851 TOCTOU (Copilot review): an existsSync() pre-check followed by a plain 'w'
+    // write leaves a race window — a concurrent process can create the file between the
+    // check and the write, and 'w' would silently truncate it. When NOT overwriting, use the
+    // exclusive-create flag 'wx' so the filesystem is the atomic guard: EEXIST (whether from
+    // a pre-existing file or one created in the race window) surfaces as the SAME
+    // PROFILE_ALREADY_EXISTS error every existing caller already handles. `{ overwrite: true }`
+    // is an explicit, already-confirmed replace (see connect.ts saveKeyAsProfile) and
+    // intentionally keeps the plain 'w' flag — it means to replace whatever is there.
+    if (opts?.overwrite) {
+        writeFileSync(profilePath(name), content, { mode: 0o600 });
+    }
+    else {
+        try {
+            writeFileSync(profilePath(name), content, { mode: 0o600, flag: 'wx' });
+        }
+        catch (err) {
+            if (err && typeof err === 'object' && 'code' in err && err.code === 'EEXIST') {
+                throw new CLIError(`Profile "${name}" already exists.`, { code: ErrorCode.PROFILE_ALREADY_EXISTS, category: 'profile' });
+            }
+            throw err;
+        }
+    }
+    // If this is the first profile, make it active. Scoped to !opts?.overwrite (Codex review,
+    // WP-628 P2): an overwrite call means the profile ALREADY existed — it can never be "the
+    // first profile ever created" — so it must never claim a missing active-profile marker.
+    // Without this guard, confirming an overwrite while that marker happens to be absent would
+    // silently activate the overwritten target globally, contradicting this function's own
+    // "does not activate globally" contract (connect.ts saveKeyAsProfile docstring).
+    if (!opts?.overwrite && !existsSync(ACTIVE_PROFILE_PATH)) {
         writeFileSync(ACTIVE_PROFILE_PATH, name, { mode: 0o600 });
     }
 }
@@ -143,7 +195,7 @@ export function resolveProfileConfig() {
     if (envProfile) {
         const config = readProfileFile(profilePath(envProfile));
         if (config)
-            return config;
+            return { ...config, profileName: envProfile };
     }
     // 2. Check active-profile file
     if (existsSync(ACTIVE_PROFILE_PATH)) {
@@ -151,30 +203,37 @@ export function resolveProfileConfig() {
         if (name) {
             const config = readProfileFile(profilePath(name));
             if (config)
-                return config;
+                return { ...config, profileName: name };
         }
     }
     // 3. Check "default" profile
     {
         const config = readProfileFile(profilePath('default'));
         if (config)
-            return config;
+            return { ...config, profileName: 'default' };
     }
-    // 4. Fall back to legacy .env
+    // 4. Fall back to legacy .env — not a named profile, so no profileName.
     {
         const config = readProfileFile(LEGACY_ENV_PATH);
         if (config)
-            return config;
+            return { ...config, profileName: null };
     }
     return null;
 }
 /**
  * Resolve config for a specific named profile.
- * Returns null if the profile doesn't exist.
+ * Returns null both when the profile file is absent AND when it exists but fails to parse
+ * (missing/empty PRODUCTBRAIN_API_KEY) — those two cases are NOT the same thing to a caller
+ * deciding whether it's safe to create; use `profileFileExists()` to tell them apart
+ * (Codex review, WP-628 P2).
  */
 export function resolveNamedProfileConfig(name) {
     return readProfileFile(profilePath(name));
 }
+/** Does a profile FILE exist at this name, independent of whether it parses (see above). */
+export function profileFileExists(name) {
+    return existsSync(profilePath(name));
+}
 // Exported for testing
 export { PROFILES_DIR, ACTIVE_PROFILE_PATH, LEGACY_ENV_PATH, HOME_CONFIG_DIR };
 //# sourceMappingURL=profiles.js.map

package/dist/lib/profiles.js.map

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

package/dist/lib/rate-limit.d.ts

@@ -0,0 +1,37 @@
+/**
+ * WP-579 — client-side rate-limit resilience for the gateway helpers in client.ts
+ * (TEN-2923 touch amplification, TEN-2924 no-backoff-on-429).
+ *
+ * Split out of client.ts rather than grown inside it: these are two self-contained
+ * policies (when to retry a throttled call, when a session touch is worth sending) with
+ * their own constants and module-level state, and client.ts is at its STD-2 budget.
+ *
+ * Depends only on the error taxonomy — NOT on client.ts's `McpError` — so the two modules
+ * don't form an import cycle. The retry keys off the error's `code`, which is exactly what
+ * the guard tested before the split (`McpError` is the only thing that sets
+ * `code === 'rate-limited'` alongside a `retryAfterSeconds`).
+ */
+/**
+ * TEN-2924: bounded, jittered retry for a rate-limited call. Honors the server's
+ * Retry-After rather than guessing a backoff curve. Only retries a rate-limit refusal —
+ * never a validation/auth/internal failure, which retrying unchanged would just repeat.
+ */
+export declare function withRateLimitRetry<T>(attempt: () => Promise<T>): Promise<T>;
+/**
+ * Per-call knobs for the gateway helpers.
+ *
+ * `retryOnRateLimit: false` is the opt-out a BACKGROUND (unawaited) call must pass. A
+ * pending retry timer keeps the Node event loop alive, so retrying a fire-and-forget call
+ * holds the CLI process open long after its foreground work finished — breaking the very
+ * "never block" contract those call sites are written against. A background call that
+ * loses to a 429 is simply dropped; it is observability, not the user's work.
+ */
+export type KernelCallOptions = {
+    retryOnRateLimit?: boolean;
+};
+/** Applies the rate-limit retry unless the caller opted out (background calls). */
+export declare function maybeRetry<T>(attempt: () => Promise<T>, options?: KernelCallOptions): Promise<T>;
+export declare function shouldTouchSession(sessionId: string): boolean;
+/** Test-only escape hatch — mirrors packages/mcp-server/src/client.ts's resetTouchThrottle. */
+export declare function resetTouchThrottle(sessionId?: string | null): void;
+//# sourceMappingURL=rate-limit.d.ts.map

package/dist/lib/rate-limit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rate-limit.d.ts","sourceRoot":"","sources":["../../src/lib/rate-limit.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAsBH;;;;GAIG;AACH,wBAAsB,kBAAkB,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAajF;AAED;;;;;;;;GAQG;AACH,MAAM,MAAM,iBAAiB,GAAG;IAAE,gBAAgB,CAAC,EAAE,OAAO,CAAA;CAAE,CAAC;AAE/D,mFAAmF;AACnF,wBAAgB,UAAU,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,CAAC,CAAC,CAEhG;AAYD,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAM7D;AAED,+FAA+F;AAC/F,wBAAgB,kBAAkB,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAMlE"}

package/dist/lib/rate-limit.js

@@ -0,0 +1,83 @@
+/**
+ * WP-579 — client-side rate-limit resilience for the gateway helpers in client.ts
+ * (TEN-2923 touch amplification, TEN-2924 no-backoff-on-429).
+ *
+ * Split out of client.ts rather than grown inside it: these are two self-contained
+ * policies (when to retry a throttled call, when a session touch is worth sending) with
+ * their own constants and module-level state, and client.ts is at its STD-2 budget.
+ *
+ * Depends only on the error taxonomy — NOT on client.ts's `McpError` — so the two modules
+ * don't form an import cycle. The retry keys off the error's `code`, which is exactly what
+ * the guard tested before the split (`McpError` is the only thing that sets
+ * `code === 'rate-limited'` alongside a `retryAfterSeconds`).
+ */
+import { ErrorCode } from './errors.js';
+const MAX_RATE_LIMIT_RETRIES = 3;
+const RATE_LIMIT_RETRY_JITTER_MS = 250;
+/**
+ * Ceiling on a single honored Retry-After. The server clamps its value to the tripped
+ * window (convex/rateLimiter.ts `retryAfterSeconds`) — 60s for the minute window, but
+ * 86_400s for the DAY window. Honoring that unconditionally would park the process for up
+ * to a day per attempt, three attempts deep. A day-quota denial is not something to wait
+ * out in-process: surface it so the caller can retry out of band.
+ */
+const MAX_RATE_LIMIT_RETRY_WAIT_SECONDS = 60;
+/** Seconds to wait, if this error is a rate-limit refusal that carries a Retry-After. */
+function rateLimitWaitOf(err) {
+    const candidate = err;
+    if (!candidate || candidate.code !== ErrorCode.RATE_LIMITED)
+        return undefined;
+    return typeof candidate.retryAfterSeconds === 'number' ? candidate.retryAfterSeconds : undefined;
+}
+/**
+ * TEN-2924: bounded, jittered retry for a rate-limited call. Honors the server's
+ * Retry-After rather than guessing a backoff curve. Only retries a rate-limit refusal —
+ * never a validation/auth/internal failure, which retrying unchanged would just repeat.
+ */
+export async function withRateLimitRetry(attempt) {
+    for (let retries = 0;; retries++) {
+        try {
+            return await attempt();
+        }
+        catch (err) {
+            const waitSeconds = rateLimitWaitOf(err);
+            if (waitSeconds === undefined || retries >= MAX_RATE_LIMIT_RETRIES)
+                throw err;
+            // Day-window denial (or any wait we won't sit on) — fail fast rather than hang.
+            if (waitSeconds > MAX_RATE_LIMIT_RETRY_WAIT_SECONDS)
+                throw err;
+            const delayMs = waitSeconds * 1000 + Math.random() * RATE_LIMIT_RETRY_JITTER_MS;
+            await new Promise((resolve) => setTimeout(resolve, delayMs));
+        }
+    }
+}
+/** Applies the rate-limit retry unless the caller opted out (background calls). */
+export function maybeRetry(attempt, options) {
+    return options?.retryOnRateLimit === false ? attempt() : withRateLimitRetry(attempt);
+}
+/**
+ * TEN-2923: client-side throttle mirroring packages/mcp-server/src/client.ts's
+ * touchSessionActivity — the server already no-ops a touch made <5s after the last one
+ * for this session (TOUCH_SESSION_THROTTLE_MS, DEC-75), so a touch inside that window is
+ * pure wasted quota. Matching the server's own window here removes the waste without
+ * changing renewal semantics at all (a throttled call was already a server-side no-op).
+ */
+const _lastTouchAtBySession = new Map();
+const TOUCH_THROTTLE_MS = 5_000;
+export function shouldTouchSession(sessionId) {
+    const now = Date.now();
+    const lastTouchAt = _lastTouchAtBySession.get(sessionId) ?? 0;
+    if (now - lastTouchAt < TOUCH_THROTTLE_MS)
+        return false;
+    _lastTouchAtBySession.set(sessionId, now);
+    return true;
+}
+/** Test-only escape hatch — mirrors packages/mcp-server/src/client.ts's resetTouchThrottle. */
+export function resetTouchThrottle(sessionId) {
+    if (sessionId) {
+        _lastTouchAtBySession.delete(sessionId);
+        return;
+    }
+    _lastTouchAtBySession.clear();
+}
+//# sourceMappingURL=rate-limit.js.map

package/dist/lib/rate-limit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rate-limit.js","sourceRoot":"","sources":["../../src/lib/rate-limit.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAExC,MAAM,sBAAsB,GAAG,CAAC,CAAC;AACjC,MAAM,0BAA0B,GAAG,GAAG,CAAC;AACvC;;;;;;GAMG;AACH,MAAM,iCAAiC,GAAG,EAAE,CAAC;AAE7C,yFAAyF;AACzF,SAAS,eAAe,CAAC,GAAY;IACnC,MAAM,SAAS,GAAG,GAAwE,CAAC;IAC3F,IAAI,CAAC,SAAS,IAAI,SAAS,CAAC,IAAI,KAAK,SAAS,CAAC,YAAY;QAAE,OAAO,SAAS,CAAC;IAC9E,OAAO,OAAO,SAAS,CAAC,iBAAiB,KAAK,QAAQ,CAAC,CAAC,CAAC,SAAS,CAAC,iBAAiB,CAAC,CAAC,CAAC,SAAS,CAAC;AACnG,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CAAI,OAAyB;IACnE,KAAK,IAAI,OAAO,GAAG,CAAC,GAAI,OAAO,EAAE,EAAE,CAAC;QAClC,IAAI,CAAC;YACH,OAAO,MAAM,OAAO,EAAE,CAAC;QACzB,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,WAAW,GAAG,eAAe,CAAC,GAAG,CAAC,CAAC;YACzC,IAAI,WAAW,KAAK,SAAS,IAAI,OAAO,IAAI,sBAAsB;gBAAE,MAAM,GAAG,CAAC;YAC9E,gFAAgF;YAChF,IAAI,WAAW,GAAG,iCAAiC;gBAAE,MAAM,GAAG,CAAC;YAC/D,MAAM,OAAO,GAAG,WAAW,GAAG,IAAI,GAAG,IAAI,CAAC,MAAM,EAAE,GAAG,0BAA0B,CAAC;YAChF,MAAM,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC;QAC/D,CAAC;IACH,CAAC;AACH,CAAC;AAaD,mFAAmF;AACnF,MAAM,UAAU,UAAU,CAAI,OAAyB,EAAE,OAA2B;IAClF,OAAO,OAAO,EAAE,gBAAgB,KAAK,KAAK,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,kBAAkB,CAAC,OAAO,CAAC,CAAC;AACvF,CAAC;AAED;;;;;;GAMG;AACH,MAAM,qBAAqB,GAAG,IAAI,GAAG,EAAkB,CAAC;AACxD,MAAM,iBAAiB,GAAG,KAAK,CAAC;AAEhC,MAAM,UAAU,kBAAkB,CAAC,SAAiB;IAClD,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IACvB,MAAM,WAAW,GAAG,qBAAqB,CAAC,GAAG,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;IAC9D,IAAI,GAAG,GAAG,WAAW,GAAG,iBAAiB;QAAE,OAAO,KAAK,CAAC;IACxD,qBAAqB,CAAC,GAAG,CAAC,SAAS,EAAE,GAAG,CAAC,CAAC;IAC1C,OAAO,IAAI,CAAC;AACd,CAAC;AAED,+FAA+F;AAC/F,MAAM,UAAU,kBAAkB,CAAC,SAAyB;IAC1D,IAAI,SAAS,EAAE,CAAC;QACd,qBAAqB,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;QACxC,OAAO;IACT,CAAC;IACD,qBAAqB,CAAC,KAAK,EAAE,CAAC;AAChC,CAAC"}

package/dist/lib/runner.d.ts

@@ -15,7 +15,15 @@ export declare function getOutputMode(): 'auto' | 'json' | 'pretty';
 /** Returns true if the current output mode resolves to JSON. */
 export declare function isJsonMode(): boolean;
 export declare function setQuietMode(quiet: boolean): void;
+/**
+ * The RAW quiet flag, independent of JSON mode. isQuietMode() conflates JSON mode,
+ * so read this when you need the literal quiet state (e.g. to assert that a window
+ * left quiet — and therefore the interactive-prompt gate — untouched).
+ */
+export declare function getQuietMode(): boolean;
 export declare function isQuietMode(): boolean;
+export declare function setSpinnersSilenced(silenced: boolean): void;
+export declare function areSpinnersSilenced(): boolean;
 export interface RunCliCommandOptions<T> {
     /** The async function that performs the MCP call and returns data. */
     fn: () => Promise<T>;

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

@@ -1 +1 @@
-{"version":3,"file":"runner.d.ts","sourceRoot":"","sources":["../../src/lib/runner.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAWH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,QAAQ,GAAG,IAAI,CAEpE;AAED,wBAAgB,aAAa,IAAI,MAAM,GAAG,MAAM,GAAG,QAAQ,CAE1D;AAED,gEAAgE;AAChE,wBAAgB,UAAU,IAAI,OAAO,CAKpC;AASD,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI,CAEjD;AAED,wBAAgB,WAAW,IAAI,OAAO,CAIrC;AAED,MAAM,WAAW,oBAAoB,CAAC,CAAC;IACrC,sEAAsE;IACtE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,CAAC;IACrB,kDAAkD;IAClD,YAAY,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,MAAM,CAAC;CACnC;AAED;;;;;;GAMG;AACH,wBAAsB,aAAa,CAAC,CAAC,EAAE,OAAO,EAAE,oBAAoB,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAwBtF"}
+{"version":3,"file":"runner.d.ts","sourceRoot":"","sources":["../../src/lib/runner.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAWH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,QAAQ,GAAG,IAAI,CAEpE;AAED,wBAAgB,aAAa,IAAI,MAAM,GAAG,MAAM,GAAG,QAAQ,CAE1D;AAED,gEAAgE;AAChE,wBAAgB,UAAU,IAAI,OAAO,CAKpC;AASD,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI,CAEjD;AAED;;;;GAIG;AACH,wBAAgB,YAAY,IAAI,OAAO,CAEtC;AAED,wBAAgB,WAAW,IAAI,OAAO,CAIrC;AAYD,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,OAAO,GAAG,IAAI,CAE3D;AAED,wBAAgB,mBAAmB,IAAI,OAAO,CAE7C;AAED,MAAM,WAAW,oBAAoB,CAAC,CAAC;IACrC,sEAAsE;IACtE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,CAAC;IACrB,kDAAkD;IAClD,YAAY,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,MAAM,CAAC;CACnC;AAED;;;;;;GAMG;AACH,wBAAsB,aAAa,CAAC,CAAC,EAAE,OAAO,EAAE,oBAAoB,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAwBtF"}

package/dist/lib/runner.js

@@ -41,12 +41,35 @@ let quietMode = false;
 export function setQuietMode(quiet) {
     quietMode = quiet;
 }
+/**
+ * The RAW quiet flag, independent of JSON mode. isQuietMode() conflates JSON mode,
+ * so read this when you need the literal quiet state (e.g. to assert that a window
+ * left quiet — and therefore the interactive-prompt gate — untouched).
+ */
+export function getQuietMode() {
+    return quietMode;
+}
 export function isQuietMode() {
     // JSON mode is inherently quiet — no decorative output needed
     if (isJsonMode())
         return true;
     return quietMode;
 }
+/**
+ * Spinner suppression — independent of quiet/json mode. Silences withSpinner()
+ * output WITHOUT making the CLI "quiet" (quiet also gates interactive prompts via
+ * prompts.ts/assertInteractive). `pb connect` flips this to hide the raw per-kernelCall
+ * spinner labels ("Loading chain getVocabulary", …) while still letting the handshake's
+ * adopt/revert prompts for PB-managed tampered files run (TEN-2561 / WP-2: legible
+ * output must never silence a prompt the user needs to answer).
+ */
+let spinnersSilenced = false;
+export function setSpinnersSilenced(silenced) {
+    spinnersSilenced = silenced;
+}
+export function areSpinnersSilenced() {
+    return spinnersSilenced;
+}
 /**
  * Execute a CLI command with unified output handling.
  *

package/dist/lib/runner.js.map

@@ -1 +1 @@
-{"version":3,"file":"runner.js","sourceRoot":"","sources":["../../src/lib/runner.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAClD,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAEvC;;;GAGG;AACH,IAAI,UAAU,GAA+B,MAAM,CAAC;AAEpD,MAAM,UAAU,aAAa,CAAC,IAAgC;IAC5D,UAAU,GAAG,IAAI,CAAC;AACpB,CAAC;AAED,MAAM,UAAU,aAAa;IAC3B,OAAO,UAAU,CAAC;AACpB,CAAC;AAED,gEAAgE;AAChE,MAAM,UAAU,UAAU;IACxB,IAAI,UAAU,KAAK,MAAM;QAAE,OAAO,IAAI,CAAC;IACvC,IAAI,UAAU,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IAC1C,4CAA4C;IAC5C,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC;AAC/B,CAAC;AAED;;;;GAIG;AACH,IAAI,SAAS,GAAG,KAAK,CAAC;AAEtB,MAAM,UAAU,YAAY,CAAC,KAAc;IACzC,SAAS,GAAG,KAAK,CAAC;AACpB,CAAC;AAED,MAAM,UAAU,WAAW;IACzB,8DAA8D;IAC9D,IAAI,UAAU,EAAE;QAAE,OAAO,IAAI,CAAC;IAC9B,OAAO,SAAS,CAAC;AACnB,CAAC;AASD;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CAAI,OAAgC;IACrE,MAAM,IAAI,GAAG,UAAU,EAAE,CAAC;IAE1B,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,MAAM,OAAO,CAAC,EAAE,EAAE,CAAC;QAEhC,IAAI,IAAI,EAAE,CAAC;YACT,MAAM,QAAQ,GAAG,oBAAoB,CAAC,IAAI,CAAC,CAAC;YAC5C,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,GAAG,IAAI,CAAC,CAAC;QACxD,CAAC;aAAM,CAAC;YACN,MAAM,SAAS,GAAG,OAAO,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC;YAC7C,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,SAAS,GAAG,IAAI,CAAC,CAAC;QACzC,CAAC;IACH,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,6EAA6E;QAC7E,+DAA+D;QAC/D,IAAI,GAAG,YAAY,QAAQ,EAAE,CAAC;YAC5B,MAAM,GAAG,CAAC;QACZ,CAAC;QACD,MAAM,IAAI,QAAQ,CAChB,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAChD,EAAE,IAAI,EAAE,UAAU,EAAE,QAAQ,EAAE,UAAU,EAAE,CAC3C,CAAC;IACJ,CAAC;AACH,CAAC"}
+{"version":3,"file":"runner.js","sourceRoot":"","sources":["../../src/lib/runner.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAClD,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAEvC;;;GAGG;AACH,IAAI,UAAU,GAA+B,MAAM,CAAC;AAEpD,MAAM,UAAU,aAAa,CAAC,IAAgC;IAC5D,UAAU,GAAG,IAAI,CAAC;AACpB,CAAC;AAED,MAAM,UAAU,aAAa;IAC3B,OAAO,UAAU,CAAC;AACpB,CAAC;AAED,gEAAgE;AAChE,MAAM,UAAU,UAAU;IACxB,IAAI,UAAU,KAAK,MAAM;QAAE,OAAO,IAAI,CAAC;IACvC,IAAI,UAAU,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IAC1C,4CAA4C;IAC5C,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC;AAC/B,CAAC;AAED;;;;GAIG;AACH,IAAI,SAAS,GAAG,KAAK,CAAC;AAEtB,MAAM,UAAU,YAAY,CAAC,KAAc;IACzC,SAAS,GAAG,KAAK,CAAC;AACpB,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,YAAY;IAC1B,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,MAAM,UAAU,WAAW;IACzB,8DAA8D;IAC9D,IAAI,UAAU,EAAE;QAAE,OAAO,IAAI,CAAC;IAC9B,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;;;;;;GAOG;AACH,IAAI,gBAAgB,GAAG,KAAK,CAAC;AAE7B,MAAM,UAAU,mBAAmB,CAAC,QAAiB;IACnD,gBAAgB,GAAG,QAAQ,CAAC;AAC9B,CAAC;AAED,MAAM,UAAU,mBAAmB;IACjC,OAAO,gBAAgB,CAAC;AAC1B,CAAC;AASD;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CAAI,OAAgC;IACrE,MAAM,IAAI,GAAG,UAAU,EAAE,CAAC;IAE1B,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,MAAM,OAAO,CAAC,EAAE,EAAE,CAAC;QAEhC,IAAI,IAAI,EAAE,CAAC;YACT,MAAM,QAAQ,GAAG,oBAAoB,CAAC,IAAI,CAAC,CAAC;YAC5C,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,GAAG,IAAI,CAAC,CAAC;QACxD,CAAC;aAAM,CAAC;YACN,MAAM,SAAS,GAAG,OAAO,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC;YAC7C,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,SAAS,GAAG,IAAI,CAAC,CAAC;QACzC,CAAC;IACH,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,6EAA6E;QAC7E,+DAA+D;QAC/D,IAAI,GAAG,YAAY,QAAQ,EAAE,CAAC;YAC5B,MAAM,GAAG,CAAC;QACZ,CAAC;QACD,MAAM,IAAI,QAAQ,CAChB,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAChD,EAAE,IAAI,EAAE,UAAU,EAAE,QAAQ,EAAE,UAAU,EAAE,CAC3C,CAAC;IACJ,CAAC;AACH,CAAC"}

package/dist/lib/session.d.ts

@@ -2,6 +2,20 @@
  * Session state — persists active session ID between CLI invocations.
  * Stored at .productbrain/session.json in the project root.
  * Solves TEN-264 (option 1: explicit session token).
+ *
+ * WP-322 S2: session.json also serves as a closed marker (closedAt present)
+ * for auto-resume logic when the last session closed <2h ago.
+ *
+ * WP-479 E2 (client half): when a conversation identity resolves (see ./conversation.ts —
+ * PB_CONVERSATION_ID / CLAUDE_CODE_SESSION_ID / CURSOR_CONVERSATION_ID / hashed
+ * CODEX_TUI_SESSION_LOG_PATH), the marker moves to `.productbrain/sessions/<conversationId>.json`
+ * so concurrent harness conversations sharing a worktree don't collide on one marker. Every
+ * function below resolves the conversation id ONCE (via resolveConversationId) and derives its
+ * path from that single value. With no identity signal present, resolveConversationId() returns
+ * null and every function falls back to the exact legacy `.productbrain/session.json` path and
+ * behavior — byte-identical, zero-config invariant. An explicit `conversationIdOverride` (only
+ * threaded from the CLI's `--conversation` flag on `pb session start`) takes priority over env
+ * detection; every other call site across the CLI calls these with no argument.
  */
 export interface SessionState {
     sessionId: string;
@@ -9,9 +23,76 @@ export interface SessionState {
     workspaceName: string;
     startedAt: string;
     entriesCaptured: string[];
+    /** Optional: set when session is closed. Presence indicates a closed-marker state. */
+    closedAt?: string;
+    /** Effective profile name at session start — backstop for detecting a profile switch. */
+    profile?: string;
+    /** WP-479 E2: the conversation identity this marker is scoped to, when one resolved. */
+    conversationId?: string;
 }
-export declare function readSession(): SessionState | null;
-export declare function writeSession(state: SessionState): void;
-export declare function clearSession(): void;
-export declare function addCapturedEntry(entryId: string): void;
+/** 2-hour window for auto-resume (WP-322 E1) — also the GC threshold for closed conversation
+ *  markers (WP-479 E2): a closed marker past this window will never be auto-resumed, so it's
+ *  garbage. Exported so commands/session.ts's resume logic uses the exact same constant. */
+export declare const RESUME_WINDOW_MS: number;
+/** Shape returned by readClosedMarker when a closed marker is present. */
+export interface ClosedMarker {
+    sessionId: string;
+    closedAt: string;
+    workspaceId: string;
+    workspaceName: string;
+    /** WP-479 E2: the conversation identity this marker was scoped to, when one resolved. */
+    conversationId?: string;
+}
+export declare function readSession(conversationIdOverride?: string): SessionState | null;
+export declare function writeSession(state: SessionState, conversationIdOverride?: string): void;
+/**
+ * Writes a closed marker instead of deleting the file.
+ * If the file is already a closed marker (closedAt present), deletes it outright
+ * to prevent a stale-marker reset loop (F2: Domain Fit review finding).
+ * Uses atomic write (tmp → rename) to prevent partial writes on active sessions.
+ * WP-322 S2 — enables auto-resume within 2h window.
+ */
+export declare function clearSession(conversationIdOverride?: string): void;
+/**
+ * Delete the CURRENT conversation's marker outright — NO closed marker. Use when discarding a
+ * single conversation's session (clearSession writes a resume marker; that is only correct for
+ * session close).
+ */
+export declare function discardSession(conversationIdOverride?: string): void;
+/**
+ * Delete EVERY session marker in this project — the legacy `session.json` AND every per-conversation
+ * marker under `.productbrain/sessions/`. Use on a WORKSPACE change (profile switch / connect
+ * redirect) so the 2h auto-resume can't re-pin the old workspace from ANY marker.
+ *
+ * Review fix (Codex): `discardSession()` resolves only the CURRENT conversation's marker, so a
+ * workspace-switch caller with no conversation env would leave other conversations' active markers
+ * behind — later reusable against the NEW workspace. A workspace change invalidates ALL of them, so
+ * this clears the whole set rather than one marker.
+ */
+export declare function discardAllSessions(): void;
+/** True if a session marker file exists at all — active session OR closed marker. */
+export declare function sessionFileExists(conversationIdOverride?: string): boolean;
+/**
+ * True if ANY session marker exists — the legacy `session.json` OR any per-conversation marker under
+ * `.productbrain/sessions/`. Used by `pb session reset` so a hard reset (and the binding-flip recovery
+ * it backs) can detect + clear a sibling conversation's marker it has no env to resolve (Codex
+ * re-review — the flip guard refuses on ANY active marker, so reset must see them ALL).
+ */
+export declare function hasAnySessionMarker(): boolean;
+/**
+ * True if ANY marker — legacy `session.json` OR any per-conversation marker — represents an ACTIVE
+ * session (no `closedAt`). Used by `pb session reset` so its confirmation/`--force` guard fires when
+ * a SIBLING conversation's session is active, not only the current one (Codex re-review: an
+ * all-marker reset must not silently strand an active sibling server session). Closed markers are
+ * inert and don't require a prompt.
+ */
+export declare function hasAnyActiveSession(): boolean;
+/**
+ * Reads the closed marker from the resolved conversation's marker file (or the legacy
+ * session.json when no conversation identity resolves).
+ * Returns the marker if closedAt is present, otherwise null.
+ * WP-322 S2 — used by runSessionStart to detect recent closed sessions.
+ */
+export declare function readClosedMarker(conversationIdOverride?: string): ClosedMarker | null;
+export declare function addCapturedEntry(entryId: string, conversationIdOverride?: string): void;
 //# sourceMappingURL=session.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../../src/lib/session.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAKH,MAAM,WAAW,YAAY;IAC3B,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,EAAE,MAAM,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC;IAClB,eAAe,EAAE,MAAM,EAAE,CAAC;CAC3B;AAUD,wBAAgB,WAAW,IAAI,YAAY,GAAG,IAAI,CAQjD;AAED,wBAAgB,YAAY,CAAC,KAAK,EAAE,YAAY,GAAG,IAAI,CAItD;AAED,wBAAgB,YAAY,IAAI,IAAI,CAGnC;AAED,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAKtD"}
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../../src/lib/session.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAOH,MAAM,WAAW,YAAY;IAC3B,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,EAAE,MAAM,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC;IAClB,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,sFAAsF;IACtF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,yFAAyF;IACzF,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,wFAAwF;IACxF,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;4FAE4F;AAC5F,eAAO,MAAM,gBAAgB,QAAqB,CAAC;AAEnD,0EAA0E;AAC1E,MAAM,WAAW,YAAY;IAC3B,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,EAAE,MAAM,CAAC;IACtB,yFAAyF;IACzF,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAiFD,wBAAgB,WAAW,CAAC,sBAAsB,CAAC,EAAE,MAAM,GAAG,YAAY,GAAG,IAAI,CAahF;AAED,wBAAgB,YAAY,CAAC,KAAK,EAAE,YAAY,EAAE,sBAAsB,CAAC,EAAE,MAAM,GAAG,IAAI,CAUvF;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,sBAAsB,CAAC,EAAE,MAAM,GAAG,IAAI,CA6BlE;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,sBAAsB,CAAC,EAAE,MAAM,GAAG,IAAI,CAIpE;AAED;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,IAAI,IAAI,CAmBzC;AAED,qFAAqF;AACrF,wBAAgB,iBAAiB,CAAC,sBAAsB,CAAC,EAAE,MAAM,GAAG,OAAO,CAG1E;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,IAAI,OAAO,CAS7C;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,IAAI,OAAO,CAkB7C;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,sBAAsB,CAAC,EAAE,MAAM,GAAG,YAAY,GAAG,IAAI,CAkBrF;AAED,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,EAAE,sBAAsB,CAAC,EAAE,MAAM,GAAG,IAAI,CAKvF"}