patchwork-os 0.2.0-beta.1 → 0.2.0-beta.3

package/README.bridge.md

@@ -5,7 +5,7 @@
 [![Docker](https://img.shields.io/badge/docker-ghcr.io%2FOolab--labs%2Fclaude--ide--bridge-blue)](https://github.com/Oolab-labs/claude-ide-bridge/pkgs/container/claude-ide-bridge)
 [![License: MIT](https://img.shields.io/npm/l/claude-ide-bridge)](https://opensource.org/licenses/MIT)
 
-**MCP bridge giving Claude Code IDE superpowers: 141 tools for LSP, debugging, git, GitHub, terminals, and more.**
+**MCP bridge giving Claude Code IDE superpowers — 170+ tools for LSP, debugging, git, GitHub, terminals, and more (see [platform-docs](documents/platform-docs.md) for the full list).**
 
 A WebSocket bridge between Claude Code CLI and your VS Code extension. Claude sees what your IDE sees — live diagnostics, go-to-definition, call hierarchies, hover types, breakpoints, debugger state — and can act on it: edit files, run tests, commit, open PRs, all without you copy-pasting anything.
 
@@ -192,7 +192,7 @@ claude-ide-bridge start-task "Refactor the auth module for clarity, keep behavio
 claude-ide-bridge continue-handoff
 ```
 
-Requires `--claude-driver subprocess` on the running bridge. All three subcommands accept `--json`, `--port`, `--source`. Enforces a 5s bridge-global cooldown per preset (shared with the sidebar).
+Requires `--driver subprocess` on the running bridge. All three subcommands accept `--json`, `--port`, `--source`. Enforces a 5s bridge-global cooldown per preset (shared with the sidebar).
 
 ---
 
@@ -223,7 +223,7 @@ Event-driven hooks that trigger Claude tasks automatically — no polling, no ma
 
 Start with:
 ```bash
-claude-ide-bridge --watch --automation --automation-policy ./policy.json --claude-driver subprocess
+claude-ide-bridge --watch --automation --automation-policy ./policy.json --driver subprocess
 ```
 
 **18 hook events:** `onFileSave`, `onFileChanged`, `onDiagnosticsError`, `onDiagnosticsCleared`, `onGitCommit`, `onGitPush`, `onGitPull`, `onBranchCheckout`, `onPullRequest`, `onTestRun`, `onTestPassAfterFailure`, `onPostCompact`, `onInstructionsLoaded`, `onTaskCreated`, `onTaskSuccess`, `onPermissionDenied`, `onCwdChanged`, `onDebugSessionEnd`
@@ -299,7 +299,7 @@ claude-ide-bridge install claude-mem
 | `--fixed-token <uuid>` | — | Stable auth token across restarts |
 | `--automation` | off | Enable automation hooks |
 | `--automation-policy <path>` | — | Path to policy JSON |
-| `--claude-driver subprocess` | none | Enable Claude subprocess orchestration |
+| `--driver subprocess` | none | Enable Claude subprocess orchestration |
 | `--plugin <path>` | — | Load a plugin (repeatable) |
 | `--plugin-watch` | off | Hot-reload plugins on change |
 | `--issuer-url <url>` | — | Activate OAuth 2.0 mode |
@@ -314,7 +314,7 @@ claude-ide-bridge install claude-mem
 | File | Description |
 |---|---|
 | [ARCHITECTURE.md](ARCHITECTURE.md) | System topology, request lifecycle, component map, design decisions |
-| [documents/platform-docs.md](documents/platform-docs.md) | Full tool reference — all 141 tools with parameters and examples |
+| [documents/platform-docs.md](documents/platform-docs.md) | Full tool reference — all 170+ tools with parameters and examples |
 | [documents/prompts-reference.md](documents/prompts-reference.md) | All MCP prompts (31 prompts, 12 plugin skills, 4 subagents) |
 | [docs/automation.md](docs/automation.md) | Automation hooks reference — all 18 events, policy schema, condition filters |
 | [docs/troubleshooting.md](docs/troubleshooting.md) | Diagnostics, common errors, and fixes |

package/README.md

@@ -4,7 +4,7 @@
 
 > Patchwork OS is a local-first personal AI runtime: pluggable model providers, hot-reloadable tools, YAML recipes, a delegation policy with approval queue, and a durable trace memory — all running on your machine, all under your policy.
 
-You decide which model. You decide which actions need a human nod. You own the credentials, the logs, and the deployment. Nothing phones home.
+You decide which model. You decide which actions need a human nod. You own the credentials, the logs, and the deployment. Nothing phones home unless you [opt in to anonymous analytics](#telemetry).
 
 **Five primitives, one runtime:**
 
@@ -25,14 +25,38 @@ The same codebase ships **two ways to use it.** Pick the layer you need.
 | | What you get | Install | Best for |
 |---|---|---|---|
 | **🔌 Claude IDE Bridge** | MCP bridge connecting Claude Code to your IDE. 170+ tools — diagnostics, LSP, debugger, terminal, git, GitHub, file ops. | `npm i -g patchwork-os` then run `claude-ide-bridge` | Anyone who wants Claude Code to see and act on their editor state |
-| **🤖 Patchwork OS** | Everything in the bridge **plus** YAML recipes, approval queue, oversight dashboard, mobile push approvals, multi-model providers, JetBrains companion. | Same package, run `patchwork patchwork-init` | Power users running automation, agent workflows, or background tasks |
+| **🤖 Patchwork OS** | Everything in the bridge **plus** YAML recipes, approval queue, oversight dashboard, mobile push approvals, multi-model providers, JetBrains companion. | Same package, run `patchwork init` | Power users running automation, agent workflows, or background tasks |
 
 Same codebase. Bridge is the foundation; Patchwork OS is the optional layer on top. **No vendor lock-in. Runs on your machine.**
 
 ---
 
+## Dashboard Only — No Code Editor Required
+
+> You do not need VS Code, Windsurf, Cursor, or Claude Code CLI to use the Patchwork dashboard.
+
+The dashboard is a standalone Next.js app that communicates with the bridge over HTTP. No editor extension required.
+
+**Prereqs:** [Node.js 20+](https://nodejs.org) · tmux on macOS/Linux (`brew install tmux` / `apt install tmux`) — auto-detected, falls back to background mode if absent. **Windows:** natively supported — no WSL required.
+
+```bash
+npm install -g patchwork-os
+patchwork-os init     # scaffolds ~/.patchwork and generates a dashboard login
+patchwork start       # launches bridge + dashboard (auto-detects tmux; falls back to background mode if absent)
+```
+
+Open **http://localhost:3200** — that's it. `patchwork-os init` auto-generates a dashboard password and saves it to `~/.patchwork/.env` — it prints the password at the end of setup, save it for your first login.
+
+**What you get:** run and schedule YAML recipes, connect external services (Gmail, Calendar, Slack), review AI drafts in the approval queue, read your AI inbox — all from the browser. No coding required.
+
+> **Want IDE features too?** See [Claude IDE Bridge — Quick Start](#-claude-ide-bridge--quick-start) below to add LSP, debugger, and editor tools on top.
+
+---
+
 ## 🔌 Claude IDE Bridge — Quick Start
 
+> Developers only — skip to [Dashboard Only](#dashboard-only--no-code-editor-required) above if you just want the web dashboard.
+
 **Prerequisites:** a supported code editor — **VS Code, Cursor, Windsurf, or Google Antigravity** (or JetBrains via the [companion plugin](#jetbrains-plugin)) — plus Node.js 20+ and the [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code). The bridge's LSP, debugger, and editor-state tools run through the editor extension; without one you're limited to the headless CLI subset.
 
 ```bash
@@ -72,7 +96,20 @@ The bridge runs without any flags. No recipes, no automation, no dashboard — j
 |---|---|
 | Claude Code CLI | WebSocket `ws://127.0.0.1:<port>` |
 | Claude Desktop | stdio shim → WebSocket |
-| Remote (claude.ai, Codex CLI) | Streamable HTTP + Bearer token |
+| Gemini CLI, Codex CLI, claude.ai | Streamable HTTP + Bearer token |
+
+**Connecting Gemini CLI:**
+
+```bash
+# Get the auth token from the bridge's lock file
+patchwork-os print-token
+
+# Add the bridge as an MCP server
+gemini mcp add patchwork http://127.0.0.1:<port>/mcp \
+  --header "Authorization: Bearer <token>"
+```
+
+The bridge auto-responds to the GET probe Gemini sends before initializing, so it shows as **Connected** immediately.
 
 **Tool modes:**
 
@@ -85,10 +122,89 @@ Bridge-only docs: [documents/platform-docs.md](documents/platform-docs.md)
 
 ---
 
+## 🪟 Windows Quick Start
+
+The bridge, VS Code extension, and full Patchwork OS orchestrator (`patchwork start`) all work natively on Windows — no WSL required. A PowerShell-native orchestrator is also available as `npm run start-all:win`.
+
+### Prerequisites
+
+- Node.js 20+ (from [nodejs.org](https://nodejs.org))
+- VS Code, Cursor, or Windsurf
+- [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code)
+- PowerShell 5.1+ (built into Windows 10/11) or PowerShell 7+ (`pwsh`)
+
+### Bridge-only (recommended starting point)
+
+Open **PowerShell** or **cmd.exe**:
+
+```powershell
+# 1. Install
+npm install -g patchwork-os
+
+# 2. Install the VS Code extension
+claude-ide-bridge install-extension
+
+# 3. Start the bridge (bash-free entry point)
+npm run start:bridge
+# or equivalently:
+node "$(npm root -g)/patchwork-os/dist/index.js" --workspace .
+
+# 4. Connect Claude Code (new terminal)
+claude --ide
+```
+
+Type `/ide` in Claude Code to confirm the connection.
+
+### Full orchestrator (bridge + Claude + dashboard)
+
+Two options — both work on Windows, macOS, and Linux:
+
+```powershell
+# Option A: cross-platform Node.js orchestrator (recommended)
+npm run start-all:node
+npm run start-all:node -- --workspace C:\myproj --full --no-dashboard
+
+# Option B: PowerShell-native orchestrator (Windows only, no Node wrapper overhead)
+npm run start-all:win
+npm run start-all:win -- -NoDashboard -Workspace C:\myproj -Full
+```
+
+Both start the bridge, wait for the lock file, launch `claude --ide` and `remote-control`, start the Next.js dashboard on `http://localhost:3200`, poll until it's ready, then open it in your default browser. The health monitor restarts the bridge automatically if it crashes, with exponential backoff.
+
+```powershell
+# Node orchestrator options (--key value form)
+npm run start-all:node -- --full               # all ~170 tools
+npm run start-all:node -- --no-dashboard       # skip dashboard
+npm run start-all:node -- --dashboard-port 3300
+npm run start-all:node -- --no-remote          # skip remote-control
+npm run start-all:node -- --notify my-topic    # ntfy.sh push notifications
+```
+
+### Known limitations on native Windows
+
+| Feature | Status |
+|---|---|
+| Bridge + extension (LSP, debugger, editor state) | ✅ Full support |
+| `npm run start:bridge` | ✅ Supported |
+| `npm run start-all:node` (Node.js orchestrator) | ✅ Supported — cross-platform |
+| `npm run start-all:win` (PS1 orchestrator) | ✅ Supported — Windows-native |
+| Dashboard (`http://localhost:3200`) | ✅ Opens automatically |
+| `patchwork start` / `npm run start-all` | ⚠️ Requires WSL2 or Git Bash (uses bash + tmux) |
+| `npm run remote:node` | ✅ Supported — cross-platform Node auto-restart wrapper |
+| `npm run remote` / `npm run vps` | ⚠️ Requires WSL2 or Git Bash |
+| Screenshot capture (standalone bridge) | ⚠️ Not yet supported; extension screenshot works via VS Code |
+| Credential storage | ✅ Uses DPAPI (Windows Data Protection API) via PowerShell |
+
+### WSL2 alternative
+
+For full Patchwork OS functionality including orchestrator, recipes, and morning-brief, run everything inside WSL2 and install the VS Code Remote-WSL extension. The bridge extension loads on the WSL side automatically (`extensionKind: ["workspace"]`), giving full tool coverage.
+
+---
+
 ## 🤖 Patchwork OS — Quick Start
 
 ```bash
-npx patchwork-os@beta patchwork-init
+npx patchwork-os@beta init
 ```
 
 Sets up 5 local recipes, detects Ollama, and opens a terminal dashboard — under 90 seconds.
@@ -99,7 +215,7 @@ Get an AI digest of your Gmail, calendar, and tasks every morning — or on dema
 
 ```bash
 # First-time setup (connect Gmail + Google Calendar)
-patchwork-os patchwork-init
+patchwork-os init
 patchwork-os connections connect gmail
 patchwork-os connections connect google-calendar
 
@@ -125,15 +241,15 @@ Think of it as a background agent that acts on your behalf — but asks before s
 
 **Recipes** are plain YAML files. They declare a trigger (cron, file save, git commit, test run, webhook) and an action (run a prompt, write to inbox, call a connector). No code required. Share them like dotfiles.
 
-**Models** are yours. Claude, GPT, Gemini, Grok, or local Ollama. Swap at any time. Nothing phones home.
+**Models** are yours. Claude, GPT, Gemini, Grok, or local Ollama. Swap at any time. Nothing phones home unless you opt in (see [Telemetry](#telemetry)).
 
-**Oversight** is non-negotiable. Every write or external action lands in `~/.patchwork/inbox/` for approval. The web UI at `http://localhost:3200` shows pending approvals, live sessions, recipe run history, and analytics.
+**Oversight** is non-negotiable. Every write or external action lands in `~/.patchwork/inbox/` for approval. The web UI at `http://localhost:3200` shows pending approvals, live sessions, recipe run history, and local analytics (the dashboard's analytics panel is computed entirely from on-disk logs — it does not transmit anything).
 
 ### Patchwork commands
 
 ```bash
 # One-command setup: extension + CLAUDE.md + starter recipes
-patchwork patchwork-init
+patchwork init
 
 # Explore
 patchwork recipe list                      # installed recipes
@@ -173,7 +289,7 @@ The package ships these in `templates/recipes/`. Recipes that need API keys are
 
 ### Automation hooks
 
-Event-driven hooks trigger Claude tasks automatically. Activate with `--automation --automation-policy <path.json> --claude-driver subprocess`.
+Event-driven hooks trigger Claude tasks automatically. Activate with `--automation --automation-policy <path.json> --driver subprocess`.
 
 Key hooks:
 
@@ -225,7 +341,7 @@ Use whichever fits your mental model.
 
 ---
 
-## Tool surface (v0.2.0-beta.0)
+## Tool surface
 
 170+ MCP tools across 15 categories. Highlights:
 
@@ -296,7 +412,7 @@ Systemd service and deploy scripts in [`deploy/`](deploy/). Full guide: [docs/re
 | 170+ MCP tools (LSP, git, tests, debugger, diagnostics) | **shipped** |
 | VS Code / Cursor / Windsurf / Antigravity extension | **shipped** |
 | JetBrains plugin (49 handlers) | **shipped** |
-| `patchwork-init` — one-command setup | **shipped** |
+| `patchwork init` — one-command setup | **shipped** |
 | Terminal dashboard | **shipped** |
 | Web oversight UI (approvals, sessions, recipes) | **shipped** |
 | Recipe runner (YAML, cron, manual, webhook) | **shipped** |
@@ -320,11 +436,32 @@ npm install && npm run build
 # Symlink installs break the macOS LaunchAgent (EPERM at startup)
 npm pack
 npm install -g patchwork-os-*.tgz
-patchwork patchwork-init
+patchwork init
 ```
 
 ---
 
+## Telemetry
+
+Patchwork ships an **opt-in** anonymous usage summary. It is **disabled by default** — the bridge sends nothing unless you explicitly turn it on.
+
+**If you opt in**, on bridge shutdown an aggregate summary is POSTed to `https://analytics.claude-ide-bridge.dev/v1/usage`:
+
+- Total session count and total tool-call count (no per-call payloads)
+- Tool name → call count + median/p95 latency, capped at the top-N tools
+- Bridge version, Node version, OS family (`darwin` / `linux` / `win32`)
+- A per-install random salt (regenerated at any time by deleting `~/.claude/ide/analytics-salt`) used to coalesce repeated installs from the same machine without sending machine identifiers
+
+**What is never sent:** workspace paths, file contents, prompts, tool arguments, tool output, project names, git history, credentials, IPs (transport-level only, dropped server-side), or anything from `~/.patchwork/`.
+
+**How to opt in:** set `analyticsEnabled: true` in the dashboard's Settings panel, or write `{"enabled": true, "decidedAt": "<iso>"}` to `~/.claude/ide/analytics.json` (mode 0600).
+
+**How to opt out / stay out:** do nothing. Default state is `null` (no preference) which behaves as opt-out. To explicitly opt out and silence future prompts, write `{"enabled": false, ...}` to the same file.
+
+**Source:** [src/analyticsSend.ts](src/analyticsSend.ts), [src/analyticsAggregator.ts](src/analyticsAggregator.ts), [src/analyticsPrefs.ts](src/analyticsPrefs.ts) — endpoint is hardcoded (not runtime-configurable, by design, to prevent redirect attacks).
+
+---
+
 ## Documentation
 
 | Doc | Contents |
@@ -345,6 +482,13 @@ patchwork patchwork-init
 
 ---
 
+## Support
+
+- **Bugs & feature requests:** [GitHub Issues](https://github.com/Oolab-labs/patchwork-os/issues)
+- **Questions & community:** [GitHub Discussions](https://github.com/Oolab-labs/patchwork-os/discussions)
+
+---
+
 ## License
 
 MIT © Oolab Labs

package/deploy/deploy-dashboard.sh

@@ -39,9 +39,17 @@ echo "==> Copying tarball to VPS..."
 scp "$TARBALL" "$VPS:/tmp/patchwork-dashboard.tar.gz"
 
 echo "==> Deploying on VPS..."
+# Pass secrets as positional args (NOT inside the heredoc body) so the
+# single-quoted heredoc still preserves remote-shell `$X` references but
+# the operator's local env reaches the VPS. Without this, the previous
+# `${PATCHWORK_BRIDGE_TOKEN:-REPLACE_ME}` inside the heredoc evaluated on
+# the remote, where the var doesn't exist, and always wrote REPLACE_ME.
 # shellcheck disable=SC2087
-ssh "$VPS" bash <<'REMOTE'
+ssh "$VPS" bash -s -- "${PATCHWORK_BRIDGE_TOKEN:-REPLACE_ME}" "${DASHBOARD_PASSWORD:-}" <<'REMOTE'
 set -euo pipefail
+# `${N:-}` so an empty/missing positional arg doesn't trip `set -u`.
+PATCHWORK_BRIDGE_TOKEN="${1:-REPLACE_ME}"
+DASHBOARD_PASSWORD="${2:-}"
 REMOTE_DIR="/opt/patchwork-dashboard"
 PM2_NAME="patchwork-dashboard"
 PORT=3200
@@ -52,10 +60,26 @@ if pm2 list | grep -q "$PM2_NAME"; then
   pm2 delete "$PM2_NAME" || true
 fi
 
+# Preserve .env.local across the deploy. Without this stash/restore, the
+# `rm -rf "$REMOTE_DIR"` below blows away every secret the operator pasted
+# (VAPID, PATCHWORK_PUSH_TOKEN, custom DASHBOARD_PASSWORD), and the "if
+# already exists, preserve" branch later in this script never fires —
+# the file no longer exists by then.
+ENV_BACKUP=""
+if [ -f "$REMOTE_DIR/.env.local" ]; then
+  ENV_BACKUP="$(mktemp /tmp/patchwork-env.XXXXXX)"
+  cp -p "$REMOTE_DIR/.env.local" "$ENV_BACKUP"
+fi
+
 # Wipe and recreate deploy dir
 rm -rf "$REMOTE_DIR"
 mkdir -p "$REMOTE_DIR"
 
+if [ -n "$ENV_BACKUP" ] && [ -f "$ENV_BACKUP" ]; then
+  cp -p "$ENV_BACKUP" "$REMOTE_DIR/.env.local"
+  rm -f "$ENV_BACKUP"
+fi
+
 # Extract
 tar -xzf /tmp/patchwork-dashboard.tar.gz -C "$REMOTE_DIR"
 rm /tmp/patchwork-dashboard.tar.gz

package/deploy/macos/README.md

@@ -0,0 +1,153 @@
+# macOS launchd setup for the bridge
+
+Make the local `claude-ide-bridge` and the SSH reverse tunnel to your
+self-hosted dashboard persistent on your Mac:
+
+- Auto-start at login
+- Auto-restart on crash (bridge has its own `--watch` supervisor; launchd
+  is the supervisor of the supervisor)
+- Auto-reconnect on network change / sleep / wake (autossh)
+- No tmux session to keep alive, no terminal to leave open
+
+## One-time setup
+
+1. **Install the patchwork CLI globally** (not via `npm link`). LaunchAgents
+   run in a tighter sandbox; symlinked installs into `~/Documents` /
+   `~/Desktop` / `~/Downloads` fail with `EPERM`:
+   ```bash
+   npm install -g patchwork-os
+   # or, from a local repo:
+   #   npm pack && npm install -g patchwork-os-*.tgz
+   ```
+
+2. **Make sure you can SSH to the VPS without a password prompt.** The
+   tunnel runs unattended; if SSH would prompt for a key passphrase,
+   add the key to your agent (`ssh-add ~/.ssh/id_ed25519`) or use a
+   passphrase-less key.
+
+3. **(Recommended) Pin the SSH target in `~/.ssh/config` first.** Using
+   the public domain as the SSH target is fragile — DNS drifts during
+   redeploys (CDN edges, transient IPs), so SSH lands on a different
+   machine and the host key changes. Add an alias once and use it
+   everywhere:
+
+   ```ssh-config
+   # ~/.ssh/config
+   Host pw-bridge
+       HostName 185.167.97.141       # your VPS IP — stable across DNS shifts
+       User wesh                      # or root, whatever your VPS allows
+       IdentityFile ~/.ssh/id_ed25519
+       ServerAliveInterval 30
+       ServerAliveCountMax 3
+       UserKnownHostsFile ~/.ssh/known_hosts.patchwork
+   ```
+
+   Verify it works once: `ssh pw-bridge "echo ok"`. The host key is
+   accepted into the dedicated `known_hosts.patchwork` file and stays
+   there even if you `ssh-keygen -R` your global known_hosts later.
+
+4. **Run the installer** with the alias (cleanest):
+   ```bash
+   VPS_HOST=pw-bridge bash deploy/macos/install-mac-bridge.sh
+   ```
+   The installer detects the alias via `ssh -G` and lets ssh_config
+   own user + identity + hostname resolution. On a VPS rebuild, you
+   only update `~/.ssh/config` — the LaunchAgents pick it up.
+
+   Without an alias (interactive, prompts for VPS host):
+   ```bash
+   bash deploy/macos/install-mac-bridge.sh
+   # → prompts; recommend the IP (185.167.97.141) over the domain
+   ```
+   Or fully env-driven:
+   ```bash
+   VPS_HOST=185.167.97.141 VPS_USER=root \
+   BRIDGE_PORT=63906 VPS_PORT=3285 \
+   bash deploy/macos/install-mac-bridge.sh
+   ```
+
+5. **Sync the bridge token to the VPS** (the installer prints the exact
+   `ssh … sed … pm2 restart` command — copy-paste).
+
+## What runs after install
+
+```
+~/Library/LaunchAgents/com.patchwork.bridge.plist
+~/Library/LaunchAgents/com.patchwork.tunnel.plist
+```
+
+Both are loaded into the per-user `gui/$UID` launchd domain at install
+time and at every login.
+
+```
+[claude-ide-bridge --port 63906 --fixed-token <…> --watch]
+        │
+        │  127.0.0.1:63906
+        ▼
+[autossh -R 127.0.0.1:3285:localhost:63906]
+        │
+        │  encrypted SSH reverse tunnel
+        ▼
+VPS:3285 ──── nginx ──── dashboard `/api/bridge/*`
+```
+
+## Logs
+
+```bash
+tail -f ~/Library/Logs/patchwork-bridge.log
+tail -f ~/Library/Logs/patchwork-tunnel.log
+```
+
+## Status
+
+```bash
+launchctl print gui/$UID/com.patchwork.bridge
+launchctl print gui/$UID/com.patchwork.tunnel
+```
+
+## Restart manually
+
+```bash
+launchctl kickstart -k gui/$UID/com.patchwork.bridge
+launchctl kickstart -k gui/$UID/com.patchwork.tunnel
+```
+
+## Uninstall
+
+```bash
+bash deploy/macos/uninstall-mac-bridge.sh
+```
+
+## Troubleshooting
+
+- **`com.patchwork.bridge` exits with status 78 / `EPERM`** — the bridge
+  CLI is installed via `npm link` and points into `~/Documents`. The
+  macOS sandbox blocks LaunchAgents from reading that tree. Reinstall
+  globally as a real package (see step 1).
+- **`com.patchwork.tunnel` keeps respawning** — check the SSH key is
+  added to `ssh-agent` (`ssh-add -l`). LaunchAgents run before the
+  user's shell rc, so an interactive `ssh-add` from `.zshrc` doesn't
+  apply. Use a passphrase-less key, or store the key in macOS Keychain
+  with `ssh-add --apple-use-keychain`.
+- **Tunnel succeeds but dashboard says offline** — VPS port already in
+  use by an old leftover bridge. SSH to the VPS and `pkill -f "autossh\|sshd: .*\@notty"`,
+  or pick a different `VPS_PORT`.
+- **Dashboard 401s on every bridge call** — `PATCHWORK_BRIDGE_TOKEN`
+  on the VPS doesn't match the `--fixed-token` value the bridge is
+  using. Re-run the install script's printed `sed … pm2 restart`
+  command.
+- **`Host key for X has changed and you have requested strict
+  checking`** every now and then — the SSH target is moving. Two
+  causes:
+  1. **DNS drift.** The public domain resolves to a different IP than
+     it did last time (CDN edge, redeploy churn). `dig +short
+     bridge.your.tld` vs your known VPS IP — if those differ, switch
+     the `VPS_HOST` to the IP or a `~/.ssh/config` alias and re-run
+     the installer.
+  2. **VPS rebuild.** A reimage regenerates `/etc/ssh/ssh_host_*_key`
+     files. Either back them up before the rebuild and restore after,
+     or accept the new key once with `ssh-keygen -R <host> && ssh
+     <host>`. The launchd tunnel uses `StrictHostKeyChecking=accept-new`
+     (only auto-trusts on first connect, not after change), so you'll
+     see the warning, accept the new key interactively once, and the
+     tunnel resumes.

package/deploy/macos/com.patchwork.bridge.plist.template

@@ -0,0 +1,54 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>com.patchwork.bridge</string>
+
+  <key>ProgramArguments</key>
+  <array>
+    <string>{{BRIDGE_BIN}}</string>
+    <string>--port</string>
+    <string>{{BRIDGE_PORT}}</string>
+    <string>--fixed-token</string>
+    <string>{{BRIDGE_TOKEN}}</string>
+    <string>--watch</string>
+    <string>--workspace</string>
+    <string>{{WORKSPACE}}</string>
+  </array>
+
+  <key>RunAtLoad</key>
+  <true/>
+  <!-- KeepAlive is redundant with `--watch` (which has its own
+       exponential-backoff supervisor and recovers from crashes faster
+       than launchd's per-second relaunch). Leave it true as belt-and-
+       suspenders in case `--watch` itself dies (its supervisor process
+       is a single Node, and that's the one launchd is keeping alive). -->
+  <key>KeepAlive</key>
+  <true/>
+
+  <key>StandardOutPath</key>
+  <string>{{HOME}}/Library/Logs/patchwork-bridge.log</string>
+  <key>StandardErrorPath</key>
+  <string>{{HOME}}/Library/Logs/patchwork-bridge.log</string>
+
+  <key>WorkingDirectory</key>
+  <string>{{WORKSPACE}}</string>
+
+  <key>EnvironmentVariables</key>
+  <dict>
+    <!-- launchd's default PATH doesn't include Homebrew. Bridge spawns
+         child processes (claude CLI, git, npm) via PATH lookup, so
+         missing /opt/homebrew/bin breaks half the tools. -->
+    <key>PATH</key>
+    <string>/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin</string>
+    <key>HOME</key>
+    <string>{{HOME}}</string>
+  </dict>
+
+  <!-- Throttle: don't relaunch faster than every 10 s on rapid crash
+       loops, prevents spinning up if the binary is broken. -->
+  <key>ThrottleInterval</key>
+  <integer>10</integer>
+</dict>
+</plist>

package/deploy/macos/com.patchwork.tunnel.plist.template

@@ -0,0 +1,76 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>com.patchwork.tunnel</string>
+
+  <key>ProgramArguments</key>
+  <array>
+    <string>{{AUTOSSH_BIN}}</string>
+    <!-- AUTOSSH_PORT=0 disables the legacy monitoring-port heartbeat in
+         favor of SSH's own ServerAliveInterval/CountMax. Modern autossh
+         docs recommend this; the monitoring port is unreliable behind
+         NAT and consumes another tunnel slot. -->
+    <string>-M</string>
+    <string>0</string>
+    <!-- -N: no remote command   -T: no pseudo-tty                 -->
+    <string>-N</string>
+    <string>-T</string>
+    <string>-R</string>
+    <string>127.0.0.1:{{VPS_PORT}}:localhost:{{BRIDGE_PORT}}</string>
+    <!-- ServerAliveInterval=30 + CountMax=3 = ssh kills the link if
+         the server doesn't respond for 90 s, autossh restarts. Critical
+         for laptop sleep/wake and Wi-Fi switches. -->
+    <string>-o</string>
+    <string>ServerAliveInterval=30</string>
+    <string>-o</string>
+    <string>ServerAliveCountMax=3</string>
+    <!-- ExitOnForwardFailure=yes makes autossh exit + retry if the
+         remote port is already bound. Otherwise the tunnel "succeeds"
+         but no traffic flows. -->
+    <string>-o</string>
+    <string>ExitOnForwardFailure=yes</string>
+    <!-- Don't auto-add new host keys (security: surface key changes
+         instead of silently trusting). Initial setup expects the user
+         to have already SSH'd at least once and accepted the key. -->
+    <string>-o</string>
+    <string>StrictHostKeyChecking=accept-new</string>
+    <string>-i</string>
+    <string>{{SSH_KEY}}</string>
+    <!-- SSH_TARGET is rendered by install-mac-bridge.sh:
+           - "user@host" form when host is an IP or hostname
+           - bare alias when host matches a `~/.ssh/config` Host entry
+             (so ssh_config's User + HostName + IdentityFile resolution
+             works as designed; passing user@alias would override the
+             config's User directive and confuse the alias case). -->
+    <string>{{SSH_TARGET}}</string>
+  </array>
+
+  <key>RunAtLoad</key>
+  <true/>
+  <key>KeepAlive</key>
+  <true/>
+
+  <key>StandardOutPath</key>
+  <string>{{HOME}}/Library/Logs/patchwork-tunnel.log</string>
+  <key>StandardErrorPath</key>
+  <string>{{HOME}}/Library/Logs/patchwork-tunnel.log</string>
+
+  <key>EnvironmentVariables</key>
+  <dict>
+    <key>PATH</key>
+    <string>/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin</string>
+    <key>HOME</key>
+    <string>{{HOME}}</string>
+    <!-- AUTOSSH_GATETIME=0: don't require a "stable" connection time
+         before counting reconnect attempts. Default 30 s makes startup
+         after a long sleep slower than necessary. -->
+    <key>AUTOSSH_GATETIME</key>
+    <string>0</string>
+  </dict>
+
+  <key>ThrottleInterval</key>
+  <integer>10</integer>
+</dict>
+</plist>