@productbrain/cli 0.1.0-beta.104 → 0.1.0-beta.10403

package/dist/commands/session.js

@@ -1,98 +1,244 @@
 /**
- * pb session start / close — CLI write session lifecycle.
- * Opens a tracked agent session (DEC-9, BR-8) with clientKind: 'cli' (DEC-184).
- * Session ID persisted to .productbrain/session.json (TEN-264 option 1).
- * BET-181 Slice 0: uses isJsonMode() for output branching. Existing --json flag
- * on session start preserved for backward compatibility.
+ * pb session start / close — CLI write session lifecycle. Opens a tracked agent session (DEC-9,
+ * BR-8) with clientKind: 'cli' (DEC-184). Session ID persisted to .productbrain/session.json
+ * (TEN-264 option 1). BET-181 Slice 0: uses isJsonMode() for output branching; existing --json
+ * flag on session start preserved for backward compatibility.
  */
+import { execSync } from 'child_process';
+import { basename } from 'path'; // WP-660 S2: module-health shrink-only budget, same-line import-combine pattern
 import { getConfigOrGuide } from '../lib/config.js';
 import { kernelCall } from '../lib/client.js';
-import { readSession, writeSession, clearSession, readClosedMarker } from '../lib/session.js';
-import { isJsonMode } from '../lib/runner.js';
-import { formatSessionStart, formatSessionClose } from '../formatters/session.js';
-import { runHandshake } from './handshake.js';
+import { readSession, writeSession, clearSession, discardSession, discardAllSessions, hasAnySessionMarker, hasAnyActiveSession, readClosedMarker, RESUME_WINDOW_MS, } from '../lib/session.js'; // WP-660 S2 same-line import-combine, to stay within the shrink-only budget
+import { resolveConversationId } from '../lib/conversation.js';
+import { isJsonMode, runCliCommand } from '../lib/runner.js';
+import { confirm, isInteractive } from '../lib/prompts.js';
+import { formatSessionStart, formatSessionClose, formatLoopUnfinished, formatSessionList, formatSessionShow, buildPromoteCommand, FEEDBACK_SUBMIT_HINT, } from '../formatters/session.js';
 import { CLIError, ErrorCode } from '../lib/errors.js';
