opencode-sesh 0.2.0 → 0.3.0

package/AGENTS.md

@@ -35,7 +35,12 @@ HOME=/tmp/fakehome bash install.sh   # installer smoke test (never touches ~/.co
 ## Layout
 
 - `bin/` — flat; no subdirs. Scripts resolve siblings from their own location.
-  Never hardcode install paths.
+  Never hardcode install paths. `sesh-waiting.sh` owns the needs-input query
+  (shared heuristic with the TUI sidebar copy, marked `NEEDS_INPUT_SQL` in
+  both); `sesh-prune.sh` archives stale sessions. Reads go through
+  `sqlite3 -readonly` (or `opencode db`); the single archive `UPDATE` in
+  `sesh-prune.sh` is the only sanctioned direct write (no archive endpoint
+  exists — deletes stay on `opencode session delete`).
 - `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
@@ -72,6 +77,11 @@ the schema below. Keystrokes never touch the database:
   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
@@ -125,10 +135,14 @@ Resume happens in place (`exec` after `cd` to the session's cwd).
 ## TUI panel (`tui/sesh-panel.tsx`)
 
 - **Sidebar:** `api.slots.register` on `sidebar_content` (append mode — native
-  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.
+  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.
+  Sessions waiting on the user (unanswered questions, stuck runs) pin a
+  **Needs input** group above the directories, with the count in the heading —
+  same `NEEDS_INPUT_SQL` heuristic as `bin/sesh-waiting.sh`.
 - **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;
@@ -168,12 +182,15 @@ Resume happens in place (`exec` after `cd` to the session's cwd).
   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.
+  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, and `n`/Esc/moving
-  cancels. The `y`/`n` layer is registered *only while armed*, so it can never
-  shadow the search box's typing.
+  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.

package/CHANGELOG.md

@@ -7,6 +7,67 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.3.0] - 2026-09-24
+
+### Added
+
+- Needs-input triage: sessions with unanswered agent questions or runs stuck
+  mid-tool pin a **Needs input** group above the sidebar directories (count in
+  the heading), and `sesh --needs-input [--json]` lists the same set in the
+  terminal. Detection reads the opencode store directly, so it works for every
+  session, not just ones owned by the current server.
+- `sesh prune [--older-than 30d] [--dry-run] [--yes] [--delete]` archives stale
+  sessions so the list stays triageable. Pinned sessions, sessions waiting on
+  you, fork children and already-archived sessions are never touched;
+  archiving is reversible, `--delete` hard-deletes through the opencode CLI,
+  and non-TTY runs need `--yes`.
+## [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
@@ -178,7 +239,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.2.0...HEAD
+[Unreleased]: https://github.com/ozandogrultan/opencode-sesh/compare/v0.3.0...HEAD
+[0.3.0]: https://github.com/ozandogrultan/opencode-sesh/compare/v0.2.1...v0.3.0
+[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

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.
@@ -112,7 +115,8 @@ 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 (asks to confirm) |
 | Escape | Exit |
@@ -123,7 +127,15 @@ 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`,
-`--json` (with `--print`, emit JSON), `--query TEXT`, `--check`.
+`--json` (with `--print`, emit JSON), `--query TEXT`, `--check`,
+`--needs-input` (list sessions waiting on you instead of opening the picker).
+
+`sesh prune [--older-than 30d] [--dry-run] [--yes] [--delete]` archives stale
+sessions (not updated within the threshold) so the list stays triageable.
+Pinned sessions, sessions waiting on you, fork children and already-archived
+sessions are never touched; archiving is reversible, while `--delete`
+hard-deletes through `opencode session delete`. Without `--dry-run`, a TTY run
+confirms first and a non-TTY run needs `--yes`.
 
 Because `--print` just emits the id and directory, `sesh` doubles as a scriptable
 session lookup:
