granttap-mcp 0.2.0 → 0.6.4

package/README.md

@@ -1,38 +1,95 @@
 # GrantTap MCP
 
 [![npm](https://img.shields.io/npm/v/granttap-mcp)](https://www.npmjs.com/package/granttap-mcp)
-[![license](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![CI](https://github.com/sergii-ziborov/granttap-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/sergii-ziborov/granttap-mcp/actions/workflows/ci.yml)
+[![Node.js 20+](https://img.shields.io/badge/node-%3E%3D20-339933?logo=node.js&logoColor=white)](package.json)
+[![MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+**Keep Codex and Claude Code moving from your iPhone or Apple Watch.**
+
+Approve commands, follow active tasks, reply, attach files, start new work, and
+run local schedules without exposing agent traffic to the relay. GrantTap MCP is
+the open-source machine-side bridge: the agents stay on your Mac, and Cloudflare
+only routes authenticated ciphertext it cannot decrypt.
+
+[Website](https://granttap.com) ·
+[npm](https://www.npmjs.com/package/granttap-mcp) ·
+[Security model](SECURITY.md) ·
+[Self-hostable relay](https://github.com/sergii-ziborov/granttap-relay)
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/sergii-ziborov/granttap-mcp/main/docs/images/iphone-command-center.png" alt="GrantTap command center on iPhone showing a Codex approval, an agent question, task search, agent switcher, chat history, and MCP usage" width="330">
+  &nbsp;&nbsp;&nbsp;
+  <img src="https://raw.githubusercontent.com/sergii-ziborov/granttap-mcp/main/docs/images/apple-watch-approval.png" alt="GrantTap Codex approval on Apple Watch" width="230">
+</p>
+
+<p align="center"><sub>Current iPhone and Apple Watch UI captured from the app's clearly labelled demo mode — no concept renders.</sub></p>
+
+The companion iPhone and Apple Watch app is currently in testing. Release
+status is published at [granttap.com](https://granttap.com).
+
+## What you get
+
+- **Real approvals away from the Mac.** Claude Code or Codex pauses at its
+  permission hook; Allow or Deny returns to that same agent flow.
+- **One task view for both agents.** See recent Codex and Claude Code tasks,
+  human-readable activity, delivery state, usage, and context data the agent
+  actually exposes.
+- **Continue work from the phone.** Reply to an existing task or create a new
+  one for the selected agent and advertised workspace. Send up to five photos,
+  camera images, or documents in one message.
+- **A useful Watch app, not an approval-only notification.** Browse tasks, open
+  recent activity, approve a command, or reply by voice or text.
+- **Per-task controls that are enforced locally.** Inspect MCP servers and
+  repository skills, disable MCP servers for later GrantTap-delivered turns,
+  choose a relevant MCP or skill, and select Codex sandbox access.
+- **A local scheduler, not a pretend provider API.** Create recurring Codex or
+  Claude Code runs manually or through a conversational planner, then inspect
+  the run history from the phone.
+- **Receipts instead of optimistic UI.** Messages have stable IDs, encrypted
+  accepted/rejected receipts, bounded retries, and queued/sending/delivered/
+  failed state.
+
+## See it in action
+
+### iPhone
+
+| Command center | Codex task controls | Observed MCP usage | Claude Code and scheduler |
+| --- | --- | --- | --- |
+| <img src="https://raw.githubusercontent.com/sergii-ziborov/granttap-mcp/main/docs/images/iphone-command-center.png" alt="GrantTap iPhone command center" width="210"> | <img src="https://raw.githubusercontent.com/sergii-ziborov/granttap-mcp/main/docs/images/iphone-task-detail.png" alt="Codex task context, MCP permissions, and sandbox access in GrantTap" width="210"> | <img src="https://raw.githubusercontent.com/sergii-ziborov/granttap-mcp/main/docs/images/iphone-mcp-usage.png" alt="Observed MCP and skill usage on iPhone" width="210"> | <img src="https://raw.githubusercontent.com/sergii-ziborov/granttap-mcp/main/docs/images/iphone-claude-tasks.png" alt="Claude Code task list and conversational scheduler on iPhone" width="210"> |
+
+The Codex task screen exposes the context window, supported compaction, MCP
+allow/deny state, and sandbox access. Claude Code gets its own visual treatment
+and planner while keeping its different permission and compaction limits clear.
+MCP usage counts only observed calls; context figures are labelled estimates,
+not separate MCP billing.
+
+### Apple Watch
+
+| Task inbox | Recent activity and reply | Command approval |
+| --- | --- | --- |
+| <img src="https://raw.githubusercontent.com/sergii-ziborov/granttap-mcp/main/docs/images/apple-watch-inbox.png" alt="GrantTap task and approval inbox on Apple Watch" width="230"> | <img src="https://raw.githubusercontent.com/sergii-ziborov/granttap-mcp/main/docs/images/apple-watch-task.png" alt="GrantTap task activity with voice and text reply on Apple Watch" width="230"> | <img src="https://raw.githubusercontent.com/sergii-ziborov/granttap-mcp/main/docs/images/apple-watch-approval.png" alt="Codex command approval on Apple Watch" width="230"> |
+
+## Connect in under a minute
+
+Add GrantTap to each agent you use:
 
-The public, auditable machine-side bridge for [GrantTap](https://granttap.com):
-ask a person, send a status update, or request an approval on their iPhone or
-Apple Watch without sending agent traffic through a model proxy.
-
-GrantTap MCP complements the agents' native permission hooks:
-
-- MCP is the voluntary channel: the agent calls `ask`, `ask_yes_no`, or `notify`.
-- Hooks are the mandatory approval channel: Claude Code or Codex pauses before
-  a tool call and waits for Allow or Deny.
-- Both channels use the same end-to-end encrypted GrantTap pairing.
-
-| Visible iPhone activity | Approval on Apple Watch |
-| --- | --- |
-| ![GrantTap activity on iPhone](docs/images/phone-activity.png) | ![GrantTap approval on Apple Watch](docs/images/watch-approval.png) |
-
-The iPhone and Apple Watch app is preparing for App Store release. Current
-status and target date are published at [granttap.com](https://granttap.com).
-Support, privacy, terms, and license information are linked below and from the
-app's About screen.
+```bash
+codex mcp add granttap -- npx -y granttap-mcp@latest
+claude mcp add granttap -- npx -y granttap-mcp@latest
+```
 
-## Install
+Start a fresh agent task and say **“Connect GrantTap.”** The `connect` tool:
 
-The shortest MCP-only setup is:
+1. creates a new end-to-end encrypted pairing;
+2. returns a scannable one-time QR directly in the agent chat;
+3. installs the Codex and Claude Code approval hooks; and
+4. installs the per-user background helper for task sync and schedules.
 
-```bash
-codex mcp add granttap -- npx -y granttap-mcp
-claude mcp add granttap -- npx -y granttap-mcp
-```
+Scan the QR with GrantTap on iPhone. No terminal QR, copied pairing JSON, or
+open background terminal is required.
 
-Pair this computer with the GrantTap app, then register the approval hooks:
+If an MCP client cannot render image content, use the CLI fallback:
 
 ```bash
 npm install -g granttap-mcp
@@ -40,51 +97,92 @@ granttap-mcp connect
 granttap-mcp setup
 ```
 
-`connect` prints a QR and an optional one-time eight-character code. It uses
-the production zero-knowledge relay by default; pass your own `wss://` URL as
-the first argument to self-host. The pairing lives locally in
-`~/.granttap/machine.json`; this package never uploads the device secret key.
-Existing beta installations using `~/.nodvox/` are migrated automatically.
-
-`connect` also registers both hooks. `setup` is an idempotent standalone
-command for upgrades: it preserves unrelated settings and writes a backup
-before changing a configuration file.
+CLI `connect` prints a one-time QR and short manual code. `setup` is idempotent:
+it preserves unrelated agent settings and backs up a configuration file before
+changing it. The pairing is stored locally in `~/.granttap/machine.json`.
+Existing beta state under `~/.nodvox/` is migrated automatically.
+
+## Codex and Claude Code: honest capability matrix
+
+| Capability | Codex | Claude Code |
+| --- | --- | --- |
+| Approval hook | `PermissionRequest` when Codex hooks are enabled | `PreToolUse` |
+| Resume an existing task | Yes, through the local Codex CLI | Yes, through the local Claude CLI |
+| Start a new persistent task | Yes | Yes |
+| Up to five attachments | Images through Codex image inputs; documents as local paths | Local image/document paths in the turn |
+| Change filesystem access from iPhone | Read-only, workspace, or full for the next GrantTap turn | Not exposed; the existing Claude policy remains authoritative |
+| Disable MCP per task | Enforced for later GrantTap-delivered turns | Enforced for later GrantTap-delivered turns |
+| Usage and context | Reported when present in local task logs | Reported when present in local task logs |
+| Trigger real context compaction | Yes, for an idle task through Codex app-server | No supported remote API; GrantTap reports this honestly |
+| Conversational schedule planner | Ephemeral read-only run | Ephemeral plan-mode run |
+
+GrantTap controls local Codex and Claude Code tasks. It does **not** claim to
+create ordinary ChatGPT chats, private ChatGPT Scheduled Tasks, Codex
+Automations, or Claude Routines through unpublished provider APIs.
+
+Globally disabled MCP servers stay disabled. A phone choice only narrows later
+turns sent through GrantTap; it cannot broaden the agent's global configuration.
+Repository skills are discovered only in the selected task workspace under
+`.agents/skills` or `.claude/skills`.
 
 ## MCP tools
 
 | Tool | Result |
 | --- | --- |
+| `connect` | Creates a pairing and returns a secure one-time QR in chat |
 | `ask` | Sends an open question and waits for a spoken or typed reply |
 | `ask_yes_no` | Sends a yes/no question and waits for a tap |
-| `notify` | Sends a non-blocking status message |
-| `setup` | Registers the Claude Code and Codex approval hooks |
-
-## CLI commands
-
-| Command | Purpose |
-| --- | --- |
-| *(no command)* | Starts the GrantTap MCP stdio server |
-| `connect [relayUrl]` | Creates an E2EE pairing and prints a QR/short code |
-| `setup` | Registers the Claude Code and Codex approval hooks |
+| `notify` | Sends a non-blocking status update |
+| `setup` | Registers both approval hooks and the terminal-free helper |
 
 The default answer timeout is three minutes. Override it with
 `GRANTTAP_ASK_TIMEOUT_MS`.
 
-## Security model
+## Why the relay cannot read a session
+
+- Endpoint keys are generated locally. The relay never receives a device's
+  secret encryption key.
+- Pairing hand-off uses an opaque mailbox ID plus an independent 256-bit
+  transfer key. Only the mailbox ID reaches Cloudflare; the key stays in the QR
+  or manual token.
+- Every attached Codex or Claude Code task receives its own random 256-bit task
+  key. Disclosure of one task key cannot decrypt another task.
+- Questions, commands, replies, attachments, approvals, scheduler drafts, and
+  task activity remain authenticated ciphertext across the network, relay,
+  Durable Objects, and APNs path.
+- APNs carries only a content-neutral wake. It contains no title, prompt,
+  command, path, task kind, or response.
+
+The relay can still observe operational metadata: opaque room/mailbox IDs, IP
+addresses, timing, ciphertext sizes, and APNs device token/environment. A
+compromised authorized endpoint can read the tasks explicitly granted to that
+endpoint; cryptography cannot hide plaintext from a device authorized to show
+it. The exact boundary and threat-model limits are documented in
+[SECURITY.md](SECURITY.md).
+
+## Task sync and scheduling
+
+The background helper publishes a bounded window of recent local Codex and
+Claude Code task metadata. Older chat metadata is available separately for up
+to 90 days and 160 chats; full activity for a task is sent only after the phone
+subscribes to it. Hidden reasoning is never converted into visible activity.
+
+New phone-created tasks default to an isolated per-agent GrantTap workspace.
+The phone can instead select a same-agent folder already advertised by a recent
+local task. The helper rejects arbitrary unadvertised paths.
+
+Schedules use standard five-field cron in the Mac's timezone. The app supports
+hourly, daily, weekday, selected-weekday, and monthly series, plus enable,
+disable, edit, delete, and run-now actions. Every run records local start/end
+time, agent, status, result, and created task ID.
 
-Message payloads are authenticated and encrypted locally with NaCl
-public-key boxes. The relay receives only routing metadata and opaque
-ciphertext. It has no device secret key and cannot decrypt questions,
-commands, replies, or approvals.
-
-This repository intentionally includes the protocol, crypto client, relay
-client, MCP server, and agent hook adapters so that the complete public
-machine-side trust boundary can be reviewed.
+## CLI commands
 
-The relay still observes metadata such as room identifiers, IP addresses,
-timing, and message sizes. Review or self-host the public
-[GrantTap relay](https://github.com/sergii-ziborov/granttap-relay) if that
-metadata matters to your deployment.
+| Command | Purpose |
+| --- | --- |
+| *(no command)* | Starts the GrantTap MCP stdio server |
+| `connect [relayUrl]` | Creates an E2EE pairing; optionally targets a self-hosted `wss://` relay |
+| `setup` | Registers the Codex/Claude hooks and background helper |
 
 ## Development
 
@@ -99,16 +197,15 @@ npm run typecheck
 ```
 
 Start the stdio server with `npm start`. Run `npm run setup` only on a machine
-where you want the hooks installed; existing config files are backed up once
-as `*.bak-granttap`.
+where you want GrantTap hooks installed.
 
-## Related
+## Links
 
-- Product: [granttap.com](https://granttap.com)
-- npm: [granttap-mcp](https://www.npmjs.com/package/granttap-mcp)
-- Relay: [sergii-ziborov/granttap-relay](https://github.com/sergii-ziborov/granttap-relay)
-- Privacy: [granttap.com/privacy](https://granttap.com/privacy)
-- Support: [granttap.com/support](https://granttap.com/support)
-- Security policy: [SECURITY.md](SECURITY.md)
+- [GrantTap product site](https://granttap.com)
+- [granttap-mcp on npm](https://www.npmjs.com/package/granttap-mcp)
+- [Public relay source](https://github.com/sergii-ziborov/granttap-relay)
+- [Privacy](https://granttap.com/privacy)
+- [Support](https://granttap.com/support)
+- [Security policy](SECURITY.md)
 
 GrantTap is not affiliated with Anthropic or OpenAI.

package/SECURITY.md

@@ -6,7 +6,7 @@ Use GitHub's private
 [security advisory form](https://github.com/sergii-ziborov/granttap-mcp/security/advisories/new).
 For urgent coordination, contact `sergii.ziborov@gmail.com`.
 
-Do not open a public issue containing pairing codes, device keys, room
+Do not open a public issue containing pairing tokens, device keys, room
 identifiers, real prompts, command payloads, local configuration, or a working
 exploit. Include the affected package version or commit, expected impact, and
 a minimal reproduction using synthetic data.
@@ -17,5 +17,61 @@ Pairing state belongs in `~/.granttap/` and must never be committed, attached
 to an issue, or pasted into logs. The package avoids printing device secret
 keys. Existing configuration files are backed up before hook installation.
 
+Current pairings contain three independent secret classes: NaCl endpoint keys,
+random per-task keys, and a random `pushAuth` room credential that only
+authorizes APNs device-token registration at the relay. None may be logged.
+The relay receives only a hash of `pushAuth` and never receives an endpoint's
+secret encryption key.
+
+## Cryptographic boundary
+
+- Every device pairing is generated locally and has unique Curve25519 secret
+  keys. A device from another pairing cannot authenticate or decrypt it.
+- Pairing hand-off v2 uses a relay-visible random 128-bit mailbox id and a
+  separate random 256-bit transfer key. Only the mailbox id is used in the HTTP
+  path. The key stays in the QR/manual token, so a relay operator or a Durable
+  Object database dump cannot open the parked pairing blob.
+- Every attached Codex or Claude Code task receives a separate random 256-bit
+  task key. Task messages, attachments, visible activity, access/MCP changes,
+  compaction results, and task-bound approvals use this additional authenticated
+  encryption layer. A key copied from one task cannot decrypt another task.
+- Task keys are delivered only inside the already authenticated device-to-device
+  NaCl channel and are stored in device-only Keychain on iOS and a mode `0600`
+  file on the agent Mac.
+- Plaintext exists only at an authorized endpoint. Every route between the Mac
+  and iPhone remains authenticated ciphertext while it crosses the app
+  transport, network, Cloudflare, Durable Objects, and APNs.
+- APNs is only a content-neutral wake. It contains no task kind, request id,
+  delivery id, title, prompt, command, path, or response.
+- Scheduler-planner turns and their structured drafts cross Cloudflare only as
+  authenticated device-to-device ciphertext. The selected CLI runs locally in
+  ephemeral read-only/plan mode; it cannot silently turn planning into a
+  persistent task or workspace mutation.
+
+Cloudflare can observe service metadata required to operate the relay: an
+opaque room/mailbox id, routing role, timestamps/expiry, IP address, ciphertext
+size, APNs device token/environment, and a content-neutral wake flag. It cannot
+derive plaintext from those fields or from its stored database.
+
+The honest limit: a device can decrypt every task key that was explicitly
+granted to that device. Possession of a device authorized for task A alone
+cannot decrypt another pairing or task B unless B's independent key was also
+granted to it. Cryptography cannot both authorize a device for a task and
+prevent that same device from reading it. Compromise of the agent Mac is
+also outside the relay threat model because the Mac necessarily has the local
+agent transcripts and keys. The isolation guarantee is against Cloudflare,
+database/network compromise, other pairings/devices, and disclosure of a
+different task's key—not against an already authorized endpoint.
+
+The delivery ledger and scheduler history are stored only on the paired Mac.
+They contain random message ids and local task metadata and are bounded and
+expired; do not attach real copies to bug reports.
+
+Chat history and capability metadata follow the same cryptographic boundary.
+The bridge reads a bounded set of local Codex/Claude logs, emits only chat
+metadata and visible activity, and places it inside the existing device or
+independent per-task NaCl box. Structured MCP/skill fields describe observed
+tool calls; hidden reasoning is never turned into activity or usage records.
+
 Relay vulnerabilities should be reported through the
 [GrantTap relay advisory form](https://github.com/sergii-ziborov/granttap-relay/security/advisories/new).

package/apps/bridge/src/approval.ts

@@ -8,6 +8,7 @@
 import type { PeerConfig } from "../../../packages/core/relay-client";
 import { RelayClient } from "../../../packages/core/relay-client";
 import type { ApprovalDecision, ApprovalRequest, Payload } from "../../../packages/protocol/schema";
+import { primeSessionKeys, sendSessionPayload } from "./session-keys";
 
 export type RequestApprovalOpts = {
   timeoutMs?: number;
@@ -23,6 +24,7 @@ export async function requestApproval(
   const timeoutMs = opts.timeoutMs ?? 60_000;
   const client = opts.client ?? new RelayClient(cfg);
   const ownsClient = !opts.client;
+  primeSessionKeys(client);
 
   try {
     if (ownsClient) {
@@ -37,7 +39,16 @@ export async function requestApproval(
         };
       }
     }
-    await client.send(req, "phone", { ttlMs: timeoutMs });
+    // The request id is random and carries no task content. Reusing it as the
+    // opaque delivery id lets a generic APNs action answer the request even if
+    // iOS has not yet pulled and decrypted the full card.
+    const sendOptions = {
+      ttlMs: timeoutMs,
+      wake: true,
+      deliveryId: req.requestId,
+    };
+    if (req.sessionId) await sendSessionPayload(client, req, req.sessionId, "phone", sendOptions);
+    else await client.send(req, "phone", sendOptions);
     const decision = await client
       .waitFor(
         (p: Payload): p is ApprovalDecision =>

package/apps/bridge/src/bin/connect.ts

@@ -1,15 +1,7 @@
 import QRCode from "qrcode";
-import { generatePairingCode, sealWithCode } from "../../../../packages/core/crypto";
-import { installClaudeHook, installCodexHook, type InstallResult } from "../install";
-import {
-  createPairing,
-  machineConfigPath,
-  pairingUri,
-  phonePairingPath,
-  saveConfig,
-} from "../config";
-
-const DEFAULT_RELAY = "wss://granttap-relay.sergii-ziborov.workers.dev";
+import type { InstallResult } from "../install";
+import { machineConfigPath, phonePairingPath } from "../config";
+import { createOneTimePairing, DEFAULT_RELAY, PAIRING_CODE_TTL_MINUTES } from "../pairing";
 
 function hookLine(name: string, result: InstallResult): string {
   switch (result.status) {
@@ -23,69 +15,48 @@ function hookLine(name: string, result: InstallResult): string {
 }
 
 async function connect(relayUrl: string): Promise<void> {
-  const { machineCfg, phoneCfg } = createPairing(relayUrl);
-  saveConfig(machineConfigPath(), machineCfg);
-  saveConfig(phonePairingPath(), phoneCfg);
-
-  const uri = pairingUri(phoneCfg);
-  const qr = await QRCode.toString(uri, {
+  const pairing = await createOneTimePairing(relayUrl);
+  const qr = await QRCode.toString(pairing.qrPayload, {
     type: "terminal",
     small: true,
     errorCorrectionLevel: "L",
   });
-  process.stdout.write(["", "  Scan this code in GrantTap on iPhone:", "", qr].join("\n"));
-
-  const code = generatePairingCode(8);
-  const sealed = sealWithCode(phoneCfg, code);
-  const httpBase = relayUrl.replace(/^ws:/, "http:").replace(/^wss:/, "https:");
-  let codeReady = false;
-  try {
-    const response = await fetch(`${httpBase}/pair/${code}`, {
-      method: "PUT",
-      headers: { "content-type": "application/json" },
-      body: JSON.stringify(sealed),
-    });
-    codeReady = response.ok;
-  } catch {
-    codeReady = false;
-  }
-
   process.stdout.write(
-    codeReady
-      ? [
-          "",
-          "  Or enter this one-time code in the app:",
-          "",
-          `        ${code.slice(0, 4)} ${code.slice(4)}`,
-          "",
-          `  Relay: ${httpBase}`,
-          "  The code expires after 15 minutes and can be used once.",
-          "",
-        ].join("\n")
-      : [
-          "",
-          `  ! The relay at ${httpBase} did not accept a short code.`,
-          "    The QR still works. Check the relay and retry for code pairing.",
-          "",
-        ].join("\n"),
+    [
+      "",
+      "  Scan this one-time code in GrantTap on iPhone:",
+      "",
+      qr,
+      "",
+      "  Or paste this one-time secure token in the app:",
+      "",
+      `        ${pairing.manualToken}`,
+      "",
+      `  Relay: ${pairing.httpBase}`,
+      `  The encrypted mailbox expires after ${PAIRING_CODE_TTL_MINUTES} minutes and can be used once.`,
+      "  Its 256-bit key is never sent to the relay.",
+      "",
+    ].join("\n"),
   );
 
-  const skipHooks = process.env.GRANTTAP_SKIP_HOOKS === "1";
-  const claude = skipHooks ? null : installClaudeHook();
-  const codex = skipHooks ? null : installCodexHook();
+  const skipHooks = pairing.claude == null || pairing.codex == null;
   process.stdout.write(
     [
       "",
       "  GrantTap is paired on this machine.",
       "",
-      `  room:        ${machineCfg.room}`,
+      `  room:        ${pairing.machineCfg.room}`,
       `  relay:       ${relayUrl}`,
       `  machine cfg: ${machineConfigPath()}`,
       `  phone cfg:   ${phonePairingPath()} (manual fallback; keep private)`,
       "",
       ...(skipHooks
         ? ["  Hooks: skipped (GRANTTAP_SKIP_HOOKS=1)"]
-        : [hookLine("Claude Code", claude!), hookLine("Codex", codex!)]),
+        : [
+            hookLine("Claude Code", pairing.claude!),
+            hookLine("Codex", pairing.codex!),
+            hookLine("Background task sync", pairing.monitor!),
+          ]),
       "",
       "  Keep the MCP server configured in your agent. Approval requests now",
       "  use the paired phone and watch; if the relay is unavailable, hooks fall",

package/apps/bridge/src/bin/monitor.ts

@@ -0,0 +1,37 @@
+/** Persistent, terminal-free task sync for the GrantTap phone app on macOS. */
+import { RelayClient } from "../../../../packages/core/relay-client";
+import { loadConfig, machineConfigPath } from "../config";
+import { startSessionMonitor } from "../monitor";
+
+let client: RelayClient;
+let monitor: ReturnType<typeof startSessionMonitor>;
+
+try {
+  client = new RelayClient(loadConfig(machineConfigPath()), { autoReconnect: true });
+  monitor = startSessionMonitor(client);
+} catch (error) {
+  process.stderr.write(
+    `[granttap-mcp] monitor is not paired: ${error instanceof Error ? error.message : String(error)}\n`,
+  );
+  process.exit(1);
+}
+
+const stop = (): void => {
+  monitor.close();
+  client.close();
+  process.exit(0);
+};
+
+process.on("SIGINT", stop);
+process.on("SIGTERM", stop);
+
+void client
+  .connect()
+  .then(() => monitor.publish())
+  .catch((error: unknown) => {
+    // RelayClient keeps reconnecting in the background. Log the initial error
+    // for diagnostics without terminating the launchd-managed helper.
+    process.stderr.write(
+      `[granttap-mcp] initial relay connection failed: ${error instanceof Error ? error.message : String(error)}\n`,
+    );
+  });

package/apps/bridge/src/bin/setup.ts

@@ -1,11 +1,13 @@
-import { installClaudeHook, installCodexHook } from "../install";
+import { installClaudeHook, installCodexHook, installMonitorHelper } from "../install";
 
 const claude = installClaudeHook();
 const codex = installCodexHook();
+const monitor = installMonitorHelper();
 
 process.stdout.write(
   [
     `Claude Code: ${claude.status} (${claude.detail})`,
     `Codex: ${codex.status} (${codex.detail})`,
+    `Background task sync: ${monitor.status} (${monitor.detail})`,
   ].join("\n") + "\n",
 );