-import { getActiveProfile } from '../lib/profiles.js';
-import { readLocalProjectConfig } from '../lib/config.js';
-/** 2-hour window for auto-resume (WP-322 E1). */
-const RESUME_WINDOW_MS = 2 * 60 * 60 * 1000;
+import { readLocalProjectConfig, refreshPreviewApiKeyFromDisk } from '../lib/config.js';
+import { isRoleRefusal, startWithPinnedRole } from '../lib/pinnedRole.js'; // TASK-639 same-line
+import { resolveAppUrl } from '../lib/constants.js';
+import { emitEffectiveTenantNotice } from '../lib/workspaceNotice.js';
+import { fingerprintBinding, bindingChanged } from '../lib/sessionBinding.js';
+import { resolveReportedProfile } from '../lib/reportedProfile.js';
+import { composeWrapupView } from '../lib/compose-wrapup-view.js'; // WP-660 S2 same-line combine, shrink-only budget
+/**
+ * Auto-populate the session `label` (WP-479 E2, founder-day fix Pass 2) — the founder's recall
+ * cue for "which of my N conversations" is the worktree/branch, never a UUID. Priority:
+ * SUPERSET_WORKSPACE_NAME env → git branch (silent fail) → cwd basename. Server-side clamps to
+ * ~120 chars (mirrors MAX_TASK_LEN) — no client-side truncation needed here.
+ */
+export function resolveSessionLabel() {
+    const superset = process.env.SUPERSET_WORKSPACE_NAME;
+    if (superset && superset.trim())
+        return superset.trim();
+    try {
+        const branch = execSync('git rev-parse --abbrev-ref HEAD', { stdio: ['ignore', 'pipe', 'ignore'] }).toString().trim();
+        if (branch)
+            return branch;
+    }
+    catch {
+        // Silent fail — not a git repo, git not installed, detached HEAD edge cases, etc.
+    }
+    return basename(process.cwd());
+}
+/**
+ * True for the auth/INTERNAL failure a stale preview apiKey produces (WP-458 E2). The server
+ * returns an opaque INTERNAL for a rejected key, and a true 401 maps to category 'auth' — either
+ * is a candidate for the one-shot preview-key refresh. Scoped to CLIError so plain Errors fall
+ * through to a normal rethrow. A role refusal (pinnedRole.ts's one code set) is never a key problem.
+ */
+function isStalePreviewKeyError(err) {
+    return !isRoleRefusal(err) && err instanceof CLIError && (err.category === 'auth' || err.code === ErrorCode.INTERNAL);
+}
+/**
+ * The OPAQUE INTERNAL a server-rejected key produces — the one failure doneWhen #1 exists to
+ * replace with a clean message. Narrower than isStalePreviewKeyError on purpose: it is the predicate
+ * for relabelling a POST-refresh retry failure, which is NOT disk-gated. A retry that fails with a
+ * specific, already-actionable auth error (e.g. the read-only-key guard's AUTH_INVALID) must keep
+ * its own guidance instead of being rewritten "reseed/rebind" (Codex P2). Only the opaque INTERNAL,
+ * which carries no useful guidance of its own, is worth converting.
+ */
+function isOpaqueKeyRejection(err) {
+    return err instanceof CLIError && err.code === ErrorCode.INTERNAL;
+}
+/**
+ * Clean, actionable replacement for the opaque INTERNAL a rejected preview key produces (WP-458
+ * doneWhen #1: no opaque INTERNAL). Thrown only when the worktree is preview-bound and the key
+ * could not be recovered from the bound key file.
+ */
+function stalePreviewKeyError() {
+    return new CLIError('Preview API key was rejected and no fresh key could be loaded from the key file pb:preview bound.', {
+        code: ErrorCode.AUTH_INVALID,
+        category: 'auth',
+        guidance: 'Reseed the preview (npm run convex:reprovision), re-bind (npm run pb:preview, with the same --as), then retry.',
+    });
+}
 export async function runSessionStart(options = {}) {
     const config = await getConfigOrGuide(() => runSessionStart(options));
     if (!config)
         return;
+    // DEC-1961 (TASK-639): `--role`, else the folder pin's role; a refusal is thrown and printed once, on stderr (TASK-649).
+    await startWithPinnedRole(options, isJsonMode() || options.json === true, async (opts) => {
+        try {
+            await establishSession(opts);
+        }
+        catch (err) {
+            await recoverStalePreviewKey(err, opts);
+        }
+    });
+}
+/** E2 (WP-458) stale-preview-key recovery, scoped to session-establishing kernel calls only. A
+ * reseeded preview mints a fresh apiKey (seed Step 6); the locally-bound key is now stale and
+ * resolveWorkspace/agent.startSession fail (opaque INTERNAL/401). Runs ONLY when preview-bound —
+ * on the real Chain the error is rethrown untouched so a genuine failure is never masked (R2). */
+async function recoverStalePreviewKey(err, options) {
+    const previewBound = readLocalProjectConfig()?.preview === true;
+    if (!previewBound || !isStalePreviewKeyError(err))
+        throw err;
+    const outcome = refreshPreviewApiKeyFromDisk();
+    if (outcome === 'refreshed') {
+        try {
+            return await establishSession(options); // one-shot retry with the freshly-read key
+        }
+        catch (retryErr) {
+            // The retry ran with a genuinely fresh key. Only convert it to the clean stale-key error if
+            // it is itself an OPAQUE INTERNAL (the failure doneWhen #1 targets). Any other failure —
+            // backend unreachable (plain Error), or an already-actionable auth error like the read-only
+            // -key guard's AUTH_INVALID — must surface its own error + remedy, never be rewritten
+            // "reseed/rebind" (Codex P2: an auth-shaped retry failure is not necessarily a stale key).
+            if (isOpaqueKeyRejection(retryErr))
+                throw stalePreviewKeyError();
+            throw retryErr;
+        }
+    }
+    if (outcome === 'unavailable') {
+        // Preview-bound but no fresh key to recover with — name the situation cleanly (doneWhen #1).
+        throw stalePreviewKeyError();
+    }
+    // 'unchanged' / 'not-bound': the bound key is current, or a genuine env override is in play, so
+    // this auth/INTERNAL failure is NOT a stale-key problem. Surface the original error rather than
+    // relabel it as a key rejection (no-masking; R2 honesty; Codex P2 env-override + unrelated-INTERNAL).
+    throw err;
+}
+async function establishSession(options) {
     // Support both legacy --json flag and global output mode (DEC-299, backward compat)
     const json = isJsonMode() || options.json === true;
+    // Effective profile for this start — shared by the switch backstop, persisted state, and every
+    // profile label this invocation renders (one read, one value, so they cannot drift mid-start).
+    // One name, one place (Codex P2 r6): a wrong name here PERSISTS into the marker and drives the
+    // switch backstop. Still offline per WP-696 — getConfigOrGuide() opened these files already.
+    const effectiveProfile = resolveReportedProfile().profile;
+    let bindingFingerprint = fingerprintBinding(); // bindings a NAME can't describe — TEN-3240
+    // WP-479 E2: resolve the conversation identity ONCE here (explicit --conversation flag wins
+    // over every env-detected channel — see lib/conversation.ts). Every session.ts read/write call
+    // below reuses this exact value (re-normalizing an already-normalized value is a no-op) so a
+    // single `pb session start` invocation can never target two different markers.
+    const conversationId = resolveConversationId(options.conversation);
+    // Review fix (Codex): `--conversation` is a manual override only `pb session start` sees — later
+    // bare `pb` commands (orient, capture, close) resolve identity from env only. If the flag resolves
+    // to a DIFFERENT conversation than a bare env-only resolution would, those follow-ups fall back to
+    // the wrong marker (or the legacy one) and can't find this session. Warn so the "advertised manual
+    // seam" gap is surfaced, not silent (the flag's documented contract is to pair it with
+    // PB_CONVERSATION_ID — index.ts). Compare RESOLVED identities so a normalized value doesn't
+    // false-trigger.
+    if (options.conversation && !json && resolveConversationId() !== conversationId) {
+        process.stderr.write(`⚠ --conversation is only read by \`pb session start\`. Set PB_CONVERSATION_ID=${conversationId} in this shell so later bare \`pb\` commands attribute to the same conversation.\n`);
+    }
     // Check for existing session
-    const existing = readSession();
+    let existing = readSession(conversationId ?? undefined);
     if (existing) {
-        if (json) {
-            process.stdout.write(JSON.stringify({
-                sessionId: existing.sessionId,
-                workspaceName: existing.workspaceName,
-                startedAt: existing.startedAt,
-                alreadyActive: true,
-                activeProfile: readLocalProjectConfig()?.profile ?? getActiveProfile(),
-            }) + '\n');
-            return;
+        // Backstop (TEN-2163 name + TEN-3240 credential): a session started against a DIFFERENT
+        // workspace is pinned to the old one — discard and start fresh. Both signals, and why neither
+        // alone suffices, live in sessionBinding.ts. Local, offline-safe.
+        const switched = bindingChanged(existing, { profile: effectiveProfile, fingerprint: bindingFingerprint });
+        // Stale-key refresh — 'refreshed' DISCARDS rather than re-stamps (Codex P1 r10): a reseed can
+        // mint a REPLACEMENT workspace, so blessing the marker handed the guard a session belonging to
+        // the orphan. It rebinds env too — re-take the fingerprint or the fresh marker carries the
+        // STALE key's (P2 r11).
+        const reseeded = !switched && refreshPreviewApiKeyFromDisk() === 'refreshed';
+        if (reseeded)
+            bindingFingerprint = fingerprintBinding();
+        if (switched || reseeded) {
+            discardSession(conversationId ?? undefined);
+            existing = null; // fall through to the fresh-start path below
+        }
+        else {
+            // WP-777, DEC-1888, INS-2674: an agent re-running session start after a compaction lands
+            // here and must get the same briefing as a fresh start. The server's start reuses this
+            // conversation's live row (reuseLiveConversationSession) and serves the full tail, so this
+            // path goes through the kernel below instead of answering from the local marker.
         }
-        process.stdout.write(`Session already active: ${existing.sessionId}\n`);
-        process.stdout.write(`Started: ${existing.startedAt}\n`);
-        process.stdout.write(`Entries captured: ${existing.entriesCaptured.length}\n`);
-        process.stdout.write('\n');
-        process.stdout.write('Run `pb session close` to end it, or `pb session close --force` to force-close.\n');
-        return;
     }
-    // WP-322 E1: Check for a recent closed session — auto-resume within 2h window
-    const closedMarker = readClosedMarker();
+    // TEN-3238 leftover: session start ESTABLISHES the binding later writes inherit, yet never named
+    // its target. An already-active session established it when it opened.
+    if (!existing)
+        await emitEffectiveTenantNotice();
+    // WP-322 E1: Check for a recent closed session — auto-resume within 2h window. A live marker and a
+    // closed marker share one file, so this is null whenever `existing` is set.
+    const closedMarker = readClosedMarker(conversationId ?? undefined);
     if (closedMarker) {
         const elapsed = Date.now() - new Date(closedMarker.closedAt).getTime();
         if (elapsed < RESUME_WINDOW_MS) {
             // Resolve workspace to get keyId (needed for resumeSession)
             const wsForResume = await kernelCall('resolveWorkspace', {});
-            if (wsForResume?.keyId) {
-                if (!json)
-                    process.stdout.write('Resuming session...\n');
+            // Backstop (TEN-2189): the closed marker is pinned to a workspace. If the current binding
+            // now resolves to a DIFFERENT workspace (a pb:preview/pb:real flip or profile switch since
+            // close), resuming would call agent.resumeSession with a foreign session id and the
+            // deployment rejects the cross-workspace resume. Discard the stale marker and fall through
+            // to a fresh start instead. This mirrors the active-session profile backstop above, keyed
+            // on workspaceId — the resume path previously had no such guard, which is the gap E2 closes.
+            if (wsForResume?._id && closedMarker.workspaceId !== wsForResume._id) {
+                discardSession(conversationId ?? undefined);
+                // fall through to the fresh-start path below
+            }
+            else if (wsForResume?.keyId) {
                 const resumed = await kernelCall('agent.resumeSession', {
                     workspaceId: wsForResume._id,
                     apiKeyId: wsForResume.keyId,
                     previousSessionId: closedMarker.sessionId,
                     clientKind: 'cli',
+                    conversationId: conversationId ?? undefined, role: options.role, team: options.team, // TASK-439, TASK-801: was silently dropped before — a resume never even read --role
                 });
                 const shortPrevId = closedMarker.sessionId.slice(-8);
+                const fresh = 'startedFresh' in resumed && resumed.startedFresh === true; // TEN-4893: the closed one acted as another seat, so the kernel started fresh
                 const state = {
                     sessionId: resumed.sessionId,
                     workspaceId: wsForResume._id,
                     workspaceName: resumed.workspaceName,
                     startedAt: new Date().toISOString(),
                     entriesCaptured: [],
+                    profile: effectiveProfile ?? undefined,
+                    bindingFingerprint,
                 };
-                writeSession(state);
+                writeSession(state, conversationId ?? undefined);
                 if (json) {
                     process.stdout.write(JSON.stringify({
                         sessionId: state.sessionId,
                         workspaceName: state.workspaceName,
                         startedAt: state.startedAt,
-                        resumed: true,
-                        linkedPreviousSessionId: closedMarker.sessionId,
-                        activeProfile: readLocalProjectConfig()?.profile ?? getActiveProfile(),
+                        resumed: !fresh,
+                        ...(fresh ? {} : { linkedPreviousSessionId: closedMarker.sessionId }),
+                        activeProfile: effectiveProfile,
+                        feedbackQueueNew: resumed.feedbackQueueNew,
+                        feedbackOldestNewAt: resumed.feedbackOldestNewAt,
+                        feedbackHint: FEEDBACK_SUBMIT_HINT,
+                        notices: resumed.notices ?? [], ruleLists: resumed.ruleLists, roleEntryId: resumed.roleEntryId, roleName: resumed.roleName, briefing: resumed.briefing, // TASK-436/439/552
                     }) + '\n');
-                    await runHandshake({ force: false, apply: true, quiet: true });
                     return;
                 }
                 const elapsedMins = Math.round(elapsed / 60_000);
-                const elapsedLabel = elapsedMins < 60
-                    ? `${elapsedMins}m ago`
-                    : `${Math.round(elapsedMins / 60)}h ago`;
-                process.stdout.write(`Resuming session (linked from ${shortPrevId}, closed ${elapsedLabel})\n`);
-                process.stdout.write(formatSessionStart(state, undefined, readLocalProjectConfig()?.profile ?? getActiveProfile()) + '\n');
-                process.stdout.write('Refreshing context...\n');
-                await runHandshake({ force: false, apply: true });
+                const elapsedLabel = elapsedMins < 60 ? `${elapsedMins}m ago` : `${Math.round(elapsedMins / 60)}h ago`;
+                process.stdout.write(fresh
+                    ? `Starting session (a new one: the closed session ${shortPrevId} acted as another role)\n`
+                    : `Resuming session (linked from ${shortPrevId}, closed ${elapsedLabel})\n`);
+                // TASK-620 (DEC-1945): the acting role, its team and body print inside the briefing.
+                process.stdout.write(formatSessionStart(state, effectiveProfile, resumed) + '\n');
                 return;
             }
         }
         else {
             // Marker is stale (>2h) — clear it so next session starts fresh
-            clearSession();
+            clearSession(conversationId ?? undefined);
         }
     }
     // Resolve workspace + keyId
@@ -104,38 +250,55 @@ export async function runSessionStart(options = {}) {
             guidance: 'Generate a readwrite key: Product Brain app → Settings → API Keys.',
         });
     }
-    // Start agent session with clientKind attribution (DEC-184)
-    if (!json)
+    // Start agent session with clientKind attribution (DEC-184). WP-479 E2: thread the resolved
+    // conversationId and an auto-populated label — parentSessionId is dormant, never set here.
+    const label = resolveSessionLabel();
+    if (!json && !existing)
         process.stdout.write('Starting session...\n');
     const result = await kernelCall('agent.startSession', {
         workspaceId: workspace._id,
         apiKeyId: workspace.keyId,
         clientKind: 'cli',
+        conversationId: conversationId ?? undefined,
+        label, role: options.role, team: options.team,
     });
-    // Persist session state
-    const state = {
-        sessionId: result.sessionId,
-        workspaceId: workspace._id,
-        workspaceName: result.workspaceName,
-        startedAt: new Date().toISOString(),
-        entriesCaptured: [],
-    };
-    writeSession(state);
+    // WP-777 (INS-2674): the server reused the live row, so the local marker (and its captures) stands.
+    // A different id means the server had already ended that session; the new row replaces the marker.
+    const kept = existing && existing.sessionId === result.sessionId ? existing : null;
+    const endedSessionId = existing && !kept ? existing.sessionId : undefined;
+    let state;
+    if (kept) {
+        state = { ...kept, workspaceName: result.workspaceName }; // local captures and start; the server's (maybe renamed) name
+    }
+    else {
+        state = {
+            sessionId: result.sessionId,
+            workspaceId: workspace._id,
+            workspaceName: result.workspaceName,
+            startedAt: new Date().toISOString(),
+            entriesCaptured: [],
+            profile: effectiveProfile ?? undefined,
+            bindingFingerprint,
+        };
+    }
+    writeSession(state, conversationId ?? undefined);
     if (json) {
         process.stdout.write(JSON.stringify({
             sessionId: state.sessionId,
             workspaceName: state.workspaceName,
             startedAt: state.startedAt,
-            activeProfile: getActiveProfile(),
+            ...(kept ? { alreadyActive: true } : {}), ...(endedSessionId ? { endedSessionId } : {}),
+            activeProfile: effectiveProfile,
+            feedbackQueueNew: result.feedbackQueueNew,
+            feedbackOldestNewAt: result.feedbackOldestNewAt,
+            feedbackHint: FEEDBACK_SUBMIT_HINT,
+            notices: result.notices ?? [], roleEntryId: result.roleEntryId, roleName: result.roleName, ruleLists: result.ruleLists, briefing: result.briefing, // DEC-1715, TASK-436/552
         }) + '\n');
-        // Refresh silently in JSON mode
-        await runHandshake({ force: false, apply: true, quiet: true });
         return;
     }
-    process.stdout.write(formatSessionStart(state, result.superseded, readLocalProjectConfig()?.profile ?? getActiveProfile()) + '\n');
-    // Refresh context files
-    process.stdout.write('Refreshing context...\n');
-    await runHandshake({ force: false, apply: true });
+    if (endedSessionId)
+        process.stdout.write(`Session ${endedSessionId} had already ended on the server; this is a new one.\n`);
+    process.stdout.write(formatSessionStart(state, effectiveProfile, result, kept ? 'already-active' : 'started') + '\n');
 }
 /**
  * pb session id — print current session ID bare to stdout (machine-readable).
@@ -152,6 +315,72 @@ export function runSessionId() {
     }
     process.stdout.write(session.sessionId + '\n');
 }
+/**
+ * pb session reset — hard-reset the worktree-local pb SESSION state. TEN-2189 / WP-456 E2.
+ *
+ * Discards session.json outright (via discardSession — NO resume marker, unlike
+ * `pb session close`). Purely local: no network call, no key needed — this is the recovery
+ * path when a session is stranded pinned to the wrong workspace (e.g. left over after a
+ * pb:preview/pb:real binding flip), so it must work even when the current binding is broken.
+ *
+ * Scope: SESSION state only. The preview *binding* (config.local.json keys + the
+ * .productbrain/PREVIEW_MODE marker) is owned end-to-end by `npm run pb:preview` /
+ * `npm run pb:real` — reset never touches it, so the marker can never disagree with the keys
+ * that actually route writes (codex PR #145 review: clearing the marker without the keys left
+ * the worktree silently still preview-bound). To return a preview-bound worktree to the real
+ * Chain: `pb session reset` (clear the session) then `npm run pb:real` (clear the binding).
+ *
+ * Guard (R4): if there IS an active session, confirm before discarding so in-flight captures
+ * aren't silently stranded. `--force` skips the prompt. In a non-interactive context the prompt
+ * can't run, so `--force` is required there.
+ *
+ * WP-479 review fix (Codex re-review): reset clears ALL session markers — the legacy session.json
+ * AND every per-conversation marker under `.productbrain/sessions/`. This is the recovery the
+ * pb:real/pb:preview binding-flip guard prints, and that guard refuses on ANY active marker; a
+ * conversation-scoped reset couldn't clear a sibling marker it has no env to resolve, so the flip
+ * would stay blocked unless `--force` (which strands the server session). A hard reset legitimately
+ * clears the whole worktree's local session state.
+ */
+export async function runSessionReset(options = {}) {
+    const active = readSession();
+    // Reset clears ALL markers, so the confirmation guard must consider ANY active session — including a
+    // SIBLING conversation's — not just the current one (Codex re-review): otherwise reset would
+    // silently delete a sibling active marker (even non-interactively) and strand that server session.
+    const anyActive = active !== null || hasAnyActiveSession();
+    // Nothing local to reset — no active session and no marker of any conversation. (A lone
+    // PREVIEW_MODE marker is binding state, not session state — `npm run pb:real` clears it.)
+    if (!active && !hasAnySessionMarker()) {
+        process.stdout.write('Nothing to reset — no local session state.\n');
+        return;
+    }
+    // Any active session present (current OR sibling): confirm before discarding (R4) unless --force.
+    if (anyActive && !options.force) {
+        if (!isInteractive()) {
+            throw new CLIError('Active session present — refusing to reset without confirmation.', {
+                code: ErrorCode.NON_INTERACTIVE,
+                category: 'session',
+                guidance: 'Re-run with `pb session reset --force` to discard the active session(s).',
+            });
+        }
+        if (active) {
+            process.stdout.write(`Active session: ${active.sessionId} (${active.entriesCaptured.length} entries captured)\n`);
+        }
+        else {
+            process.stdout.write('An active session exists in another conversation in this worktree.\n');
+        }
+        const ok = await confirm({
+            message: 'Discard all local sessions and any in-flight captures?',
+            initialValue: false,
+        });
+        if (!ok) {
+            process.stdout.write('Reset cancelled — session left intact.\n');
+            return;
+        }
+    }
+    // Hard-reset: discard ALL session markers (no resume marker). Binding state is left untouched.
+    discardAllSessions();
+    process.stdout.write('Session state reset — all local session markers cleared.\n');
+}
 export async function runSessionClose(options = {}) {
     const config = await getConfigOrGuide(() => runSessionClose(options));
     if (!config)
@@ -161,14 +390,59 @@ export async function runSessionClose(options = {}) {
         process.stdout.write('No active session. Run `pb session start` to begin.\n');
         return;
     }
-    // Record wrapup metrics
-    const entriesCount = session.entriesCaptured.length;
-    if (entriesCount > 0) {
+    // TEN-2370: fetch the SERVER's post-promote truth (committed vs still-draft) so close
+    // reflects reality, not the local capture-time snapshot. Best-effort — a read failure
+    // degrades to the legacy snapshot rendering rather than blocking the close.
+    let wrapup = null;
+    try {
+        const raw = await kernelCall('agent.getSessionWrapup', { sessionId: session.sessionId });
+        // TEN-2370 + TEN-2402: composeWrapupView is the single place the capped ∪ overflow
+        // merge happens (committed AND drafts), pinned against the MCP twin by the parity test.
+        // The gate, the promote command, and the draft/committed listings all then operate on
+        // the COMPLETE sets — never just the first WRAPUP_ENTRY_CAP.
+        const composed = composeWrapupView(raw);
+        wrapup = {
+            committed: composed.committed,
+            drafts: composed.drafts, discarded: composed.discarded, // TASK-743 (TEN-4624): discarded is named, never counted as committed
+            // Entries past OVERFLOW_SCAN_CAP the server did not enumerate — the gate treats a
+            // nonzero count as "cannot certify" and fails CLOSED (blocks the close) so an
+            // enormous session can never slip through unread.
+            overflowUnscanned: composed.overflowUnscanned,
+            acceptIndependenceDigest: raw.acceptIndependenceDigest, // WP-660 S2 review fix (round 2, P1-A)
+        };
+        // D3a (WP-754/TASK-213): the pending domain-tag proposal advisory is deleted — its route
+        // (authorityDomains.readiness) is deleted in this same slice.
+    }
+    catch {
+        // Wrapup read failed — degrade to legacy local-snapshot rendering, no enforcement.
+    }
+    // ENFORCEMENT (TEN-2370 / ASM-40): drafts remain and the operator did not pass --force.
+    // Print the promote command, exit non-zero (LOOP_UNFINISHED), and DO NOT close — the
+    // session stays open so the agent can promote and re-close. --force is the documented
+    // escape so automation can never deadlock on this gate.
+    if (wrapup && (wrapup.drafts.length > 0 || (wrapup.overflowUnscanned ?? 0) > 0) && !options.force) {
+        // In --json mode emit ONLY the structured error (thrown below) — the human nudge would
+        // corrupt stdout for the automation callers this remediation path exists to serve. The
+        // LOOP_UNFINISHED error carries the same promote command in its guidance.
+        if (!isJsonMode()) {
+            process.stdout.write(formatLoopUnfinished(wrapup) + '\n');
+        }
+        const draftIds = wrapup.drafts.map((d) => d.entryId);
+        throw new CLIError(`Loop unfinished: ${wrapup.drafts.length} draft(s) not committed to the Chain.`, {
+            code: ErrorCode.LOOP_UNFINISHED,
+            category: 'session',
+            guidance: `Promote with \`${buildPromoteCommand(draftIds)}\`, then re-run \`pb session close\` — or \`pb session close --force\` to close anyway.`,
+        });
+    }
+    // Record wrapup metrics — use server truth (real committed count) when available.
+    const draftsReviewed = wrapup ? wrapup.committed.length + wrapup.drafts.length : session.entriesCaptured.length;
+    const draftsCommitted = wrapup ? wrapup.committed.length : 0;
+    if (draftsReviewed > 0) {
         try {
             await kernelCall('agent.recordWrapup', {
                 sessionId: session.sessionId,
-                draftsReviewed: entriesCount,
-                draftsCommitted: 0, // CLI captures are drafts; user commits in Cortex
+                draftsReviewed,
+                draftsCommitted,
                 linksCreated: 0,
             });
         }
@@ -178,26 +452,91 @@ export async function runSessionClose(options = {}) {
         }
     }
     // Close the session
+    let closed = null; // TASK-816: printed counts come from here
     try {
-        await kernelCall('agent.closeSession', {
-            sessionId: session.sessionId,
-            status: 'closed',
-        });
+        closed = await kernelCall('agent.closeSession', { sessionId: session.sessionId, status: 'closed' });
     }
     catch (err) {
         if (!options.force) {
-            throw new CLIError(`Failed to close session: ${err instanceof Error ? err.message : String(err)}`, {
+            const detail = err instanceof Error ? err.message : String(err);
+            throw new CLIError(`Failed to close session: ${detail}. Run \`pb session close --force\` to clear local state anyway.`, {
                 code: ErrorCode.NETWORK_UNREACHABLE,
                 category: 'network',
-                guidance: 'Use `pb session close --force` to clear local state anyway.',
+                guidance: 'Run `pb session close --force` to clear local state anyway.',
             });
         }
     }
-    process.stdout.write(formatSessionClose(session) + '\n');
+    // Suppress the ratify deep link when preview-bound without an explicit PB_APP_URL: the
+    // session id belongs to the preview deployment, so a default (prod) app link can't open it
+    // (Codex P2, PR #151). Set PB_APP_URL to print a preview-correct link during dogfood.
+    const appUrl = readLocalProjectConfig()?.preview === true && !process.env.PB_APP_URL ? null : resolveAppUrl();
+    // WP-582 B2 round 1 (T10): rituals surface, best-effort (formatSessionClose has the rest).
+    let rituals = null;
+    // PR #532 late review fix (P2): minute-bucketed `now` (conflictQueue.ts's convention) forces a
+    // fresh reactive result once a snooze expires on wall-clock time alone, no DB write to bust it.
+    try {
+        rituals = await kernelCall('chain.getRitualsSurface', { now: Math.floor(Date.now() / 60_000) * 60_000 });
+    }
+    catch { /* non-critical */ }
+    process.stdout.write(formatSessionClose(session, wrapup, closed?.workspaceSlug ?? undefined, appUrl, rituals, closed) + '\n');
     // Clear local state
     clearSession();
-    // Refresh context files so next session starts with updated knowledge
-    process.stdout.write('Refreshing context...\n');
-    await runHandshake({ force: false, apply: true });
+}
+// ─── WP-479 E4: pb session list / pb session show ────────────────────────────
+/**
+ * pb session list — active sessions (with the per-key quota gauge) + a handful of recent
+ * non-active ones. Pure read over `agent.listSessions`; no local session required — this is
+ * exactly the command you run when you're NOT sure which session is yours.
+ */
+export async function runSessionList() {
+    const config = await getConfigOrGuide(() => runSessionList());
+    if (!config)
+        return;
+    await runCliCommand({
+        fn: () => kernelCall('agent.listSessions', {}),
+        formatPretty: (data) => formatSessionList(data),
+    });
+}
+/**
+ * Convex document ids are ~32 chars of lowercase base32 — used only to decide which arg KIND to
+ * try first. It is a routing heuristic, not a validator: a conversationId can coincidentally match
+ * (it allows the same charset), so a shaped arg that fails as a sessionId is retried as a
+ * conversationId before giving up (the spec's contract: a copied `list` row id — either column —
+ * must be directly usable by `show`).
+ */
+const CONVEX_DOC_ID_RE = /^[a-z0-9]{25,40}$/;
+/**
+ * pb session show <id-or-conversation> — reconstruct the full conversation lineage (all
+ * agentSessions rows across 2h resumes + legacy linkedPreviousSessionId chains) plus the
+ * governance serves recorded for the conversation.
+ */
+export async function runSessionShow(idOrConversation) {
+    const config = await getConfigOrGuide(() => runSessionShow(idOrConversation));
+    if (!config)
+        return;
+    const arg = idOrConversation.trim();
+    if (!arg) {
+        throw new CLIError('Provide a session id or conversation id.', {
+            code: ErrorCode.VALIDATION_FAILED,
+            category: 'validation',
+            guidance: 'Copy one from `pb session list`.',
+        });
+    }
+    const fetchShow = async () => {
+        if (CONVEX_DOC_ID_RE.test(arg)) {
+            try {
+                return await kernelCall('agent.showConversation', { sessionId: arg });
+            }
+            catch {
+                // Not a session doc id after all (validation reject or not-found) — fall through and
+                // retry the same string as a conversationId before reporting failure.
+            }
+        }
+        return await kernelCall('agent.showConversation', { conversationId: arg });
+    };
+    await runCliCommand({
+        fn: fetchShow,
+        formatPretty: (data) => formatSessionShow(data),
+    });
 }
 //# sourceMappingURL=session.js.map