shipwright-cli 1.7.1 → 1.9.0

package/docs/KNOWN-ISSUES.md

@@ -11,6 +11,7 @@ Tracked bugs and limitations in Claude Code Agent Teams + tmux integration, with
 **Problem:** When Claude Code spawns 4+ agent panes simultaneously using `split-window` + `send-keys`, tmux can deliver keystrokes to the wrong pane. This happens because tmux processes `split-window` and `send-keys` asynchronously — the new pane may not be the active pane by the time `send-keys` fires.
 
 **Symptoms:**
+
 - Agent commands appear in the wrong pane
 - Panes start with garbled or partial commands
 - Some panes sit empty while others received duplicate input
@@ -38,6 +39,7 @@ tmux send-keys -t "$session" "claude" Enter
 **Problem:** Agent teams can silently fall back to in-process mode if tmux isn't detected properly. No error is shown — agents just spawn in the same process instead of separate panes.
 
 **Symptoms:**
+
 - You're inside tmux but agents don't get their own panes
 - All agent output appears in a single terminal
 - No tmux split-windows are created
@@ -68,25 +70,27 @@ If only one pane is listed while agents are active, the fallback occurred.
 **Severity:** Medium — affects users of these terminals
 
 **Problem:** Claude Code's tmux-based agent pane spawning does not work in:
+
 - **VS Code's integrated terminal** — VS Code's terminal emulator doesn't support the tmux control mode and pane management that Claude Code uses for agent teams.
 - **Ghostty** — As of current versions, Ghostty lacks the tmux integration hooks needed for split-pane agent spawning.
 
 **Symptoms:**
+
 - Agent teams silently fall back to in-process mode
 - No tmux split panes are created
 - Everything works, but you lose the visual multi-pane experience
 
 **Workaround:** Use a supported terminal emulator:
 
-| Terminal | Status | Notes |
-|----------|--------|-------|
-| **iTerm2** (macOS) | Supported | Recommended for macOS |
-| **Alacritty** | Supported | Fast, cross-platform |
-| **Kitty** | Supported | Feature-rich, cross-platform |
-| **WezTerm** | Supported | Cross-platform, GPU-accelerated |
-| **macOS Terminal.app** | Supported | Built-in, basic but works |
-| VS Code terminal | Not supported | Use an external terminal |
-| Ghostty | Not supported | May be supported in future versions |
+| Terminal               | Status        | Notes                               |
+| ---------------------- | ------------- | ----------------------------------- |
+| **iTerm2** (macOS)     | Supported     | Recommended for macOS               |
+| **Alacritty**          | Supported     | Fast, cross-platform                |
+| **Kitty**              | Supported     | Feature-rich, cross-platform        |
+| **WezTerm**            | Supported     | Cross-platform, GPU-accelerated     |
+| **macOS Terminal.app** | Supported     | Built-in, basic but works           |
+| VS Code terminal       | Not supported | Use an external terminal            |
+| Ghostty                | Not supported | May be supported in future versions |
 
 **Tip:** You can run tmux in an external terminal while keeping VS Code open for editing. Claude Code doesn't need to run inside VS Code to work with your project.
 
@@ -101,6 +105,7 @@ If only one pane is listed while agents are active, the fallback occurred.
 **Problem:** Each agent in a team uses its own context window. With 3+ agents running complex tasks, individual agents can hit context limits faster than expected, especially if tasks are too broad.
 
 **Symptoms:**
+
 - Agent output becomes less coherent toward the end of long tasks
 - Agents start losing track of earlier context
 - Auto-compact kicks in frequently
@@ -112,6 +117,7 @@ If only one pane is listed while agents are active, the fallback occurred.
 2. **Keep tasks focused.** 5-6 specific tasks per agent is the sweet spot. Avoid vague tasks like "improve the codebase."
 
 3. **Set aggressive auto-compact:**
+
    ```json
    {
      "env": {
@@ -121,6 +127,7 @@ If only one pane is listed while agents are active, the fallback occurred.
    ```
 
 4. **Use haiku for subagent lookups** to save context budget for the main agent:
