handoff-relay 0.1.0

package/docs/launch-copy.md

@@ -0,0 +1,70 @@
+# Launch Copy
+
+## Short X Post
+
+Public beta: Handoff, human-approved context handoffs between coding agents.
+
+Package selected agent-session context, review before send, review before hydration, keep claims separate from evidence, and get audit receipts for every step.
+
+Not shared memory. Not agent Slack. Just safer teammate handoffs.
+
+## Preflight Before Posting
+
+- Push the release branch to the public GitHub repo.
+- Publish `handoff-relay` to npm.
+- Verify `npx -y handoff-relay doctor --json` runs from a clean temp directory.
+- Record the short demo from `docs/demo-video-script.md` after the npm package is live.
+
+## GitHub Release Announcement
+
+Handoff is a local-first public beta for human-approved context handoffs between coding agents.
+
+The first release focuses on one workflow: a developer can package selected session context into a reviewable packet so another teammate's coding agent can continue without reconstructing the investigation.
+
+What is included:
+
+- Structured ask, share, reply, and clarification packets.
+- Sender approval before send.
+- Recipient review before hydration.
+- Reply approval before return.
+- Sender-controlled reply hydration.
+- Claims and evidence as separate fields.
+- Redaction that blocks secret-looking content by default.
+- Explicit state machine with invalid transition rejection.
+- SQLite coordination storage.
+- Fastify coordination API.
+- MCP server for Claude Code, Codex, and generic MCP clients.
+- Profile-backed setup with `start`, `invite`, `join`, and `doctor`.
+- CLI support for setup, admin flows, approval tokens, debugging, watch, and demos. Normal handoffs happen through MCP tools inside the coding agent.
+- Audit and hydration receipts.
+- Local polling watcher with terminal output, best-effort desktop notifications, and generic webhook posts.
+- Docs, examples, and a five-minute two-user demo.
+
+What this is not:
+
+- Not passive agent memory.
+- Not Slack for agents.
+- Not autonomous agent-to-agent chat.
+- Not a hosted SaaS dependency.
+
+Try it:
+
+```bash
+# Sam hosts a reachable workspace
+npx -y handoff-relay start --lan
+npx -y handoff-relay invite alice
+
+# Alice joins from her machine
+npx -y handoff-relay join http://<host>:3737/invite/<invite-token>
+npx -y handoff-relay doctor
+
+# Then wire Handoff into Codex, Claude Code, Cursor, or another MCP client.
+```
+
+## Comparison
+
+Compared with raw Slack or paste workflows, Relay keeps handoffs structured, reviewed, evidence-backed, and auditable.
+
+Compared with passive memory tools, Relay does not watch every session or ingest everything by default. A human chooses what crosses the boundary.
+
+Compared with autonomous agent-to-agent systems, Relay keeps both humans in the loop: sender approves send, recipient approves hydration, recipient approves replies, sender approves reply hydration.

package/docs/local-self-hosting.md

