opencode-sesh 0.6.0 → 0.7.0

package/AGENTS.md

@@ -147,17 +147,24 @@ Resume happens in place (`exec` after `cd` to the session's cwd).
   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`.
-- **Presence / click-to-focus (cmux-only).** Each sidebar pane heartbeats
-  `{workspace, surface, updated}` to the session file
-  `${XDG_DATA_HOME:-~/.local/share}/sesh/presence/<sessionId>.json` every poll,
-  but only when `CMUX_WORKSPACE_ID` is set; without it nothing is written and a
-  click always navigates locally. Opening a session reads that file and, when a
-  *fresh* (≤45 s), *foreign* workspace claims it, runs
-  `cmux workspace select <id>` instead of `api.route.navigate`. One file per
-  session means concurrent panes never share a file; writes are tmp+rename and
-  stale files are swept on each poll. A crashed pane falls through to a local
-  open after the TTL. The dispatch lives in the sidebar only — the picker and
-  home list always open locally.
+- **cmux bridge (cmux-only, opt-out by absence).** When `CMUX_WORKSPACE_ID` is
+  set the sidebar talks to the `cmux` CLI; outside cmux no cmux call is made and
+  every click opens locally. Two behaviors, both keyed on cmux's *own* per-
+  surface resume record (`cmux surface resume show` → `restore_record.
+  checkpoint_id`), not on anything sesh writes:
+  - **Click-to-focus.** `pickFocusWorkspace` (pure, covered by `tests/tui.mjs`)
+    scans `cmux tree --json --all` plus each surface's checkpoint and, when
+    another workspace runs the clicked session, runs
+    `cmux workspace select <ref>` instead of `api.route.navigate`. The caller's
+    own surface/workspace never match (a same-workspace focus is a no-op, so it
+    opens locally). Works for background agents and older panels too.
+  - **Workspace naming.** The poll renames this workspace to the current
+    session title (`cmux workspace rename <id> --title …`), skipping titles that
+    are still the pre-first-turn placeholder. `bin/sesh-cmux-sync.sh` does the
+    same for every workspace at once. The session title is the source of truth;
+    a manual cmux rename is overwritten on the next session-title change.
+  These are the only cmux calls in the panel; keep them behind the
+  `CMUX_WORKSPACE_ID` guard.
 - **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;

package/CHANGELOG.md

@@ -7,6 +7,21 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.7.0] - 2026-09-24
+
+### Added
+
+- The sidebar renames its cmux workspace to the current session title, so the
+  workspace list matches the session. Pre-first-turn placeholder titles
+  (`New session - …`) are never pushed.
+- `sesh cmux-sync [--dry-run] [--json]` names every cmux workspace after the
+  opencode session it is running, using cmux's own per-surface resume record.
+
+### Changed
+
+- Click-to-focus now reads cmux's per-surface resume record (`checkpoint_id`)
+  instead of heartbeat files, so it also finds background agents and panes
+  running an older panel, and has no files to sweep.
 ## [0.6.0] - 2026-09-24
 
 ### Added
@@ -16,6 +31,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   pane. Panes advertise their open session (cmux-only, one heartbeat file per
   session, ~45 s TTL); outside cmux or with no live claimant, the click opens
   the session locally as before.
+
 ## [0.5.0] - 2026-09-24
 
 ### Added
@@ -277,7 +293,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.6.0...HEAD
+[Unreleased]: https://github.com/ozandogrultan/opencode-sesh/compare/v0.7.0...HEAD
+[0.7.0]: https://github.com/ozandogrultan/opencode-sesh/compare/v0.6.0...v0.7.0
 [0.6.0]: https://github.com/ozandogrultan/opencode-sesh/compare/v0.5.0...v0.6.0
 [0.5.0]: https://github.com/ozandogrultan/opencode-sesh/compare/v0.4.0...v0.5.0
 [0.4.0]: https://github.com/ozandogrultan/opencode-sesh/compare/v0.3.0...v0.4.0

package/README.md

@@ -145,6 +145,10 @@ per-project record.
 (`New session - …`) with the start of the session's first user message. Only
 placeholder titles are touched, and the same dry-run/`--yes` gating applies.
 
+`sesh cmux-sync [--dry-run] [--json]` names every [cmux](https://cmux.dev)
+workspace after the opencode session its pane is running, so the sidebar and the
+workspace list agree. cmux-only; a no-op without the cmux CLI.
+
 When searching, title matches outrank transcript-only matches and the current
 project rises, so the list answers "where was that thing I worked on" before it
 answers "what is newest". Pins still win outright.
@@ -188,10 +192,10 @@ 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. Clicking (or Enter on) a session opens it here — unless a live cmux
-workspace is already showing that session, in which case the sidebar focuses
-that workspace instead of opening a duplicate. The full picker is one
-keystroke away.
+shortcut. Clicking (or Enter on) a session opens it here — unless another cmux
+workspace is already running that session, in which case the sidebar focuses
+that workspace instead of opening a duplicate (and the workspace is kept named
+after its session). 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

package/bin/sesh

@@ -34,5 +34,9 @@ case ${1:-} in
     shift
     exec bash "$SCRIPT_DIR/sesh-retitle.sh" "$@"
     ;;
+  cmux-sync)
+    shift
+    exec bash "$SCRIPT_DIR/sesh-cmux-sync.sh" "$@"
+    ;;
 esac
 exec "$SCRIPT_DIR/sesh.sh" "$@"

package/bin/sesh-cmux-sync.sh

@@ -0,0 +1,146 @@
+#!/usr/bin/env bash
+# Name each cmux workspace after the opencode session it is running.
+#
+# cmux records the session behind every terminal surface (its resume
+# `checkpoint_id`), so the mapping needs no bookkeeping: for each surface whose
+# checkpoint is an opencode session (`ses_…`), rename its workspace to that
+# session's current title. Titles are the opencode session title (the source of
+# truth) unless it is still the pre-first-turn placeholder, which is skipped.
+#
+# cmux-only: exits cleanly when the cmux CLI is unavailable. Renames are
+# lossless (a title), so there is no confirmation; --dry-run previews instead.
+#
+# Usage: sesh-cmux-sync.sh [--dry-run] [--json]
+set -euo pipefail
+
+OPENCODE_BIN=${SESH_OPENCODE:-opencode}
+CMUX_BIN=${SESH_CMUX:-cmux}
+dry_run=0
+emit_json=0
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    --dry-run) dry_run=1 ;;
+    --json) emit_json=1 ;;
+    --help) echo "usage: ${0##*/} [--dry-run] [--json]"; exit 0 ;;
+    *) echo "unknown option: $1" >&2; exit 2 ;;
+  esac
+  shift
+done
+
+command -v "$CMUX_BIN" >/dev/null 2>&1 || { echo 'sesh: cmux is not available' >&2; exit 1; }
+export CMUX_QUIET=1
+
+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
+
+JQ_BIN=${SESH_JQ:-$(command -v jq || true)}
+[ -n "$JQ_BIN" ] || { echo 'sesh: jq is required' >&2; exit 1; }
+
+DB_PATH=$(resolve_db) || { echo 'sesh: session database unavailable' >&2; exit 1; }
+[ -f "$DB_PATH" ] || { echo 'sesh: session database unavailable' >&2; exit 1; }
+
+# 1. Every terminal surface cmux knows about, with its workspace.
+SURFACES=$("$CMUX_BIN" tree --json --all 2>/dev/null | "$JQ_BIN" -c '
+  [ .windows[]?.workspaces[]? as $w
+    | $w.panes[]?.surfaces[]?
+    | select(.type == "terminal" and (.ref | type) == "string")
+    | {surface: .ref, workspace: $w.ref} ]') || SURFACES='[]'
+[ -n "$SURFACES" ] || SURFACES='[]'
+
+# 2. The opencode session each surface is running (cmux resume checkpoint).
+PAIRS='[]'
+while IFS=$'\t' read -r surface workspace; do
+  [ -n "$surface" ] || continue
+  checkpoint=$("$CMUX_BIN" surface resume show --surface "$surface" --json 2>/dev/null \
+    | "$JQ_BIN" -r '.restore_record.checkpoint_id // empty' 2>/dev/null || true)
+  case "$checkpoint" in
+    ses_[A-Za-z0-9]*) ;;
+    *) continue ;;
+  esac
+  PAIRS=$(printf '%s' "$PAIRS" | "$JQ_BIN" -c \
+    --arg ws "$workspace" --arg sid "$checkpoint" \
+    '. + [{workspace: $ws, session: $sid}]')
+done < <(printf '%s' "$SURFACES" | "$JQ_BIN" -r '.[] | [.surface, .workspace] | @tsv')
+
+if [ "$(printf '%s' "$PAIRS" | "$JQ_BIN" 'length')" = 0 ]; then
+  echo 'No cmux workspace is running an opencode session.'
+  exit 0
+fi
+
+# 3. Session titles (one query) and current workspace titles.
+IN_LIST=''
+for id in $(printf '%s' "$PAIRS" | "$JQ_BIN" -r '.[].session'); do
+  case "$id" in
+    ses_[A-Za-z0-9]*) IN_LIST="$IN_LIST'$id'," ;;
+    *) echo 'sesh: unexpected session id shape' >&2; exit 1 ;;
+  esac
+done
+IN_LIST=${IN_LIST%,}
+if [ -n "$SQLITE_BIN" ]; then
+  TITLE_ROWS=$("$SQLITE_BIN" -json -readonly "$DB_PATH" "SELECT id, title FROM session WHERE id IN ($IN_LIST);")
+else
+  TITLE_ROWS=$("$OPENCODE_BIN" db "SELECT id, title FROM session WHERE id IN ($IN_LIST);" --format json)
+fi
+[ -n "$TITLE_ROWS" ] || TITLE_ROWS='[]'
+
+CURRENT=$("$CMUX_BIN" workspace list --json 2>/dev/null | "$JQ_BIN" -c \
+  '[.workspaces[] | {workspace: .ref, title: (.custom_title // .title // "")}]') || CURRENT='[]'
+[ -n "$CURRENT" ] || CURRENT='[]'
+
+# 4. Keep only the real renames: a non-placeholder session title that differs
+#    from what the workspace already shows.
+FINAL=$(printf '%s' "$PAIRS" | "$JQ_BIN" -c \
+  --slurpfile sessions <(printf '%s' "$TITLE_ROWS") \
+  --slurpfile current <(printf '%s' "$CURRENT") '
+  ($sessions[0] | map({key: .id, value: .title}) | from_entries) as $byId
+  | ($current[0] | map({key: .workspace, value: .title}) | from_entries) as $shown
+  | [ .[]
+      | ($byId[.session] // "" | gsub("^ +| +$"; "")) as $t
+      | select($t != "" and ($t | test("^New session\\b"; "i") | not))
+      | select(($shown[.workspace] // "") != $t)
+      | . + {title: $t} ]')
+
+COUNT=$(printf '%s' "$FINAL" | "$JQ_BIN" 'length')
+if [ "$COUNT" = 0 ]; then
+  echo 'Every cmux workspace already matches its session.'
+  exit 0
+fi
+
+if [ "$emit_json" = 1 ]; then
+  printf '%s\n' "$FINAL"
+  exit 0
+fi
+
+printf '%s' "$FINAL" | "$JQ_BIN" -r '.[] | "\(.workspace)\t\(.title)"' | while IFS=$'\t' read -r ws title; do
+  printf '%s → %s\n' "$ws" "$title"
+done
+
+if [ "$dry_run" = 1 ]; then
+  printf 'Would rename %s workspace(s) (--dry-run: nothing changed).\n' "$COUNT" >&2
+  exit 0
+fi
+
+renamed=0
+while IFS=$'\t' read -r ws title; do
+  if "$CMUX_BIN" workspace rename "$ws" --title "$title" >/dev/null 2>&1; then
+    renamed=$((renamed + 1))
+  else
+    echo "sesh: could not rename $ws" >&2
+  fi
+done < <(printf '%s' "$FINAL" | "$JQ_BIN" -r '.[] | [.workspace, .title] | @tsv')
+echo "Renamed $renamed workspace(s)."

package/contrib/cmux/README.md

@@ -35,6 +35,19 @@ sesh --print --json --query "auth refactor" \
 Wrap that in a cmux `command` action (as above) or a shell function; it is
 caller-side on purpose, so sesh stays terminal-agnostic.
 
+## Keep workspace names in step
+
+The sidebar renames its workspace to the opencode session title as you work, and
+`sesh cmux-sync` does it for every workspace at once:
+
+```bash
+sesh cmux-sync --dry-run   # preview
+sesh cmux-sync             # rename to match
+```
+
+It reads cmux's own per-surface resume record, so it also names workspaces whose
+agent was started outside the sidebar.
+
 ## Needs-input triage from cmux
 
 `sesh --needs-input` prints (or `--json` emits) the sessions with unanswered

package/install.sh

@@ -235,6 +235,7 @@ for path in \
   bin/sesh.sh \
   bin/sesh-list.sh \
   bin/sesh-preview.sh \
+  bin/sesh-cmux-sync.sh \
   bin/sesh-costs.sh \
   bin/sesh-delete.sh \
   bin/sesh-prune.sh \

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-sesh",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "type": "module",
   "description": "Browse, search, preview and resume opencode sessions from the terminal and the TUI.",
   "license": "MIT",

package/tui/sesh-panel.tsx

@@ -2,7 +2,7 @@
 import type { TuiPlugin, TuiPluginApi } from "@opencode-ai/plugin/tui"
 import type { Project, Session } from "@opencode-ai/sdk/v2"
 import { createEffect, createMemo, createSignal, For, onCleanup, onMount, Show } from "solid-js"
-import { mkdir, readFile, readdir, rename, rmdir, unlink, writeFile } from "node:fs/promises"
+import { mkdir, readFile, rename, rmdir, unlink, writeFile } from "node:fs/promises"
 import { dirname, join } from "node:path"
 import { execFile } from "node:child_process"
 import { promisify } from "node:util"
@@ -177,6 +177,9 @@ function pinnedFirst(entries: Entry[], pins: Pins): Entry[] {
 // dialog). Native `/sessions` and session_list (<leader>l) stay untouched.
 const BASE_MODE = "base"
 const POLL_MS = 15_000
+// opencode names a session only after its first turn; until then the title is
+// a placeholder that should not become a cmux workspace name.
+const PLACEHOLDER_TITLE = /^New session\b/i
 
 function shortDir(dir: string, home: string): string {
   if (!dir || dir === "/") return "other"
@@ -390,49 +393,62 @@ async function queryWaitingIds(db: any): Promise<Map<string, string>> {
   return out
 }
 
-// Presence registry: which cmux workspace is showing which session, so opening
-// a session that is already visible elsewhere focuses that workspace instead
-// of opening a duplicate here. Each panel heartbeats its own session file
-// (one file per session: concurrent panes never share a file, and renames are
-// atomic, so no locking is needed); files older than PRESENCE_TTL_MS are
-// treated as gone. Outside cmux nothing is written and nothing is read.
-const PRESENCE_TTL_MS = 45000
-function presenceDir(): string {
-  const home = process.env.HOME ?? ""
-  const dataHome = process.env.XDG_DATA_HOME ?? `${home}/.local/share`
-  return join(dataHome, "sesh", "presence")
-}
-function parsePresence(raw: string, now: number): string | undefined {
-  let parsed: { workspace?: unknown; updated?: unknown }
+// cmux bridge: which surface is running which agent session, so opening a
+// session that is live in another cmux workspace focuses that workspace
+// instead of opening a duplicate here. The truth is cmux's own resume record
+// (`checkpoint_id` per surface), not anything this panel writes — so it also
+// covers background agents and panes running an older panel. Outside cmux
+// (no CMUX_WORKSPACE_ID) no cmux call is made.
+type CmuxSurface = { ref: string; workspaceRef: string; here: boolean; checkpoint?: string }
+
+async function cmuxJson(args: string[]): Promise<any | undefined> {
   try {
-    parsed = JSON.parse(raw)
+    const { stdout } = await promisify(execFile)("cmux", args)
+    return JSON.parse(stdout)
   } catch {
     return undefined
   }
-  if (typeof parsed?.workspace !== "string" || !parsed.workspace) return undefined
-  if (typeof parsed?.updated !== "number" || now - parsed.updated > PRESENCE_TTL_MS) return undefined
-  return parsed.workspace
 }
-async function sweepPresence(): Promise<void> {
-  try {
-    const dir = presenceDir()
-    const now = Date.now()
-    const names = await readdir(dir)
-    await Promise.all(
-      names
-        .filter((name) => name.endsWith(".json"))
-        .map(async (name) => {
-          try {
-            const raw = await readFile(join(dir, name), "utf8")
-            if (!parsePresence(raw, now)) await unlink(join(dir, name))
-          } catch {
-            // ignore races with other panes
+
+async function cmuxSurfaces(): Promise<CmuxSurface[]> {
+  const tree = await cmuxJson(["tree", "--json", "--all"])
+  if (!tree) return []
+  const surfaces: CmuxSurface[] = []
+  for (const w of tree.windows ?? []) {
+    for (const ws of w.workspaces ?? []) {
+      if (typeof ws?.ref !== "string") continue
+      for (const pane of ws.panes ?? []) {
+        for (const s of pane.surfaces ?? []) {
+          if (s?.type === "terminal" && typeof s.ref === "string") {
+            surfaces.push({ ref: s.ref, workspaceRef: ws.ref, here: s.here === true })
           }
-        }),
-    )
-  } catch {
-    // missing directory or concurrent cleanup; presence is best-effort
+        }
+      }
+    }
   }
+  await Promise.all(
+    surfaces.map(async (surface) => {
+      const info = await cmuxJson(["surface", "resume", "show", "--surface", surface.ref, "--json"])
+      const checkpoint = info?.restore_record?.checkpoint_id
+      if (typeof checkpoint === "string") surface.checkpoint = checkpoint
+    }),
+  )
+  return surfaces
+}
+
+// Pure selection: the workspace to focus for a session, or undefined to open
+// locally. Prefers a live surface in a different workspace; ignores the
+// caller's own surface and workspace (focusing where you already are is a
+// no-op, so a local open is the better answer).
+function pickFocusWorkspace(surfaces: CmuxSurface[], sessionID: string): string | undefined {
+  const self = surfaces.find((surface) => surface.here)
+  for (const surface of surfaces) {
+    if (self && surface.ref === self.ref) continue
+    if (surface.checkpoint !== sessionID) continue
+    if (self && surface.workspaceRef === self.workspaceRef) continue
+    return surface.workspaceRef
+  }
+  return undefined
 }
 
 function addTranscript(index: Map<string, string>, sid: string, data: string): void {
@@ -708,6 +724,7 @@ function SidebarSessions(props: { api: TuiPluginApi } & PinProps) {
   const [pendingDelete, setPendingDelete] = createSignal<string>()
   const [waiting, setWaiting] = createSignal<Map<string, string>>(new Map())
   let confirmTimer: ReturnType<typeof setTimeout> | undefined
+  let lastSyncedTitle: string | undefined
   const currentID = createMemo(() => {
     const route = props.api.route.current
     if (route.name !== "session") return undefined
@@ -743,30 +760,20 @@ function SidebarSessions(props: { api: TuiPluginApi } & PinProps) {
       } catch {
         // leave the previous waiting set in place rather than flashing
       }
-      // Heartbeat this pane's session so another pane can focus it instead of
-      // opening a duplicate. cmux-only: without CMUX_WORKSPACE_ID nothing is
-      // written and opening a session always navigates locally.
+      // Keep this cmux workspace named after the session it is showing, so the
+      // sidebar and the workspace list agree. The session title is the source
+      // of truth; a placeholder title is never pushed. cmux-only.
       try {
         const workspace = process.env.CMUX_WORKSPACE_ID
         const id = currentID()
-        if (workspace && id && SESSION_ID_PATTERN.test(id)) {
-          const dir = presenceDir()
-          await mkdir(dir, { recursive: true })
-          const tmp = join(dir, `${id}.tmp`)
-          await writeFile(
-            tmp,
-            JSON.stringify({
-              workspace,
-              surface: process.env.CMUX_SURFACE_ID ?? null,
-              updated: Date.now(),
-            }),
-          )
-          await rename(tmp, join(dir, `${id}.json`))
+        const title = id ? (props.api.state.session.get(id)?.title ?? "").trim() : ""
+        if (workspace && title && !PLACEHOLDER_TITLE.test(title) && title !== lastSyncedTitle) {
+          await promisify(execFile)("cmux", ["workspace", "rename", workspace, "--title", title])
+          lastSyncedTitle = title
         }
       } catch {
-        // presence is best-effort; a failed heartbeat only disables focusing
+        // renaming is best-effort; a failure leaves the workspace name alone
       }
-      if (process.env.CMUX_WORKSPACE_ID) void sweepPresence()
     }
     void load()
     const clock = setInterval(() => void load(), POLL_MS)
@@ -845,26 +852,19 @@ function SidebarSessions(props: { api: TuiPluginApi } & PinProps) {
     setSectionCollapsed((value) => !value)
   }
 
-  // Open a session. If a live cmux workspace is already showing it, focus that
-  // workspace instead of opening a duplicate here. The heartbeat self-entry is
-  // ignored (it is this pane); a stale file (crashed pane) falls through to a
-  // local navigate. Only the sidebar goes through here.
+  // Open a session. If a cmux surface is already running it in another
+  // workspace, focus that workspace instead of opening a duplicate here;
+  // otherwise open it locally. `cmux` calls only run inside cmux.
   const openSession = async (entry: Entry) => {
-    const selfWorkspace = process.env.CMUX_WORKSPACE_ID
-    if (selfWorkspace) {
-      try {
-        const raw = await readFile(join(presenceDir(), `${entry.id}.json`), "utf8")
-        const workspace = parsePresence(raw, Date.now())
-        if (workspace && workspace !== selfWorkspace) {
-          try {
-            await promisify(execFile)("cmux", ["workspace", "select", workspace])
-            return
-          } catch {
-            // cmux unavailable; fall through to a local open
-          }
+    if (process.env.CMUX_WORKSPACE_ID) {
+      const target = pickFocusWorkspace(await cmuxSurfaces(), entry.id)
+      if (target) {
+        try {
+          await promisify(execFile)("cmux", ["workspace", "select", target])
+          return
+        } catch {
+          // cmux unavailable; fall through to a local open
         }
-      } catch {
-        // no presence file for this session
       }
     }
     props.api.route.navigate("session", { sessionID: entry.id })