[Juliusolsson05]

Closes #120. Companion to #119 (mitmdump bundling). With this merged, both core helpers ship inside packaged Agent Code — no Homebrew install required for proxy streaming or terminal-pane persistence.

Key design decision

The original plan for #120 was to build static tmux from source (tmux + libevent + ncurses + utf8proc), which the review-agent on #121 flagged as the higher-risk of the two bundling efforts because of ncurses terminfo and utf8proc static-linking gotchas.

Research turned up tmux/tmux-builds — the official upstream prebuilt-binary repo maintained by the tmux project itself. macOS binaries:

• 1.6 MB single binary, no archive structure beyond a one-file tar.gz
• Link ONLY to `/usr/lib/libSystem.B.dylib` and `/usr/lib/libresolv.9.dylib` (verified with `otool -L`)
• Pass the full lifecycle proof from the review (`tmux -V`, `new-session`, `send-keys`, `capture-pane` returning `term=tmux-256color cols=80`, `kill-session`) cleanly without external dependencies
• Maintained on the upstream tmux project's own CI

Owning a custom static build for what already exists upstream is unnecessary maintenance, so this PR adopts the upstream artifact as-is. The static-build path stays documented in case upstream ever stops publishing.

Repo plumbing

Bundled artifact (mirrors mitmproxy's shape from #119)

• `third_party/tmux/manifest.json` — pins `tmux 3.6a`, per-arch archive sha256 + bytes
• `third_party/tmux/README.md` — updated from PR-1 stub to real description, including upstream sourcing rationale
• `third_party/tmux/LICENSE.md` — tmux ISC, unchanged
• `third_party/tmux/.gitignore` — `cache/` excluded
• `scripts/runtime-tools/fetch-tmux.mjs` — downloads pinned archive, sha256-verifies, extracts inner binary, chmod +x, discards archive. Idempotent via a `tmux -V` cache hit.
• `scripts/runtime-tools/verify-tmux.mjs` — verifies binary is executable, `tmux -V` matches the pin, and `otool -L` shows NO Homebrew dylib linkage. Strict mode is the CI gate.
• `scripts/runtime-tools/build-tmux.mjs` — deleted. No longer needed.
• `package.json` — `runtime:build:tmux` → `runtime:fetch:tmux`; `runtime:prepare:mac` now fetches + strict-verifies both tools.

Runtime resolver

• `src/main/setup/runtimeTools.ts` — `resolveBundledTool('tmux')` and `isBundledArchiveAvailable('tmux')` implemented. Because tmux is a single binary, the resolver returns the asar-unpacked path directly — no extraction, no userData copy, no install marker (unlike mitmproxy's multi-file .app, which needs atomic temp+rename). Defensive `chmod 0o755` on each call rules out electron-builder signing dropping the executable bit.

Wiring

• `src/main/tmux/TmuxRegistry.ts` — adds `getBinary()` accessor.
• `src/main/index.ts` — `new TmuxRegistry({ tmuxBinary: await resolveBundledTool('tmux') })`. Bundled-only: no `getToolPath('tmux', 'tmux')` fallback. If the binary is missing, tmux availability resolves to false and terminals fall back to direct PTY — same behaviour as a machine without tmux. No silent system-tmux usage.
• `src/main/sessionManager.ts` — threads `tmuxRegistry.getBinary()` into `TerminalSession` so attach-as-child-PTY uses the SAME binary the registry used for `new-session`.

Setup-gate cleanup

• `src/shared/types/setup.ts` — `'tmux'` removed from `SetupToolId` and `SetupInstallTarget`.
• `src/main/setup/prerequisites.ts` — drops tmux from `TOOL_META` and `CHECK_ORDER`. Bundled tools are not a user-installable concept.
• `src/main/setup/binaryResolver.ts` / `homebrewInstaller.ts` / `ipc/setup.ts` — drop the tmux entries.
• `src/renderer/src/features/setup/ui/SetupGate.tsx` — drops the tmux row.

Verification

• `npm run runtime:fetch:tmux -- --all` — clean, both arches.
• `npm run runtime:verify:tmux -- --strict` — `darwin-arm64` reports `(3.6a, no Homebrew linkage)`; `darwin-x86_64` presence-only OK (can't run cross-arch `tmux -V` from arm64).
• `npm run build:app` — clean. `out/main/runtime/tmux//tmux` lands at a real filesystem path with the executable bit set.
• Lifecycle proof against the upstream binary (the review-agent's risk gate): `tmux -L probe new-session -d -s t /bin/zsh` → `send-keys 'echo $TERM cols=$(tput cols)'` → `capture-pane` returns `term=tmux-256color cols=80`. Terminfo works out of the box. `kill-session` clean.

Size impact

DMG grows by ~1.3 MiB total (`tmux-3.6a-macos-arm64.tar.gz` 624 KB + `tmux-3.6a-macos-x86_64.tar.gz` 650 KB). No userData footprint — we spawn from the asar-unpacked path directly.

Follow-up

A separate cleanup PR will give mitmproxy the same treatment (drop the setup-gate visibility + PATH fallback now that the bundled artifact is canonical, per the discussion that motivated this PR's setup-gate cleanup). tmux landed first because #120 demanded it; mitmproxy was already bundled in #119, so the cleanup is a pure "remove redundant fallback" change.

Test plan

• Run packaged app on a clean macOS profile without Homebrew tmux installed → terminals persist across restarts.
• Run in dev with `npm run runtime:prepare:mac` → bundled tmux is used; `ps` / `lsof` shows the spawn comes from `out/main/runtime/tmux/darwin-arm64/tmux`.
• Run in dev WITHOUT `runtime:prepare:mac` → tmux availability is false, terminals fall back to direct PTY, no silent Homebrew-tmux usage.
• SetupGate visual: tmux row gone.

🤖 Generated with Claude Code

[Juliusolsson05]

Pushed a63e558 addressing the three findings from the review.

1. Cross-arch binary execution → hash-based identity (fetch-tmux.mjs, verify-tmux.mjs, third_party/tmux/manifest.json)

Pinned binarySha256 per platform alongside the archive hash. All identity checks — cache-hit detection, post-extract validation, cross-arch strict verification — are now hash-based and platform-agnostic. No more tmux -V spawn on the non-native arch, so a clean Apple-Silicon CI host without Rosetta can now legitimately validate the x86_64 artifact it just downloaded.

2. Loose cross-arch verification → real cross-arch verification (verify-tmux.mjs)

Same fix as #1. Strict mode's darwin-x86_64 row now reports OK (hash matches; cross-arch) instead of presence-only. A corrupted or swapped cross-arch binary that previously slipped past strict will now fail it. The native arch keeps the additional tmux -V + otool -L smoke checks layered on top of the hash gate.

3. Sentinel path → genuine optional (src/main/tmux/TmuxRegistry.ts, src/main/index.ts, src/main/sessionManager.ts)

Replaced the 'tmux-bundled-missing' sentinel. TmuxRegistry.tmuxBinary is now genuinely optional; when undefined, detectAvailability() short-circuits to false without spawning anything. getBinary() returns string | null. src/main/index.ts passes undefined when resolveBundledTool('tmux') returns null. Zero PATH lookups, zero spawn attempts, zero name-collision risk.

Also softened the chmod 0o755 comment in resolveTmux per your note — it no longer claims electron-builder definitively drops the exec bit, just frames the defensive chmod as a cheap safety net.

Verification on this commit

• npm run runtime:fetch:tmux -- --all: both arches hit the new content-hash cache path on rerun (no binary spawn).
• npm run runtime:verify:tmux -- --strict:
  • darwin-arm64: OK (3.6a, hash + linkage clean)
  • darwin-x86_64: OK (hash matches; cross-arch)
• npm run build:app: clean.

Pre-merge test plan items (clean-packaged-app, dev-without-prepare, SetupGate visual) still owed per your review.