@productbrain/cli 0.1.0-beta.14 → 0.1.0-beta.14010

package/dist/commands/session.js

@@ -1,78 +1,302 @@
 /**
- * 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 { mcpCall } from '../lib/client.js';
-import { readSession, writeSession, clearSession } from '../lib/session.js';
-import { isJsonMode } from '../lib/runner.js';
-import { formatSessionStart, formatSessionClose } from '../formatters/session.js';
-import { runHandshake } from './handshake.js';
+import { kernelCall } from '../lib/client.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, formatSessionList, formatSessionShow, buildAcceptCommand, uncheckedRefusal, FEEDBACK_SUBMIT_HINT, } from '../formatters/session.js';
+import { CLIError, ErrorCode } from '../lib/errors.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 { 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;
+    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 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` 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) {
-        if (json) {
-            process.stdout.write(JSON.stringify({
-                sessionId: existing.sessionId,
-                workspaceName: existing.workspaceName,
-                startedAt: existing.startedAt,
-                alreadyActive: true,
-            }) + '\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: 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.
+        }
+    }
+    // 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', {});
+            // 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) {
+                // 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,
+                    workspaceName: resumed.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,
+                        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;
+                }
+                const elapsedMins = Math.round(elapsed / 60_000);
+                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(conversationId ?? undefined);
         }
-        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;
     }
     // Resolve workspace + keyId
-    const workspace = await mcpCall('resolveWorkspace', {});
+    const workspace = await kernelCall('resolveWorkspace', {});
     if (!workspace?.keyId) {
-        throw new Error('API key has read-only scope. Write operations require a readwrite key.\n' +
-            'Generate one: Product Brain app → Settings → API Keys.');
+        throw new CLIError('API key has read-only scope. Write operations require a readwrite key.', {
+            code: ErrorCode.AUTH_INVALID,
+            category: 'auth',
+            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 mcpCall('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: [],
-    };
-    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,
+            ...(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
-        await runHandshake({ force: false, dryRun: false, quiet: true });
         return;
     }
-    process.stdout.write(formatSessionStart(state, result.superseded) + '\n');
-    // Refresh context files
-    process.stdout.write('Refreshing context...\n');
-    await runHandshake({ force: false, dryRun: 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).
@@ -81,28 +305,135 @@ export async function runSessionStart(options = {}) {
 export function runSessionId() {
     const session = readSession();
     if (!session) {
-        process.stderr.write('No active session. Run `pb session start` first.\n');
-        process.exit(1);
+        throw new CLIError(copy.noSession, {
+            code: ErrorCode.SESSION_REQUIRED,
+            category: 'session',
+            guidance: copy.noSessionGuidance,
+        });
     }
     process.stdout.write(session.sessionId + '\n');
 }
-export async function runSessionClose(options = {}) {
-    const config = await getConfigOrGuide(() => runSessionClose(options));
-    if (!config)
+/**
+ * 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;
-    const session = readSession();
+    }
+    // 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 = {}) {
+    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;
     }
-    // Record wrapup metrics
-    const entriesCount = session.entriesCaptured.length;
-    if (entriesCount > 0) {
+    // 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 });
+        // 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);
+    }
+    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);
+        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: `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; // TASK-923: held drafts not counted
+    const draftsCommitted = wrapup ? wrapup.committed.length : 0;
+    if (draftsReviewed > 0) {
         try {
-            await mcpCall('agent.recordWrapup', {
+            await kernelCall('agent.recordWrapup', {
                 sessionId: session.sessionId,
-                draftsReviewed: entriesCount,
-                draftsCommitted: 0, // CLI captures are drafts; user commits in Studio
+                draftsReviewed,
+                draftsCommitted,
                 linksCreated: 0,
             });
         }
@@ -112,23 +443,84 @@ export async function runSessionClose(options = {}) {
         }
     }
     // Close the session
+    let closed = null; // TASK-816: printed counts come from here
     try {
-        await mcpCall('agent.closeSession', {
-            sessionId: session.sessionId,
-            status: 'closed',
-        });
+        closed = await kernelCall('agent.closeSession', { sessionId: session.sessionId, status: 'closed' });
     }
     catch (err) {
         if (!options.force) {
-            throw new Error(`Failed to close session: ${err instanceof Error ? err.message : String(err)}\n` +
-                'Use `pb session close --force` to clear local state anyway.');
+            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: 'Run `pb session close --force` to clear local state anyway.',
+            });
         }
     }
-    process.stdout.write(formatSessionClose(session) + '\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, dryRun: false });
+    // 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;
+    try {
+        rituals = await kernelCall('chain.getRitualsSurface', {});
+    }
+    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`.',
+        });
+    }
+    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