+
    ```json
    {
      "env": {
@@ -143,7 +150,7 @@ If only one pane is listed while agents are active, the fallback occurred.
 
 **Root Cause:** tmux's `window-style` applies at the window level but newly spawned panes from external processes (like Claude Code) don't always inherit it.
 
-**Fix:** As of v1.3.0, `claude-teams-overlay.conf` uses `set-hook` to force the dark theme on every new pane:
+**Fix:** As of v1.3.0, `shipwright-overlay.conf` uses `set-hook` to force the dark theme on every new pane:
 
 ```conf
 set-hook -g after-split-window "select-pane -P 'bg=#1a1a2e,fg=#e4e4e7'"
@@ -182,6 +189,7 @@ git clone https://github.com/tmux-plugins/tpm ~/.tmux/plugins/tpm
 **Problem:** When Claude Code teammates shut down (via `shutdown_request` → `shutdown_response`), the Claude process exits but the tmux pane remains open with an idle shell. There is no Claude Code hook event for teammate shutdown — the available hooks (`TeammateIdle`, `TaskCompleted`, `Notification`, `Stop`, etc.) do not fire on agent exit.
 
 **Symptoms:**
+
 - After a team finishes work, panes remain with idle shell prompts
 - `shipwright ps` shows panes as "idle" with increasing idle time
 - `~/.claude/teams/` and `~/.claude/tasks/` directories accumulate

package/docs/TIPS.md