@@ -0,0 +1,170 @@
+# Local Self-Hosting
+
+Handoff is local-first, but team handoff needs a server Alice's machine can reach. For teammates on the same Wi-Fi, Sam can host directly from his machine:
+
+```bash
+npx -y handoff-relay start --lan
+npx -y handoff-relay invite alice
+npx -y handoff-relay doctor
+```
+
+Alice runs the printed join command on her own machine:
+
+```bash
+npx -y handoff-relay join http://<sam-lan-ip>:3737/invite/<invite-token>
+npx -y handoff-relay doctor
+```
+
+Plain `start` is for local demos, CI smoke tests, or two profiles on one machine. It resets the active profile to loopback-only invite links. Re-run `start --lan` or pass `--public-url` before creating new invites that another machine should join.
+
+For a dedicated trusted host, run one coordination server and have teammates join an invite from that server.
+
+## Coordination Server
+
+```bash
+npx -y handoff-relay server start \
+  --db /srv/handoff/relay.db \
+  --host 10.0.0.10 \
+  --port 3737
+```
+
+Put the host behind your normal network controls. Handoff does not provide a hosted cloud service.
+
+For local profile-managed servers started by `handoff start`, inspect or stop the recorded background process:
+
+```bash
+npx -y handoff-relay server status
+npx -y handoff-relay server stop
+```
+
+## Profiles For Teammates
+
+Create a workspace and invite members with the advanced commands, or run `start --lan` on the host machine and use the printed invite command.
+
+After a teammate runs:
+
+```bash
+npx -y handoff-relay join http://10.0.0.10:3737/invite/<invite-token>
+```
+
+their local profile stores the server URL, member token, workspace ID, and approval secret. They can install one supported local MCP config while joining:
+
+```bash
+npx -y handoff-relay join http://10.0.0.10:3737/invite/<invite-token> --install-mcp codex
+# or
+npx -y handoff-relay join http://10.0.0.10:3737/invite/<invite-token> --install-mcp cursor
+```
+
+Their MCP command stays profile-backed:
+
+```bash
+npx -y handoff-relay server mcp --profile default
+```
+
+## Explicit Server-Backed Commands
+
+Low-level server-backed commands remain available for automation:
+
+```bash
+npx -y handoff-relay inbox \
+  --server-url http://10.0.0.10:3737 \
+  --token <token> \
+  --workspace <workspace-id>
+```
+
+Configure project/repo aliases once per workspace so clone names and local repo aliases resolve to the same packet history:
+
+```bash
+npx -y handoff-relay workspace alias set \
+  --server-url http://10.0.0.10:3737 \
+  --token <admin-token> \
+  --workspace <workspace-id> \
+  --canonical handoff \
+  --alias relay-local \
+  --json
+
+npx -y handoff-relay workspace alias list \
+  --server-url http://10.0.0.10:3737 \
+  --token <token> \
+  --workspace <workspace-id> \
+  --json
+```
+
+## Approval Tokens
+
+Strict profile-backed approval tokens use the local profile:
+
+```bash
+npx -y handoff-relay approval-token <packet-id> --action send
+npx -y handoff-relay approval-token <packet-id> --action hydrate
+```
+
+Profile-backed MCP can opt into agent-confirmed approvals:
+
+```bash
+npx -y handoff-relay server mcp --profile default --agent-approvals
+```
+
+In that mode, the MCP process requests and consumes the same short-lived approval tokens through the configured Handoff backend after the agent shows the packet and you explicitly tell it to send, approve, or hydrate. Local database profiles keep that request local; remote/self-hosted profiles send the approval secret to the configured Handoff server API.
+
+Explicit approval-token mode remains available:
+
+```bash
+npx -y handoff-relay approval-token <packet-id> \
+  --server-url http://10.0.0.10:3737 \
+  --token <token> \
+  --approval-secret <approval-secret> \
+  --action send
+```
+
+Approval secrets stay outside MCP config. `HANDOFF_APPROVAL_SECRET` and the older `AGENT_RELAY_APPROVAL_SECRET` alias are supported for the terminal running approval commands.
+
+## SQLite Operations
+
+- The coordination server database path is controlled with `--db`, `HANDOFF_DB`, or `AGENT_RELAY_DB`.
+- Back up the main `.db` file plus WAL/SHM files when WAL mode is active.
+- Treat the database as sensitive: packet bodies and token hashes live there.
+- Do not put `.relay/*.db` in git.
+
+## Watch Mode
+
+Terminal polling watcher:
+
+```bash
+npx -y handoff-relay watch \
+  --server-url http://10.0.0.10:3737 \
+  --token <token> \
+  --workspace <workspace-id> \
+  --interval 5000
+```
+
+Add best-effort native desktop notifications on the machine running the watcher:
+
+```bash
+npx -y handoff-relay watch \
+  --server-url http://10.0.0.10:3737 \
+  --token <token> \
+  --workspace <workspace-id> \
+  --desktop-notifications
+```
+
+Post concise notification summaries to a generic webhook endpoint:
+
+```bash
+npx -y handoff-relay watch \
+  --server-url http://10.0.0.10:3737 \
+  --token <token> \
+  --workspace <workspace-id> \
+  --webhook-url https://hooks.example.test/relay \
+  --webhook-header "Authorization: Bearer <token>"
+```
+
+The watcher always uses polling. Terminal, desktop, and webhook notifications include sender handle, packet type, title, project, summary, and the open/review action, but never evidence bodies or raw transcripts. For scripts or tests, use `--once` to poll a single time and exit.
+
+## From A Local Checkout
+
+```bash
+pnpm install
+pnpm build
+node dist/cli.js server start --db /srv/handoff/relay.db --host 10.0.0.10 --port 3737
+```

