opencode-sesh 0.1.7 → 0.2.0

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,13 @@ 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).
 
 **Output contract** (TSV, 6 fields):
 `agentId  sessionId  liveState  display  cwd  trackingId`. `display` is the only
@@ -69,8 +80,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 +102,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 +115,37 @@ 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 the newest `SIDEBAR_LIMIT` unarchived sessions
+  with the current one highlighted, polled every 15 s; space previews a row and
+  ctrl+x deletes one (armed, then confirmed). Anything bulkier belongs to the
+  picker.
 - **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 +164,32 @@ 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, and the section is capped at `SIDEBAR_LIMIT` (`… N more · ctrl+o for
+  all` is the escape hatch) — it must stay a glanceable recent list.
+- **Delete in the TUI is two-step.** The first `ctrl+x` arms `pendingDelete`,
+  the second (or `y`, or Enter in the picker footer) commits, and `n`/Esc/moving
+  cancels. 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,43 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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 +178,8 @@ 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.0...HEAD
+[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

@@ -58,7 +58,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
@@ -113,20 +114,28 @@ bash install.sh --uninstall   # from source
 | Ctrl-G | Toggle current-directory scope / all sessions |
 | Space (empty query) | 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 |
@@ -137,10 +146,16 @@ read -r id cwd < <(sesh --print --query "auth")
 | `↑`/`↓`, `PgUp`/`PgDn`, `Home`/`End` | Move the selection |
 | Space | 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 |
 | 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,
+Space to preview, Ctrl-X to delete, Esc to leave). The sidebar shows the 15 most
+recent sessions — 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
@@ -162,19 +177,21 @@ All variables are optional.
 
 ## 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 +219,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,14 +115,47 @@ 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" '
       def ago($epoch):
@@ -128,23 +163,34 @@ render() {
         | 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))))
+      | [.[] | 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), 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),
         ($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 + ($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"
 }
@@ -336,6 +382,7 @@ 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)}
@@ -356,5 +403,6 @@ refresh() {
   fi
 }
 
+if [ "$HEADER" = 1 ]; then header; exit 0; fi
 if [ "$REFRESH" = 1 ] || [ "$TOGGLE_SCOPE" = 1 ]; then refresh; fi
 render

package/bin/sesh-shortcuts.sh

@@ -9,9 +9,10 @@ sesh shortcuts
   Ctrl-G            Toggle current-directory scope / all sessions
   Space             Toggle transcript preview
   ?                 Toggle this help
-  Ctrl-X            Delete the selected session
+  Ctrl-X            Delete the selected session (asks to confirm)
   Escape            Exit the picker
 
 Flags: --cwd (current directory only), --limit N (default: all),
-       --archived (include archived), --print (print id instead of resuming)
+       --archived (include archived), --print (print id instead of resuming),
+       --json (with --print, emit JSON)
 HELP

package/bin/sesh.sh

@@ -59,6 +59,7 @@ picker_limit=0
 picker_archived=0
 picker_print=0
 picker_fork=0
+picker_json=0
 picker_query=''
 while [ "$#" -gt 0 ]; do
   case "$1" in
@@ -67,12 +68,14 @@ while [ "$#" -gt 0 ]; do
     --archived) picker_archived=1 ;;
     --print) picker_print=1 ;;
     --fork) picker_fork=1 ;;
+    --json) picker_json=1 ;;
     --query) picker_query=${2:-}; shift ;;
     *) echo "unknown option: $1" >&2; exit 2 ;;
   esac
   shift
 done
 case "$picker_limit" in ''|*[!0-9]*) echo "--limit must be a non-negative integer" >&2; exit 2;; esac
