Skip to content

feat: park a session to set it aside - #51

Merged
jongracecox merged 1 commit into
mainfrom
worktree/20260921-add-park-option
Sep 22, 2026
Merged

jongracecox merged 1 commit into
mainfrom
worktree/20260921-add-park-option

Conversation

@jongracecox

Copy link
Copy Markdown
Owner

Summary

Adds Park alongside Stop as a way to end a session: same operation, different
intent. A parked session renders 🅿️ instead of 🟠 and sits out the bulk restore.

Why

Stopping is right for a break, but not for work you are consciously shelving. A stopped
session lands in the same orange bucket as everything a restart took away, and
Restore N stopped sessions sweeps it back up with the rest — so shelved work keeps
coming back.

Design

Parking is a flavour of stopped, not a third intent. SessionRecord.parked is a flag
on the existing open record, so is_stopped stays true for a parked session and
everything keyed off it — resume, terminate, placement in the sessions section —
keeps working untouched. Only two things change:

  • the icon (🅿️ instead of 🟠)
  • Restore N stopped sessions skips it, and its count excludes it

mark_open writes a fresh record, so launching or resuming un-parks — the natural exit,
mirroring how a stopped session leaves that state.

🟢 running        ← in flight
🅿️ parked         ← set aside on purpose
🟠 stopped        ← a restart or an out-of-band kill took it away
───── inactive worktrees ─────
⚫ terminated / never launched

Changes

  • session_state.py — SessionRecord.parked, coerced with bool() on load so an older
    record still loads. touch(..., parked=None) is tri-state: None leaves the flag
    alone, so a plain stop of a parked session doesn't silently un-park it.
  • cli.py — ICON_PARKED, SessionInfo.is_parked, _end_session(..., park=...),
    Park in the Ctrl-A x prompt (Terminate / Park / Stop / Cancel) and in the session
    actions menu, and the running → parked → stopped ordering in the home list.
  • Docs — CLAUDE.md (session status table, module responsibilities, design decisions),
    README.md (icon legend, home screen, actions table) and CONTRIBUTING.md (manual test
    steps).

Testing

1002 tests pass. New coverage for the icon, the row ordering, the restore exclusion, the
flag round-trip (park → launch clears it), a plain stop leaving the flag alone, and both
entry points (menu item and prompt).

Compatibility

A record written before this change has no parked key and loads as unparked. An older
fujimoto reading a parked record ignores the field — it shows the session as 🟠 and will
include it in a restore, but nothing is corrupted and the flag survives.

Stopping a session is the right move for a break, but not for work you are
consciously shelving: the row goes orange alongside everything a restart took
away, and "Restore N stopped sessions" sweeps it back up with the rest.

Park is the same operation with a flag. `SessionRecord.parked` makes it a
flavour of stopped rather than a third intent, so everything keyed off
`is_stopped` — resume, terminate, the sessions section — keeps working; only
the icon (blue P) and the restore sweep change. `mark_open` writes a fresh
record, so launching or resuming un-parks.

The sessions section now reads running, then parked, then stopped, and the
`Ctrl-A x` prompt gains a Park option beside Stop.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
@jongracecox
jongracecox merged commit d0fa78f into main Sep 22, 2026
5 checks passed
@jongracecox
jongracecox deleted the worktree/20260921-add-park-option branch September 22, 2026 15:13
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant