opencode-sesh 0.1.7 → 0.2.1

package/AGENTS.md

@@ -23,10 +23,12 @@ slot section plus an xlarge modal picker; the terminal UI is fullscreen fzf.
 ## Start here
 
 ```bash
-npm install            # dev deps (TypeScript, opencode/OpenTUI types)
-npm test               # fixture-DB regression suite — must stay green
-npm run typecheck      # tsc over tui/ and opencode/
-npm run lint:sh        # bash -n on every script
+bun install            # dev deps (TypeScript, opencode/OpenTUI types)
+bun run test           # fixture-DB regression suite — must stay green
+bun run test:changelog # release-tooling regressions (scripts/changelog.sh)
+bun run test:picker    # PTY picker suite (needs fzf >= 0.73)
+bun run typecheck      # tsc over tui/ and opencode/
+bun run lint:sh        # bash -n on every script
 HOME=/tmp/fakehome bash install.sh   # installer smoke test (never touches ~/.config)
 ```
 
@@ -36,6 +38,9 @@ HOME=/tmp/fakehome bash install.sh   # installer smoke test (never touches ~/.co
   Never hardcode install paths.
 - `tui/sesh-panel.tsx` — SolidJS panel, `/** @jsxImportSource @opentui/solid */`.
 - `opencode/tools/sesh-list.ts` — the agent-facing `sesh-list` tool.
+- `scripts/changelog.sh` — release tooling: drafts `[Unreleased]` from
+  conventional commits, promotes it to a dated version, prints release notes and
+  checks the compare links. `tests/changelog.sh` covers it in a throwaway repo.
 - `themes/`, `tests/`, `install.sh`, `README.md`.
 
 The **filename becomes the tool name** in opencode, so `sesh-list.ts` is the
@@ -60,7 +65,18 @@ the schema below. Keystrokes never touch the database:
   the whole DB and pruning is always safe.
 - render (cheap, pure `jq`): reads the snapshot only. Filters on `searchText`
   (title + `fulltextLower`, both lowercased at extraction), groups by `cwd`,
-  sorts groups/items by recency, renders the TSV.
+  sorts groups/items by recency, renders the TSV. Notice rows (headers, a
+  vanished selection, an empty store, a query matching nothing) carry an empty
+  `sessionId` and a unique `trackingId`. `--header` prints the one-line
+  scope/count/status that the picker uses as fzf's header, and a non-actionable
+  selection leaves a one-shot `STATE_DIR/action-notice` the next render shows
+  and consumes. Snapshot records carry `archived` as 0/1 (the DB column is an
+  epoch, not a boolean).
+- Session and directory pins live in `${XDG_DATA_HOME:-$HOME/.local/share}/sesh/pins.json`
+  (`SESH_PINS_FILE` overrides it for tests), shared by fzf and the TUI. Writes
+  use a sibling lock directory and atomic rename. Option-S toggles a selected
+  session; Option-D toggles its directory. Pinned directories sort before groups
+  containing pinned sessions, with pinned sessions first inside each group.
 
 **Output contract** (TSV, 6 fields):
 `agentId  sessionId  liveState  display  cwd  trackingId`. `display` is the only
@@ -69,8 +85,11 @@ empty `sessionId` and are a selection no-op — keep that guard.
 
 One worker (`sesh-refresh-worker.sh`, per picker, TERMed on exit) serializes
 scans; fzf's `start`/`every(3)`/`change` bindings render only. Selection requests