package/docs/packet-schema.md

@@ -0,0 +1,116 @@
+# Packet Schema
+
+Relay packets are Zod-validated TypeScript objects. The source lives in `src/protocol/schema.ts`.
+
+## Packet Types
+
+- `ask`: requires `question`.
+- `share`: requires `finding`.
+- `reply`: requires `answer`.
+- `clarification`: requires `question` and references an original packet.
+
+## Required Contract Fields
+
+- `packet_id`
+- `packet_type`
+- `workspace_id`
+- `sender_member_id`
+- `recipient_member_ids`
+- `created_at`
+- `updated_at`
+- `expires_at` or `recheck_by`
+- `status`
+- `project`
+- `source_client`
+- `title`
+- `summary`
+- `claims`
+- `evidence`
+- `files_or_symbols`
+- `commands_or_tests_run`
+- `what_was_tried`
+- `known_failures`
+- `current_hypothesis`
+- `confidence`
+- `suggested_next_steps`
+- `redaction_report`
+- `hydration_policy`
+- `audit_receipt`
+
+## Project Identity
+
+Packet `project.repo_name` is the canonical workspace project name when a matching project/repo alias is configured. Configure aliases with `workspace alias set` or `relay_configure_project_alias`; history/search filters accept either the canonical project or a configured alias.
+
+```json
+{
+  "repo_name": "handoff",
+  "git_remote_fingerprint": "sha256:...",
+  "branch": "main",
+  "commit_hash": "abc123"
+}
+```
+
+## Claims
+
+```json
+{
+  "claim_id": "clm_1",
+  "text": "The failure happens after refresh token rotation.",
+  "confidence": "medium",
+  "status": "observed",
+  "evidence_ids": ["ev_1"],
+  "needs_recheck": true
+}
+```
+
+## Evidence
+
+```json
+{
+  "evidence_id": "ev_1",
+  "kind": "test_failure",
+  "label": "vitest failure",
+  "source": "pnpm test auth-refresh",
+  "excerpt": "expected 200, received 401",
+  "hash": "sha256:...",
+  "captured_at": "2026-06-15T12:00:00.000Z",
+  "sensitivity": "normal"
+}
+```
+
+## State Model
+
+Supported statuses:
+
+```text
+draft
+pending_sender_approval
+sent
+delivered
+viewed
+accepted
+clarification_requested
+response_drafting
+pending_recipient_approval
+replied
+hydrated
+archived
+declined
+expired
+superseded
+closed_resolved
+closed_unresolved
+```
+
+Invalid transitions throw `INVALID_STATE_TRANSITION`.
+
+Examples:
+
+- `pending_sender_approval` drafts can be edited with `update-draft`/`relay_update_draft`; edits recalculate redaction and write an `edit` audit receipt.
+- `pending_sender_approval -> sent` only by sender.
+- `sent -> delivered` only by system.
+- `delivered -> viewed -> accepted -> hydrated` only by recipient.
+- `response_drafting -> pending_recipient_approval -> replied` only by recipient.
+- `replied -> viewed -> hydrated` by the reply recipient.
+
+See [example packets](../examples/packets/).

