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

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>

package/deploy/macos/install-mac-bridge.sh

@@ -0,0 +1,244 @@
+#!/usr/bin/env bash
+# install-mac-bridge.sh — make the bridge + reverse tunnel persistent on macOS
+# via launchd LaunchAgents (auto-start at login, auto-restart on crash,
+# auto-reconnect on network change via autossh).
+#
+# Usage (interactive):
+#   bash deploy/macos/install-mac-bridge.sh
+#
+# Usage (env-driven, idempotent re-install):
+#   VPS_HOST=185.167.97.141 VPS_USER=root BRIDGE_PORT=63906 \
+#   VPS_PORT=3285 BRIDGE_TOKEN="$(uuidgen | tr '[:upper:]' '[:lower:]')" \
+#   bash deploy/macos/install-mac-bridge.sh
+#
+# Tip: prefer the VPS IP (or a `~/.ssh/config` Host alias) over the
+# public domain. The domain may resolve via DNS that drifts, putting
+# you on a different machine after a redeploy and breaking host-key
+# verification. The IP is whatever your deploy script targets — a
+# stable identity across rebuilds.
+#
+# Using a ~/.ssh/config alias (cleanest):
+#   # in ~/.ssh/config:
+#   #   Host pw-bridge
+#   #       HostName 185.167.97.141
+#   #       User wesh
+#   #       IdentityFile ~/.ssh/id_ed25519
+#   VPS_HOST=pw-bridge VPS_USER=wesh \
+#   bash deploy/macos/install-mac-bridge.sh
+#   # → tunnel.plist uses `pw-bridge` as the SSH target (User from
+#   #   ssh_config wins over the plist's user@host form when an alias
+#   #   exists; we still set both so the resolution is explicit).
+#
+# After install:
+#   tail -f ~/Library/Logs/patchwork-bridge.log
+#   tail -f ~/Library/Logs/patchwork-tunnel.log
+#
+# Update VPS .env.local PATCHWORK_BRIDGE_TOKEN to match the printed token,
+# then `pm2 restart patchwork-dashboard` on the VPS.
+#
+# Uninstall: bash deploy/macos/uninstall-mac-bridge.sh
+
+set -euo pipefail
+
+# ──────────────────────────────────────────────────────────────────────
+# Sanity checks
+# ──────────────────────────────────────────────────────────────────────
+
+if [[ "$OSTYPE" != "darwin"* ]]; then
+  echo "This script is for macOS (launchd). Detected: $OSTYPE" >&2
+  exit 1
+fi
+
+if ! command -v claude-ide-bridge >/dev/null 2>&1; then
+  echo "claude-ide-bridge not found on PATH." >&2
+  echo "Install with:  npm install -g patchwork-os" >&2
+  exit 1
+fi
+
+# Real-path resolution: a symlinked global install (npm link) breaks the
+# LaunchAgent because launchd's sandbox follows the symlink target into
+# ~/Documents and EPERMs on file IO. Recommend a real install.
+BRIDGE_REAL="$(readlink -f "$(command -v claude-ide-bridge)" 2>/dev/null || \
+               python3 -c "import os,sys; print(os.path.realpath('$(command -v claude-ide-bridge)'))")"
+case "$BRIDGE_REAL" in
+  *Documents*|*Desktop*|*Downloads*)
+    echo "⚠️  claude-ide-bridge is symlinked into a sandboxed user-data folder:"
+    echo "   $BRIDGE_REAL"
+    echo "   LaunchAgent startup will fail with EPERM under the macOS sandbox."
+    echo "   Fix: cd to the patchwork-os repo, run \`npm pack && npm install -g patchwork-os-*.tgz\`"
+    echo "   Or: \`npm install -g patchwork-os\` from the public registry."
+    echo ""
+    read -p "   Continue anyway? [y/N] " -r yn
+    [[ "$yn" =~ ^[Yy]$ ]] || exit 1
+    ;;
+esac
+
+if ! command -v autossh >/dev/null 2>&1; then
+  echo "autossh not found. Installing via Homebrew…"
+  if ! command -v brew >/dev/null 2>&1; then
+    echo "Homebrew not found. Install from https://brew.sh and re-run." >&2
+    exit 1
+  fi
+  brew install autossh
+fi
+
+# ──────────────────────────────────────────────────────────────────────
+# Gather config (env-driven with interactive fallback)
+# ──────────────────────────────────────────────────────────────────────
+
+VPS_HOST="${VPS_HOST:-}"
+VPS_USER="${VPS_USER:-$USER}"
+BRIDGE_PORT="${BRIDGE_PORT:-63906}"
+VPS_PORT="${VPS_PORT:-3285}"
+BRIDGE_TOKEN="${BRIDGE_TOKEN:-}"
+WORKSPACE="${WORKSPACE:-$PWD}"
+SSH_KEY="${SSH_KEY:-$HOME/.ssh/id_ed25519}"
+[[ -f "$SSH_KEY" ]] || SSH_KEY="$HOME/.ssh/id_rsa"
+
+if [[ -z "$VPS_HOST" ]]; then
+  cat <<'PROMPT'
+
+VPS target — three choices, in increasing order of stability:
+
+  (1) Public domain     e.g. bridge.your.tld
+      DNS-resolved each connection. Drifts during redeploys → host-key churn.
+
+  (2) VPS IP            e.g. 185.167.97.141
+      Stable per VPS. Doesn't survive a VPS rebuild but doesn't drift between.
+
+  (3) ~/.ssh/config alias  e.g. pw-bridge
+      Most stable. Pins IP + identity in one place; the rest of the
+      stack (this script, deploy.sh, manual ssh) all use the alias.
+      Update one ssh_config entry on a rebuild, everything follows.
+
+PROMPT
+  read -p "VPS host (IP or ssh alias preferred): " VPS_HOST
+fi
+if [[ -z "$VPS_HOST" ]]; then
+  echo "VPS host is required." >&2
+  exit 1
+fi
+
+# When VPS_HOST is a ~/.ssh/config alias, ssh resolves both User and
+# HostName from the config, so VPS_USER becomes redundant. The plist
+# still passes user@host to be explicit (and to support the IP-direct
+# case where ssh_config has nothing). If `ssh -G $VPS_HOST` reports a
+# resolved hostname different from VPS_HOST, treat that as confirmation
+# the value is an alias.
+if ssh -G "$VPS_HOST" 2>/dev/null | awk '$1 == "hostname"' | grep -qv "^hostname $VPS_HOST$"; then
+  echo "Detected '$VPS_HOST' is a ~/.ssh/config alias — host + identity resolved from there."
+  IS_SSH_ALIAS=1
+else
+  IS_SSH_ALIAS=0
+fi
+
+if [[ -z "$BRIDGE_TOKEN" ]]; then
+  if command -v uuidgen >/dev/null 2>&1; then
+    BRIDGE_TOKEN="$(uuidgen)"
+  else
+    BRIDGE_TOKEN="$(python3 -c 'import uuid; print(uuid.uuid4())')"
+  fi
+  echo "Generated bridge token: $BRIDGE_TOKEN"
+fi
+
+if [[ ! -f "$SSH_KEY" ]]; then
+  echo "SSH key not found: $SSH_KEY" >&2
+  echo "Either set SSH_KEY=... or generate one with \`ssh-keygen -t ed25519\`." >&2
+  exit 1
+fi
+
+# ──────────────────────────────────────────────────────────────────────
+# Render templates
+# ──────────────────────────────────────────────────────────────────────
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+LAUNCH_AGENTS="$HOME/Library/LaunchAgents"
+LOGS="$HOME/Library/Logs"
+BRIDGE_BIN="$(command -v claude-ide-bridge)"
+AUTOSSH_BIN="$(command -v autossh)"
+
+mkdir -p "$LAUNCH_AGENTS" "$LOGS"
+
+# SSH target string: bare alias when VPS_HOST is a `~/.ssh/config` Host
+# entry, "user@host" form otherwise. The alias case lets ssh_config own
+# user + identity + hostname resolution, which is the most stable setup
+# (one place to update on a VPS rebuild).
+if [ "$IS_SSH_ALIAS" = "1" ]; then
+  SSH_TARGET="$VPS_HOST"
+  echo "SSH target: $SSH_TARGET (resolved via ~/.ssh/config)"
+else
+  SSH_TARGET="$VPS_USER@$VPS_HOST"
+  echo "SSH target: $SSH_TARGET"
+fi
+
+render() {
+  local tmpl="$1" out="$2"
+  sed \
+    -e "s|{{BRIDGE_BIN}}|$BRIDGE_BIN|g" \
+    -e "s|{{AUTOSSH_BIN}}|$AUTOSSH_BIN|g" \
+    -e "s|{{BRIDGE_PORT}}|$BRIDGE_PORT|g" \
+    -e "s|{{VPS_PORT}}|$VPS_PORT|g" \
+    -e "s|{{BRIDGE_TOKEN}}|$BRIDGE_TOKEN|g" \
+    -e "s|{{VPS_HOST}}|$VPS_HOST|g" \
+    -e "s|{{SSH_USER}}|$VPS_USER|g" \
+    -e "s|{{SSH_TARGET}}|$SSH_TARGET|g" \
+    -e "s|{{SSH_KEY}}|$SSH_KEY|g" \
+    -e "s|{{WORKSPACE}}|$WORKSPACE|g" \
+    -e "s|{{HOME}}|$HOME|g" \
+    "$tmpl" >"$out"
+}
+
+BRIDGE_PLIST="$LAUNCH_AGENTS/com.patchwork.bridge.plist"
+TUNNEL_PLIST="$LAUNCH_AGENTS/com.patchwork.tunnel.plist"
+
+render "$SCRIPT_DIR/com.patchwork.bridge.plist.template" "$BRIDGE_PLIST"
+render "$SCRIPT_DIR/com.patchwork.tunnel.plist.template" "$TUNNEL_PLIST"
+
+# Tighten permissions — these contain the bridge token.
+chmod 600 "$BRIDGE_PLIST" "$TUNNEL_PLIST"
+
+# ──────────────────────────────────────────────────────────────────────
+# (Re)load
+# ──────────────────────────────────────────────────────────────────────
+
+# bootout removes the old service if present (idempotent re-install).
+# Errors are non-fatal — first run won't have anything to bootout.
+launchctl bootout "gui/$UID" "$BRIDGE_PLIST" 2>/dev/null || true
+launchctl bootout "gui/$UID" "$TUNNEL_PLIST" 2>/dev/null || true
+
+launchctl bootstrap "gui/$UID" "$BRIDGE_PLIST"
+launchctl bootstrap "gui/$UID" "$TUNNEL_PLIST"
+
+launchctl enable "gui/$UID/com.patchwork.bridge"
+launchctl enable "gui/$UID/com.patchwork.tunnel"
+
+# ──────────────────────────────────────────────────────────────────────
+# Status
+# ──────────────────────────────────────────────────────────────────────
+
+cat <<INFO
+
+────────────────────────────────────────────────────────────────────────
+Installed.
+
+  Bridge: 127.0.0.1:$BRIDGE_PORT
+  Tunnel: -> $SSH_TARGET:$VPS_PORT
+  Token:  $BRIDGE_TOKEN
+
+Logs:
+  ~/Library/Logs/patchwork-bridge.log
+  ~/Library/Logs/patchwork-tunnel.log
+
+Status:
+  launchctl print gui/$UID/com.patchwork.bridge
+  launchctl print gui/$UID/com.patchwork.tunnel
+
+Update the VPS dashboard's PATCHWORK_BRIDGE_TOKEN to match the token
+above, then \`pm2 restart patchwork-dashboard\` on the VPS so the new
+token takes effect:
+
+  ssh $SSH_TARGET 'sed -i "s|^PATCHWORK_BRIDGE_TOKEN=.*|PATCHWORK_BRIDGE_TOKEN=$BRIDGE_TOKEN|" /opt/patchwork-dashboard/.env.local && pm2 restart patchwork-dashboard'
+
+Uninstall: bash deploy/macos/uninstall-mac-bridge.sh
+────────────────────────────────────────────────────────────────────────
+INFO

package/deploy/macos/uninstall-mac-bridge.sh

@@ -0,0 +1,22 @@
+#!/usr/bin/env bash
+# uninstall-mac-bridge.sh — stop + remove the patchwork bridge and tunnel
+# LaunchAgents installed by install-mac-bridge.sh.
+
+set -euo pipefail
+
+if [[ "$OSTYPE" != "darwin"* ]]; then
+  echo "macOS only." >&2
+  exit 1
+fi
+
+BRIDGE_PLIST="$HOME/Library/LaunchAgents/com.patchwork.bridge.plist"
+TUNNEL_PLIST="$HOME/Library/LaunchAgents/com.patchwork.tunnel.plist"
+
+# bootout: stop + remove the service registration. `|| true` so the
+# script doesn't fail when one of them isn't installed.
+launchctl bootout "gui/$UID" "$BRIDGE_PLIST" 2>/dev/null || true
+launchctl bootout "gui/$UID" "$TUNNEL_PLIST" 2>/dev/null || true
+
+rm -f "$BRIDGE_PLIST" "$TUNNEL_PLIST"
+
+echo "Uninstalled. Logs preserved at ~/Library/Logs/patchwork-{bridge,tunnel}.log"

package/dist/approvalHttp.d.ts

@@ -39,6 +39,20 @@ export interface ApprovalHttpDeps {
     pushServiceToken?: string;
     /** Public base URL of this bridge (e.g. https://mybridge.example.com). Embedded in push payload as callback base. */
     pushServiceBaseUrl?: string;
+    /**
+     * ntfy.sh topic for direct phone-path approvals via action buttons. When set
+     * AND `pushServiceBaseUrl` is set (so the action URLs can reach the bridge),
+     * each queued approval is published to the topic with Approve / Reject HTTP
+     * action buttons that POST back to the bridge with the single-use approval
+     * token. Independent of `pushServiceUrl` — ntfy can be the sole phone path
+     * (no FCM/APNS relay needed) or run alongside it.
+     */
+    ntfyTopic?: string;
+    /**
+     * ntfy server. Defaults to `https://ntfy.sh`. Set to a self-hosted instance
+     * (e.g. `https://ntfy.your-domain.tld`) for auth/private-topic deployments.
+     */
+    ntfyServer?: string;
     /**
      * Optional ActivityLog used to compute passive risk personalization
      * signals (`src/approvalSignals.ts`). When omitted, personalSignals are