@@ -144,18 +156,25 @@ non-interactive `sesh-delete.sh` refuses unless given `--yes`.
 | `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. 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.
+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.
+Sessions waiting on you (unanswered agent questions, runs stuck mid-tool) pin
+themselves to a **Needs input** group above the directories, with the count in
+the heading; `sesh --needs-input` lists the same set in the terminal.
+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
@@ -174,6 +193,7 @@ 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
 

package/bin/sesh

@@ -22,5 +22,9 @@ case ${1:-} in
     shift
     exec bash "$SCRIPT_DIR/../install.sh" --uninstall "$@"
     ;;
+  prune)
+    shift
+    exec bash "$SCRIPT_DIR/sesh-prune.sh" "$@"
+    ;;
 esac
 exec "$SCRIPT_DIR/sesh.sh" "$@"

package/bin/sesh-list.sh

@@ -157,7 +157,7 @@ render() {
   {
     [ -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;
@@ -180,17 +180,20 @@ render() {
          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),
+       | 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
          # 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]";" ")) + (if $s.archived == 1 then " · archived" else "" end) + $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"
 }
@@ -372,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[]
@@ -387,7 +390,7 @@ refresh() {
           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'

package/bin/sesh-pins.sh

@@ -0,0 +1,55 @@
+#!/usr/bin/env bash
+# Persistent pins shared by the fzf picker and the opencode TUI plugin.
+set -euo pipefail
+umask 077
+
+PINS_FILE=${SESH_PINS_FILE:-"${XDG_DATA_HOME:-$HOME/.local/share}/sesh/pins.json"}
+JQ_BIN=${SESH_JQ:-jq}
+empty='{"sessions":[],"directories":[]}'
+action=${1:-}
+value=${2:-}
+
+read_pins() {
+  if [ -f "$PINS_FILE" ]; then
+    local pins=''
+    pins=$("$JQ_BIN" -c 'select(type == "object") | {sessions: ((.sessions // []) | map(select(type == "string"))), directories: ((.directories // []) | map(select(type == "string")))}' "$PINS_FILE" 2>/dev/null) || pins=''
+    printf '%s\n' "${pins:-$empty}"
+  else
+    printf '%s\n' "$empty"
+  fi
+}
+
+case "$action" in
+  read) read_pins; exit 0 ;;
+  toggle-session)
+    [[ "$value" =~ ^ses_[A-Za-z0-9]+$ ]] || exit 2
+    field=sessions ;;
+  toggle-directory)
+    [[ "$value" == /* && "$value" != *$'\n'* ]] || exit 2
+    field=directories ;;
+  *) echo 'usage: sesh-pins.sh read|toggle-session ID|toggle-directory PATH' >&2; exit 2 ;;
+esac
+
+mkdir -p "$(dirname "$PINS_FILE")"
+lock="$PINS_FILE.lock"
+for ((attempt = 0; attempt < 50; attempt++)); do
+  if mkdir "$lock" 2>/dev/null; then printf '%s\n' "$$" > "$lock/pid"; break; fi
+  owner=''
+  [ ! -f "$lock/pid" ] || owner=$(cat "$lock/pid" 2>/dev/null || true)
+  if [[ "$owner" =~ ^[0-9]+$ ]] && ! kill -0 "$owner" 2>/dev/null; then
+    rm -f "$lock/pid" 2>/dev/null || true
+    rmdir "$lock" 2>/dev/null || true
+  fi
+  [ "$attempt" -lt 49 ] || { echo 'sesh: pins are busy; try again' >&2; exit 1; }
+  sleep 0.1
+done
+tmp=''
+cleanup() { [ -z "$tmp" ] || rm -f "$tmp"; rm -f "$lock/pid"; rmdir "$lock" 2>/dev/null || true; }
+trap cleanup EXIT
+tmp=$(mktemp "${PINS_FILE}.XXXXXX")
+read_pins | "$JQ_BIN" -c --arg field "$field" --arg value "$value" '
+  .[$field] |= (if index($value) then map(select(. != $value)) else . + [$value] end)
+' > "$tmp"
+mv -f "$tmp" "$PINS_FILE"
+tmp=''
+read_pins

package/bin/sesh-prune.sh

@@ -0,0 +1,175 @@
+#!/usr/bin/env bash
+# Archive (or, with --delete, hard-delete) stale sessions: not updated within
+# the threshold, never pinned, never waiting on the user, never already
+# archived, never a fork child.
+#
+# Archive is the default because it is reversible; hard deletes go through
+# `opencode session delete` so its own safeguards apply. The archive itself
+# is a single atomic UPDATE through the same sqlite3-or-`opencode db` read
+# path the list commands use — there is no archive endpoint in the opencode
+# API or CLI, so a direct write is the only route (deletes stay on the CLI).
+#
+# Usage: sesh-prune.sh [--older-than 30d] [--dry-run] [--yes] [--delete]
+#   --older-than Nd|Nh|Nw (bare N means days; default 30d)
+#   --dry-run lists candidates and changes nothing
+#   without --dry-run, a TTY run confirms first; a non-TTY run needs --yes
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+OPENCODE_BIN=${SESH_OPENCODE:-opencode}
+
+older_than=30d
+dry_run=0
+assume_yes=0
+hard_delete=0
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    --older-than) older_than=${2:-}; shift ;;
+    --older-than=*) older_than=${1#--older-than=} ;;
+    --dry-run) dry_run=1 ;;
+    --yes|-y) assume_yes=1 ;;
+    --delete) hard_delete=1 ;;
+    --help) echo "usage: ${0##*/} [--older-than 30d] [--dry-run] [--yes] [--delete]"; exit 0 ;;
+    *) echo "unknown option: $1" >&2; exit 2 ;;
+  esac
+  shift
+done
+
+if [[ "$older_than" =~ ^([0-9]+)([dhw])?$ ]]; then
+  amount=$((10#${BASH_REMATCH[1]}))
+  unit=${BASH_REMATCH[2]:-d}
+  [ "$amount" -gt 0 ] || { echo "--older-than must be positive" >&2; exit 2; }
+else
+  echo "--older-than takes Nd, Nh or Nw (bare N means days)" >&2
+  exit 2
+fi
+case "$unit" in
+  h) threshold_ms=$((amount * 3600000)) ;;
+  d) threshold_ms=$((amount * 86400000)) ;;
+  w) threshold_ms=$((amount * 604800000)) ;;
+esac
+NOW_MS=$(python3 -c 'import time; print(int(time.time() * 1000))' 2>/dev/null || echo "$(( $(date +%s) * 1000 ))")
+CUTOFF=$((NOW_MS - threshold_ms))
+
+resolve_db() {
+  if [ -n "${SESH_DB:-}" ]; then printf '%s\n' "$SESH_DB"; return 0; fi
+  local from_cli=''
+  if command -v "$OPENCODE_BIN" >/dev/null 2>&1; then
+    from_cli=$("$OPENCODE_BIN" db path 2>/dev/null || true)
+  fi
+  if [ -n "$from_cli" ] && [ -f "$from_cli" ]; then printf '%s\n' "$from_cli"; return 0; fi
+  if [ -f "$HOME/.local/share/opencode/opencode.db" ]; then printf '%s\n' "$HOME/.local/share/opencode/opencode.db"; return 0; fi
+  return 1
+}
+
+SQLITE_BIN=''
+if [ -n "${SESH_SQLITE:-}" ]; then
+  SQLITE_BIN=$SESH_SQLITE
+elif command -v sqlite3 >/dev/null 2>&1; then
+  SQLITE_BIN=sqlite3
+fi
+
+DB_PATH=$(resolve_db) || { echo 'sesh: session database unavailable' >&2; exit 1; }
+[ -f "$DB_PATH" ] || { echo 'sesh: session database unavailable' >&2; exit 1; }
+
+if [ -n "$SQLITE_BIN" ]; then
+  query() { "$SQLITE_BIN" -json -readonly "$DB_PATH" "$1"; }
+  write_db() { "$SQLITE_BIN" "$DB_PATH" "$1"; }
+else
+  command -v "$OPENCODE_BIN" >/dev/null 2>&1 || { echo 'sesh: neither sqlite3 nor opencode is available' >&2; exit 1; }
+  query() { "$OPENCODE_BIN" db "$1" --format json; }
+  write_db() { "$OPENCODE_BIN" db "$1" --format json > /dev/null; }
+fi
+
+JQ_BIN=${SESH_JQ:-$(command -v jq || true)}
+[ -n "$JQ_BIN" ] || { echo 'sesh: jq is required' >&2; exit 1; }
+
+CANDIDATES=$(query "SELECT id, directory, title, time_updated AS updated FROM session WHERE time_updated < $CUTOFF AND COALESCE(time_archived, 0) = 0 AND parent_id IS NULL ORDER BY time_updated ASC;")
+# sqlite3 -json prints nothing (not []) when no rows match.
+[ -n "$CANDIDATES" ] || CANDIDATES='[]'
+PINS=$("$SCRIPT_DIR/sesh-pins.sh" read 2>/dev/null || printf '{"sessions":[],"directories":[]}')
+WAITING_IDS=$(bash "$SCRIPT_DIR/sesh-waiting.sh" --json 2>/dev/null | "$JQ_BIN" -r '.[].id' || true)
+[ -n "$WAITING_IDS" ] || WAITING_IDS='__none__'
+
+ELIGIBLE=$(printf '%s' "$CANDIDATES" | "$JQ_BIN" -c --slurpfile _pins <(printf '%s' "$PINS") --arg waiting "$WAITING_IDS" '
+  ($waiting | split("\n") | map(select(. != "" and . != "__none__"))) as $waiting_ids
+  | [ .[]
+      | .id as $id
+      | .directory as $dir
+      | select($id | test("^ses_[A-Za-z0-9]+$"))
+      | select(([$_pins[0].sessions[]] | index($id) | not))
+      | select(([$_pins[0].directories[]] | index($dir) | not))
+      | select(($waiting_ids | index($id) | not))
+    ]
+')
+COUNT=$(printf '%s' "$ELIGIBLE" | "$JQ_BIN" -r 'length')
+VERB=Archive
+[ "$hard_delete" = 0 ] || VERB=Delete
+
+if [ "$COUNT" = 0 ]; then
+  echo "Nothing to prune older than $older_than."
+  exit 0
+fi
+
+printf '%s' "$ELIGIBLE" | "$JQ_BIN" -r --argjson now "$NOW_MS" '
+  def ago(ms): ((($now - ms) / 1000) | floor) as $s
+    | if $s < 3600 then "\($s / 60 | floor)m"
+      elif $s < 86400 then "\($s / 3600 | floor)h"
+      else "\($s / 86400 | floor)d" end;
+  .[] | "\(.id)\t\(.title // "untitled")\t\(ago(.updated)) ago"
+' | while IFS=$'\t' read -r id title age; do
+  printf '%s  %s  \033[90m%s\033[0m\n' "$id" "$title" "$age"
+done
+
+if [ "$dry_run" = 1 ]; then
+  printf '%s %s session(s) older than %s (--dry-run: nothing changed).\n' "$VERB" "$COUNT" "$older_than" >&2
+  exit 0
+fi
+
+if [ "$assume_yes" = 0 ]; then
+  if [ -t 0 ]; then
+    printf '%s' "$VERB $COUNT session(s) older than $older_than? [y/N] "
+    reply=''
+    IFS= read -r -n 1 reply || reply=''
+    printf '\n'
+    case "$reply" in
+      y|Y) ;;
+      *) echo 'Cancelled; nothing was changed.'; exit 0 ;;
+    esac
+  else
+    echo "Refusing to prune $COUNT session(s): pass --yes when stdin is not a terminal." >&2
+    exit 2
+  fi
+fi
+
+if [ "$hard_delete" = 0 ]; then
+  IDS=$(printf '%s' "$ELIGIBLE" | "$JQ_BIN" -r '.[].id')
+  IN_LIST=''
+  for id in $IDS; do
+    case "$id" in
+      ses_[A-Za-z0-9]*) IN_LIST="$IN_LIST'$id'," ;;
+      *) echo "Refusing: unexpected session id shape." >&2; exit 1 ;;
+    esac
+  done
+  IN_LIST=${IN_LIST%,}
+  write_db "UPDATE session SET time_archived = $NOW_MS WHERE id IN ($IN_LIST);"
+  echo "Archived $COUNT session(s) older than $older_than."
+else
+  command -v "$OPENCODE_BIN" >/dev/null 2>&1 || { echo 'sesh: opencode executable is unavailable for deletes.' >&2; exit 1; }
+  failed=0
+  done_count=0
+  for id in $(printf '%s' "$ELIGIBLE" | "$JQ_BIN" -r '.[].id'); do
+    case "$id" in
+      ses_[A-Za-z0-9]*) ;;
+      *) echo "Refusing: unexpected session id shape." >&2; exit 1 ;;
+    esac
+    if "$OPENCODE_BIN" session delete "$id" >/dev/null 2>&1; then
+      done_count=$((done_count + 1))
+    else
+      echo "Could not delete $id." >&2
+      failed=$((failed + 1))
+    fi
+  done
+  echo "Deleted $done_count session(s) older than $older_than."
+  [ "$failed" = 0 ] || exit 1
+fi

package/bin/sesh-shortcuts.sh

@@ -7,7 +7,9 @@ sesh shortcuts
   Enter             Resume the selected session here
   Ctrl-F            Resume the selected session as a fork
   Ctrl-G            Toggle current-directory scope / all sessions
-  Space             Toggle transcript preview
+  Ctrl-P            Toggle transcript preview
+  Option-S          Pin / unpin selected session
+  Option-D          Pin / unpin selected directory
   ?                 Toggle this help
   Ctrl-X            Delete the selected session (asks to confirm)
   Escape            Exit the picker

package/bin/sesh-waiting.sh

@@ -0,0 +1,127 @@
+#!/usr/bin/env bash
+# List sessions waiting on the user: unanswered agent questions and runs
+# stuck with a tool still marked running. Server-independent: it reads the
+# opencode SQLite store directly, so it sees every session — not just ones
+# owned by a running TUI server, whose in-memory permission/question state
+# is invisible cross-project.
+#
+# A session waits when it is not archived, is not a fork child, and either
+#   - has a `question` tool part that never completed with no later user
+#     message in the same session (awaiting an answer, errored included), or
+#   - has a `tool` part still marked `running` older than STUCK_AFTER_MS
+#     (awaiting approval, or orphaned by a dead server).
+#
+# Usage: sesh-waiting.sh [--json]
+#   default prints a human table; --json prints [{id,reason,title,directory,updated}]
+# Keep NEEDS_INPUT_SQL in sync with the TUI sidebar copy in tui/sesh-panel.tsx.
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+OPENCODE_BIN=${SESH_OPENCODE:-opencode}
+JSON=0
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    --json) JSON=1 ;;
+    --help) echo "usage: ${0##*/} [--json]"; exit 0 ;;
+    *) echo "unknown option: $1" >&2; exit 2 ;;
+  esac
+  shift
+done
+
+resolve_db() {
+  if [ -n "${SESH_DB:-}" ]; then printf '%s\n' "$SESH_DB"; return 0; fi
+  local from_cli=''
+  if command -v "$OPENCODE_BIN" >/dev/null 2>&1; then
+    from_cli=$("$OPENCODE_BIN" db path 2>/dev/null || true)
+  fi
+  if [ -n "$from_cli" ] && [ -f "$from_cli" ]; then printf '%s\n' "$from_cli"; return 0; fi
+  if [ -f "$HOME/.local/share/opencode/opencode.db" ]; then printf '%s\n' "$HOME/.local/share/opencode/opencode.db"; return 0; fi
+  return 1
+}
+
+SQLITE_BIN=''
+if [ -n "${SESH_SQLITE:-}" ]; then
+  SQLITE_BIN=$SESH_SQLITE
+elif command -v sqlite3 >/dev/null 2>&1; then
+  SQLITE_BIN=sqlite3
+fi
+
+DB_PATH=$(resolve_db) || { echo 'sesh: session database unavailable' >&2; exit 1; }
+[ -f "$DB_PATH" ] || { echo 'sesh: session database unavailable' >&2; exit 1; }
+
+NOW_MS=$(python3 -c 'import time; print(int(time.time() * 1000))' 2>/dev/null || date +%s000)
+STUCK_BEFORE=$((NOW_MS - 600000))
+
+# NEEDS_INPUT_SQL (shared heuristic — keep in sync with tui/sesh-panel.tsx).
+read -r -d '' QUERY <<SQL || true
+SELECT s.id AS id, s.directory AS directory, s.title AS title, s.time_updated AS updated,
+  CASE WHEN EXISTS (
+    SELECT 1 FROM part p
+    WHERE p.session_id = s.id
+      AND json_extract(p.data, '\$.type') = 'tool'
+      AND json_extract(p.data, '\$.tool') = 'question'
+      AND COALESCE(json_extract(p.data, '\$.state.status'), 'pending') != 'completed'
+      AND NOT EXISTS (
+        SELECT 1 FROM message m
+        WHERE m.session_id = s.id
+          AND json_extract(m.data, '\$.role') = 'user'
+          AND m.time_created > p.time_created)
+  ) THEN 'question' ELSE 'stuck' END AS reason
+FROM session s
+WHERE COALESCE(s.time_archived, 0) = 0
+  AND s.parent_id IS NULL
+  AND (EXISTS (
+    SELECT 1 FROM part p
+    WHERE p.session_id = s.id
+      AND json_extract(p.data, '\$.type') = 'tool'
+      AND json_extract(p.data, '\$.tool') = 'question'
+      AND COALESCE(json_extract(p.data, '\$.state.status'), 'pending') != 'completed'
+      AND NOT EXISTS (
+        SELECT 1 FROM message m
+        WHERE m.session_id = s.id
+          AND json_extract(m.data, '\$.role') = 'user'
+          AND m.time_created > p.time_created)
+  ) OR EXISTS (
+    SELECT 1 FROM part p2
+    WHERE p2.session_id = s.id
+      AND json_extract(p2.data, '\$.type') = 'tool'
+      AND json_extract(p2.data, '\$.state.status') = 'running'
+      AND p2.time_created < $STUCK_BEFORE))
+ORDER BY s.time_updated DESC;
+SQL
+
+if [ -n "$SQLITE_BIN" ]; then
+  # Read-only: sesh never writes the store on this path (archive writes go
+  # through `opencode db`, hard deletes through `opencode session delete`).
+  ROWS=$("$SQLITE_BIN" -json -readonly "$DB_PATH" "$QUERY")
+else
+  command -v "$OPENCODE_BIN" >/dev/null 2>&1 || { echo 'sesh: neither sqlite3 nor opencode is available' >&2; exit 1; }
+  ROWS=$("$OPENCODE_BIN" db "$QUERY" --format json)
+fi
+
+# sqlite3 -json prints nothing (not []) when no rows match.
+[ -n "$ROWS" ] || ROWS='[]'
+
+if [ "$JSON" = 1 ]; then
+  printf '%s\n' "$ROWS"
+  exit 0
+fi
+
+JQ_BIN=${SESH_JQ:-$(command -v jq || true)}
+[ -n "$JQ_BIN" ] || { echo 'sesh: jq is required for the table view (or use --json)' >&2; exit 1; }
+COUNT=$(printf '%s' "$ROWS" | "$JQ_BIN" -r 'length')
+if [ "$COUNT" = 0 ]; then
+  echo 'No sessions are waiting on you.'
+  exit 0
+fi
+printf '%s' "$ROWS" | "$JQ_BIN" -r --argjson now "$NOW_MS" '
+  def ago(ms): ((($now - ms) / 1000) | 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 reason(t): if t == "question" then "awaiting answer" else "run stuck" end;
+  .[] | "\(.id)\t\(reason(.reason))\t\(.title // "untitled")\t\(.directory)\t\(ago(.updated)) ago"
+' | while IFS=$'\t' read -r id reason title dir age; do
+  printf '%s  \033[33m%s\033[0m  %s  \033[90m%s · %s\033[0m\n' "$id" "$reason" "$title" "$dir" "$age"
+done