sesh: add svibe --agents CSV mode and --no-specstory opt-out

daviddwlee84 · daviddwlee84 · commit 03e927ee10e0 · 2026-04-23T20:43:11.000+08:00
Heterogeneous svibe layouts via --agents claude,codex,opencode,... (list length = pane count, mixing with positional N rejected for unambiguous semantics). Per-pane wrapping means one opencode pane can sit next to specstory-wrapped claude panes in the same window. Add --no-specstory opt-out to scode/svibe for raw agent invocation without markdown auto-save. Track upstream specstoryai/getspecstory#156 in backlog so opencode joins the auto-wrap list when the PR ships.
diff --git a/TODO.md b/TODO.md
@@ -47,6 +47,8 @@ with a one-line summary of what shipped.
 
 ## P? — Needs evaluation before committing
 
+- [ ] **[?/M] tmux window status indicators (running / idle / error)** — show per-window state on the tab list (e.g. `1 opencode ⚙` busy vs `2 opencode 💤` idle vs `❌` errored). Three options evaluated; lean toward hook-based per-pane state file driven by opencode `session.*` + Claude `Stop`/`UserPromptSubmit` hooks. Blocked on (a) verifying opencode hook event names, (b) confirming the `dot_claude/modify_settings.json` merger handles multiple entries per event so we don't ping-pong with CodeIsland. → [research](backlog/tmux-window-status-indicators.md)
+- [ ] **[?/S] specstory: enable opencode auto-wrap when upstream lands** — `_sesh_wrap_agent` in `dot_config/zsh/tools/22_sesh.zsh` currently passes `opencode` through raw because specstory doesn't support it as a provider. Add to the case statement (one-line change) once `specstoryai/getspecstory#156` merges + ships. → [research](backlog/specstory-opencode-support.md)
 - [ ] **[?/L] Use mise to manage most runtime versions** — already used for Node (Neovim) and Rust (Cargo) per `README.md`. Question: extend to python/go/ruby and retire ad-hoc PATH wiring + nvm? Trade-off: another layer vs unified version pinning. Spike: pick one runtime currently outside mise (go?), try alongside current setup for two weeks.
 - [ ] **[?/L] Optimize zsh & tmux startup time** — needs profiling first (`zprof`, `time zsh -i -c exit`). Current state: conda/nvm are lazy-loaded already, so low-hanging fruit may be gone. Don't optimize blind.
 - [ ] **[?/XL] CUDA / ML toolchain ansible role** — driver/cudnn/nccl version matrix is large; only relevant on Linux ML hosts. Defer until there's a concrete host that needs it. Likely belongs behind a new `ml_linux` profile.
diff --git a/backlog/README.md b/backlog/README.md
@@ -96,5 +96,7 @@ Add new entries here as you create them. Keep alphabetical.
 
 | Slug | Status | TODO entry |
 |---|---|---|
+| [`specstory-opencode-support`](specstory-opencode-support.md) | P? deferred | "specstory: enable opencode auto-wrap when upstream lands" |
 | [`starship-context-modules`](starship-context-modules.md) | P1 ready | "Starship status-aware modules" |
 | [`tmux2k-tuning`](tmux2k-tuning.md) | P1 ready | "tmux2k bandwidth bug" + "tmux2k theme alignment" |