+[ "$picker_json" = 0 ] || [ "$picker_print" = 1 ] || { echo '--json requires --print' >&2; exit 2; }
 
 shell_quote() {
   # Quotes fixed command arguments embedded in fzf's shell action strings.
@@ -106,6 +109,12 @@ trap cleanup EXIT
 trap 'exit 130' HUP INT TERM
 
 cache_cmd="$q_worker render --state-dir $q_state --query {q} --selected-id {6}"
+# fzf's --header is the only place a persistent scope/status line can live
+# without becoming a selectable row, so it is refreshed by transform-header on
+# start, on the 3s poll and after either action that can change it. Order
+# matters: a transform-* action placed AFTER reload/reload-sync in the chain
+# leaves the list empty, so the header is always transformed first.
+header_cmd="$q_list --header --state-dir $q_state"
 preview_cmd="if [ -f $q_state/help ]; then $q_shortcuts; else $q_preview $q_state {2}; fi"
 help_bind="?:transform:[ -z {q} ] && ( [ -f $q_state/help ] && rm -f $q_state/help && echo hide-preview || ( : > $q_state/help && echo show-preview+refresh-preview ) ) || echo 'put(?)'"
 toggle_cmd="$q_list --toggle-scope --state-dir $q_state >/dev/null"
@@ -113,16 +122,18 @@ delete_cmd="$q_delete $q_state {2}"
 
 query="$picker_query"
 while :; do
-selection=''
-set +e
-selection=$(FZF_DEFAULT_COMMAND='printf ""' FZF_DEFAULT_OPTS='' FZF_DEFAULT_OPTS_FILE='' "$SESH_FZF" --print-query --expect=ctrl-f --query="$query" --ansi --delimiter=$'\t' --with-nth=4 --track --id-nth=6 --disabled --layout=reverse --info=hidden --prompt='❯ ' \
-  --preview="$preview_cmd" --preview-window='right,50%,wrap,hidden' \
-  --bind='space:transform:[ -z {q} ] && echo toggle-preview || echo "put( )"' \
-  --bind="$help_bind" \
-  --bind="ctrl-x:execute($delete_cmd)+reload($cache_cmd)" \
-  --bind="ctrl-g:execute($toggle_cmd)+reload($cache_cmd)" \
-  --bind="change:reload:$cache_cmd" \
-  --bind="start,every(3):reload-sync:$cache_cmd")
+  header_line=$("$SCRIPT_DIR/sesh-list.sh" --header --state-dir "$state_dir" 2>/dev/null || true)
+  selection=''
+  set +e
+  selection=$(FZF_DEFAULT_COMMAND='printf ""' FZF_DEFAULT_OPTS='' FZF_DEFAULT_OPTS_FILE='' "$SESH_FZF" --print-query --expect=ctrl-f --query="$query" --ansi --delimiter=$'\t' --with-nth=4 --track --id-nth=6 --disabled --layout=reverse --info=hidden --prompt='❯ ' \
+    --preview="$preview_cmd" --preview-window='right,50%,wrap,hidden' \
+    --header-first --header="$header_line" \
+    --bind='space:transform:[ -z {q} ] && echo toggle-preview || echo "put( )"' \
+    --bind="$help_bind" \
+    --bind="ctrl-x:execute($delete_cmd)+transform-header($header_cmd)+reload($cache_cmd)" \
+    --bind="ctrl-g:execute($toggle_cmd)+transform-header($header_cmd)+reload($cache_cmd)" \
+    --bind="change:reload:$cache_cmd" \
+    --bind="start,every(3):transform-header($header_cmd)+reload-sync:$cache_cmd")
 status=$?
 set -e
 case "$status" in 0) ;; 1|130) exit 0;; *) echo "sesh: picker failed ($status)" >&2; exit "$status";; esac
@@ -132,13 +143,30 @@ selection=${selection#*$'\n'}
 key=${selection%%$'\n'*}
 selection=${selection#*$'\n'}
 session_id=$(printf '%s\n' "$selection" | cut -f2)
-[ -n "$session_id" ] || continue
+tracking_id=$(printf '%s\n' "$selection" | cut -f6)
+if [ -z "$session_id" ]; then
+  # Enter/Ctrl-F on a directory header or a notice row. Leave a one-shot
+  # message for the reopened picker so the keypress visibly did something,
+  # and keep the query so the user has not lost their place.
+  case "$tracking_id" in
+    hdr:*) printf '%s' 'That row is a directory header, not a session.' > "$state_dir/action-notice" ;;
+    notice:*) printf '%s' 'That row is a notice, not a session; pick a session row.' > "$state_dir/action-notice" ;;
+  esac
+  continue
+fi
 # Dispatch queues a new worker scan and waits for that exact serialized poll.
 # It cannot accept a previously fresh status while the worker owns its lock.
-poll_target=$("$SCRIPT_DIR/sesh-refresh-worker.sh" request --state-dir "$state_dir")
-if ! "$SCRIPT_DIR/sesh-refresh-worker.sh" wait --state-dir "$state_dir" --target "$poll_target" --timeout 12; then
-  echo 'Live state unavailable; retry selection after refresh' >&2
-  continue
+# A --print lookup reads the published snapshot, so it skips the wait entirely
+# and stays usable from scripts without paying a rescan.
+if [ "$picker_print" = 0 ]; then
+  printf 'sesh: refreshing session state…' >&2
+  poll_target=$("$SCRIPT_DIR/sesh-refresh-worker.sh" request --state-dir "$state_dir")
+  if ! "$SCRIPT_DIR/sesh-refresh-worker.sh" wait --state-dir "$state_dir" --target "$poll_target" --timeout 12; then
+    printf '\r\033[K' >&2
+    echo 'sesh: session state unavailable; selection cancelled, retry after refresh' >&2
+    continue
+  fi
+  printf '\r\033[K' >&2
 fi
 record=$("$SESH_JQ" -c --arg sid "$session_id" 'select(.sessionId==$sid)' "$state_dir/snapshot.jsonl")
 [ -n "$record" ] || continue
@@ -146,7 +174,10 @@ cwd=$(printf '%s' "$record" | "$SESH_JQ" -r '.cwd')
 fork=0
 if [ "$picker_fork" = 1 ] || [ "$key" = ctrl-f ]; then fork=1; fi
 if [ "$picker_print" = 1 ]; then
-  if [ "$fork" = 1 ]; then printf '%s\t%s\tfork\n' "$session_id" "$cwd"; else printf '%s\t%s\n' "$session_id" "$cwd"; fi
+  if [ "$picker_json" = 1 ]; then
+    "$SESH_JQ" -cn --arg sessionId "$session_id" --arg cwd "$cwd" --argjson fork "$fork" \
+      '{sessionId: $sessionId, cwd: $cwd, fork: ($fork == 1)}'
+  elif [ "$fork" = 1 ]; then printf '%s\t%s\tfork\n' "$session_id" "$cwd"; else printf '%s\t%s\n' "$session_id" "$cwd"; fi
   exit 0
 fi
 if [ ! -d "$cwd" ]; then