@@ -9,36 +9,43 @@ Patterns and tricks for getting the most out of Claude Code Agent Teams with tmu
 Based on [Addy Osmani's research](https://addyosmani.com/blog/claude-code-agent-teams/) and community experience:
 
 ### When Teams Add Value
+
 - **Competing hypotheses** — Multiple agents investigating different theories for a bug
 - **Parallel review** — Security, performance, and test coverage by dedicated reviewers
 - **Cross-layer features** — Frontend, backend, and tests developed simultaneously
 
 ### When to Stay Single-Agent
+
 - Sequential, tightly-coupled work where each step depends on the last
 - Simple bugs or single-file changes
 - Tasks where coordination overhead exceeds the parallel benefit
 
 ### The Task Sizing Sweet Spot
+
 Too small and coordination overhead dominates. Too large and agents work too long without check-ins. Aim for **5-6 focused tasks per agent** with clear deliverables.
 
 ### Specification Quality = Output Quality
-Detailed spawn prompts with technical constraints, acceptance criteria, and domain context produce dramatically better results. Don't just say "fix the tests" — say "fix the auth tests in src/auth/__tests__/, ensuring all edge cases for expired tokens are covered, using the existing MockAuthProvider pattern."
+
+Detailed spawn prompts with technical constraints, acceptance criteria, and domain context produce dramatically better results. Don't just say "fix the tests" — say "fix the auth tests in src/auth/**tests**/, ensuring all edge cases for expired tokens are covered, using the existing MockAuthProvider pattern."
 
 ---
 
 ## Hook Patterns for Teams
 
 ### Quality Gates (Most Valuable)
+
 - **TeammateIdle** — Run typecheck before letting agents idle. Catches errors early.
 - **TaskCompleted** — Run lint + related tests before allowing task completion.
 - **Stop** — Verify all work is complete before Claude stops responding.
 
 ### Observability
+
 - **Notification** — Desktop alerts so you can work on other things.
 - **PostToolUse** on `Bash` — Log all commands agents run to a file.
 - **SubagentStart/SubagentStop** — Track when agents spawn and finish.
 
 ### Context Preservation
+
 - **PreCompact** — Save git status, recent commits, and project reminders before compaction.
 - **SessionStart** on `compact` — Re-inject critical context after compaction.
 
@@ -124,7 +131,7 @@ This compacts the conversation when it hits 70% of the context window (default i
 
 ### Watch all agents at once
 
-Use `shipwright status` (alias: `cct`, `sw`) to see a dashboard of running team sessions:
+Use `shipwright status` (alias: `sw`, `cct`) to see a dashboard of running team sessions:
 
 ```bash
 shipwright status
@@ -139,6 +146,7 @@ Press `prefix + G` to toggle zoom on the current pane. This makes one agent fill
 ### Synchronized input
 
 Press `prefix + Alt-t` to toggle synchronized panes. When enabled, anything you type goes to ALL panes simultaneously. Useful for:
+
 - Stopping all agents at once (`Ctrl-C` in all panes)
 - Running the same command in all agent directories
 
@@ -246,17 +254,17 @@ shipwright cleanup --force   # Actually kills orphaned sessions
 
 ## Environment Variables Reference
 
-| Variable | Default | What it does |
-|----------|---------|--------------|
-| `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` | — | **Required.** Enables agent teams feature |
-| `CLAUDE_CODE_SUBAGENT_MODEL` | (parent model) | Model for subagent lookups. Set to `"haiku"` to save money |
-| `CLAUDE_CODE_AUTOCOMPACT_PCT_OVERRIDE` | `"80"` | Context compaction threshold. Lower = more aggressive |
-| `CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY` | `"3"` | Parallel tool calls per agent. Higher = faster but more API usage |
-| `CLAUDE_CODE_GLOB_HIDDEN` | — | Include dotfiles in glob searches |
-| `CLAUDE_CODE_BASH_MAINTAIN_PROJECT_WORKING_DIR` | — | Keep bash cwd consistent across tool calls |
-| `CLAUDE_CODE_EMIT_TOOL_USE_SUMMARIES` | — | Show tool use summaries in output |
-| `CLAUDE_CODE_TST_NAMES_IN_MESSAGES` | — | Show teammate names in messages |
-| `CLAUDE_CODE_EAGER_FLUSH` | — | Flush output eagerly (reduces perceived latency) |
+| Variable                                        | Default        | What it does                                                      |
+| ----------------------------------------------- | -------------- | ----------------------------------------------------------------- |
+| `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS`          | —              | **Required.** Enables agent teams feature                         |
+| `CLAUDE_CODE_SUBAGENT_MODEL`                    | (parent model) | Model for subagent lookups. Set to `"haiku"` to save money        |
+| `CLAUDE_CODE_AUTOCOMPACT_PCT_OVERRIDE`          | `"80"`         | Context compaction threshold. Lower = more aggressive             |
+| `CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY`          | `"3"`          | Parallel tool calls per agent. Higher = faster but more API usage |
+| `CLAUDE_CODE_GLOB_HIDDEN`                       | —              | Include dotfiles in glob searches                                 |
+| `CLAUDE_CODE_BASH_MAINTAIN_PROJECT_WORKING_DIR` | —              | Keep bash cwd consistent across tool calls                        |
+| `CLAUDE_CODE_EMIT_TOOL_USE_SUMMARIES`           | —              | Show tool use summaries in output                                 |
+| `CLAUDE_CODE_TST_NAMES_IN_MESSAGES`             | —              | Show teammate names in messages                                   |
+| `CLAUDE_CODE_EAGER_FLUSH`                       | —              | Flush output eagerly (reduces perceived latency)                  |
 
 ---
 
@@ -290,14 +298,17 @@ started_at: 2026-02-07T10:00:00Z
 ---
 
 ## Completed
+
 - [x] Scanned existing auth patterns
 - [x] Built User model
 
 ## In Progress
+
 - [ ] JWT route handlers
 - [ ] React login components
 
 ## Blocked
+
 - Integration tests blocked on route completion
 ```
 
@@ -306,6 +317,7 @@ started_at: 2026-02-07T10:00:00Z
 Each agent writes findings/results to a file in this directory. The team lead reads all outputs between waves.
 
 **Add to `.gitignore`:**
+
 ```
 .claude/team-state.local.md
 .claude/team-outputs/
@@ -313,19 +325,19 @@ Each agent writes findings/results to a file in this directory. The team lead re
 
 ### When to Use Waves vs. Single-Pass Teams
 
-| Situation | Approach |
-|-----------|----------|
-| Independent tasks with clear file ownership | Single-pass team — spawn agents, collect results |
-| Tasks that require iteration (tests must pass, errors must be fixed) | Wave pattern — iterate until completion criteria met |
-| Exploratory work that builds on previous findings | Wave pattern — each wave goes deeper based on last wave's results |
-| Simple parallel review (code quality + security + tests) | Single-pass team — each reviewer works independently |
+| Situation                                                            | Approach                                                          |
+| -------------------------------------------------------------------- | ----------------------------------------------------------------- |
+| Independent tasks with clear file ownership                          | Single-pass team — spawn agents, collect results                  |
+| Tasks that require iteration (tests must pass, errors must be fixed) | Wave pattern — iterate until completion criteria met              |
+| Exploratory work that builds on previous findings                    | Wave pattern — each wave goes deeper based on last wave's results |
+| Simple parallel review (code quality + security + tests)             | Single-pass team — each reviewer works independently              |
 
 ### Quick Reference: Five Wave Patterns
 
-| Pattern | Waves | Agents | Best For |
-|---------|-------|--------|----------|
-| [Feature Implementation](patterns/feature-implementation.md) | 3-4 | 2-3 | Multi-component features |
-| [Research & Exploration](patterns/research-exploration.md) | 2-3 | 2-3 | Understanding codebases |
-| [Test Generation](patterns/test-generation.md) | 3-4+ | 2-3 | Coverage campaigns |
-| [Refactoring](patterns/refactoring.md) | 3-4 | 2 | Large-scale transformations |
-| [Bug Hunt](patterns/bug-hunt.md) | 3-4 | 2-3 | Complex, elusive bugs |
+| Pattern                                                      | Waves | Agents | Best For                    |
+| ------------------------------------------------------------ | ----- | ------ | --------------------------- |
+| [Feature Implementation](patterns/feature-implementation.md) | 3-4   | 2-3    | Multi-component features    |
+| [Research & Exploration](patterns/research-exploration.md)   | 2-3   | 2-3    | Understanding codebases     |
+| [Test Generation](patterns/test-generation.md)               | 3-4+  | 2-3    | Coverage campaigns          |
+| [Refactoring](patterns/refactoring.md)                       | 3-4   | 2      | Large-scale transformations |
+| [Bug Hunt](patterns/bug-hunt.md)                             | 3-4   | 2-3    | Complex, elusive bugs       |

package/docs/patterns/README.md

@@ -18,6 +18,7 @@ Wave 1: Research       Wave 2: Build           Wave 3: Integrate
 ```
 
 Each wave:
+
 1. **Assess** — What did the previous wave accomplish? What failed?
 2. **Decompose** — What can be done in parallel now?
 3. **Spawn** — Launch agents in tmux panes for each independent task
@@ -27,13 +28,13 @@ Each wave:
 
 ## Available Patterns
 
-| Pattern | When to Use | Typical Waves | Team Size |
-|---------|-------------|---------------|-----------|
-| [Feature Implementation](feature-implementation.md) | Building multi-component features | 3-4 | 2-3 agents |
-| [Research & Exploration](research-exploration.md) | Understanding a codebase or problem space | 2-3 | 2-3 agents |
-| [Test Generation](test-generation.md) | Comprehensive test coverage campaigns | 3-4+ | 2-3 agents |
-| [Refactoring](refactoring.md) | Large-scale code transformations | 3-4 | 2 agents |
-| [Bug Hunt](bug-hunt.md) | Tracking down complex, elusive bugs | 3-4 | 2-3 agents |
+| Pattern                                             | When to Use                               | Typical Waves | Team Size  |
+| --------------------------------------------------- | ----------------------------------------- | ------------- | ---------- |
+| [Feature Implementation](feature-implementation.md) | Building multi-component features         | 3-4           | 2-3 agents |
+| [Research & Exploration](research-exploration.md)   | Understanding a codebase or problem space | 2-3           | 2-3 agents |
+| [Test Generation](test-generation.md)               | Comprehensive test coverage campaigns     | 3-4+          | 2-3 agents |
+| [Refactoring](refactoring.md)                       | Large-scale code transformations          | 3-4           | 2 agents   |
+| [Bug Hunt](bug-hunt.md)                             | Tracking down complex, elusive bugs       | 3-4           | 2-3 agents |
 
 ---
 
@@ -52,18 +53,22 @@ started_at: 2026-02-07T10:00:00Z
 ---
 
 ## Completed
+
 - [x] Scanned existing auth patterns
 - [x] Identified middleware structure
 - [x] Built User model
 
 ## In Progress
+
 - [ ] JWT route handlers
 - [ ] Login/signup React components
 
 ## Blocked
+
 - None
 
 ## Agent Outputs
+
 - wave-1-scan-auth.md — Existing auth analysis
 - wave-1-scan-deps.md — Dependency audit
 - wave-2-model.md — User model implementation notes
@@ -79,7 +84,7 @@ Each agent writes its results to a markdown file in this directory. The team lea
 
 ## Quick Start
 
-Pick a pattern, then use `shipwright` (alias: `cct`, `sw`) to set up the team:
+Pick a pattern, then use `shipwright` (alias: `sw`, `cct`) to set up the team:
 
 ```bash
 # Start a tmux session
@@ -97,32 +102,37 @@ shipwright session my-feature
 ## Key Principles
 
 ### 1. Parallel Everything
+
 If two tasks don't depend on each other, run them at the same time in separate panes. The whole point of waves is maximizing parallel throughput.
 
 ### 2. Synthesize Between Waves
+
 Don't just fire-and-forget. After each wave, the team lead reads all agent outputs, identifies gaps, and adjusts the plan. This is where the real value happens.
 
 ### 3. Iterate Until Done
+
 Waves repeat until the goal is met. Failed tasks get retried with better instructions. Each wave builds on the last. Set a reasonable max (5-10 waves for most tasks).
 
 ### 4. File-Based State Is the Source of Truth
+
 The `.claude/team-state.local.md` file tracks what's done, what's pending, and what's blocked. Agents update their output files; the team lead updates the state file.
 
 ### 5. Keep Teams Small
+
 2-3 agents per team. More agents means more tmux panes, more coordination overhead, and more risk of file conflicts. The sweet spot is 2-3 focused agents.
 
 ---
 
 ## Anti-Patterns
 
-| Don't | Why | Instead |
-|-------|-----|---------|
-| Spawn 5+ agents per wave | Coordination overhead, race conditions | 2-3 agents per wave |
-| Skip synthesis between waves | You'll lose track of progress and duplicate work | Always read outputs and update state |
-| Give vague task descriptions | Agents waste context figuring out what to do | Be specific: files, functions, acceptance criteria |
-| Let agents touch overlapping files | One will overwrite the other's changes | Partition files by agent |
-| Keep iterating when stuck | Wastes tokens and your time | After 3 failed attempts, rethink the approach |
-| Use waves for trivial tasks | Overhead exceeds benefit | Just do it in a single agent |
+| Don't                              | Why                                              | Instead                                            |
+| ---------------------------------- | ------------------------------------------------ | -------------------------------------------------- |
+| Spawn 5+ agents per wave           | Coordination overhead, race conditions           | 2-3 agents per wave                                |
+| Skip synthesis between waves       | You'll lose track of progress and duplicate work | Always read outputs and update state               |
+| Give vague task descriptions       | Agents waste context figuring out what to do     | Be specific: files, functions, acceptance criteria |
+| Let agents touch overlapping files | One will overwrite the other's changes           | Partition files by agent                           |
+| Keep iterating when stuck          | Wastes tokens and your time                      | After 3 failed attempts, rethink the approach      |
+| Use waves for trivial tasks        | Overhead exceeds benefit                         | Just do it in a single agent                       |
 
 ---
 
@@ -130,10 +140,10 @@ The `.claude/team-state.local.md` file tracks what's done, what's pending, and w
 
 Choose the right model for each agent's task:
 
-| Task Type | Model | Why |
-|-----------|-------|-----|
-| File search, simple lookups | `haiku` | Fast, cheap |
-| Implementation, clear requirements | `sonnet` | Balanced speed/quality |
-| Architecture decisions, complex debugging | `opus` | Best reasoning |
-| Test generation | `sonnet` | Good pattern matching |
-| Documentation, reports | `sonnet` | Clear writing |
+| Task Type                                 | Model    | Why                    |
+| ----------------------------------------- | -------- | ---------------------- |
+| File search, simple lookups               | `haiku`  | Fast, cheap            |
+| Implementation, clear requirements        | `sonnet` | Balanced speed/quality |
+| Architecture decisions, complex debugging | `opus`   | Best reasoning         |
+| Test generation                           | `sonnet` | Good pattern matching  |
+| Documentation, reports                    | `sonnet` | Clear writing          |

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "shipwright-cli",
-  "version": "1.7.1",
+  "version": "1.9.0",
   "description": "Orchestrate autonomous Claude Code agent teams in tmux",
   "bin": {
-    "shipwright": "./scripts/cct",
-    "sw": "./scripts/cct"
+    "shipwright": "./scripts/sw",
+    "sw": "./scripts/sw",
+    "cct": "./scripts/sw"
   },
   "files": [
     "scripts/",
@@ -16,8 +17,11 @@
     "templates/",
     "tmux/templates/",
     "tmux/tmux.conf",
-    "tmux/claude-teams-overlay.conf",
+    "tmux/shipwright-overlay.conf",
+    "dashboard/",
     "claude-code/",
+    ".claude/agents/",
+    ".claude/hooks/",
     "completions/",
     "docs/",
     "LICENSE",
@@ -25,7 +29,7 @@
   ],
   "scripts": {
     "postinstall": "node scripts/postinstall.mjs",
-    "test": "bash scripts/cct-pipeline-test.sh && bash scripts/cct-daemon-test.sh && bash scripts/cct-prep-test.sh && bash scripts/cct-fleet-test.sh && bash scripts/cct-fix-test.sh && bash scripts/cct-memory-test.sh"
+    "test": "bash scripts/sw-pipeline-test.sh && bash scripts/sw-daemon-test.sh && bash scripts/sw-prep-test.sh && bash scripts/sw-fleet-test.sh && bash scripts/sw-fix-test.sh && bash scripts/sw-memory-test.sh && bash scripts/sw-session-test.sh && bash scripts/sw-init-test.sh && bash scripts/sw-tracker-test.sh && bash scripts/sw-heartbeat-test.sh && bash scripts/sw-remote-test.sh && bash scripts/sw-intelligence-test.sh && bash scripts/sw-pipeline-composer-test.sh && bash scripts/sw-self-optimize-test.sh && bash scripts/sw-predictive-test.sh && bash scripts/sw-frontier-test.sh && bash scripts/sw-connect-test.sh && bash scripts/sw-github-graphql-test.sh && bash scripts/sw-github-checks-test.sh && bash scripts/sw-github-deploy-test.sh && bash scripts/sw-docs-test.sh && bash scripts/sw-tmux-test.sh"
   },
   "keywords": [
     "claude",

package/scripts/adapters/iterm2-adapter.sh

@@ -4,7 +4,7 @@
 # ║                                                                          ║
 # ║  Uses AppleScript (osascript) to create iTerm2 tabs with named titles   ║
 # ║  and working directories. macOS only.                                    ║
-# ║  Sourced by cct-session.sh — exports: spawn_agent, list_agents,         ║
+# ║  Sourced by sw-session.sh — exports: spawn_agent, list_agents,         ║
 # ║  kill_agent, focus_agent.                                                ║
 # ╚═══════════════════════════════════════════════════════════════════════════╝
 

package/scripts/adapters/tmux-adapter.sh

@@ -3,37 +3,52 @@
 # ║  tmux-adapter.sh — Terminal adapter for tmux pane management            ║
 # ║                                                                          ║
 # ║  Default adapter. Creates tmux panes within a named window.             ║
-# ║  Sourced by cct-session.sh — exports: spawn_agent, list_agents,         ║
+# ║  Sourced by sw-session.sh — exports: spawn_agent, list_agents,         ║
 # ║  kill_agent, focus_agent.                                                ║
+# ║                                                                          ║
+# ║  Uses pane IDs (%N) instead of indices to avoid the pane-base-index    ║
+# ║  bug where teammate instructions are sent to wrong panes when           ║
+# ║  pane-base-index != 0. See: claude-code#23527                          ║
 # ╚═══════════════════════════════════════════════════════════════════════════╝
 
-# Track spawned panes by agent name
-declare -A _TMUX_AGENT_PANES
+# Track spawned panes by agent name → pane ID (file-based for bash 3.2 compat)
+_TMUX_PANE_MAP="${TMPDIR:-/tmp}/shipwright-tmux-pane-map.$$"
+: > "$_TMUX_PANE_MAP"
+trap 'rm -f "$_TMUX_PANE_MAP"' EXIT
 
 spawn_agent() {
     local name="$1"
     local working_dir="${2:-#{pane_current_path}}"
     local command="${3:-}"
 
-    # If no window exists yet, create one
+    local new_pane_id=""
+
+    # If no window exists yet, create one and capture the pane ID
     if ! tmux list-windows -F '#W' 2>/dev/null | grep -qx "$WINDOW_NAME"; then
-        tmux new-window -n "$WINDOW_NAME" -c "$working_dir"
+        # -P prints the new pane's ID (e.g. %5)
+        new_pane_id=$(tmux new-window -n "$WINDOW_NAME" -c "$working_dir" -P -F '#{pane_id}')
     else
-        # Split the current window to add a pane
-        tmux split-window -t "$WINDOW_NAME" -c "$working_dir"
+        # Split the current window and capture the new pane ID
+        new_pane_id=$(tmux split-window -t "$WINDOW_NAME" -c "$working_dir" -P -F '#{pane_id}')
     fi
 
+    # Record the mapping: name → pane_id
+    echo "${name}=${new_pane_id}" >> "$_TMUX_PANE_MAP"
+
     sleep 0.1
 
-    # Set the pane title
-    tmux send-keys -t "$WINDOW_NAME" "printf '\\033]2;${name}\\033\\\\'" Enter
+    # Set the pane title using the stable pane ID (not index)
+    tmux send-keys -t "$new_pane_id" "printf '\\033]2;${name}\\033\\\\'" Enter
     sleep 0.1
-    tmux send-keys -t "$WINDOW_NAME" "clear" Enter
+    tmux send-keys -t "$new_pane_id" "clear" Enter
+
+    # Apply dark theme to the new pane
+    tmux select-pane -t "$new_pane_id" -P 'bg=#1a1a2e,fg=#e4e4e7' 2>/dev/null || true
 
     # Run the command if provided
     if [[ -n "$command" ]]; then
         sleep 0.1
-        tmux send-keys -t "$WINDOW_NAME" "$command" Enter
+        tmux send-keys -t "$new_pane_id" "$command" Enter
     fi
 
     # Re-tile after adding each pane
@@ -41,9 +56,9 @@ spawn_agent() {
 }
 
 list_agents() {
-    # List all panes in the window with their titles
+    # List all panes in the window with their titles and IDs
     if tmux list-windows -F '#W' 2>/dev/null | grep -qx "$WINDOW_NAME"; then
-        tmux list-panes -t "$WINDOW_NAME" -F '#{pane_index}: #{pane_title} (#{pane_current_command})' 2>/dev/null
+        tmux list-panes -t "$WINDOW_NAME" -F '#{pane_id}: #{pane_title} (#{pane_current_command})' 2>/dev/null
     fi
 }
 
@@ -54,10 +69,17 @@ kill_agent() {
         return 1
     fi
 
-    # Find the pane with the matching title
-    local pane_id
-    pane_id=$(tmux list-panes -t "$WINDOW_NAME" -F '#{pane_id} #{pane_title}' 2>/dev/null \
-        | grep " ${name}$" | head -1 | cut -d' ' -f1)
+    # First try: look up from our pane map
+    local pane_id=""
+    if [[ -f "$_TMUX_PANE_MAP" ]]; then
+        pane_id=$(grep "^${name}=" "$_TMUX_PANE_MAP" 2>/dev/null | tail -1 | cut -d= -f2) || true
+    fi
+
+    # Fallback: find the pane with the matching title (handles external spawns)
+    if [[ -z "$pane_id" ]]; then
+        pane_id=$(tmux list-panes -t "$WINDOW_NAME" -F '#{pane_id} #{pane_title}' 2>/dev/null \
+            | grep " ${name}$" | head -1 | cut -d' ' -f1) || true
+    fi
 
     if [[ -n "$pane_id" ]]; then
         tmux kill-pane -t "$pane_id"
@@ -73,14 +95,21 @@ focus_agent() {
         return 1
     fi
 
-    # Find the pane with the matching title
-    local pane_index
-    pane_index=$(tmux list-panes -t "$WINDOW_NAME" -F '#{pane_index} #{pane_title}' 2>/dev/null \
-        | grep " ${name}$" | head -1 | cut -d' ' -f1)
+    # First try: look up from our pane map
+    local pane_id=""
+    if [[ -f "$_TMUX_PANE_MAP" ]]; then
+        pane_id=$(grep "^${name}=" "$_TMUX_PANE_MAP" 2>/dev/null | tail -1 | cut -d= -f2) || true
+    fi
 
-    if [[ -n "$pane_index" ]]; then
+    # Fallback: find the pane by title
+    if [[ -z "$pane_id" ]]; then
+        pane_id=$(tmux list-panes -t "$WINDOW_NAME" -F '#{pane_id} #{pane_title}' 2>/dev/null \
+            | grep " ${name}$" | head -1 | cut -d' ' -f1) || true
+    fi
+
+    if [[ -n "$pane_id" ]]; then
         tmux select-window -t "$WINDOW_NAME"
-        tmux select-pane -t "$WINDOW_NAME.$pane_index"
+        tmux select-pane -t "$pane_id"
         return 0
     fi
     return 1

package/scripts/adapters/wezterm-adapter.sh

@@ -4,7 +4,7 @@
 # ║                                                                          ║
 # ║  Uses `wezterm cli` to spawn panes/tabs with named titles and working   ║
 # ║  directories. Cross-platform.                                            ║
-# ║  Sourced by cct-session.sh — exports: spawn_agent, list_agents,         ║
+# ║  Sourced by sw-session.sh — exports: spawn_agent, list_agents,         ║
 # ║  kill_agent, focus_agent.                                                ║
 # ╚═══════════════════════════════════════════════════════════════════════════╝
 
@@ -14,8 +14,10 @@ if ! command -v wezterm &>/dev/null; then
     exit 1
 fi
 
-# Track spawned pane IDs for agent management
-declare -A _WEZTERM_AGENT_PANES
+# Track spawned pane IDs for agent management (file-based for bash 3.2 compat)
+_WEZTERM_PANE_MAP="${TMPDIR:-/tmp}/shipwright-wezterm-pane-map.$$"
+: > "$_WEZTERM_PANE_MAP"
+trap 'rm -f "$_WEZTERM_PANE_MAP"' EXIT
 
 spawn_agent() {
     local name="$1"
@@ -30,12 +32,16 @@ spawn_agent() {
     local pane_id
 
     # Spawn a new pane in the current tab (split right by default)
-    if [[ ${#_WEZTERM_AGENT_PANES[@]} -eq 0 ]]; then
+    local pane_count
+    pane_count=$(wc -l < "$_WEZTERM_PANE_MAP" 2>/dev/null | tr -d ' ')
+    pane_count="${pane_count:-0}"
+    if [[ "$pane_count" -eq 0 ]]; then
         # First agent: create a new tab
         pane_id=$(wezterm cli spawn --cwd "$working_dir" 2>/dev/null)
     else
         # Subsequent agents: split from the first pane
-        local first_pane="${_WEZTERM_AGENT_PANES[${!_WEZTERM_AGENT_PANES[*]}]}"
+        local first_pane
+        first_pane=$(head -1 "$_WEZTERM_PANE_MAP" 2>/dev/null | cut -d= -f2-)
         pane_id=$(wezterm cli split-pane --cwd "$working_dir" --right --pane-id "${first_pane:-0}" 2>/dev/null) || \
         pane_id=$(wezterm cli split-pane --cwd "$working_dir" --bottom 2>/dev/null)
     fi
@@ -45,8 +51,8 @@ spawn_agent() {
         return 1
     fi
 
-    # Store mapping
-    _WEZTERM_AGENT_PANES["$name"]="$pane_id"
+    # Store mapping (file-based)
+    echo "${name}=${pane_id}" >> "$_WEZTERM_PANE_MAP"
 
     # Set the pane title
     wezterm cli set-tab-title --pane-id "$pane_id" "$name" 2>/dev/null || true
@@ -70,30 +76,36 @@ list_agents() {
     done
 
     # Also show our tracked agents
-    if [[ ${#_WEZTERM_AGENT_PANES[@]} -gt 0 ]]; then
+    if [[ -s "$_WEZTERM_PANE_MAP" ]]; then
         echo ""
         echo "Tracked agents:"
-        for name in "${!_WEZTERM_AGENT_PANES[@]}"; do
-            echo "  ${name} → pane ${_WEZTERM_AGENT_PANES[$name]}"
-        done
+        while IFS='=' read -r _name _pid; do
+            echo "  ${_name} → pane ${_pid}"
+        done < "$_WEZTERM_PANE_MAP"
     fi
 }
 
 kill_agent() {
     local name="$1"
-    local pane_id="${_WEZTERM_AGENT_PANES[$name]:-}"
+    local pane_id
+    pane_id=$(grep "^${name}=" "$_WEZTERM_PANE_MAP" 2>/dev/null | head -1 | cut -d= -f2-)
 
     if [[ -z "$pane_id" ]]; then
         return 1
     fi
 
     wezterm cli kill-pane --pane-id "$pane_id" 2>/dev/null
-    unset '_WEZTERM_AGENT_PANES[$name]'
+    # Remove entry from pane map
+    local _tmp
+    _tmp=$(mktemp)
+    grep -v "^${name}=" "$_WEZTERM_PANE_MAP" > "$_tmp" 2>/dev/null || true
+    mv "$_tmp" "$_WEZTERM_PANE_MAP"
 }
 
 focus_agent() {
     local name="$1"
-    local pane_id="${_WEZTERM_AGENT_PANES[$name]:-}"
+    local pane_id
+    pane_id=$(grep "^${name}=" "$_WEZTERM_PANE_MAP" 2>/dev/null | head -1 | cut -d= -f2-)
 
     if [[ -z "$pane_id" ]]; then
         return 1