csb resume / csb view: handle pruned UUIDs (prompt-to-restore + temporary resurrection)

[djdarcy]

Summary

csb resume <uuid> and csb view <uuid> (the latter per #14) should
gracefully handle pruned UUIDs (sessions with deleted_at set in
the DB; JSONL no longer on disk; bytes still recoverable from git).

Today:

• csb resume <pruned-uuid> resolves the UUID, calls claude --resume,
  which fails because the JSONL doesn't exist on disk. User gets a
  Claude Code error with no path forward.
• csb view <pruned-uuid> (when CLI launcher for claude-code-history-viewer -- csb view (Alpha #3) #14 ships) would face the same gap.

Proposed surface:

• csb resume <pruned-uuid>: detect the pruned state, prompt
  the user once: "Session <name> was pruned . Restore from
  git before resuming? [Y/n]". On Y, run cmd_restore (the full
  v0.3.12 implementation: jsonl + subagents + tool-results +
  session-states + sesslogs), then launch claude --resume. On n,
  abort with a hint about csb restore <uuid> for manual control.
• csb view <pruned-uuid>: temporary resurrection -- restore
  to a sandboxed location, launch the viewer against it, clean up
  on exit. The on-disk ~/.claude/ is never touched.

Both features build on top of v0.3.12's cmd_restore -- they should
NOT reimplement restore logic.

Consolidation discipline (non-negotiable)

This project has a clear pattern of consolidating shared functionality
across list / scan / search / resume / show / restore:

• v0.2.7 -- short-UUID resolver shared via ids.py:resolve_session_id
• v0.2.10 -- csb search parity with list/scan for sort, -f/-ff
• v0.3.1 -- shared transcript_walker consolidating JSONL parsing
• v0.3.5 -- shared -d/-D dir-scope CLI flags across list/scan/search

The new behaviors here MUST plug into the same machinery:

Concern	Existing shared call-site	New use
UUID resolution (prefix/suffix accepted)	_resolve_session_or_exit in commands.py (uses ids.py:resolve_session_id)	Reused unchanged
"Is this session pruned?" detection	scattered between list_sessions(show_deleted=True), cmd_show, cmd_restore -- needs extraction	Single helper (proposed: is_pruned(session_row) -> bool)
Restore execution (file-level + UUID-keyed)	cmd_restore (v0.3.12 -- multi-file with git_ls_tree_for_uuid + preserve-present policy)	Extract _restore_session(claude_dir, uuid, slug, commit, ...) -> RestoreResult from cmd_restore; both cmd_resume and cmd_view (and future csb scan -d ... --restore) call it
User prompt UX	_confirm_destructive or similar (probably new)	Shared; one place to thread --yes / --no-prompt through

The implementation MUST extract these into shared helpers before
adding cmd_resume / cmd_view consumers. Doing it inline (copying
restore logic into each cmd_) would compound bug surface across the
expanding tool set -- exactly what the consolidation arc has been
trying to avoid.

Open design questions

1. csb view temporary location. Options:
   a. Restore to ~/.claude/ then clean up on viewer exit. Risk:
   viewer crashes / user kills, leaves residue. Mitigation: stamp
   a .csb-view-temp marker, sweep on next csb invocation.
   b. Restore to %TEMP%/csb-view-<uuid>/ mirroring the ~/.claude/
   structure. Viewer must accept arbitrary paths.
   claude-code-history-viewer's current path assumption: TBD --
   check CLI launcher for claude-code-history-viewer -- csb view (Alpha #3) #14's design.
   c. Stream JSONL bytes directly to a viewer's stdin. Eliminates
   filesystem residue but limits to viewers that accept stdin.
2. Cleanup on resume-after-prompt. If user says Y to restore-then-resume,
   should the post-resume state be:
   a. Permanent (csb restore + claude --resume + done; user has the
   session back). RECOMMENDED.
   b. Temporary (restore + claude --resume + clean up on claude exit).
   Surprising; users probably want it to stick.
3. --yes / --restore / --no-restore flags for non-interactive use.
   Cron / scripts shouldn't hang on a prompt. Default: prompt when TTY,
   abort with hint when non-TTY.
4. Pruned-state cache staleness. The DB's deleted_at could lag
   reality (e.g. user manually rm'd a JSONL since last csb backup).
   Do we check the filesystem too, or trust the DB? cmd_resume
   currently trusts the DB; should we add a stat() fallback?

Acceptance criteria

• Investigation pass: catalog every existing call-site that
  checks deleted_at and every restore code path. Identify the
  duplication. Decide the extraction shape (is_pruned,
  _restore_session, etc.) BEFORE writing new code.
• Extract _restore_session() from cmd_restore into a callable
  helper that returns a structured result (counts, conflicts,
  preserve-list). cmd_restore becomes a thin wrapper around it
  that handles CLI flag parsing + output formatting.
• cmd_resume detects pruned sessions, prompts (TTY) or aborts
  with hint (non-TTY), and invokes the shared _restore_session
  on confirmation. Reuses existing _resolve_session_or_exit.
• cmd_view (or its v0.3.x equivalent under CLI launcher for claude-code-history-viewer -- csb view (Alpha #3) #14) handles pruned
  UUIDs via temporary restoration. Implementation per the
  Decision-1 outcome above.
• Non-interactive flags (--yes / --no-restore / equivalent)
  with consistent semantics across resume and view.
• Tests cover: pruned + Y prompt, pruned + n prompt, pruned + TTY
  detection, pruned + --yes, alive session (no prompt), restore
  failure mid-resume, view + cleanup-on-success, view + cleanup-on-crash.
• docs/maintenance.md updated to document the resume / view
  flow for pruned sessions.

Out of scope (for this issue)

• The viewer implementation itself (that's CLI launcher for claude-code-history-viewer -- csb view (Alpha #3) #14).
• Refactoring list/scan/search SQL filter composition (the
  v0.3.12 UUID-prefix fix already started this; further consolidation
  is a separate cleanup issue worth filing).
• Filesystem-derived --deleted semantics (separate from DB-derived;
  noted in the v0.2.8 design doc as Phase 2 of the deletion discovery).

Related

• Parent: Roadmap #1 (Roadmap)
• Companion / extends: CLI launcher for claude-code-history-viewer -- csb view (Alpha #3) #14 (csb view -- viewer launcher; this issue
  adds pruned-UUID support to it)
• Builds on: csb restore: also restore subagents/ and tool-results/ sidecars #32 + csb restore: also restore session-states/<uuid>.{json,name-cache} #33 (v0.3.12 full-restore implementation -- the
  _restore_session extraction operates on the code that landed there)
• Consolidation lineage: v0.2.7 (shared UUID resolver), v0.2.10
  (search parity), v0.3.1 (shared transcript_walker), v0.3.5
  (shared dir-scope flags)

Design references (filename only):

• 2026-06-03__03-36-19__csb-restore-completeness-design.md -- v0.3.12
  DWP describing the cmd_restore architecture that this issue extracts from

[djdarcy]

v0.3.14 ships the resume half

Substantial progress on this issue's primary goal: csb resume <pruned-uuid>
no longer fails with a Claude Code error. The shared _restore_session()
helper extraction (AC #1 + #2) is the load-bearing piece; resume gets
pruned-handling by calling it. View half deferred to #14.

Commit: TBD on restore-shoring-up (not yet pushed; will merge to
main after this lands).

Acceptance criteria status

#	Criterion	Status	Evidence
1	Investigation pass: catalog deleted_at callsites + restore paths; identify duplication; decide extraction shape BEFORE code	DONE	Pre-implementation grep across 8 files surfaced the duplication shape: write loop + per-file overwrite check + backup_lock acquisition were inline in cmd_restore. Extraction shape (_restore_session(claude_dir, full_uuid, jsonl_path, commit, *flags) -> RestoreResult) decided before any code change.
2	Extract _restore_session() from cmd_restore into callable helper returning structured result; cmd_restore becomes thin wrapper	DONE	commands.py now has RestoreResult dataclass + _restore_session() helper. cmd_restore reduced from ~130 lines of inline logic to ~75 lines (CLI parsing + DB/git fallback resolution + output formatting). cmd_resume calls the same helper -- no duplicated write loop, no duplicated overwrite policy, no duplicated lock acquisition.
3	cmd_resume detects pruned, prompts (TTY) or aborts with hint (non-TTY), invokes shared helper, reuses _resolve_session_or_exit	DONE	cmd_resume invokes _resolve_pruned_resume_decision() after the session lookup; on "restore" calls _restore_session(); on "abort" exits 0; on "error" exits 1 with a clear hint. The existing _resolve_session_or_exit is reused (no changes).
4	cmd_view handles pruned UUIDs via temporary restoration (per #14)	NOT DONE	cmd_view doesn't exist yet (#14 is still open). v0.3.14 explicitly defers this. The helper extraction in #2 means future wiring is one call site, not a re-implementation of the policy.
5	Non-interactive flags (--yes / --no-restore / equivalent) with consistent semantics across resume + view	PARTIAL	Resume side: --restore-pruned (auto-yes) and --no-restore-pruned (auto-no), mutually exclusive, symmetric naming. View side N/A until #14 lands; when it does, the same flag-naming convention should extend.
6	Tests cover: pruned + Y prompt, n prompt, TTY detection, --yes, alive session, restore failure mid-resume, view + cleanup-on-success, view + cleanup-on-crash	PARTIAL	7 of 8 applicable cases covered: Y prompt, n prompt, TTY/non-TTY detection, --restore-pruned, --no-restore-pruned, alive-session regression, and a direct-invocation smoke test for _restore_session. Missing on resume side: restore-failure-mid-resume (small polish; could land in v0.3.15). View + cleanup tests N/A pending #14.
7	docs/maintenance.md updated for resume / view flow	PARTIAL	Resume flow documented in the Recovery section's "Related verbs" entry. View flow pending #14.

3 DONE, 3 PARTIAL (resume side complete; view side pending #14), 1 NOT DONE.
Refs (not Closes).

What's in v0.3.14

• _restore_session() + RestoreResult dataclass in commands.py
• cmd_restore refactored to thin wrapper around the helper
• cmd_resume detects pruned, prompts on TTY, calls helper on restore
• --restore-pruned / --no-restore-pruned mutually-exclusive flags
• 7 new tests (TTY + non-TTY paths, alive-session regression, helper smoke)
• docs/maintenance.md Recovery section updated
• 808/808 tests pass (was 801; +7 new)

What remains to close this issue

1. cmd_view implementation depends on CLI launcher for claude-code-history-viewer -- csb view (Alpha #3) #14 (the viewer launcher).
   Once that lands, plug pruned-handling into it via the same
   _restore_session() helper -- one call site.
2. View-side flags mirroring --restore-pruned /
   --no-restore-pruned for consistency.
3. View + cleanup tests (AC Session discovery, categorization, and AI summaries (peek, tag, summarize, projects) #6 last two bullets).
4. docs/maintenance.md view section.

After #14 lands and (1) + (2) + (3) + (4) ship, this issue can close.

Related

• Parent / blocker: CLI launcher for claude-code-history-viewer -- csb view (Alpha #3) #14 (csb view launcher, Alpha Content Search -- 2-Phase Epic (Phase 1 grep-first, Phase 2 FTS5) #3)
• Builds on: v0.3.12 (_restore_session operates on the full restore
  policy that landed there)
• Consolidation lineage: v0.2.7 (shared UUID resolver), v0.3.1
  (shared transcript_walker), v0.3.5 (shared dir-scope flags). This
  commit adds: v0.3.14 (shared _restore_session helper).

Design

• 2026-06-03__03-36-19__csb-restore-completeness-design.md -- the
  v0.3.12 DWP whose helper extraction this work realizes

[djdarcy]

View-half implemented in 4883dba (v0.3.20); the resume-half shipped in v0.3.14. Closing with one documented design change:

Temporary restoration (AC4 / Decision-1) is superseded by restore-in-place. The temp-dir / stdin sandboxing options were designed when a restore was a lossy intrusion worth isolating. Since then, restore became byte+metadata-exact: v0.3.15 closed the symlink-clobber class, v0.3.16 added the verify gate, v0.3.17/v0.3.18 recreate symlinks and reapply original timestamps (#38/#39/#40). A restored session is simply back, correctly -- there is nothing to sandbox and nothing to clean up, and the "does CCHV accept arbitrary paths?" open question is moot. csb view <pruned-uuid> therefore restores in-place via the same _restore_session + decision-helper flow as csb resume (the helper generalized with a verb parameter; one policy, two surfaces).

AC accounting:

• Investigation / _restore_session extraction / resume-half: DONE (v0.3.14).
• cmd_view pruned handling: DONE (restore-in-place, rationale above).
• Consistent flags across resume + view: DONE (--restore-pruned / --no-restore-pruned, identical semantics, TTY prompt default).
• Test matrix: DONE -- including the long-open "restore failure mid-resume" gap (a failed auto-restore now provably never launches claude --resume) and its view mirror (failed restore never launches the viewer). The cleanup-on-success / cleanup-on-crash tests are superseded along with the temporary-restoration design.
• docs/maintenance.md: DONE -- documents both pruned flows side by side, including the restore-in-place rationale.