@productbrain/cli 0.1.0-beta.1428 → 0.1.0-beta.14280

package/dist/commands/session.js

@@ -1,32 +1,56 @@
 /**
- * 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, resolveHarnessName } from '../lib/conversation.js';
+import { openSeatWithNotes, seatConversationId, startTextOf } from '../lib/sessionOpen.js'; // TASK-1408
+import { isJsonMode, runCliCommand } from '../lib/runner.js';
 import { confirm, isInteractive } from '../lib/prompts.js';
-import { formatSessionStart, formatSessionClose, formatLoopUnfinished, buildPromoteCommand, } from '../formatters/session.js';
-import { runHandshake } from './handshake.js';
+import { formatSessionStart, formatSessionClose, formatLoopUnfinished, formatSessionList, formatSessionShow, buildAcceptCommand, uncheckedRefusal, FEEDBACK_SUBMIT_HINT, } from '../formatters/session.js';
 import { CLIError, ErrorCode } from '../lib/errors.js';
-import { getActiveProfile } from '../lib/profiles.js';
-import { readLocalProjectConfig, resolveEffectiveProfile, refreshPreviewApiKeyFromDisk } from '../lib/config.js';
+import { copy } from '../lib/style.js'; // same-line combine, shrink-only budget
+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 { composeWrapupView } from '../lib/compose-wrapup-view.js';
-/** 2-hour window for auto-resume (WP-322 E1). */
-const RESUME_WINDOW_MS = 2 * 60 * 60 * 1000;
+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.
+ * through to a normal rethrow. A role refusal (pinnedRole.ts's one code set) is never a key problem.
  */
 function isStalePreviewKeyError(err) {
-    return err instanceof CLIError && (err.category === 'auth' || err.code === ErrorCode.INTERNAL);
+    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
@@ -42,41 +66,31 @@ function isOpaqueKeyRejection(err) {
 /**
  * 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 preview.json.
+ * 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 .productbrain/preview.json.', {
+    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), then retry.',
+        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;
-    let post;
-    try {
-        post = await establishSession(options);
-    }
-    catch (err) {
-        post = await recoverStalePreviewKey(err, options);
-    }
-    // Context refresh runs OUTSIDE the recovery scope above. runHandshake throws ErrorCode.INTERNAL
-    // for a body-fetch failure that has nothing to do with the apiKey; keeping it here means such a
-    // failure surfaces as itself instead of being misread as a stale-key rejection and swallowed by
-    // the retry or relabelled "preview key rejected" (no-masking; R2 honesty).
-    if (post.run) {
-        await runHandshake({ force: false, apply: true, quiet: post.quiet, invocationPath: 'session-start' });
-    }
+    await getConfigOrGuide();
+    // 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 the 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). Recovery runs ONLY when the
- * worktree is preview-bound — on the real Chain the error is rethrown untouched so a genuine
- * failure is never masked (R2). The retry runs at most once.
- */
+/** 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))
@@ -109,47 +123,57 @@ async function recoverStalePreviewKey(err, options) {
 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
+        // 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 {
-            // Codex P2: an already-active session returns here without any kernel call, so the
-            // catch-based recovery never fires. After a reseed the locally-bound preview key is stale,
-            // and leaving it bound would make the NEXT pb write fail with the rejected key. Proactively
-            // re-read the fresh key from preview.json — disk-to-disk, no network, so the offline-safe
-            // status report stays offline-safe (refreshPreviewApiKeyFromDisk no-ops off a preview binding).
-            refreshPreviewApiKeyFromDisk();
-            if (json) {
-                process.stdout.write(JSON.stringify({
-                    sessionId: existing.sessionId,
-                    workspaceName: existing.workspaceName,
-                    startedAt: existing.startedAt,
-                    alreadyActive: true,
-                    activeProfile: readLocalProjectConfig()?.profile ?? getActiveProfile(),
-                }) + '\n');
-                return { run: true, quiet: true };
-            }
-            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 { run: true, quiet: true };
+            // WP-777, DEC-1888, INS-2674: a start re-run after a compaction gets the same briefing as a fresh start: the server
+            // reuses this conversation's live row and serves the full tail, so this path goes through the kernel below.
         }
     }
-    // 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) {
@@ -162,19 +186,18 @@ async function establishSession(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',
-                });
-                const shortPrevId = closedMarker.sessionId.slice(-8);
+                // TASK-1408 (DEC-2495): the seat (one retry on a timeout), then its start notes and their stamp.
+                const opened = await openSeatWithNotes('agent.resumeSession', {
+                    workspaceId: wsForResume._id, apiKeyId: wsForResume.keyId, previousSessionId: closedMarker.sessionId,
+                    clientKind: 'cli', clientName: resolveHarnessName(), role: options.role, team: options.team, // TASK-1211, TASK-439, TASK-801
+                    previewMethod: options.previewMethod, previewSituation: options.previewSituation, // TASK-1214
+                }, seatConversationId(conversationId, bindingFingerprint));
+                const resumed = opened.view, 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,
@@ -182,32 +205,37 @@ async function establishSession(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, text: startTextOf(opened, formatSessionStart(state, effectiveProfile, resumed, 'started', conversationId), conversationId), // TASK-1022, TASK-1408
+                        notices: resumed.notices ?? [], ruleLists: resumed.ruleLists, roleEntryId: resumed.roleEntryId, roleName: resumed.roleName, briefing: resumed.briefing, // TASK-436/439/552
                     }) + '\n');
-                    return { run: 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');
-                return { run: true, quiet: false };
+                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(startTextOf(opened, formatSessionStart(state, effectiveProfile, resumed, 'started', conversationId), conversationId) + '\n');
+                return;
             }
         }
         else {
             // Marker is stale (>2h) — clear it so next session starts fresh
-            clearSession();
+            clearSession(conversationId ?? undefined);
         }
     }
     // Resolve workspace + keyId
@@ -219,38 +247,56 @@ async function establishSession(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',
-    });
-    // Persist session state
-    const state = {
-        sessionId: result.sessionId,
-        workspaceId: workspace._id,
-        workspaceName: result.workspaceName,
-        startedAt: new Date().toISOString(),
-        entriesCaptured: [],
-        profile: effectiveProfile ?? undefined,
-    };
-    writeSession(state);
+    const opened = await openSeatWithNotes('agent.startSession', {
+        workspaceId: workspace._id, apiKeyId: workspace.keyId, clientKind: 'cli', clientName: resolveHarnessName(), // TASK-1211: the tool behind the CLI
+        label, role: options.role, team: options.team, previewMethod: options.previewMethod, previewSituation: options.previewSituation, // TASK-1214
+    }, seatConversationId(conversationId, bindingFingerprint));
+    const result = opened.view;
+    const usage = await kernelCall('usage.getWorkspaceSummary', { periodDays: 1 }, { actingSessionId: result.sessionId }).catch(() => null);
+    // 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);
+    const startText = startTextOf(opened, // TASK-1022, TASK-1014, TASK-1408: the timing line, or the headline-only form without its notes
+    formatSessionStart(state, effectiveProfile, { ...result, allowanceLine: usage?.allowanceLine }, kept ? 'already-active' : 'started', conversationId), conversationId);
     if (json) {
         process.stdout.write(JSON.stringify({
             sessionId: state.sessionId,
             workspaceName: state.workspaceName,
             startedAt: state.startedAt,
-            activeProfile: getActiveProfile(),
+            ...(kept ? { alreadyActive: true } : {}), ...(endedSessionId ? { endedSessionId } : {}), allowanceLine: usage?.allowanceLine, // TASK-1014
+            activeProfile: effectiveProfile,
+            feedbackQueueNew: result.feedbackQueueNew,
+            feedbackOldestNewAt: result.feedbackOldestNewAt,
+            feedbackHint: FEEDBACK_SUBMIT_HINT, text: startText, // TASK-1022: the hook prints this
+            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 (runs in the caller, outside the recovery scope).
-        return { run: true, quiet: true };
+        return;
     }
-    process.stdout.write(formatSessionStart(state, result.superseded, readLocalProjectConfig()?.profile ?? getActiveProfile()) + '\n');
-    // Refresh context files (runHandshake runs in the caller, outside the recovery scope).
-    process.stdout.write('Refreshing context...\n');
-    return { run: true, quiet: false };
+    if (endedSessionId)
+        process.stdout.write(`Session ${endedSessionId} had already ended on the server; this is a new one.\n`);
+    process.stdout.write(startText + '\n');
 }
 /**
  * pb session id — print current session ID bare to stdout (machine-readable).
@@ -259,10 +305,10 @@ async function establishSession(options) {
 export function runSessionId() {
     const session = readSession();
     if (!session) {
-        throw new CLIError('No active session.', {
+        throw new CLIError(copy.noSession, {
             code: ErrorCode.SESSION_REQUIRED,
             category: 'session',
-            guidance: 'Run `pb session start` first.',
+            guidance: copy.noSessionGuidance,
         });
     }
     process.stdout.write(session.sessionId + '\n');
@@ -285,27 +331,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) {
@@ -313,72 +375,58 @@ 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();
+    await getConfigOrGuide();
+    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');
+        process.stdout.write(`${copy.noSession} ${copy.noSessionGuidance}\n`);
         return;
     }
-    // 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.
+    // The SERVER's post-promote truth (committed vs still-draft), never the local snapshot.
+    // A failed read is no answer, so the close refuses unless --force; a refusal the server sent passes through.
     let wrapup = null;
+    let canClose = false;
     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,
-            // 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,
-        };
-        // Pending domain-tag proposal count is admin-gated (http.ts: authorityDomains.readiness).
-        // A plain API-key session has no management role, so this 403s — surface the count when
-        // available, omit silently otherwise. The hint is advisory, never required.
-        try {
-            const readiness = await kernelCall('authorityDomains.readiness', {});
-            wrapup.pendingDomainProposals = readiness?.proposals?.pendingDomainTagCount;
-        }
-        catch {
-            // Non-admin or unavailable — omit the domain-tag advisory.
-        }
-    }
-    catch {
-        // Wrapup read failed — degrade to legacy local-snapshot rendering, no enforcement.
+        // The server decides whether the loop is empty; the CLI never recomputes it.
+        canClose = raw.canClose;
+        // composeWrapupView alone merges the capped and overflow sets (pinned against the MCP twin).
+        wrapup = composeWrapupView(raw);
     }
-    // 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');
+    catch (err) {
+        // Only a transport failure takes the signed line; auth, session, quota and the rest are the server's own answer.
+        const transport = !(err instanceof CLIError) || ((err.category === 'network' || err.category === 'internal') && err.code !== ErrorCode.RATE_LIMITED);
+        if (!options.force && !transport)
+            throw err;
+        if (!options.force) {
+            const code = err instanceof CLIError ? err.code : ErrorCode.NETWORK_UNREACHABLE;
+            throw new CLIError(copy.closeCheckFailed(session.sessionId), { code, category: 'session', guidance: copy.closeCheckFailedGuidance });
         }
+    }
+    // ENFORCEMENT: loop open, no --force: print the next step, exit LOOP_UNFINISHED, DO NOT close (--force escapes).
+    if (wrapup && !canClose && !options.force) {
+        // --json gets ONLY the structured error thrown below; the human nudge would corrupt stdout.
+        const nudge = formatLoopUnfinished(wrapup);
+        if (!isJsonMode() && nudge.trim())
+            process.stdout.write(nudge + '\n');
         const draftIds = wrapup.drafts.map((d) => d.entryId);
-        throw new CLIError(`Loop unfinished: ${wrapup.drafts.length} draft(s) not committed to the Chain.`, {
+        if (draftIds.length === 0) {
+            const { message, guidance } = uncheckedRefusal(wrapup, session);
+            throw new CLIError(message, { code: ErrorCode.LOOP_UNFINISHED, category: 'session', guidance });
+        }
+        throw new CLIError(`Loop unfinished: ${wrapup.drafts.length} draft(s) not yet accepted.`, {
             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.`,
+            guidance: `Accept with \`${buildAcceptCommand(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 draftsReviewed = wrapup ? wrapup.committed.length + wrapup.drafts.length : session.entriesCaptured.length; // TASK-923: held drafts not counted
     const draftsCommitted = wrapup ? wrapup.committed.length : 0;
     if (draftsReviewed > 0) {
         try {
@@ -395,13 +443,9 @@ export async function runSessionClose(options = {}) {
         }
     }
     // Close the session
-    let workspaceSlug;
+    let closed = null; // TASK-816: printed counts come from here
     try {
-        const closeResult = await kernelCall('agent.closeSession', {
-            sessionId: session.sessionId,
-            status: 'closed',
-        });
-        workspaceSlug = closeResult.workspaceSlug ?? undefined;
+        closed = await kernelCall('agent.closeSession', { sessionId: session.sessionId, status: 'closed' });
     }
     catch (err) {
         if (!options.force) {
@@ -417,32 +461,66 @@ export async function runSessionClose(options = {}) {
     // 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();
-    process.stdout.write(formatSessionClose(session, wrapup, workspaceSlug, appUrl) + '\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.
+    // WP-582 B2 round 1 (T10): rituals surface, best-effort (formatSessionClose has the rest).
+    let rituals = null;
     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', {});
     }
-    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() {
+    await getConfigOrGuide();
+    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) {
+    await getConfigOrGuide();
+    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, invocationPath: 'session-close' });
+    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