package/docs/security-privacy.md

@@ -0,0 +1,90 @@
+# Security And Privacy Model
+
+Handoff is built around review gates, bounded packets, and local ownership.
+
+## What Crosses The Boundary
+
+Packets carry selected fields:
+
+- Summary, question/finding/answer.
+- Claims with confidence, status, evidence ids, and recheck flags.
+- Evidence with kind, source, excerpt, hash, capture time, and sensitivity.
+- Project identity: repo name, remote fingerprint, branch, optional commit.
+- Audit and redaction receipts.
+
+Raw transcripts are not captured or shared by default.
+
+## Required Human Gates
+
+- Sender reviews and approves ask/share packets before send.
+- Recipient views and accepts ask/share packets before hydration.
+- Recipient reviews and approves replies before return.
+- Sender views replies and hydrates them explicitly.
+
+The service rejects invalid state transitions, and send/reply/hydrate actions require a short-lived human approval token. Strict mode generates that token outside MCP through the local CLI confirmation prompt. Agent-confirmed mode is an opt-in profile-backed MCP mode where the MCP process can request the same short-lived token through the configured Handoff backend after the agent shows the packet and the user explicitly tells it to send, approve, or hydrate. Local database profiles keep that request local; remote profiles send the approval secret to the configured Handoff server API.
+
+Approval-token minting requires both the member token and a separate per-member approval secret returned during setup/acceptance. A member token alone cannot mint approval tokens. Agent-confirmed mode does not cryptographically prove a fresh terminal phrase; it treats explicit instruction in the active local agent session as the approval event.
+
+## Redaction
+
+The redaction engine blocks by default when it sees:
+
+- API-key or token-looking values.
+- Private key blocks.
+- Credential-bearing URLs.
+- `.env`-like secret values.
+- Evidence marked `secret_detected` or `restricted`.
+
+Redaction scans packet titles, summaries, questions/findings/answers, hypotheses, claims, evidence labels/sources/excerpts, files or symbols, commands/tests, tried steps, known failures, and suggested next steps before a packet can be approved.
+
+It warns, but does not block by default, for:
+
+- Local absolute paths.
+- Oversized excerpts that should be compressed.
+
+Hashes are preserved when evidence excerpts are truncated or omitted.
+
+## Authorization
+
+Authorization is enforced in the service/storage layer:
+
+- Members can send only inside their workspace.
+- Members can read packets they sent or packets addressed to them.
+- Admins can manage workspace membership and view audit metadata by default.
+- Admin packet body access is off by default and must be enabled as a workspace setting.
+- Audit receipts are available through CLI, API, and MCP. Workspace-wide audit listing is admin-only; packet-specific audit listing follows metadata visibility.
+- Revoked members cannot authenticate and cannot receive future packets.
+- Search and history filter before returning results. Admins without body access can search and filter metadata fields only; body/provenance text is not exposed as a search oracle.
+
+## Audit Receipts
+
+Receipts are recorded for:
+
+- `draft`
+- `approve`
+- `send`
+- `deliver`
+- `view`
+- `accept`
+- `edit`
+- `hydrate`
+- `reply`
+- `decline`
+- `archive`
+- `close`
+- `configure_project_alias`
+- `revoke`
+- `rotate_token`
+- `rotate_approval_secret`
+- `search`
+
+Receipts avoid logging extra raw sensitive evidence beyond the approved packet body.
+
+## Operational Notes
+
+- Treat `.relay/*.db` as sensitive. It contains packet bodies, member token hashes, audit metadata, and hydration receipts.
+- Treat approval secrets like local signing material. Keep them out of MCP config, tool schemas, and committed files. Strict mode uses them through `approval-token`; agent-confirmed mode lets the local profile-backed MCP process load them without exposing them to the agent as arguments.
+- Rotate approval secrets with `member rotate-approval-secret` if one appears in shell history, terminal logs, or copied demo output. Rotation requires the current approval secret, returns the replacement once, invalidates unconsumed approval tokens minted by that member, and records `rotate_approval_secret`.
+- Back up the SQLite database like any local coordination data store.
+- Prefer private network access or localhost-only binding for the Fastify coordination server.
+- Rotate member tokens if a token is pasted into a prompt, shell history, ticket, or chat. Rotate both credentials if both the member token and approval secret are exposed.

