@productbrain/cli 0.1.0-beta.1065 → 0.1.0-beta.10656

package/dist/commands/session.js

@@ -1,63 +1,181 @@
 /**
- * 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, discardSession, sessionFileExists, readClosedMarker } from '../lib/session.js';
-import { isJsonMode } from '../lib/runner.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 } from '../formatters/session.js';
-import { runHandshake } from './handshake.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, resolveEffectiveProfile } 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 — used both for the switch-backstop decision and to
-    // stamp the session (one read, one value, so they can't disagree mid-start).
-    const effectiveProfile = resolveEffectiveProfile().profile;
+    // 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` and `close` see —
+    // later bare `pb` commands (orient, capture) 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 read only by session start and close. Set PB_CONVERSATION_ID=${conversationId} 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) {
-        // Backstop (TEN-2163): if the effective profile changed since this session started,
-        // it's pinned to the old workspace — discard it and start fresh. Local, offline-safe.
-        const currentProfile = effectiveProfile;
-        const switched = existing.profile && currentProfile && existing.profile !== currentProfile;
-        if (switched) {
-            discardSession();
-            // fall through to the fresh-start path below
-        }
-        else 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 {
-            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-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.
         }
     }
-    // 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) {
@@ -70,19 +188,19 @@ export async function runSessionStart(options = {}) {
             // 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();
+                discardSession(conversationId ?? undefined);
                 // fall through to the fresh-start path below
             }
             else if (wsForResume?.keyId) {
-                if (!json)
-                    process.stdout.write('Resuming session...\n');
                 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,
@@ -90,34 +208,37 @@ export async function runSessionStart(options = {}) {
                     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
@@ -129,39 +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: [],
-        profile: effectiveProfile ?? undefined,
-    };
-    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).
@@ -196,27 +333,43 @@ export function runSessionId() {
  * 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();
-    // Nothing local to reset — neither an active session nor a closed marker. (A lone
+    // 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 && !sessionFileExists()) {
+    if (!active && !hasAnySessionMarker()) {
         process.stdout.write('Nothing to reset — no local session state.\n');
         return;
     }
-    // Active session present: confirm before discarding (R4) unless --force.
-    if (active && !options.force) {
+    // 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.',
+                guidance: 'Re-run with `pb session reset --force` to discard the active session(s).',
             });
         }
-        process.stdout.write(`Active session: ${active.sessionId} (${active.entriesCaptured.length} entries captured)\n`);
+        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 this active session and any in-flight captures?',
+            message: 'Discard all local sessions and any in-flight captures?',
             initialValue: false,
         });
         if (!ok) {
@@ -224,27 +377,73 @@ export async function runSessionReset(options = {}) {
             return;
         }
     }
-    // Hard-reset: discard session.json (no resume marker). Binding state is left untouched.
-    discardSession();
-    process.stdout.write('Session state reset — session.json cleared.\n');
+    // 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)
         return;
-    const session = readSession();
+    const conversationId = resolveConversationId(options.conversation) ?? undefined; // TEN-4855: resolved as start does, so start resumes
+    const session = readSession(conversationId);
     if (!session) {
         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,
             });
         }
@@ -254,11 +453,9 @@ 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) {
@@ -270,32 +467,76 @@ export async function runSessionClose(options = {}) {
             });
         }
     }
-    process.stdout.write(formatSessionClose(session) + '\n');
-    // WP-439 S6: surface unrepaired setup-asset receipts as a non-blocking
-    // advisory. Failures here are silent — never let a network blip or schema
-    // gap prevent a session from closing.
+    // 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 {
-        const advisory = await kernelCall('setup.listFailedAuditReceipts', {});
-        if (advisory.total > 0) {
-            const preview = advisory.entries
-                .slice(0, 3)
-                .map((e) => `${e.entryId} (${e.status})`)
-                .join(', ');
-            const more = advisory.total > 3 ? ` and ${advisory.total - 3} more` : '';
-            process.stdout.write(`\nNote: ${advisory.total} unrepaired setup-asset receipt(s) on file — ${preview}${more}.\n` +
-                'Run `pb setup-audit` to inspect; `pb setup-audit --repair` to retry.\n');
-        }
+        rituals = await kernelCall('chain.getRitualsSurface', { now: Math.floor(Date.now() / 60_000) * 60_000 });
     }
-    catch {
-        // Advisory call failure is non-fatal.
+    catch { /* non-critical */ }
+    process.stdout.write(formatSessionClose(session, wrapup, closed?.workspaceSlug ?? undefined, appUrl, rituals, closed) + '\n');
+    clearSession(conversationId); // writes the closed marker the next start on this conversation resumes from (TEN-3977)
+}
+// ─── 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`.',
+        });
     }
-    // Clear local state
-    clearSession();
-    // Refresh context files so next session starts with updated knowledge.
-    // WP-439 S4: internal handshake runs lenient — strict-mode failures from an
-    // automatic refresh would block close; orphans are surfaced via the
-    // advisory above + `pb handshake` (called directly) instead.
-    process.stdout.write('Refreshing context...\n');
-    await runHandshake({ force: false, apply: true, lenient: true });
+    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