granttap-mcp 0.6.7 → 0.7.0

package/README.md

@@ -2,303 +2,198 @@
 
 [![npm](https://img.shields.io/npm/v/granttap-mcp)](https://www.npmjs.com/package/granttap-mcp)
 [![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.**
+GrantTap is a Personal live control center for local coding agents.
 
-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.
+> See what your coding agents are doing. Step in when they need you.
 
-[Website](https://granttap.com) ·
-[npm](https://www.npmjs.com/package/granttap-mcp) ·
+This repository is the canonical machine runtime: CLI, MCP server, provider
+hooks, local adapters, and TypeScript wire schemas. Agents and provider
+credentials stay on your computer. Native iPhone and Apple Watch traffic is
+end-to-end encrypted.
+
+[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)
+[Relay source](https://github.com/sergii-ziborov/granttap-relay)
+
+## iPhone and Apple Watch
 
 <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">
+  <img src="docs/images/iphone-command-center.png" width="230" alt="GrantTap Now with Needs You and at-risk tasks">
+  <img src="docs/images/iphone-chat.png" width="230" alt="GrantTap live task timeline and composer">
+  <img src="docs/images/iphone-mcp-usage.png" width="230" alt="GrantTap actionable usage overview">
 </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>
+<p align="center">
+  <img src="docs/images/apple-watch-inbox.png" width="180" alt="GrantTap Needs You on Apple Watch">
+  <img src="docs/images/apple-watch-approval.png" width="180" alt="GrantTap approval on Apple Watch">
+</p>
 
-The companion iPhone and Apple Watch app is currently in testing. Release
-status is published at [granttap.com](https://granttap.com).
+## Supported providers
 
-## What you get
+- Primary: Claude Code and Codex.
+- Beta: Cursor.
+- Experimental where available: Grok Build.
 
-- **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.
+GrantTap reports the depth each provider actually exposes. Visibility does not
+imply deterministic remote blocking or full mobile continuation.
 
-## See it in action
+## Project Mesh and task handoff
 
-### iPhone
+Project Mesh adds stable Project and Task identity above provider-native
+sessions. A Task can retain its `taskId` across multiple executions, agents,
+and computers while each native session remains intact.
 
-| 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"> |
+Agents can read the compact `granttap://mesh/current` MCP resource and publish
+bounded progress, dependency, question, answer, claim, conflict, and completion
+events through the existing `notify` tool. Full transcripts and hidden
+reasoning are never mesh payloads. Claims have TTLs; a colliding claim is
+rejected before it is recorded so agents can choose different work or contact
+the owner before escalating to Needs You.
 
-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.
+The first executable handoff path is Claude Code ↔ Codex across linked
+computers. GrantTap builds a bounded Task Capsule from explicit task/git facts,
+requires local phone authorization, creates a separate target branch/worktree,
+starts the target execution, and returns a receipt bound to the exact capsule.
+Cursor and Grok Build use the same provider-neutral schema and discovery model;
+unsupported remote-start paths fail closed instead of claiming parity.
 
-### Apple Watch
+### Grok Bot as a scoped Mesh participant
 
-| 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"> |
+Grok Bot is a persistent agent, not a coding-agent integration. The iPhone
+issues a one-time encrypted Mesh Invite scoped to the Projects you select, and
+the invite is redeemed on the trusted CLI:
 
-## Connect in under a minute
+```bash
+granttap mesh connect <one-time-invite>
+```
+
+Grok Bot then runs `granttap internal mesh-mcp`, a separate scoped MCP server
+that exposes only the twelve task-scoped Mesh operations. It cannot create
+invites, change the relay, expand Project scope, or reach `setup`; revoking the
+endpoint from the iPhone stops new Mesh operations immediately while local Task
+history stays on the device.
 
-Add GrantTap to each agent you use:
+## Install
 
 ```bash
-npm install
-npm install -g .
-codex mcp add granttap -- granttap
-claude mcp add granttap -- granttap
+npm install -g granttap-mcp
+granttap setup
 ```
 
-Those commands use this checkout. Publish/release it before replacing the local
-install with an npm registry version.
-
-Start a fresh agent task and say **“Connect GrantTap.”** The `connect` tool:
+`granttap setup` detects supported local agents, installs or repairs their
+hooks, installs the background helper, configures Cursor's persistent local
+OAuth service when Cursor is present, and starts phone pairing when run in an
+interactive terminal. It ends with one exact next action.
 
-1. creates a new end-to-end encrypted pairing;
-2. returns a scannable one-time QR directly in the agent chat.
+The normal CLI surface is intentionally small:
 
-Then run the separate MCP `setup` tool. It installs Cursor shell/MCP policy
-hooks, the complete Claude Code matcher, both Codex hooks, and the per-user
-background helper for task sync and schedules.
+```text
+granttap setup
+granttap status [--json]
+granttap connect [--relay <wss-url>]
+granttap reset [--yes]
+granttap mesh connect <one-time-invite>
+```
 
-Scan the QR with GrantTap on iPhone. No terminal QR, copied pairing JSON, or
-open background terminal is required.
+`connect` reuses a valid pairing. If none exists, it creates a one-time QR.
+Custom relays are CLI-only and explicit. `reset` moves active pairing files to
+recoverable local backups before a new pairing can be created.
 
-If an MCP client cannot render image content, use the CLI fallback:
+Cursor setup is automatic in the normal flow. The advanced repair command is:
 
 ```bash
-npm install -g granttap-mcp
-granttap connect
-granttap setup
-granttap status
+granttap cursor repair
 ```
 
-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.
+After Codex hooks are installed, open `/hooks`, review and trust both exact
+GrantTap hooks, then restart Codex. GrantTap never treats installation as user
+trust.
 
-After setup, open `/hooks` in Codex, review and trust both exact GrantTap hooks,
-then restart Codex. Installation alone is not reported as trusted or connected.
+## MCP contract
 
-## Cursor Settings → Authorize
+`tools/list` returns exactly four public tools:
 
-Cursor only shows **Authorize / Sign in** for **HTTP/SSE** MCP servers that
-speak OAuth (same pattern as Lovable / Figma). The default stdio entry
-(`command` + `args`) cannot show that button — Cursor documents stdio auth as
-**Manual**.
+| Tool | Contract |
+| --- | --- |
+| `connect` | Reuse the existing production pairing or return a one-time QR |
+| `notify` | Send a non-blocking status update of at most 2,000 characters |
+| `ask_yes_no` | Ask a yes/no question and wait for the explicit answer |
+| `ask` | Ask an open question and wait for typed or spoken text |
 
-To enable Authorize for GrantTap, use the one-step local setup:
+MCP `connect` accepts no custom routing, replacement, or key-rotation input.
+Setup is CLI-only because it changes provider configuration and must not be
+available to a model through prompt injection.
 
-```bash
-npm install -g granttap-mcp
-granttap authorize
-```
+`notify` may alternatively carry one bounded task-scoped Mesh event. This does
+not add a fifth MCP tool or grant any global setup capability.
 
-It preserves unrelated entries in `~/.cursor/mcp.json`, replaces only the
-`granttap` entry with the loopback HTTP endpoint, keeps a one-time
-`.bak-granttap`, and starts the OAuth MCP server. Then open
-**Cursor Settings → MCP → GrantTap → Authorize**. The local consent page shows
-the pairing QR plus a manual-token fallback when the Mac is not paired yet.
-`granttap authorize` installs a loopback-only per-user LaunchAgent, verifies its
-exact `/healthz` identity, writes Cursor config only after that check succeeds,
-and exits. The service uses RunAtLoad + KeepAlive, so closing the terminal or
-restarting the Mac does not leave Cursor pointing at a dead URL.
+Provider-native approvals and mobile continuation require the matching local
+adapter. MCP registration alone is never reported as proof that an integration
+is ready.
 
-The foreground troubleshooting flow is:
+## What the runtime publishes
 
-1. Run the local HTTP OAuth server (loopback only):
+The bounded encrypted protocol preserves:
 
-```bash
-granttap serve
-# listens on http://127.0.0.1:17342/mcp
-```
+- provider, task, computer, model, workspace, branch, state, and summary;
+- visible activity, delivery state, context and token counters;
+- MCP, Skill, and CLI observations;
+- child-agent relationships;
+- per-capability outcome: `success`, `error`, `cancelled`, or `unknown`.
 
-2. Point Cursor at the HTTP URL in `~/.cursor/mcp.json` (replace the stdio
-   `command` entry):
-
-```json
-{
-  "mcpServers": {
-    "granttap": {
-      "url": "http://127.0.0.1:17342/mcp"
-    }
-  }
-}
-```
+An optional bounded `errorClass` may describe an error category. Full tool
+error payloads are not copied into usage telemetry by default.
 
-3. Open **Cursor Settings → MCP → GrantTap** and click **Authorize**.
-   A local browser page confirms linking Cursor to this Mac’s pairing
-   (`~/.granttap`). If unpaired, it shows a one-time QR first.
-
-OAuth tokens are stored in `~/.granttap/mcp-oauth.json` (mode `0600`). They do
-**not** replace E2EE pairing keys. Claude Code / Codex can keep using the
-stdio transport; Authorize is a Cursor Settings affordance.
-
-Details: [docs/cursor-authorize.md](docs/cursor-authorize.md).
-
-`granttap setup` is the policy-hook entry point: it installs Cursor
-`beforeShellExecution`, `afterShellExecution`, and `beforeMCPExecution` hooks,
-plus Claude/Codex hooks and background task sync. It does not opt a new user
-into OAuth; when an exact Cursor HTTP entry already exists, it also repairs the
-persistent OAuth service. Per-chat blocks are checked before phone routing,
-and ambiguous/unscoped Cursor calls fall back to Cursor's native permission UI.
-
-## 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 within one encrypted-frame budget | 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 update |
-| `setup` | Registers Cursor/Claude/Codex policy hooks and the terminal-free helper |
-
-The default answer timeout is three minutes. Override it with
-`GRANTTAP_ASK_TIMEOUT_MS`.
-
-## 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.
-- Cloudflare accepts at most a 32 MiB WebSocket frame. Because task messages are
-  sealed and base64-encoded twice, attachments share a 16,000,000-character
-  base64 budget (about 12 MB raw total); five small files fit, five 6 MB files do not.
-
-The in-chat QR is marked user-only for MCP hosts, but that annotation is not a
-cryptographic separation from the model provider. Use CLI `connect` when the
-model provider itself is part of your threat model; Cloudflare still receives
-only the mailbox id and ciphertext in either flow.
-
-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.
-
-## CLI commands
-
-| Command | Purpose |
+## Local enforcement
+
+GrantTap can narrow later actions for an exact task only where a provider
+offers a deterministic local hook. Global provider configuration always wins.
+Read-only integrations stay read-only in the app instead of presenting a fake
+toggle.
+
+The user-facing approval modes map to the existing runtime policy:
+
+| Personal UI | Runtime |
 | --- | --- |
-| *(no command)* | Starts the GrantTap MCP stdio server |
-| `serve` | HTTP MCP + loopback OAuth for Cursor Settings → Authorize |
-| `authorize` | Installs the persistent loopback OAuth service, verifies health, and configures Cursor |
-| `connect [relayUrl]` | Creates an E2EE pairing; optionally targets a self-hosted `wss://` relay |
-| `setup` | Registers Cursor/Claude/Codex hooks, background sync, and repairs configured OAuth |
-| `status [--json]` | Reads local readiness; JSON uses `granttap.provider-status.v1` and contains no keys |
-
-The installed public command is `granttap`; `granttap-mcp` remains an alias for
-existing scripts. `status` only reads configuration and runtime state—it does
-not install hooks, pair a device, start OAuth, or reload the background helper.
-If Cursor has an HTTP GrantTap entry, status requires both an owned persistent
-service and a live identity-checked health response; a dead URL is never shown
-as connected. Without an HTTP entry, OAuth remains optional and Cursor policy
-readiness is based on the full hook set, pairing, and background sync.
+| Ask for risky actions | `except_push` |
+| Ask for every action | `ask` |
+| Use agent defaults | no GrantTap gate for that task |
 
-## Development
+Legacy custom levels remain compatible but are not part of the primary flow.
+
+## Relay boundary
+
+Pairing and task keys are generated locally. The relay receives opaque routing
+metadata and ciphertext, not provider credentials or task plaintext. Pairing
+handoff uses a relay-visible random mailbox ID plus an independent transfer key
+that stays in the QR.
+
+APNs carries a content-neutral wake only. It contains no prompt, task title,
+command, path, request ID, or ciphertext. See [SECURITY.md](SECURITY.md) for the
+complete boundary and reporting instructions.
 
-Requires Node.js 20 or newer.
+## Development
 
 ```bash
-git clone https://github.com/sergii-ziborov/granttap-mcp.git
-cd granttap-mcp
 npm install
-npm test
 npm run typecheck
+npm test
+npm run package:allowlist
+npm run test:coverage   # macOS only — see below
 ```
 
-Start the stdio server with `npm start`. Run `npm run setup` only on a machine
-where you want GrantTap hooks installed.
-
-## Links
+`npm test` runs everywhere. Both suites run with an isolated `HOME`, so a
+developer's own Claude/Codex/Cursor data can never inflate a local result: the
+numbers on this machine and in CI are the same. The coverage contract is
+measured on macOS because the background helper, the Cursor OAuth service, and
+the installer only execute there, so a Linux percentage understates real
+runtime coverage. CI runs the cross-platform suite on Linux and the coverage
+gate on macOS, and `npm publish` enforces the same gate through
+`prepublishOnly`.
 
-- [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)
+Do not publish from a dirty checkout or before the package allowlist, tests,
+typecheck, and release checks pass.
 
-GrantTap is not affiliated with Anthropic or OpenAI.
+GrantTap is not affiliated with Anthropic, OpenAI, Apple, Anysphere, or xAI.

package/SECURITY.md

@@ -6,82 +6,76 @@ 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 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.
+Do not open a public issue containing pairing tokens, device keys, room IDs,
+real prompts, command payloads, APNs tokens, local configuration, or a working
+exploit. Use synthetic data and include the affected package version or commit.
 
 ## Local secrets
 
-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.
+Pairing state belongs in `~/.granttap/`. It must never be committed, attached
+to an issue, or printed in logs. The active secret classes are endpoint NaCl
+keys, per-task keys, the one-time pairing transfer key, and the random room
+credential used for authenticated WebSocket and APNs registration.
 
-Current pairings contain three independent secret classes: NaCl endpoint keys,
-random per-task keys, and a random `pushAuth` room credential that authorizes
-the room WebSocket and 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.
+Provider credentials remain in each provider's own local authentication flow.
+GrantTap does not send them to the relay.
 
 ## 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.
-- The terminal `connect` flow keeps that transfer key outside model context.
-  The MCP `connect` tool deliberately returns a QR in chat for convenience and
-  marks it user-only, but MCP audience annotations are not a cryptographic
-  boundary: depending on the host, the chat/model provider may receive tool
-  images. Use terminal pairing when the model provider is in your threat model.
-- 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.
-  It is a best-effort silent background notification; after waking, iOS pulls
-  and decrypts the queue and creates the single actionable local notification.
-- 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. Delivery ACK is emitted only
-after a consumer accepts the decrypted payload. A processing lease recovers
-after a crash; agent execution is at-least-once across that rare crash window,
-because third-party Codex/Claude CLIs do not expose a transactional idempotency key.
-
-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.
+- Every computer pairing is generated locally with unique Curve25519 keys.
+- Pairing handoff uses an opaque 128-bit mailbox ID and an independent 256-bit
+  transfer key. The relay receives the mailbox ID and ciphertext, not the key.
+- Each attached task has an independent 256-bit task key. One task key cannot
+  decrypt another task.
+- Project Mesh snapshots have independent project keys. Cross-computer events
+  remain under their Task key, and a linked destination receives either key
+  only through an explicit phone-mediated route.
+- Task keys travel only inside the authenticated device channel and are stored
+  in device-protected storage.
+- Native phone/watch payloads remain authenticated ciphertext across the
+  network, Cloudflare, Durable Objects, and the offline queue.
+- APNs is a neutral wake. It contains no prompt, task title, command, path,
+  task/request/delivery ID, or task ciphertext.
+- MCP audience annotations are not a cryptographic model-provider boundary.
+  Use CLI `granttap connect` when the model provider itself is in the threat
+  model.
+
+Cloudflare can observe operational metadata required to run the relay: opaque
+room/mailbox IDs, routing role, IP address, timing, expiry, ciphertext size, and
+APNs token/environment. It cannot decrypt task content from those fields.
+
+The honest endpoint limit remains: a compromised device can read the tasks
+whose independent keys were granted to it. The protection is against relay,
+database/network compromise, other pairings, and disclosure of a different
+task key—not against an endpoint already authorized for that task.
+
+Task Capsules are strict, bounded schemas containing goal, explicit status,
+repository/commit facts, changed-file names, tests, dependencies, claims,
+remaining work, and explicit decisions. Unknown fields are rejected; hidden
+reasoning and transcript replication are outside the contract. Handoff
+acceptance includes a SHA-256 receipt over a canonical capsule and the source,
+target, Task identity, and acceptance time. Stale claims expire, replayed event
+IDs are ignored, and destination routing is explicit.
+
+## Runtime controls
+
+Provider hooks enforce policy on the computer. Global provider deny always
+wins. If a provider cannot deterministically block a capability, GrantTap must
+report the observation as read-only instead of implying enforcement.
+
+`setup` is CLI-only because it writes local provider configuration and installs
+background services. The public MCP server can only connect an existing or new
+phone pairing, notify, and ask bounded questions; it cannot reconfigure the
+machine or select a custom relay.
+
+A Grok Bot endpoint is a separate scoped identity. Its one-time invite is
+created only on the iPhone, stored on the relay as ciphertext, redeemed only by
+the trusted `granttap mesh connect` CLI, and written to disk with `0600`
+permissions. Its MCP server exposes only task-scoped Mesh operations bound to
+one credential: every call re-checks endpoint, credential, policy revision,
+expiry, actor, Project scope, and operation, and a revoked or disabled endpoint
+fails closed. Invite creation, actor enablement, Project scope, and revocation
+stay in the iPhone UI and the trusted CLI, never in a model-callable tool.
 
 Relay vulnerabilities should be reported through the
 [GrantTap relay advisory form](https://github.com/sergii-ziborov/granttap-relay/security/advisories/new).