feat: make the wmux CLI work out of the box in agent shells (PATH cli-bin) - #75

The problem we hit

We use wmux heavily for Claude Code multi-agent orchestration — it's become our daily driver for exactly the workflow the README describes. But on a fresh install, orchestration silently degrades: spawn-agents.sh prints "WARNING: wmux not found in PATH" and falls back to subagent mode, and the coordinator's own wmux calls fail. The only way we could make it work as-is was hand-writing shims into ~/.local/bin and adding that to PATH on every machine.

Root cause

The orchestrator (and Claude Code itself) invokes bare wmux from non-interactive shells — Claude Code's Bash tool and the plugin's hook scripts run bash -c, not an interactive pane shell. wmux currently exposes the CLI two ways, and neither reaches that context:

1. $WMUX_CLI — injected into every spawned shell's env, but nothing that calls bare wmux reads it.
2. The wmux shell function — dot-sourced by the shell-integration scripts into the pane's interactive shell only. Shell functions don't propagate to bash -c children.

(You can't fix it by putting the install folder on PATH either: wmux.exe shadows any wmux.cmd via PATHEXT ordering, so wmux <command> would launch the GUI.)

The fix

PtyManager prepends a bundled cli-bin/ directory — containing tiny wmux (bash) and wmux.cmd (cmd) shims that just run node "$WMUX_CLI" — to PATH in the env it already builds for every spawned shell. PATH inherits down the entire process tree regardless of shell/login/interactive state, which is exactly what the shell function can't do. So bare wmux resolves everywhere: Claude Code's Bash tool, orchestrator hooks, cmd, PowerShell, Git Bash.

• No PATHEXT collision — cli-bin/ contains no wmux.exe.
• No behavior change in panes — the interactive wmux function still shadows the PATH shim (function > PATH).
• Instance-correct — the shims prefer $WMUX_CLI/$WMUX_PIPE from the spawning instance.
• Zero user setup: unzip → run wmux.exe → orchestration works.

Changes:

• src/main/pty-manager.ts — getCliBinPath() + case-insensitive PATH prepend (the Windows env key is Path).
• src/cli-bin/{wmux,wmux.cmd} — the shims; .gitattributes forces LF on the bash one.
• electron-builder.json — ship src/cli-bin → resources/cli-bin via extraResources.
• resources/wmux-orchestrator/scripts/wmux-resolve.sh (+ sourced from orchestration-state.sh / detect-wmux.sh) — a defense-in-depth fallback for the bundled plugin: if wmux still isn't on PATH (older wmux), it defines wmux() { node "$WMUX_CLI" "$@"; }, which also makes the existing command -v wmux guards pass. We're submitting the same fallback to the standalone wmux-orchestrator repo so plugin users on current wmux releases get working orchestration immediately.

Verification

• With cli-bin prepended and our ~/.local/bin shims deleted, a non-interactive bash -c resolves wmux to the cli-bin shim and wmux ping → pong via $WMUX_CLI.
• With wmux off PATH entirely, sourcing wmux-resolve.sh makes detect-wmux.sh report available and wmux ping → pong.
• Running this build daily: real Claude Code orchestration spawns panes, hooks update the dashboard, and the coordinator drives wmux — with no shims installed anywhere.
• build:main + vite build clean; all tests pass (158/158).

Also: orchestration lessons learned, folded into the distributed skills

We have been running heavy multi-agent Claude Code orchestrations on wmux, and this PR also contributes that operating knowledge back into the distributed skills so they match how orchestration actually behaves:

• skills/orchestrate Phase 7 (monitoring) corrected — the completion signal is the agent's result file, not process exit: launch-agent.js runs agents interactively, so a finished agent idles at its TUI and never exits, and the previous "poll wmux agent list for exited" loop never terminates. The skill now polls result files, and documents that the coordinator owns state.json (Claude Code Stop/SubagentStop hooks don't fire for wmux-spawned agents) using the status vocabulary the sidebar actually counts (exited for agents, complete for waves/run).
• Consistent agent ids — bare ids ("a", not "agent-a"): the scripts prefix agent- themselves, so the old schema example produced double-prefixed prompt/result filenames the launcher couldn't find.
• Windows reliability notes — align TMPDIR with the temp dir the sidebar watches (Git Bash), forward-slash paths in state.json (backslashes are invalid JSON escapes and freeze the cockpit), retry reads that race the app's 1 s poller.
• Pane hygiene — start each run from a single coordinator pane (re-gridding over leftover panes orphans their surfaces as dead tabs), collapse after; wmux send targets the caller's own surface by default (use --surface); agent kill doesn't kill agents' child processes (sweep orphaned dev-server ports).
• New skills/orchestrate/references/browser-driving.md — field recipes for agents driving the browser panel: bare eN refs, the single persistent eval scope (IIFE), snapshot parsing, React/Radix synthetic-event input recipes, the transient-UI polling caveat, and the port-9222 CDP collision warning.