+| [`tmux-window-status-indicators`](tmux-window-status-indicators.md) | P? deferred | "tmux window status indicators (running / idle / error)" |
diff --git a/backlog/specstory-opencode-support.md b/backlog/specstory-opencode-support.md
@@ -0,0 +1,91 @@
+# Add `opencode` to specstory provider auto-wrap list
+
+**Status**: P? deferred — waiting upstream
+**Effort**: S (one-line change once upstream lands)
+**Related**: `dot_config/zsh/tools/22_sesh.zsh` `_sesh_wrap_agent`,
+docs/tools/sesh.md → "Agent wrapping"
+
+## Context
+
+`scode` and `svibe` (and the underlying `_sesh_wrap_agent` helper) auto-wrap
+known specstory providers in `specstory run X` to get markdown auto-save
+logging. The known-provider list as of 2026-04 is:
+
+```
+claude / codex / cursor / droid / gemini
+```
+
+`opencode` is intentionally NOT in this list because **specstory itself does
+not support it yet**. Calling `specstory run opencode` returns an unknown
+provider error, so we currently pass `opencode` through raw — losing the
+auto-save markdown that the other agents get.
+
+## Investigation
+
+Upstream tracking (read top to bottom for the latest):
+
+- Issue: <https://github.com/specstoryai/getspecstory/issues/146>
+  "Add opencode support" — opened by users running opencode locally and
+  wanting the same markdown capture as the other CLIs.
+- PR: <https://github.com/specstoryai/getspecstory/pull/156>
+  WIP implementation. As of 2026-04 not yet merged. Once merged + released
+  in a specstory version, `specstory run opencode` should work.
+
+Local check used during this investigation:
+
+```sh
+$ specstory run --help
+  Available provider IDs: claude (Claude Code), codex (Codex CLI),
+  cursor (Cursor CLI), droid (Factory Droid CLI), gemini (Gemini CLI).
+```
+
+Note `opencode` is absent from the available provider list.
+
+## Options considered
+
+| Option | Pros | Cons |
+|---|---|---|
+| A. Wait for upstream PR #156 to merge, then add `opencode` to the case statement | Zero engineering on our end; consistent with how other providers were added | Blocked on external timeline (unknown ETA) |
+| B. Maintain a local shim wrapper that fakes specstory output | We control the timing | Reinvents specstory; output format may diverge from upstream's eventual implementation; high churn |
+| C. Use a different recorder for opencode (asciinema, script(1), etc.) | Independent of specstory | Different output format from other agents; breaks the single-source-of-truth markdown story |
+
+Going with A. The cost of waiting is "opencode panes lose the auto-save
+nicety"; the cost of B/C is ongoing maintenance plus eventual migration to
+upstream.
+
+## Current blocker
+
+Waiting on `specstoryai/getspecstory#156` to merge + ship in a release.
+
+## Activation steps (when unblocked)
+
+When PR #156 merges and is released:
+
+1. Bump local specstory: `npm i -g @specstoryai/specstory@latest`
+   (or whatever the install command is on this machine).
+2. Verify: `specstory run --help` now lists `opencode`.
+3. Edit `dot_config/zsh/tools/22_sesh.zsh` → `_sesh_wrap_agent`:
+
+   ```diff
+   -        claude|codex|cursor|droid|gemini)
+   +        claude|codex|cursor|droid|gemini|opencode)
+                print -r -- "specstory run $agent"
+                ;;
+   ```
+
+4. Update the case-statement comment + the "Agent wrapping (auto)" tables
+   in:
+   - `_sesh_wrap_agent` docstring
+   - `sesh-code` and `sesh-vibe` `--help` output
+   - `docs/tools/sesh.md` → `scode` + `svibe` → "Agent wrapping" sections
+5. Move this entry from `TODO.md` (P?) to `## Done`.
+
+## Decision
+
+`2026-04 deferred — waiting on getspecstory#156 release`
+
+## References
+
+- <https://github.com/specstoryai/getspecstory/pull/156>
+- <https://github.com/specstoryai/getspecstory/issues/146>
+- `_sesh_wrap_agent` in `dot_config/zsh/tools/22_sesh.zsh`
diff --git a/docs/tools/sesh.md b/docs/tools/sesh.md
@@ -79,7 +79,10 @@ existing session pointing at the *wrong* repo.
 ```bash
 scode                          # current repo, default agent (specstory → claude)
 scode codex                    # right pane runs `specstory run codex`
-scode opencode                 # right pane runs `opencode` raw (not a specstory provider)
+scode opencode                 # right pane runs `opencode` raw (not yet a specstory provider)
+scode --no-specstory claude    # right pane runs `claude` raw (no markdown auto-save)
+scode --on-exit kill claude    # Ctrl+C closes the right pane (vs default: drops to shell)
+scode --on-exit restart codex  # codex auto-respawns on crash
 scode -p ~/work/foo            # explicit repo path
 scode --no-attach              # build the session in the background, don't switch
 scode -h                       # help
@@ -102,13 +105,42 @@ heavy layout. Use `shere` for bare shells or `svibe` if you really want a
 vibe layout in a non-repo directory (svibe also requires a repo, but that's
 because vibe layouts make even less sense without git context).
 
-The agent override resolves to:
+##### Agent wrapping (auto, opt out with `--no-specstory`)
 
 | Argument | Right-pane command |
 |----------|--------------------|
 | (none) | `specstory run` (defaults to claude with auto-save md) |
 | `claude` / `codex` / `cursor` / `droid` / `gemini` | `specstory run <name>` (known specstory providers) |
-| anything else, e.g. `opencode` | runs the binary directly |
+| `opencode` and other unknown CLIs | runs the binary directly |
+| any agent + `--no-specstory` | runs the binary directly (raw) |
+
+> `opencode` is currently raw because specstory upstream doesn't support it
+> as a provider yet. Tracked in
+> [`backlog/specstory-opencode-support.md`](../../backlog/specstory-opencode-support.md)
+> — when `specstoryai/getspecstory#156` lands, the case statement in
+> `_sesh_wrap_agent` gets a one-line update and opencode joins the auto-wrap
+> list.
+
+##### `--on-exit` modes
+
+What happens when the agent exits (clean quit, Ctrl+C, crash):
+
+| Mode | Behavior |
+|------|----------|
+| `shell` (default) | Pane prints a yellow hint and drops into `$SHELL`. You can re-launch the agent (the hint shows the exact command), switch to lazygit, or close the pane manually. Costs one background `$SHELL` process per pane. |
+| `kill` | Pane closes when the agent exits. The historical / tmux-default behavior. |
+| `restart` | Wraps the agent in `while true; do AGENT \|\| true; sleep 1; done`. Use Ctrl+C twice quickly to break the loop and land in shell. Useful for crash-prone development of an agent itself. |
+
+> The `shell` default trades one background process per pane for far better
+> recoverability — the most common reported pain point with the old
+> `coding-agent` workflow was "I hit Ctrl+C and lost the pane plus the
+> 75/25 layout".
+
+##### Single-agent only
+
+`scode` is single-agent by design. If you want multiple agents in parallel,
+use `svibe --agents …`. Passing `--agents` to `scode` errors with a hint to
+switch to `svibe`.
 
 > The legacy `coding-agent` named session in `sesh.toml` is **kept for
 > back-compat** (still appears in the sesh picker, still works as
@@ -120,29 +152,67 @@ The agent override resolves to:
 Built directly with tmux scripting (not tmuxp) because pane counts are
 parametric and tmuxp YAML can't express that.
 
+Two ways to specify which agents run:
+
 ```bash
-svibe                          # 4× claude (default) + lazygit + nvim
-svibe 2                        # 2× claude
-svibe 4 codex                  # 4× codex
-svibe 6 opencode               # 6× opencode (heavy — large monitor recommended)
-svibe -p ~/repo 4 claude       # explicit path
-svibe -h                       # help
+# Homogeneous (positional): all panes run the same agent
+svibe                                            # 4× claude (default)
+svibe 2                                          # 2× claude
+svibe 4 codex                                    # 4× codex
+svibe 6 opencode                                 # 6× opencode (heavy — large monitor recommended)
+
+# Heterogeneous (--agents): one entry per pane, list length = pane count
+svibe --agents claude,codex,codex,opencode       # 4 panes, mixed
+svibe --agents claude,opencode                   # 2 panes, mixed
+svibe --agents 'claude, codex, opencode'         # whitespace around commas tolerated
+
+# Other flags (work with both modes)
+svibe --on-exit kill 4 claude                    # Ctrl+C closes panes
+svibe --on-exit restart --agents codex,opencode  # auto-respawn loop
+svibe --no-specstory 4 claude                    # 4× raw claude (no markdown auto-save)
+svibe -p ~/repo --agents claude,codex            # explicit path
+svibe -h                                         # help
 ```
 
+Mixing positional `[N] [CLI]` with `--agents` is **rejected** to keep
+semantics unambiguous — pick one mode.
+
 Layout (3 windows):
 
 ```
-window 1 "agents"    — N tiled panes, each running AGENT_CLI
+window 1 "agents"    — N tiled panes, each running its agent (mixed allowed)
 window 2 "git"       — lazygit (or `git status` fallback)
 window 3 "edit"      — nvim
 ```
 
-`N_AGENTS` is bounded `[1, 12]`. Above ~6 the tiled layout becomes too
+Pane count is bounded `[1, 12]`. Above ~6 the tiled layout becomes too
 cramped on most displays — the cap is conservative, not technical.
 
-Like `scode`, `svibe` refuses outside a git repo. The agent CLI is checked
-against PATH up-front; missing → error with the list of available agents
-detected on this machine.
+##### Validation (fail-fast)
+
+`svibe` validates before building anything:
+
+1. `--agents` and positional `[N] [CLI]` cannot both be set
+2. `--on-exit` must be `shell` / `kill` / `restart`
+3. Pane count in `[1, 12]`
+4. Must be inside a git repo
+5. **Every** agent CLI in the list must exist in `$PATH`
+
+This avoids the "4-pane window where one pane is silently dead" failure mode
+you'd get if validation were per-pane.
+
+##### `--no-specstory` and `--on-exit`
+
+Same semantics as `scode`. The wrapping is **per-pane**, so you can mix
+opencode (raw) with claude (specstory-wrapped) freely:
+
+```bash
+# 3 panes — opencode raw, claude wrapped, codex wrapped, all share --on-exit shell
+svibe --agents opencode,claude,codex
+```
+
+Like `scode`, `svibe` refuses outside a git repo. Use `shere` for plain
+shells in arbitrary directories.
 
 ### Picking between the four
 
diff --git a/docs/zsh/aliases.md b/docs/zsh/aliases.md
@@ -447,8 +447,8 @@ Quick reference for custom aliases and shell functions defined in this dotfiles
 | `sesh-sessions` | function | `dot_config/zsh/tools/22_sesh.zsh` | fzf popup picker for all sesh sessions (also bound to `Alt+S`) |
 | `sesh-here` / `shere` | function / alias | `dot_config/zsh/tools/22_sesh.zsh` | Lightweight: bare shell session at `$PWD` (no nvim, no project layout). Pass args/`-c CMD` to override |
 | `sesh-root` / `sroot` | function / alias | `dot_config/zsh/tools/22_sesh.zsh` | Connect sesh to current git root (falls back to `$PWD`); honors sesh.toml wildcards/default |
-| `sesh-code` / `scode` | function / alias | `dot_config/zsh/tools/22_sesh.zsh` | Repo-scoped coding-agent layout: nvim 75% \| `specstory run [agent]` 25%, plus btop window. Session named `coding-agent/<repo>` (collision-safe). Refuses outside git repos |
-| `sesh-vibe` / `svibe` | function / alias | `dot_config/zsh/tools/22_sesh.zsh` | Parametric multi-agent layout: `svibe [N_AGENTS] [AGENT_CLI]` (default `4 claude`). N tiled agent panes + lazygit window + nvim window. Session named `vibe/<repo>`. Refuses outside git repos |
+| `sesh-code` / `scode` | function / alias | `dot_config/zsh/tools/22_sesh.zsh` | Repo-scoped coding-agent layout: nvim 75% \| `specstory run [agent]` 25%, plus btop window. Session named `coding-agent/<repo>` (collision-safe). Refuses outside git repos. Flags: `--on-exit shell\|kill\|restart`, `--no-specstory` |
+| `sesh-vibe` / `svibe` | function / alias | `dot_config/zsh/tools/22_sesh.zsh` | Parametric multi-agent layout: `svibe [N] [CLI]` (homogeneous) or `svibe --agents claude,codex,opencode,…` (heterogeneous). N tiled agent panes + lazygit window + nvim window. Session named `vibe/<repo>`. Same `--on-exit` / `--no-specstory` flags as scode |
 | `try-sesh` / `tsesh` | function / alias | `dot_config/zsh/tools/32_try.zsh` | Open a `try` ephemeral workspace and immediately connect via sesh |
 
 ---
diff --git a/dot_config/zsh/tools/22_sesh.zsh b/dot_config/zsh/tools/22_sesh.zsh
