@productbrain/cli 0.1.0-beta.1395 → 0.1.0-beta.13957

package/dist/lib/session.js

@@ -5,10 +5,26 @@
  *
  * 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.
  */
-import { existsSync, readFileSync, writeFileSync, renameSync, mkdirSync, unlinkSync } from 'fs';
+import { existsSync, readFileSync, writeFileSync, renameSync, mkdirSync, unlinkSync, readdirSync } from 'fs';
 import { join } from 'path';
 import { findProjectRoot } from './config.js';
+import { resolveConversationId } from './conversation.js';
+/** 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 const RESUME_WINDOW_MS = 2 * 60 * 60 * 1000;
 /**
  * Resolve the `.productbrain/` session directory off the CLI project root — the SAME
  * walked-up root config.ts resolves credentials against (findProjectRoot), which is also the
@@ -28,8 +44,65 @@ function getSessionPath() {
 function getTmpSessionPath() {
     return join(getSessionDir(), 'session.json.tmp');
 }
-export function readSession() {
-    const p = getSessionPath();
+/** WP-479 E2: directory holding one marker file per resolved conversation id. */
+function getSessionsDir() {
+    return join(getSessionDir(), 'sessions');
+}
+function getConversationMarkerPath(conversationId) {
+    return join(getSessionsDir(), `${conversationId}.json`);
+}
+function getConversationTmpMarkerPath(conversationId) {
+    return join(getSessionsDir(), `${conversationId}.json.tmp`);
+}
+/**
+ * Resolve the marker path for a given (already-resolved) conversation id: the conversation-scoped
+ * path under `.productbrain/sessions/` when non-null, else the legacy shared path — the single
+ * fork point every function below routes through.
+ */
+function markerPath(conversationId) {
+    return conversationId ? getConversationMarkerPath(conversationId) : getSessionPath();
+}
+function tmpMarkerPath(conversationId) {
+    return conversationId ? getConversationTmpMarkerPath(conversationId) : getTmpSessionPath();
+}
+/**
+ * WP-479 E2 GC: delete closed conversation markers whose `closedAt` is older than the 2h resume
+ * window — a closed marker outside that window will never be auto-resumed, so it's inert litter.
+ * Best-effort, and cheap (no-ops when the sessions dir doesn't exist yet). Scoped to the
+ * conversation-marker directory only — the single legacy `session.json` is never GC'd here (its
+ * own clearSession/discardSession lifecycle is unchanged).
+ */
+function gcExpiredConversationMarkers() {
+    const dir = getSessionsDir();
+    if (!existsSync(dir))
+        return;
+    let entries;
+    try {
+        entries = readdirSync(dir);
+    }
+    catch {
+        return;
+    }
+    const now = Date.now();
+    for (const entry of entries) {
+        if (!entry.endsWith('.json'))
+            continue;
+        const full = join(dir, entry);
+        try {
+            const raw = JSON.parse(readFileSync(full, 'utf8'));
+            if (raw.closedAt && now - new Date(raw.closedAt).getTime() > RESUME_WINDOW_MS) {
+                unlinkSync(full);
+            }
+        }
+        catch {
+            // Malformed or concurrently-removed marker — ignore, non-blocking.
+        }
+    }
+}
+export function readSession(conversationIdOverride) {
+    gcExpiredConversationMarkers();
+    const conversationId = resolveConversationId(conversationIdOverride);
+    const p = markerPath(conversationId);
     if (!existsSync(p))
         return null;
     try {
@@ -43,11 +116,17 @@ export function readSession() {
         return null;
     }
 }
-export function writeSession(state) {
-    const dir = getSessionDir();
+export function writeSession(state, conversationIdOverride) {
+    const conversationId = resolveConversationId(conversationIdOverride);
+    // Stamp the resolved conversation id onto the state itself (WP-479 E2: "store the
+    // conversationId in it") so a later bare readSession() round-trips it, and so the marker file's
+    // own contents self-identify which conversation it belongs to.
+    state.conversationId = conversationId ?? undefined;
+    const dir = conversationId ? getSessionsDir() : getSessionDir();
     if (!existsSync(dir))
         mkdirSync(dir, { recursive: true });
-    writeFileSync(getSessionPath(), JSON.stringify(state, null, 2));
+    writeFileSync(markerPath(conversationId), JSON.stringify(state, null, 2));
+    gcExpiredConversationMarkers();
 }
 /**
  * Writes a closed marker instead of deleting the file.
@@ -56,8 +135,9 @@ export function writeSession(state) {
  * Uses atomic write (tmp → rename) to prevent partial writes on active sessions.
  * WP-322 S2 — enables auto-resume within 2h window.
  */
-export function clearSession() {
-    const p = getSessionPath();
+export function clearSession(conversationIdOverride) {
+    const conversationId = resolveConversationId(conversationIdOverride);
+    const p = markerPath(conversationId);
     if (!existsSync(p))
         return;
     try {
@@ -74,39 +154,172 @@ export function clearSession() {
             startedAt: existing.startedAt,
             entriesCaptured: [],
             closedAt: new Date().toISOString(),
+            conversationId: conversationId ?? undefined,
         };
-        const dir = getSessionDir();
+        const dir = conversationId ? getSessionsDir() : getSessionDir();
         if (!existsSync(dir))
             mkdirSync(dir, { recursive: true });
-        const tmp = getTmpSessionPath();
+        const tmp = tmpMarkerPath(conversationId);
         writeFileSync(tmp, JSON.stringify(marker, null, 2));
         renameSync(tmp, p);
     }
     catch {
         // If we can't write the marker, the file stays as-is (non-blocking).
     }
+    gcExpiredConversationMarkers();
 }
 /**
- * Delete session.json outright — NO closed marker. Use on a workspace change
- * (profile switch / connect redirect) so the 2h auto-resume can't re-pin the old
- * workspace. (clearSession writes a resume marker; that is only correct for session close.)
+ * 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 function discardSession() {
-    const p = getSessionPath();
+export function discardSession(conversationIdOverride) {
+    const conversationId = resolveConversationId(conversationIdOverride);
+    const p = markerPath(conversationId);
     if (existsSync(p))
         unlinkSync(p);
 }
-/** True if a session.json file exists at all — active session OR closed marker. */
-export function sessionFileExists() {
-    return existsSync(getSessionPath());
+/**
+ * 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 function discardAllSessions() {
+    const legacy = getSessionPath();
+    if (existsSync(legacy))
+        unlinkSync(legacy);
+    const dir = getSessionsDir();
+    if (!existsSync(dir))
+        return;
+    let entries;
+    try {
+        entries = readdirSync(dir);
+    }
+    catch {
+        return;
+    }
+    for (const entry of entries) {
+        if (!entry.endsWith('.json'))
+            continue;
+        try {
+            unlinkSync(join(dir, entry));
+        }
+        catch {
+            // concurrently removed — ignore, non-blocking.
+        }
+    }
+}
+/**
+ * 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 function hasAnySessionMarker() {
+    if (existsSync(getSessionPath()))
+        return true;
+    const dir = getSessionsDir();
+    if (!existsSync(dir))
+        return false;
+    try {
+        return readdirSync(dir).some((f) => f.endsWith('.json'));
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * 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 function hasAnyActiveSession() {
+    const isActive = (p) => {
+        try {
+            const raw = JSON.parse(readFileSync(p, 'utf8'));
+            return !raw.closedAt;
+        }
+        catch {
+            return false; // malformed/unreadable — treat as not-active (inert)
+        }
+    };
+    const legacy = getSessionPath();
+    if (existsSync(legacy) && isActive(legacy))
+        return true;
+    const dir = getSessionsDir();
+    if (!existsSync(dir))
+        return false;
+    try {
+        return readdirSync(dir).some((f) => f.endsWith('.json') && isActive(join(dir, f)));
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Find the ACTIVE marker carrying `sessionId`, across both storage shapes, or null.
+ *
+ * TEN-3315: the write-binding guard compares the bound credential against a marker's fingerprint,
+ * but a command can select a DIFFERENT conversation's session and pass its id explicitly (e.g.
+ * `pb rework report --conversation A`). Judging the ambient marker there would judge the wrong
+ * session, so the guard used to skip — blind exactly where the caller was most deliberate about
+ * which session it meant. This lets it judge the marker the call actually uses.
+ *
+ * Enumerates the same two places `hasAnyActiveSession()` does — the legacy `session.json` and the
+ * per-conversation directory — because a session id says nothing about which conversation owns it.
+ * Closed markers are not sessions, so they never match; a malformed one is skipped rather than
+ * throwing, since this sits in front of every session-attributed write.
+ */
+export function readSessionBySessionId(sessionId) {
+    const match = (p) => {
+        try {
+            const raw = JSON.parse(readFileSync(p, 'utf8'));
+            return !raw.closedAt && raw.sessionId === sessionId ? raw : null;
+        }
+        catch {
+            return null; // malformed/unreadable — skip, never throw in front of a write
+        }
+    };
+    const legacy = getSessionPath();
+    if (existsSync(legacy)) {
+        const found = match(legacy);
+        if (found)
+            return found;
+    }
+    const dir = getSessionsDir();
+    if (!existsSync(dir))
+        return null;
+    try {
+        for (const f of readdirSync(dir)) {
+            if (!f.endsWith('.json'))
+                continue;
+            const found = match(join(dir, f));
+            if (found)
+                return found;
+        }
+    }
+    catch {
+        // Directory vanished mid-scan — nothing to validate against.
+    }
+    return null;
 }
 /**
- * Reads the closed marker from session.json.
+ * 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 function readClosedMarker() {
-    const p = getSessionPath();
+export function readClosedMarker(conversationIdOverride) {
+    gcExpiredConversationMarkers();
+    const conversationId = resolveConversationId(conversationIdOverride);
+    const p = markerPath(conversationId);
     if (!existsSync(p))
         return null;
     try {
@@ -118,17 +331,18 @@ export function readClosedMarker() {
             closedAt: raw.closedAt,
             workspaceId: raw.workspaceId,
             workspaceName: raw.workspaceName,
+            conversationId: raw.conversationId,
         };
     }
     catch {
         return null;
     }
 }
-export function addCapturedEntry(entryId) {
-    const session = readSession();
+export function addCapturedEntry(entryId, conversationIdOverride) {
+    const session = readSession(conversationIdOverride);
     if (!session)
         return;
     session.entriesCaptured.push(entryId);
-    writeSession(session);
+    writeSession(session, conversationIdOverride);
 }
 //# sourceMappingURL=session.js.map

package/dist/lib/session.js.map

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

package/dist/lib/sessionBinding.d.ts

@@ -0,0 +1,62 @@
+import type { SessionState } from './session.js';
+/**
+ * One-way digest of the credential + gateway currently bound, or undefined when nothing is.
+ *
+ * By the time this runs, `getConfigOrGuide()` has already called `loadEnv()`, so `process.env`
+ * holds the credential that actually WON — whatever supplied it (export, pin, profile, preview).
+ * That is exactly the property wanted here: the fingerprint moves whenever the effective binding
+ * moves, without this module having to know which source produced it.
+ *
+ * Head-truncated to 16 hex chars: this value is only ever COMPARED, so keeping more would store
+ * more of a secret than the job needs. Never the key itself, never sent anywhere.
+ */
+export declare function fingerprintBinding(): string | undefined;
+/**
+ * The digest itself, taken as arguments rather than read from the environment.
+ *
+ * Split out so the hashing rules can be tested WITHOUT mutating `process.env`: vitest runs test
+ * files in parallel inside shared workers, so a test that deletes `PRODUCTBRAIN_API_KEY` to set up
+ * a case yanks it out from under whatever unrelated file is running beside it (observed live —
+ * it broke an unrelated suite while passing on its own).
+ */
+export declare function fingerprintOf(key: string, gateway: string | undefined): string;
+/**
+ * Has the workspace this session was started against changed underneath it?
+ *
+ * TWO signals, because neither alone is sufficient:
+ *
+ *  - **Profile name** (TEN-2163, the original backstop) — catches `pb profile use`, a preview
+ *    flip, a pin edit. Blind to a raw exported `PRODUCTBRAIN_API_KEY`, which carries no profile
+ *    name at all: repoint that key at another workspace and the name never moves, so the session
+ *    stayed "already active" while every write went to a foreign Chain (TEN-3240).
+ *  - **Binding fingerprint** (TEN-3240) — catches exactly that, because it tracks the credential
+ *    rather than a name for it.
+ *
+ * Either firing is enough. Both comparisons are skipped when one side is absent, which is what
+ * keeps a session marker written BEFORE `bindingFingerprint` existed on the original name-only
+ * behaviour instead of being discarded on every start.
+ */
+export declare function bindingChanged(existing: Pick<SessionState, 'profile' | 'bindingFingerprint'>, current: {
+    profile: string | null;
+    fingerprint: string | undefined;
+}): boolean;
+/**
+ * Refuse a session-attributed write whose credential has MOVED since the session opened.
+ *
+ * `pb session start`'s switch-backstop is not the only door (Codex P1 r9): an operator can
+ * repoint an exported PRODUCTBRAIN_API_KEY and then run `pb capture` / `relate` / `update`
+ * directly, never re-running start. The marker still names the old workspace while the gateway
+ * derives the new one from the key (BR-18) — a cross-workspace write with a stale session id.
+ *
+ * Compares the fingerprint only: `getConfig()` above has already resolved the credential into
+ * `process.env`, so this is arithmetic on values already in hand — no file, no network, on the
+ * hot path of every write. Markers written before the field existed carry no fingerprint and are
+ * skipped, exactly as the session-start backstop skips them.
+ */
+export declare function assertSessionStillBound(session: {
+    sessionId: string;
+    bindingFingerprint?: string;
+    workspaceName?: string;
+    profile?: string;
+} | null, current?: string | undefined, describeCurrent?: () => string | undefined): void;
+//# sourceMappingURL=sessionBinding.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"sessionBinding.d.ts","sourceRoot":"","sources":["../../src/lib/sessionBinding.ts"],"names":[],"mappings":"AAmBA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAEjD;;;;;;;;;;GAUG;AACH,wBAAgB,kBAAkB,IAAI,MAAM,GAAG,SAAS,CAGvD;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAS9E;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,cAAc,CAC5B,QAAQ,EAAE,IAAI,CAAC,YAAY,EAAE,SAAS,GAAG,oBAAoB,CAAC,EAC9D,OAAO,EAAE;IAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,WAAW,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,GACnE,OAAO,CAqBT;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,EAAE;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,EAG5G,OAAO,GAAE,MAAM,GAAG,SAAgC,EAKlD,eAAe,CAAC,EAAE,MAAM,MAAM,GAAG,SAAS,GACzC,IAAI,CAgBN"}

package/dist/lib/sessionBinding.js

@@ -0,0 +1,126 @@
+/**
+ * Session binding identity — "is this session still pointed at the same Chain?"
+ *
+ * Lives outside commands/session.ts, which is grandfathered shrink-only (STD-2 / DEC-1504),
+ * and outside config.ts for the same reason. Pure and offline by construction: `process.env` and
+ * the stored marker, never a file and never the network — so the deliberately offline
+ * already-active session path (WP-696) can call it.
+ *
+ * It fingerprints the CREDENTIAL, always. An earlier version keyed a preview binding on its
+ * workspace NAME so a reseed would not read as a switch — that was unsound twice over (Codex r6
+ * P1, r8 P1): an exported key outranks the preview binding, and `seed-preview.mjs` hardcodes the
+ * name `Preview Workspace` while deliberately orphaning a stale workspace in the SAME deployment,
+ * so two genuinely different workspaces shared one fingerprint. The reseed nuisance it was buying
+ * — one extra session restart — is not worth trading a safety property for. Fail safe.
+ */
+import { createHash } from 'crypto';
+import { CLIError, ErrorCode } from './errors.js';
+import { DEFAULT_SITE_URL } from './constants.js';
+import { copy } from './style.js';
+/**
+ * One-way digest of the credential + gateway currently bound, or undefined when nothing is.
+ *
+ * By the time this runs, `getConfigOrGuide()` has already called `loadEnv()`, so `process.env`
+ * holds the credential that actually WON — whatever supplied it (export, pin, profile, preview).
+ * That is exactly the property wanted here: the fingerprint moves whenever the effective binding
+ * moves, without this module having to know which source produced it.
+ *
+ * Head-truncated to 16 hex chars: this value is only ever COMPARED, so keeping more would store
+ * more of a secret than the job needs. Never the key itself, never sent anywhere.
+ */
+export function fingerprintBinding() {
+    const key = process.env.PRODUCTBRAIN_API_KEY;
+    return key ? fingerprintOf(key, process.env.CONVEX_SITE_URL) : undefined;
+}
+/**
+ * The digest itself, taken as arguments rather than read from the environment.
+ *
+ * Split out so the hashing rules can be tested WITHOUT mutating `process.env`: vitest runs test
+ * files in parallel inside shared workers, so a test that deletes `PRODUCTBRAIN_API_KEY` to set up
+ * a case yanks it out from under whatever unrelated file is running beside it (observed live —
+ * it broke an unrelated suite while passing on its own).
+ */
+export function fingerprintOf(key, gateway) {
+    // Strip the trailing slash exactly as getConfigOrGuide()/loadEnv() do before using the URL.
+    // Without this, `https://x/` and `https://x` — the SAME effective endpoint — hash differently,
+    // and a session started under one form is spuriously discarded under the other (Codex P2 r2).
+    // Resolve the SAME way getConfigOrGuide() does — absent means DEFAULT_SITE_URL, not "no
+    // gateway". Hashing '' for the absent case made an explicit export of that exact default look
+    // like a different endpoint, discarding a valid session for no reason (Codex P2 r3).
+    const normalized = (gateway ?? DEFAULT_SITE_URL).replace(/\/$/, '');
+    return createHash('sha256').update(`${key} ${normalized}`).digest('hex').slice(0, 16);
+}
+/**
+ * Has the workspace this session was started against changed underneath it?
+ *
+ * TWO signals, because neither alone is sufficient:
+ *
+ *  - **Profile name** (TEN-2163, the original backstop) — catches `pb profile use`, a preview
+ *    flip, a pin edit. Blind to a raw exported `PRODUCTBRAIN_API_KEY`, which carries no profile
+ *    name at all: repoint that key at another workspace and the name never moves, so the session
+ *    stayed "already active" while every write went to a foreign Chain (TEN-3240).
+ *  - **Binding fingerprint** (TEN-3240) — catches exactly that, because it tracks the credential
+ *    rather than a name for it.
+ *
+ * Either firing is enough. Both comparisons are skipped when one side is absent, which is what
+ * keeps a session marker written BEFORE `bindingFingerprint` existed on the original name-only
+ * behaviour instead of being discarded on every start.
+ */
+export function bindingChanged(existing, current) {
+    const profileSwitched = Boolean(existing.profile && current.profile && existing.profile !== current.profile);
+    const credentialSwitched = Boolean(existing.bindingFingerprint && current.fingerprint && existing.bindingFingerprint !== current.fingerprint);
+    // MIGRATION BACKSTOP. A marker written before `bindingFingerprint` existed cannot be compared on
+    // the credential at all, so there is no evidence its workspace is unchanged — and a
+    // cross-workspace session survived the upgrade (Codex P1 r7, r8).
+    //
+    // A matching profile NAME is not that evidence, tempting as it looks: `pb connect` can overwrite
+    // an existing profile's credentials in place (connect.ts), so one name can point at two
+    // workspaces over time (Codex P1 r13). Treating it as proof was an escape hatch that could be
+    // wrong; without it the rule is both simpler and stricter.
+    //
+    // So it fails CLOSED, always: an unnecessary re-start costs one kernel call, once, while a
+    // missed switch costs a wrong-Chain write. It cannot fire on a marker this version wrote —
+    // those always carry a fingerprint — so it retires itself as old markers roll over.
+    const unprovable = !existing.bindingFingerprint && Boolean(current.fingerprint);
+    return profileSwitched || credentialSwitched || unprovable;
+}
+/**
+ * Refuse a session-attributed write whose credential has MOVED since the session opened.
+ *
+ * `pb session start`'s switch-backstop is not the only door (Codex P1 r9): an operator can
+ * repoint an exported PRODUCTBRAIN_API_KEY and then run `pb capture` / `relate` / `update`
+ * directly, never re-running start. The marker still names the old workspace while the gateway
+ * derives the new one from the key (BR-18) — a cross-workspace write with a stale session id.
+ *
+ * Compares the fingerprint only: `getConfig()` above has already resolved the credential into
+ * `process.env`, so this is arithmetic on values already in hand — no file, no network, on the
+ * hot path of every write. Markers written before the field existed carry no fingerprint and are
+ * skipped, exactly as the session-start backstop skips them.
+ */
+export function assertSessionStillBound(session, 
+// Injectable for the same reason `fingerprintOf` takes arguments: a test must not mutate the
+// shared process env to set this up (see that function's note).
+current = fingerprintBinding(), 
+// WP-711/712: names the tenant CURRENTLY in play, for the refusal message only. A thunk, not
+// a plain value — resolving it (e.g. via config.ts's resolveEffectiveProfile) can mean a local
+// file read, and this function stays pure/offline on every PASSING call by invoking it only
+// once it has already decided to refuse. Never called when nothing is bound or the two agree.
+describeCurrent) {
+    // Nothing bound, or a match: nothing to object to.
+    if (!session || !current || current === session.bindingFingerprint)
+        return;
+    // Falling through means either the fingerprints DISAGREE, or the marker carries none at all.
+    // A marker without one predates the field, so nothing can prove it still targets the workspace
+    // this credential belongs to — the same reasoning `bindingChanged` uses, and now the same answer
+    // (Codex P1 r15). Letting that through was the bigger hole of the two: `pb relate` sends no
+    // session id, so nothing downstream re-checks. `pb session start` restarts it once and stamps a
+    // fingerprint, after which this never fires again.
+    const expected = session.workspaceName || session.profile || undefined;
+    const found = describeCurrent?.() || undefined;
+    throw new CLIError(copy.sessionRebound(session.sessionId, expected, found), {
+        code: ErrorCode.SESSION_REQUIRED,
+        category: 'session',
+        guidance: copy.sessionReboundGuidance(found),
+    });
+}
+//# sourceMappingURL=sessionBinding.js.map

package/dist/lib/sessionBinding.js.map

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

package/dist/lib/sessionNotices.d.ts

@@ -0,0 +1,52 @@
+export interface SessionNoticeAction {
+    verb: string;
+    args: Record<string, string | number | boolean | null>;
+    /** Optional, additive — the original §3.9a verb label, when the route alone is ambiguous
+     *  (convex/lib/notices/types.ts's NoticeAction.label doc comment). */
+    label?: string;
+}
+/** WP-638 S4 (§7.5 of the routed-questions design spec) — one bounded onboarding brief inside a
+ *  question notice's `payload.questions` array. Mirrors convex/lib/notices/types.ts's
+ *  `NoticeQuestionBrief` (the CLI-side twin every notice-payload type carries, HARD CONSTRAINT 2). */
+export interface SessionNoticeQuestionBrief {
+    name: string;
+    question: string;
+    asker: string;
+    sourcePointer: string;
+    domain: string;
+    whyYou: string;
+    ageDays: number;
+    dependents: {
+        count: number;
+        truncated?: boolean;
+        named: {
+            name: string;
+            id: string;
+        }[];
+    };
+    actions: SessionNoticeAction[];
+}
+export interface SessionNotice {
+    source: string;
+    type: string;
+    severity: 'none' | 'advisory' | 'warning' | 'emergency';
+    subject: string;
+    change: string;
+    occurredAt: number;
+    action: SessionNoticeAction;
+    /** WP-638 S4 (§7.5, R23) — the Notice-contract extension, additive/optional. */
+    payload?: {
+        questions: SessionNoticeQuestionBrief[];
+        truncated?: boolean;
+    };
+    requiresDisposition?: boolean;
+    actions?: SessionNoticeAction[];
+}
+export declare function noticeCommand(action: SessionNoticeAction): string;
+export declare const QUESTION_ACK_GATE_SOURCE_ID = "question-ack-gate";
+/** One line per notice, oldest first (server already sorts producers' output this way) — except
+ *  the question-ack-gate notice, which renders §7.5's full multi-line block instead of the
+ *  generic one-liner (R23: the Notice-contract extension is additive, so every OTHER producer's
+ *  one-liner is untouched). */
+export declare function formatSessionNoticeLines(notices: readonly SessionNotice[] | undefined): string[];
+//# sourceMappingURL=sessionNotices.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"sessionNotices.d.ts","sourceRoot":"","sources":["../../src/lib/sessionNotices.ts"],"names":[],"mappings":"AAWA,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,CAAC,CAAC;IACvD;0EACsE;IACtE,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;sGAEsG;AACtG,MAAM,WAAW,0BAA0B;IACzC,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,aAAa,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,OAAO,CAAC;QAAC,KAAK,EAAE;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,EAAE,EAAE,MAAM,CAAA;SAAE,EAAE,CAAA;KAAE,CAAC;IAC1F,OAAO,EAAE,mBAAmB,EAAE,CAAC;CAChC;AAED,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS,GAAG,WAAW,CAAC;IACxD,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,mBAAmB,CAAC;IAC5B,gFAAgF;IAChF,OAAO,CAAC,EAAE;QAAE,SAAS,EAAE,0BAA0B,EAAE,CAAC;QAAC,SAAS,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC;IAC3E,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAC9B,OAAO,CAAC,EAAE,mBAAmB,EAAE,CAAC;CACjC;AA4BD,wBAAgB,aAAa,CAAC,MAAM,EAAE,mBAAmB,GAAG,MAAM,CAMjE;AAED,eAAO,MAAM,2BAA2B,sBAAsB,CAAC;AAwE/D;;;+BAG+B;AAC/B,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,SAAS,aAAa,EAAE,GAAG,SAAS,GAAG,MAAM,EAAE,CAWhG"}