package/docs/troubleshooting.md

@@ -0,0 +1,180 @@
+# Troubleshooting
+
+## Start With Doctor
+
+Run:
+
+```bash
+npx -y handoff-relay doctor
+npx -y handoff-relay doctor --json
+```
+
+Doctor checks the Handoff home directory, active profile, credential file permissions, member token, approval secret, server reachability, workspace access, and the profile-backed MCP command.
+
+If the profile is missing and you are hosting a workspace for teammates, run:
+
+```bash
+npx -y handoff-relay start --lan
+npx -y handoff-relay invite alice
+```
+
+If you are joining someone else's workspace, ask them for the invite command and run:
+
+```bash
+npx -y handoff-relay join <invite-link>
+```
+
+Plain `start` is only the right recovery path for local demos, CI smoke tests, or two profiles on one machine.
+
+If `doctor` reports `WARN` for `mcp_config`, add Handoff to your MCP client. For Codex or Cursor, Handoff can write the common global config while hosting or joining:
+
+```bash
+npx -y handoff-relay start --lan --install-mcp codex
+npx -y handoff-relay start --lan --install-mcp cursor
+npx -y handoff-relay join <invite-link> --install-mcp codex
+npx -y handoff-relay join <invite-link> --install-mcp cursor
+```
+
+For Claude Code or another MCP client, add the printed profile-backed command:
+
+```bash
+npx -y handoff-relay server mcp --profile default
+```
+
+If a teammate cannot join from another machine, restart the host in LAN mode and send a fresh invite:
+
+```bash
+npx -y handoff-relay start --lan
+npx -y handoff-relay invite alice
+```
+
+## `better-sqlite3` Cannot Find Native Bindings
+
+Run:
+
+```bash
+pnpm rebuild better-sqlite3 esbuild
+```
+
+This package includes `pnpm-workspace.yaml` with `onlyBuiltDependencies` for `better-sqlite3` and `esbuild`. If your pnpm policy still blocks builds, approve those packages for this checkout.
+
+## MCP Server Starts But Tools Do Not Appear
+
+- Confirm `pnpm build` produced `dist/cli.js`.
+- Run the command directly:
+
+  ```bash
+  npx -y handoff-relay server mcp --profile default
+  ```
+
+- In Claude Code, check `/mcp` or start with `--mcp-config`.
+- In Codex, confirm the trusted `config.toml` has the expected `mcp_servers.<id>.command` and `args`.
+- Confirm the MCP args use `--profile default` unless you intentionally need `--explicit-auth`.
+
+## Redaction Blocks A Packet
+
+Handoff blocks secret-looking content by default. Remove the evidence excerpt, replace it with a hash or summary, then create a new draft.
+
+Common causes:
+
+- `API_KEY=...`
+- `TOKEN=...`
+- Private key PEM blocks.
+- `postgres://user:pass@host/db`
+- Evidence marked `secret_detected` or `restricted`.
+
+## Recipient Cannot See A Packet
+
+Check:
+
+- The recipient handle is in the same workspace.
+- The member is active, not revoked.
+- The packet was approved and delivered.
+- The token belongs to the intended workspace.
+
+Use:
+
+```bash
+npx -y handoff-relay member list --db .relay/team.db --token <admin-token> --workspace <workspace-id>
+npx -y handoff-relay status <packet-id> --db .relay/team.db --token <sender-token>
+```
+
+## Hydration Or Approval Is Rejected
+
+Strict mode requires explicit review and a human approval token:
+
+- Ask/share packets: recipient must `view`, then `accept`, then generate an `approval-token --approval-secret <secret> --action hydrate`, then `hydrate`.
+- Reply packets: sender must `view`, then generate an `approval-token --approval-secret <secret> --action hydrate`, then `hydrate`.
+
+Invalid transitions return `INVALID_STATE_TRANSITION`.
+
+Missing, expired, reused, or wrong-action approval tokens return `FORBIDDEN`.
+
+If you intended to use agent-confirmed approvals, confirm your MCP command includes profile mode and `--agent-approvals`:
+
+```bash
+npx -y handoff-relay server mcp --profile default --agent-approvals
+```
+
+Agent-confirmed approvals are not available in explicit-auth MCP mode or when the local profile credentials are missing.
+
+If `/packets/:packetId/approval-token` returns `FORBIDDEN` with an approval secret message, use the CLI `approval-token` command with the approval secret returned during setup/acceptance. Static local-renderer headers are ignored.
+
+In profile-backed mode:
+
+```bash
+npx -y handoff-relay approval-token <packet-id> --action send
+```
+
+In explicit advanced mode:
+
+```bash
+npx -y handoff-relay approval-token <packet-id> --db .relay/team.db --token <member-token> --approval-secret <approval-secret> --action send
+```
+
+For audit/debugging:
+
+```bash
+npx -y handoff-relay history --db .relay/team.db --token <member-token> --workspace <workspace-id> --filter open
+npx -y handoff-relay audit --db .relay/team.db --token <admin-token> --workspace <workspace-id>
+```
+
+If an approval secret leaks, rotate it and update your local secret manager:
+
+```bash
+npx -y handoff-relay member rotate-approval-secret --db .relay/team.db --token <member-token> --approval-secret <current-approval-secret> --json
+```
+
+The old approval secret stops working immediately, and unconsumed approval tokens already minted by that member are invalidated. If you no longer have the current approval secret, ask a workspace admin to revoke and reinvite the member.
+
+## Packet Needs More Evidence
+
+Recipients can ask for clarification before hydration:
+
+```bash
+npx -y handoff-relay clarify <packet-id> --db .relay/team.db --token <recipient-token> --question "Can you include the failing assertion?" --requested-evidence "test failure"
+```
+
+## Watcher Prints Nothing
+
+The watcher only reports new packet ids once per process. Check `inbox` directly:
+
+```bash
+npx -y handoff-relay inbox --db .relay/team.db --token <token> --workspace <workspace-id>
+```
+
+## Desktop Or Webhook Notifications Do Not Fire
+
+Desktop notifications are best-effort from the local watcher process:
+
+- macOS uses `osascript`.
+- Linux uses `notify-send`; install your desktop notification package if it is missing.
+- Windows uses a PowerShell tray notification.
+
+Webhook notifications require a reachable endpoint that accepts JSON POSTs:
+
+```bash
+npx -y handoff-relay watch --db .relay/team.db --token <token> --workspace <workspace-id> --webhook-url https://hooks.example.test/relay --once
+```
+
+If the adapter fails, `watch` still prints the terminal notification and writes an adapter warning to stderr.

package/examples/hydration-receipts/reply-hydration.json

@@ -0,0 +1,14 @@
+{
+  "receipt_id": "rcp_hydrate_example",
+  "action": "hydrate",
+  "actor_member_id": "mem_sam",
+  "packet_id": "pkt_example_reply",
+  "workspace_id": "wrk_example",
+  "created_at": "2026-06-15T12:25:00.000Z",
+  "metadata": {
+    "client": "codex",
+    "session_id": "sam-session",
+    "packet_type": "reply"
+  },
+  "receipt_hash": "sha256:example"
+}