-a fresh poll (`request`/`wait`, ≤12 s) before dispatch. opencode has no
-live-agent API, so `liveState` is always `unknown` and rows render gray;
+a fresh poll (`request`/`wait`, ≤12 s) before dispatch — skipped for `--print`,
+which is a pure snapshot lookup — and prints a progress line to stderr while it
+waits, because fzf has already exited and the terminal is idle. opencode has no
+live-agent API, so `liveState` is always `unknown` and rows render gray unless
+they are archived (opt-in, tagged `· archived`);
 dispatch is always `opencode --session <id>` (`--fork` with Ctrl-F or --fork).
 Resume happens in place (`exec` after `cd` to the session's cwd).
 
@@ -88,7 +107,12 @@ Resume happens in place (`exec` after `cd` to the session's cwd).
   raw string.
 - fzf: stock only, `>= 0.73` (`transform:`, `every():`). `{q}` in binds is
   shell-quoted by fzf — don't add quoting. Ctrl-G is bind-only (stays open);
-  Ctrl-F is `--expect` (accepts with fork).
+  Ctrl-F is `--expect` (accepts with fork). A `transform-header` inside a chained
+  action must come **before** `reload`/`reload-sync`: placed after, fzf silently
+  publishes an empty list (verified on 0.74.3).
+- Destructive actions confirm. `sesh-delete.sh` prompts on a TTY and refuses
+  without `--yes` when stdin is not one; the TUI arms on the first Ctrl-X and
+  commits on the second (or `y`).
 - The installer prefers the local opencode version for `@opencode-ai/*` and
   merges (never clobbers) the config `package.json`; opencode runs `bun install`
   at startup.
@@ -96,23 +120,38 @@ Resume happens in place (`exec` after `cd` to the session's cwd).
   (`feat`, `fix`, `docs`, `ci`, …). See
   [CONTRIBUTING.md](CONTRIBUTING.md#commit-messages) for the types and the
   version mapping.
+- `CHANGELOG.md` follows Keep a Changelog: notable changes are written under
+  `[Unreleased]` as the work lands, and the Release workflow promotes that
+  section (dated, relinked) into the published version, using it verbatim as the
+  GitHub release body. `scripts/changelog.sh draft` can seed entries from
+  conventional commits, but hand-written prose is the expected form — never let
+  a draft overwrite curated entries.
 
 ## TUI panel (`tui/sesh-panel.tsx`)
 
 - **Sidebar:** `api.slots.register` on `sidebar_content` (append mode — native
-  sidebar content stays). Renders the most recent unarchived sessions with the
-  current one highlighted, polled every 15 s. Display-only; the picker does
-  actions.
+  sidebar content stays). Renders pinned sessions before the newest unarchived
+  sessions, with the current one highlighted, polled every 15 s; Ctrl-P previews
+  a row and ctrl+x deletes one (armed, then confirmed). The section lists every
+  session without a row cap and flex-grows to fill the sidebar, with overflow
+  scrolling inside; the picker remains the place for transcript search.
 - **Picker:** a custom dialog (not `DialogSelect`) grouped by
   project/directory, recency-ordered, resume via
   `api.route.navigate("session", …)`. `ctrl+o` and the command palette open it;
-  Ctrl-X deletes via the opencode CLI and removes the row only after the server
-  confirms the deletion.
+  Ctrl-X arms and then confirms a delete through `api.client.session.delete` and
+  removes the row only after the server confirms; Ctrl-F forks through
+  `api.client.session.fork`; Ctrl-G scopes the list to the selected session's
+  project.
 - **Picker search:** pages the global session list (`SESSION_PAGE_LIMIT`, capped
   at `SESSION_MAX` and reported when truncated) instead of a fixed 500-row
   window, then indexes transcript text for **every** session in batches
   (`TRANSCRIPT_BATCH`) with bounded remote concurrency (`REMOTE_CONCURRENCY`).
   The header shows indexing progress/coverage. `tests/tui.mjs` locks this.
+- **Durable install:** opencode imports plugins once at startup and never hot
+  reloads, so panel changes need a full quit/reopen. `install.sh --sync-panel`
+  (run by the `postinstall`) refreshes an already-installed panel and is a
+  no-op when absent, and `sesh --check` reports when the installed copy differs
+  from the bundled one.
 
 ### Hard-won rules — do not regress
 
@@ -131,12 +170,35 @@ Resume happens in place (`exec` after `cd` to the session's cwd).
   removes any leftover `commands/sesh.md`.
 - Do not bind `<leader>l` (native `session_list`) or shadow the native
   `/sessions` command.
+- **The sidebar never binds arrow keys globally.** Keyboard navigation is
+  opt-in: clicking the *Sessions* heading (or its search box) activates a
+  priority-20 layer, because a global `↑`/`↓` would hijack the main prompt.
+  Cursor state is derived from `itemRows()`, so hover and cursor resolve to the
+  same row. The section lists every session with no row cap
+  (`tests/tui.mjs` asserts the cap stays out); overflow scrolls inside the
+  stretched section.
+- **Delete in the TUI is two-step.** The first `ctrl+x` arms `pendingDelete`,
+  the second (or `y`, or Enter in the picker footer) commits the armed row
+  wherever the pointer or cursor is, and `n`/Esc (or a five-second timeout)
+  cancels. Moving the pointer must never disarm: edge-hover flicker ate the
+  confirm before `confirmArmed` landed. The `y`/`n` layer is registered *only
+  while armed*, so it can never shadow the search box's typing.
+- **Picker `ctrl+g` is project scope**, not close (parity with the fzf picker's
+  `Ctrl-G`); Esc is the only close key. `ctrl+f` forks through
+  `api.client.session.fork` and navigates to the returned session.
+- Row titles render through `<Highlighted>`, and JSX must stay out of the
+  `function shortDir` … `const TRANSCRIPT_PREVIEW_TURNS` window that
+  `tests/tui.mjs` extracts and evaluates as the data layer.
 
 ## Verifying
 
-- `npm test` — fixture-DB regression suite, hermetic via `SESH_*` overrides.
-- `npm run typecheck` — `tsc` over `tui/` and `opencode/`.
-- `npm run lint:sh` — `bash -n` on every script.
+- `bun run test` — fixture-DB regression suite, hermetic via `SESH_*` overrides.
+- `bun run test:changelog` — release-tooling regressions; builds its own git
+  history in a temp dir (included in `bun run test`).
+- `bun run test:picker` — PTY suite driving the real fzf picker (needs fzf
+  `>= 0.73` and Python 3).
+- `bun run typecheck` — `tsc` over `tui/` and `opencode/`.
+- `bun run lint:sh` — `bash -n` on every script.
 - `HOME=/tmp/fakehome bash install.sh` — installer smoke test.
 - Keep `tui/sesh-panel.tsx` and any installed copy byte-identical when testing
   the panel locally.

package/CHANGELOG.md

@@ -7,6 +7,90 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.2.1] - 2026-09-24
+
+### Changed
+
+- The TUI sidebar's Sessions section now lists every session and fills the
+  available sidebar height: the fixed 15-row cap is gone, with overflow
+  scrolling inside the section.
+
+### Added
+
+- Pin sessions with Option-S or directories with Option-D in both pickers. Pins live
+  in a shared XDG data file, appear with a star, and sort ahead of recent
+  sessions in the terminal picker, TUI picker, sidebar and home list.
+
+### Fixed
+
+- The sidebar delete confirm no longer disarms when the pointer leaves the
+  armed row: the second Ctrl+X (or `y`) commits the visibly armed row wherever
+  the pointer is, so deleting works while hovering the sidebar edges.
+
+- Session previews now use Ctrl-P rather than Space in the terminal picker,
+  sidebar and home list, so typing cannot accidentally open a preview.
+- Hovering a sidebar session while keyboard navigation is active now moves the
+  selection to that row, so Option-S/Option-D pin the row under the pointer rather
+  than the previously selected (often currently open) session.
+- The TUI sidebar's Sessions section now has a working show/hide control,
+  separate from clicking the heading to activate keyboard navigation.
+- Transcript previews pass OpenTUI's tree-sitter client to the markdown
+  renderer, restoring themed Markdown and fenced-code highlighting.
+- Preview Markdown now uses the active theme's semantic accents for headings,
+  emphasis, code and list markers when the default Markdown colors read like
+  body text.
+
+### Changed
+
+- Pin shortcuts are labeled Option-S/Option-D (the macOS key) in both pickers
+  and the docs. The terminal picker still binds fzf's `alt-s`/`alt-d`, which is
+  fzf's name for Option and unchanged.
+- The TUI picker now shows transcript search matches as indexing progresses,
+  identifies transcript-only hits, and distinguishes an in-progress search from
+  a completed search with no results.
+- Session previews identify the selected session and show loading feedback
+  while it changes, instead of displaying another session's transcript.
+- The TUI picker uses `Ctrl-P` for transcript preview; Space always enters a
+  space in the search field, including at the start of a query.
+- Sidebar and home searches direct users to the full picker for transcript
+  search when no titles or directories match.
+## [0.2.0] - 2026-09-21
+
+### Added
+
+- The picker header always names the effective scope, the session count and
+  whether the index is fresh or stale (`sesh-list.sh --header`), so a `Ctrl-G`
+  scope toggle or a degraded snapshot is no longer invisible.
+- `sesh --print --json` emits `{"sessionId","cwd","fork"}` for scripting.
+- Archived sessions are tagged `· archived` when included with `--archived`,
+  replacing the agent-state colours that could never fire (opencode exposes no
+  live agent state, so every row rendered grey either way).
+- The TUI picker takes `Ctrl-X` (delete), `Ctrl-F` (fork) and `Ctrl-G` (scope to
+  the selected session's project), so both UIs now agree on the same keys.
+- The TUI sidebar is capped at the 15 most recent sessions with
+  `… N more · ctrl+o for all`, and clicking the **Sessions** heading drives it
+  from the keyboard (`↑`/`↓`, Enter, Space, `Ctrl-X`, Esc).
+- Empty stores, queries that match nothing, vanished selections and an
+  unavailable session list now say so instead of rendering a blank screen.
+- Session titles highlight the part of the row the search matched, and the
+  sidebar search accepts uppercase and punctuation.
+
+### Changed
+
+- Deleting a session asks first. The picker prompts `[y/N]` before dispatching,
+  the TUI arms on the first `Ctrl-X` and commits on a second `Ctrl-X` (or `y`;
+  `n`, Esc or moving cancels), and `sesh-delete.sh` refuses a non-terminal stdin
+  unless given `--yes` — a piped newline can no longer authorize an irreversible
+  delete.
+- Resuming no longer stalls silently while the picker waits for a fresh scan: it
+  prints a progress line first, and `--print` lookups skip that poll entirely.
+- Selecting a directory header or a notice row explains itself with a one-shot
+  notice row instead of repainting the same list as if the key had been ignored.
+- Reconciled README, AGENTS.md and SECURITY.md with current behavior: the
+  terminal UI is described as the full set of scripts (including the refresh
+  worker and shortcut help), the extraction cache key documents the latest part
+  timestamp, the PTY picker suite (`npm run test:picker`) is listed, and the
+  npm distribution and supported-version policy are stated.
 ## [0.1.7] - 2026-09-13
 
 ### Fixed
@@ -141,7 +225,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Fixture-database regression suite, TypeScript typechecking, and ShellCheck in
   CI.
 
-[Unreleased]: https://github.com/ozandogrultan/opencode-sesh/compare/v0.1.7...HEAD
+[Unreleased]: https://github.com/ozandogrultan/opencode-sesh/compare/v0.2.1...HEAD
+[0.2.1]: https://github.com/ozandogrultan/opencode-sesh/compare/v0.2.0...v0.2.1
+[0.2.0]: https://github.com/ozandogrultan/opencode-sesh/compare/v0.1.7...v0.2.0
 [0.1.7]: https://github.com/ozandogrultan/opencode-sesh/compare/v0.1.6...v0.1.7
 [0.1.6]: https://github.com/ozandogrultan/opencode-sesh/compare/v0.1.5...v0.1.6
 [0.1.5]: https://github.com/ozandogrultan/opencode-sesh/compare/v0.1.4...v0.1.5

package/README.md

@@ -27,7 +27,10 @@ grouped by directory, full-text searchable, and previewable from anywhere.
 ## Why sesh
 
 - **Every session, everywhere.** Sessions are grouped by project directory and
-  sorted by recency — across *all* your projects, not just the current one.
+  sorted by pins, then recency — across *all* your projects, not just the current one.
+- **Pin what matters.** Option-S pins a session and Option-D pins its directory in
+  either picker. Pins are shared across the terminal and opencode TUI and
+  persist across restarts; pinned directories and sessions sort first.
 - **Full-text search.** Type to match against session titles *and* the text of
   the conversation itself. Reasoning and tool output are excluded, so the index
   stays clean.
@@ -58,7 +61,8 @@ cd opencode-sesh
 bash install.sh
 ```
 
-`sesh install` (or `bash install.sh`) links `sesh` into `~/.local/bin`, copies
+`sesh install` (or `bash install.sh`) links `sesh` into `$XDG_BIN_HOME`
+(default `~/.local/bin`), copies
 the `sesh-list` tool and the TUI panel into
 `${XDG_CONFIG_HOME:-~/.config}/opencode`, registers the panel in `tui.json`, and
 declares the plugin dependencies (opencode installs them on next start). The
@@ -111,22 +115,31 @@ bash install.sh --uninstall   # from source
 | Enter | Resume the selected session in this terminal |
 | Ctrl-F       | Resume as a fork (the original is untouched) |
 | Ctrl-G | Toggle current-directory scope / all sessions |
-| Space (empty query) | Toggle the transcript preview |
+| Option-S / Option-D | Pin or unpin the selected session / directory |
+| Ctrl-P | Toggle the transcript preview |
 | `?` (empty query) | Toggle shortcut help |
-| Ctrl-X | Delete the selected session |
+| Ctrl-X | Delete the selected session (asks to confirm) |
 | Escape | Exit |
 
+The header line always shows the effective scope, the session count and whether
+the index is fresh or stale, so a `Ctrl-G` toggle is never silent. A query that
+matches nothing says so instead of showing an empty screen.
+
 Flags: `--cwd` (current directory only), `--limit N` (default: all),
 `--archived`, `--print` (print `id<TAB>cwd` instead of resuming), `--fork`,
-`--query TEXT`, `--check`.
+`--json` (with `--print`, emit JSON), `--query TEXT`, `--check`.
 
 Because `--print` just emits the id and directory, `sesh` doubles as a scriptable
 session lookup:
 
 ```bash
 read -r id cwd < <(sesh --print --query "auth")
+sesh --print --json --query "auth" | jq -r .cwd
 ```
 
+Deleting is irreversible, so the picker asks before dispatching it, and a
+non-interactive `sesh-delete.sh` refuses unless given `--yes`.
+
 ### TUI panel
 
 | Key | Action |
@@ -135,12 +148,22 @@ read -r id cwd < <(sesh --print --query "auth")
 | `ctrl+o` | Open the full picker (also in the command palette) |
 | Type | Search titles, directories and transcript text |
 | `↑`/`↓`, `PgUp`/`PgDn`, `Home`/`End` | Move the selection |
-| Space | Toggle the transcript preview |
+| Ctrl-P | Toggle the transcript preview |
 | Enter | Open the selected session |
+| Ctrl-X | Delete the selected session (asks to confirm) |
+| Ctrl-F | Fork the selected session |
+| Ctrl-G | Toggle scope: the selected session's project, or every project |
+| Option-S / Option-D | Pin or unpin the selected session / directory |
 | Esc | Close |
 
 Click the sidebar's `search…` box to filter recent sessions in place; click
-elsewhere or press Esc to leave search.
+elsewhere or press Esc to leave search. Click the **Sessions** heading to drive
+the list from the keyboard instead of the mouse (`↑`/`↓` to move, Enter to open,
+Ctrl-P to preview, Option-S/Option-D to pin, Ctrl-X to delete, Esc to leave). Pinned
+sessions appear ahead of the rest; the section lists every session and scrolls
+to fill the sidebar, so click **▾ hide** to collapse it when you need the room.
+Hovering a row while keyboard navigation is active selects it for the next
+shortcut. The full picker is one keystroke away.
 
 The full picker pages through your whole global session list (no fixed window)
 and indexes transcript text for every session in the background, showing
@@ -159,22 +182,25 @@ All variables are optional.
 | `SESH_GLOW` | first `glow` on `PATH` | optional Markdown preview renderer |
 | `SESH_OPENCODE` | `opencode` | opencode executable (resume / delete) |
 | `SESH_CACHE_DIR` | `~/.cache/sesh` | persistent search-index cache |
+| `SESH_PINS_FILE` | `${XDG_DATA_HOME:-~/.local/share}/sesh/pins.json` | shared persistent session/directory pins |
 
 ## How it works
 
-`bin/sesh-list.sh` is the only place that reads the opencode session store
-(SQLite: `session` / `message` / `part`). Each refresh extracts session metadata
-and text-only parts into a persistent per-session cache keyed on `time_updated`
-and part count, then atomically publishes a `snapshot.jsonl`. Every keystroke
-re-renders that snapshot with `jq` alone, so typing never starts competing
-database scans. Reasoning and tool payloads are never indexed or previewed, and
-session ids are validated before any SQL interpolation.
-
-Four flat scripts back the terminal UI — the picker (`sesh.sh`), snapshot
-builder (`sesh-list.sh`), preview renderer (`sesh-preview.sh`) and deleter
-(`sesh-delete.sh`) — with one worker process per picker serializing refreshes.
-The TUI panel (`tui/sesh-panel.tsx`) is a SolidJS OpenTUI plugin that talks to
-the opencode SDK over the same store.
+`bin/sesh-list.sh` is the only `bin/` script that reads the opencode session
+store (SQLite: `session` / `message` / `part`). Each refresh extracts session
+metadata and text-only parts into a persistent per-session cache keyed on
+`time_updated`, part count and the latest part timestamp, then atomically
+publishes a `snapshot.jsonl`. Every keystroke re-renders that snapshot with `jq`
+alone, so typing never starts competing database scans. Reasoning and tool
+payloads are never indexed or previewed, and session ids are validated before
+any SQL interpolation.
+
+Flat scripts back the terminal UI — the picker (`sesh.sh`), the refresh engine
+(`sesh-list.sh`, driven by a per-picker `sesh-refresh-worker.sh` that serializes
+scans), preview renderer (`sesh-preview.sh`), deleter (`sesh-delete.sh`) and
+shortcut help (`sesh-shortcuts.sh`). The TUI panel (`tui/sesh-panel.tsx`) is a
+SolidJS OpenTUI plugin that talks to the opencode SDK over the same store; the
+`sesh-list` agent tool reads it through `opencode db`.
 
 ## FAQ
 
@@ -202,10 +228,11 @@ guide; this project follows the [Code of Conduct](CODE_OF_CONDUCT.md). Run the
 checks before opening a PR:
 
 ```bash
-npm install
-npm test             # fixture-database regression suite
-npm run typecheck    # tsc over tui/ and opencode/
-npm run lint:sh      # bash -n on every script
+bun install
+bun run test         # fixture-database regression suite
+bun run test:picker  # PTY picker suite (needs fzf >= 0.73)
+bun run typecheck    # tsc over tui/ and opencode/
+bun run lint:sh      # bash -n on every script
 ```
 
 `HOME=/tmp/fakehome bash install.sh` smoke-tests the installer without touching

package/bin/sesh-delete.sh

@@ -1,12 +1,25 @@
 #!/usr/bin/env bash
-# Usage: sesh-delete.sh STATE_DIR SESSION_ID
+# Usage: sesh-delete.sh [--yes] STATE_DIR SESSION_ID
 # Ctrl-X deletes through the opencode CLI so its own safeguards apply.
-# There is no confirmation prompt, matching the Claude picker.
+# Deletion is irreversible, so this confirms first: an interactive run asks for
+# a y, and a non-interactive run must pass --yes rather than inherit whatever
+# stdin happens to be. Rows with no session id (headers, notices) stay silent
+# no-ops.
 set -euo pipefail
 
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-state_dir=${1:-}
-session_id=${2:-}
+assume_yes=0
+positional=()
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    --yes|-y) assume_yes=1 ;;
+    --help) echo "usage: ${0##*/} [--yes] STATE_DIR SESSION_ID"; exit 0 ;;
+    *) positional+=("$1") ;;
+  esac
+  shift
+done
+state_dir=${positional[0]:-}
+session_id=${positional[1]:-}
 snapshot="$state_dir/snapshot.jsonl"
 lock="$state_dir/refresh.lock"
 OPENCODE_BIN=${SESH_OPENCODE:-opencode}
@@ -40,6 +53,27 @@ acquire_lock() {
 [[ "$session_id" =~ ^ses_[A-Za-z0-9]+$ ]] || { echo "Invalid session identity."; pause; exit 0; }
 [ -n "$state_dir" ] && [ -f "$snapshot" ] || { echo "No session snapshot available."; pause; exit 0; }
 
+# Confirm before taking the lock: a human can sit on the prompt for as long as
+# they like without blocking the snapshot publisher. The row is re-checked
+# against the snapshot below, so a session that vanishes meanwhile still loses.
+if [ "$assume_yes" = 0 ]; then
+  if [ -t 0 ]; then
+    title=$("$JQ_BIN" -r --arg sid "$session_id" 'select(.sessionId == $sid) | .title // ""' "$snapshot" 2>/dev/null || true)
+    [ -n "$title" ] || title='untitled'
+    printf '%s' "Delete \"$title\" ($session_id)? [y/N] "
+    reply=''
+    IFS= read -r -n 1 reply || reply=''
+    printf '\n'
+    case "$reply" in
+      y|Y) ;;
+      *) echo "Cancelled; nothing was deleted."; pause; exit 0 ;;
+    esac
+  else
+    echo "Refusing to delete $session_id: pass --yes when stdin is not a terminal." >&2
+    exit 2
+  fi
+fi
+
 # Serialize this action with the sole snapshot publisher. A short collision
 # is safer than deleting against a moving snapshot.
 if ! acquire_lock; then

package/bin/sesh-list.sh

@@ -12,6 +12,7 @@ LIMIT=0
 LIMIT_SET=0
 SCOPE_SET=0
 REFRESH=0
+HEADER=0
 WAIT_LOCK=0
 TOGGLE_SCOPE=0
 INCLUDE_ARCHIVED=0
@@ -20,10 +21,11 @@ STATE_DIR=''
 QUERY=''
 SELECTED_ID=''
 SCOPE_CWD=''
-usage() { echo "usage: ${0##*/} [--refresh] [--wait-lock SECONDS] --state-dir DIR [--cwd] [--limit N] [--archived] [--toggle-scope] [--query TEXT]" >&2; }
+usage() { echo "usage: ${0##*/} [--refresh] [--header] [--wait-lock SECONDS] --state-dir DIR [--cwd] [--limit N] [--archived] [--toggle-scope] [--query TEXT]" >&2; }
 while [ "$#" -gt 0 ]; do
   case "$1" in
     --refresh) REFRESH=1 ;;
+    --header) HEADER=1 ;;
     --wait-lock) WAIT_LOCK=${2:-}; shift ;;
     --state-dir) STATE_DIR=${2:-}; shift ;;
     --cwd) SCOPE_CWD=$PWD; SCOPE_SET=1 ;;
@@ -113,38 +115,85 @@ atomic_text() {
 }
 set_status() { atomic_text "$STATUS" "$1"; }
 
+# One-line fzf --header: the effective scope, how many sessions the snapshot
+# holds and whether it is fresh. Reads published state only, so it stays cheap
+# enough to run on fzf's 3s poll without touching the database.
+header() {
+  local state='' count=0 scope='all dirs' line=''
+  [ -f "$STATUS" ] && state=$(cat "$STATUS" 2>/dev/null || true)
+  if [ -f "$SNAPSHOT" ]; then
+    count=$(wc -l < "$SNAPSHOT" 2>/dev/null || printf '0')
+    count=${count//[!0-9]/}
+    [ -n "$count" ] || count=0
+  fi
+  if [ -n "$SCOPE_CWD" ]; then
+    case "$SCOPE_CWD" in
+      "$HOME") scope='~' ;;
+      "$HOME"/*) scope="~${SCOPE_CWD#"$HOME"}" ;;
+      *) scope=$SCOPE_CWD ;;
+    esac
+  fi
+  line="${CYAN}${scope}${RESET}  ${GRAY}·${RESET}  ${GRAY}${count} sessions${RESET}"
+  [ "$INCLUDE_ARCHIVED" = 1 ] && line="${line}  ${GRAY}·${RESET}  ${YELLOW}archived shown${RESET}"
+  [ -n "$state" ] && [ "$state" != fresh ] && line="${line}  ${GRAY}·${RESET}  ${YELLOW}${state}${RESET}"
+  printf '%s' "$line"
+}
+
 render() {
-  local state=''
+  local state='' notice=''
   [ -f "$STATUS" ] && state=$(cat "$STATUS" 2>/dev/null || true)
+  # A non-actionable selection (a directory header, a stale notice) leaves a
+  # one-shot message here so the reopened picker explains itself instead of
+  # repainting the same list as if the key had been ignored.
+  if [ -f "$STATE_DIR/action-notice" ]; then
+    notice=$(cat "$STATE_DIR/action-notice" 2>/dev/null || true)
+    rm -f "$STATE_DIR/action-notice" 2>/dev/null || true
+  fi
   if [ ! -f "$SNAPSHOT" ]; then
+    [ -n "$notice" ] && printf '\t\tunknown\t%s%s%s\t\tnotice:action\n' "$YELLOW" "$notice" "$RESET"
     [ -n "$state" ] && [ "$state" != fresh ] && printf '\t\tunknown\t%s%s%s\t\tnotice:live-state\n' "$YELLOW" "$state" "$RESET"
     return 0
   fi
   {
+    [ -n "$notice" ] && printf '\t\tunknown\t%s%s%s\t\tnotice:action\n' "$YELLOW" "$notice" "$RESET"
     [ -n "$state" ] && [ "$state" != fresh ] && printf '\t\tunknown\t%s%s%s\t\tnotice:live-state\n' "$YELLOW" "$state" "$RESET"
-    "$JQ_BIN" -sr --arg green "$GREEN" --arg cyan "$CYAN" --arg gray "$GRAY" --arg magenta "$MAGENTA" --arg red "$RED" --arg bold "$BOLD" --arg yellow "$YELLOW" --arg reset "$RESET" --arg query "$QUERY" --arg home "$HOME" --arg selected "$SELECTED_ID" '
+    "$JQ_BIN" -sr --argjson pins "$("${BASH_SOURCE[0]%/*}/sesh-pins.sh" read)" --arg green "$GREEN" --arg cyan "$CYAN" --arg gray "$GRAY" --arg magenta "$MAGENTA" --arg red "$RED" --arg bold "$BOLD" --arg yellow "$YELLOW" --arg reset "$RESET" --arg query "$QUERY" --arg home "$HOME" --arg selected "$SELECTED_ID" '
       def ago($epoch):
         ((now - ($epoch | tonumber)) | floor) as $s
         | if $s < 60 then "now" elif $s < 3600 then "\($s / 60 | floor)m" elif $s < 86400 then "\($s / 3600 | floor)h" else "\($s / 86400 | floor)d" end;
       def homepath:
         . as $p | if $p == "" then "?" elif $p == $home then "~" elif ($home != "" and startswith($home + "/")) then "~" + .[($home|length):] else . end;
-      # Preserve a vanished selection as a non-actionable row with its original
-      # tracking key. Otherwise fzf falls back to a different session. Keep it
-      # until the user moves away; empty field 2 makes Enter/Ctrl-F/Ctrl-X no-ops.
+      # Non-actionable rows: an empty field 2 makes Enter/Ctrl-F/Ctrl-X no-ops,
+      # and the unique id keeps fzf from falling back to a neighbouring session.
+      def notice_row($msg; $id): (["", "", "unknown", ($yellow + $msg + $reset), "", $id] | @tsv);
+      # Preserve a vanished selection so the picker keeps its identity instead
+      # of jumping to a different session; keep it until the user moves away.
       (if ($selected | test("^ses_[A-Za-z0-9]+$")) and (any(.sessionId == $selected) | not)
-       then (["", "", "unknown", ($yellow + "Selected session is no longer available; choose another session" + $reset), "", $selected] | @tsv)
+       then notice_row("Selected session is no longer available; choose another session"; $selected)
        else empty end),
+      # An empty result set must say so: with the info line hidden and an empty
+      # preview, a filtered-to-nothing list is otherwise an indistinguishable
+      # blank screen.
       (($query | ascii_downcase) as $q
-      | map(select($q == "" or (.searchText | contains($q))))
-      | group_by(.cwd)
-      | map({cwd: .[0].cwd, updated: (map(.updatedEpoch) | max), items: (sort_by(.updatedEpoch) | reverse)})
-      | sort_by(.updated) | reverse
-      | .[] as $g
-      | (["", "", "unknown", ($magenta + ($g.cwd | homepath | gsub("[\u0000-\u001f\u007f-\u009f]";" ")) + $reset), $g.cwd, ("hdr:" + $g.cwd)] | @tsv),
+      | [.[] | select($q == "" or (.searchText | contains($q)))] as $matched
+      | (if ($matched | length) == 0
+         then notice_row(if $q == "" then "No sessions in this store" else "No sessions match \"" + $query + "\"" end; "notice:no-match")
+         else empty end),
+        ($matched
+       | group_by(.cwd)
+       | map({cwd: .[0].cwd, updated: (map(.updatedEpoch) | max),
+              pinDirectory: (.[0].cwd as $dir | $pins.directories | index($dir) != null),
+              pinSession: (any(.[]; .sessionId as $id | $pins.sessions | index($id) != null)),
+              items: (sort_by([(.sessionId as $id | $pins.sessions | index($id) != null), .updatedEpoch]) | reverse)})
+       | sort_by([.pinDirectory, .pinSession, .updated]) | reverse
+       | .[] as $g
+       | (["", "", "unknown", ($magenta + (if $g.pinDirectory then "★ " else "" end) + ($g.cwd | homepath | gsub("[\u0000-\u001f\u007f-\u009f]";" ")) + $reset), $g.cwd, ("hdr:" + $g.cwd)] | @tsv),
         ($g.items | to_entries[] | .key as $i | .value as $s
-         | (if $s.liveState == "running" then ($bold + $green) elif $s.agentId != "" and $s.agentState == "failed" then $red elif $s.agentId != "" then $cyan else $gray end) as $c
+         # Archived rows are opt-in and need to look like it; nothing else about
+         # a row is knowable here (live agent state is not exposed by opencode).
+         | (if $s.archived == 1 then $yellow else $gray end) as $c
          | ($gray + (if $i == (($g.items|length)-1) then "└" else "├" end) + $reset) as $branch
-         | [$s.agentId, $s.sessionId, $s.liveState, ($branch + " " + $c + ($s.title | gsub("[\u0000-\u001f\u007f-\u009f]";" ")) + $reset + "  " + $gray + ago($s.updatedEpoch) + $reset), $s.cwd, $s.sessionId] | @tsv))
+          | [$s.agentId, $s.sessionId, $s.liveState, ($branch + " " + $c + (if ($s.sessionId as $id | $pins.sessions | index($id)) != null then "★ " else "" end) + ($s.title | gsub("[\u0000-\u001f\u007f-\u009f]";" ")) + (if $s.archived == 1 then " · archived" else "" end) + $reset + "  " + $gray + ago($s.updatedEpoch) + $reset), $s.cwd, $s.sessionId] | @tsv)))
     ' "$SNAPSHOT"
   } || printf '\t\tunknown\t%sSnapshot rendering failed; retry refresh%s\t\tnotice:render-error\n' "$YELLOW" "$RESET"
 }
@@ -326,7 +375,7 @@ refresh() {
     done < "$records"
   fi
 
-  if ! "$JQ_BIN" -c --slurpfile hist "$historical" --arg scope "$SCOPE_CWD" --argjson limit "$LIMIT" --argjson archived "$INCLUDE_ARCHIVED" '
+  if ! "$JQ_BIN" -c --slurpfile hist "$historical" --argjson pins "$("${BASH_SOURCE[0]%/*}/sesh-pins.sh" read)" --arg scope "$SCOPE_CWD" --argjson limit "$LIMIT" --argjson archived "$INCLUDE_ARCHIVED" '
     .meta as $meta
     | ($hist | map({key: .sessionId, value: .}) | from_entries) as $histById
     | [$meta[]
@@ -336,11 +385,12 @@ refresh() {
        | . as $m | ($histById[$m.id] // {}) as $h
        | {sessionId: $m.id, malformedRecords: 0, agentId: "", agentState: "",
           liveState: "unknown", transcriptPath: "", source: "opencode",
+          archived: (if (($m.archived // 0) | tonumber) == 0 then 0 else 1 end),
           cwd: (if ($h.cwd // "") != "" then $h.cwd else $m.directory end),
           updatedEpoch: ($h.updatedEpoch // (($m.time_updated / 1000 | floor))),
           title: (if ($h.title // "") != "" then $h.title else ($m.title // "(untitled)") end)}
        | .searchText = ((.title | ascii_downcase) + " " + ($histById[.sessionId].fulltextLower // ""))]
-    | sort_by(.updatedEpoch) | reverse
+     | sort_by([(.cwd as $dir | $pins.directories | index($dir) != null), (.sessionId as $id | $pins.sessions | index($id) != null), .updatedEpoch]) | reverse
     | (if $limit == 0 then . else .[:$limit] end)[]
   ' "$cache_state" > "$out"; then
     set_status 'stale: snapshot construction failed; showing last good snapshot'
@@ -356,5 +406,6 @@ refresh() {
   fi
 }
 
+if [ "$HEADER" = 1 ]; then header; exit 0; fi
 if [ "$REFRESH" = 1 ] || [ "$TOGGLE_SCOPE" = 1 ]; then refresh; fi
 render