@hansjm10/volt-coding-agent 0.0.0-bootstrap.0 → 0.1.0

package/docs/iroh-remote-protocol.md

@@ -0,0 +1,431 @@
+# Iroh Remote Protocol v1
+
+Iroh remote access tunnels Volt RPC JSONL over an Iroh QUIC bidirectional stream. The host runs on the user's machine; clients dial a ticket, send one handshake line, then exchange the same LF-delimited RPC messages documented in [RPC mode](rpc.md), subject to the remote command allowlist below.
+
+This protocol is preview-stable for external client authors. Clients must reject unsupported required values, ignore unknown fields unless this document says otherwise, and treat secrets as one-time credentials.
+
+For user-facing setup, start the background daemon with `volt daemon start` (see [Background daemon](daemon.md)), create tickets with `volt remote pair`, inspect `volt remote status`, revoke clients with `volt remote revoke <node-id>`, and approve same-device re-pairing with `volt remote approve-repair <node-id>`. The host-side management workflow, state/audit paths, unsafe tool warnings, relay mode, and npm/source-only daemon limitation are documented in [Using Volt](usage.md#remote-access-over-iroh-preview) and [Security](security.md#remote-access-over-iroh-preview). This document defines the wire contract only.
+
+## Version and ALPN
+
+- Ticket prefix: `volt+iroh://v1/`
+- ALPN: `volt-rpc/0`
+- Handshake type: `volt_iroh_hello`
+- Handshake response type: `volt_iroh_handshake`
+- Host feature: `multi_streams.v1`
+- Host feature: `conversation_streams.v1`
+- Host feature: `working_directories.v1`
+- Host feature: `agent_settled.v1`
+- Host feature: `session_runtime_state.v1`
+
+The URL prefix selects protocol v1. The `alpn` ticket field and `protocol` hello field must be exactly `volt-rpc/0`.
+
+## Ticket
+
+A v1 ticket is:
+
+```text
+volt+iroh://v1/<base64url-json>
+```
+
+The decoded JSON payload is an object with these fields:
+
+| Field | Required | Meaning |
+| --- | --- | --- |
+| `alpn` | yes | Must be `volt-rpc/0`. |
+| `irohTicket` | yes | Native Iroh endpoint ticket used to dial the running host. |
+| `workspace` | yes | Registered workspace name requested by the client. The host resolves this name from persisted state; clients must not send host paths. |
+| `secret` | no | One-time pairing secret. Present only in pairing tickets. Persisted host state stores only a hash. |
+| `expiresAt` | no | Unix epoch milliseconds after which the pairing secret is invalid. |
+| `nodeId` | no | Host node ID. Required for saved-host reconnect records and verified against the native Iroh ticket plus handshake host identity. |
+| `relayMode` | no | `default` or `disabled`; clients may use it only as a diagnostic hint. |
+
+Unknown ticket fields are reserved for compatible extension and must be ignored by v1 clients.
+
+Example decoded payload:
+
+```json
+{
+  "alpn": "volt-rpc/0",
+  "expiresAt": 1790000000000,
+  "irohTicket": "<iroh-endpoint-ticket>",
+  "nodeId": "<host-node-id>",
+  "relayMode": "default",
+  "secret": "<one-time-pairing-secret>",
+  "workspace": "volt"
+}
+```
+
+Pairing tickets are explicit Pair Phone invitations. They are short-lived, one-time credentials for adding a new client, not durable reconnect credentials. Mobile-facing host startup does not create an active pairing ticket; `volt remote pair` creates the QR/ticket from a running host when a phone is being added. The ticket's `workspace` is the initial registered workspace for that pairing, not the client's permanent workspace boundary.
+
+Saved-host reconnect data uses the same ticket payload shape without `secret` or `expiresAt`. A saved reconnect record must retain a non-empty `nodeId`, supported `relayMode`, `workspace`, and `irohTicket`; records missing those required reconnect fields are invalid and should not be dialed. Ordinary reconnect after app restart, network loss, or host restart with the same host state uses this saved-host data and does not require another QR scan. A saved-host client may synthesize a reconnect ticket for any registered workspace name it learned from verified host metadata; the host remains authoritative and rejects unknown names with `workspace_unregistered`, removed authorizations with `workspace_authorization_removed`, and registered names whose local directory is unavailable with `workspace_unavailable`.
+
+## Stream handshake
+
+After opening an Iroh bidirectional stream, the client writes one UTF-8 JSON object followed by LF (`\n`):
+
+```json
+{"type":"volt_iroh_hello","protocol":"volt-rpc/0","workspace":"volt","conversation":{"target":"last"},"secret":"<one-time-pairing-secret>","clientLabel":"Jordan iPhone","clientNodeId":"<claimed-client-node-id>"}
+```
+
+Fields:
+
+| Field | Required | Meaning |
+| --- | --- | --- |
+| `type` | yes | Must be `volt_iroh_hello`. |
+| `protocol` | yes | Must be `volt-rpc/0`. |
+| `workspace` | yes | Registered workspace name requested by the client. |
+| `conversation` | one mode required | Conversation stream target: `{ "target": "last" }`, `{ "target": "new" }`, or `{ "target": "session", "sessionId": "..." }`. A `new` target may include a `worktreeId` on `worktrees.v1` hosts and/or `workingDirectory` on `working_directories.v1` hosts. |
+| `workspaceDiscovery` | one mode required | Utility stream target. The only v1 payload is `{ "purpose": "list_sessions" }`. |
+| `workspaceManagement` | one mode required | Utility stream target. Payloads are `{ "purpose": "unregister_workspace" }` or, on `worktrees.v1` hosts, `{ "purpose": "manage_worktrees" }`. |
+| `secret` | no | Pairing secret when completing a pairing ticket. Omitted for already-paired clients. |
+| `clientLabel` | no | Human-readable client label requested during pairing. |
+| `clientNodeId` | no | Client-claimed node ID for diagnostics only. It is not authoritative. |
+
+Mobile clients must include exactly one stream mode: `conversation`, `workspaceDiscovery`, or `workspaceManagement`. A `conversation.target:"session"` payload must include a strict lowercase remote session ID. `last` and `new` targets must not include a session ID. A `worktreeId` (lowercase worktree id syntax) is accepted only on `target:"new"` and only by hosts advertising `worktrees.v1`; `last` and `session` targets must not include one — resumes derive the worktree from the host's persisted session binding, never from the client. A `workingDirectory` is accepted only on `target:"new"`; it must be a POSIX-style relative path with no absolute prefix, control characters, empty segment, `.`, `..`, or `.git`. The host resolves it inside the registered workspace and rejects symlink escapes. Discovery and management payloads reject unknown purposes and unexpected fields.
+
+The authoritative client identity is the remote Iroh node ID observed by the host on the accepted connection, not `clientNodeId` from the hello. Unknown top-level hello fields are ignored.
+
+The host responds with one UTF-8 JSON object followed by LF.
+
+Success:
+
+```json
+{"type":"volt_iroh_handshake","success":true,"workspace":"volt","hostNodeId":"<authoritative-host-node-id>","clientNodeId":"<authoritative-client-node-id>","features":["multi_streams.v1","conversation_streams.v1","worktrees.v1","working_directories.v1"],"sessionId":"abc123","conversation":{"target":"last","sessionId":"abc123","selection":"resumed"},"child":"volt"}
+```
+
+Failure:
+
+```json
+{"type":"volt_iroh_handshake","success":false,"outcome":"client_unknown","hostNodeId":"<authoritative-host-node-id>","error":"client is not paired"}
+```
+
+On success, `hostNodeId` is the host's authoritative Iroh node ID and `clientNodeId` is the client's authoritative Iroh node ID observed by the host on the accepted connection. Stream-mode successes require `features` to include both `multi_streams.v1` and `conversation_streams.v1`. Conversation successes also require matching top-level `sessionId` and canonical `conversation.sessionId`, plus `conversation.target` and `conversation.selection` (`resumed`, `created`, `created_missing_last`, or `session_rekeyed`). A `session_rekeyed` selection is valid only for `conversation.target:"session"`, must include `conversation.requestedSessionId`, and means the requested session is an alias for the returned canonical session. Discovery and management successes include purpose metadata and no session metadata:
+
+```json
+{"type":"volt_iroh_handshake","success":true,"workspace":"volt","hostNodeId":"<authoritative-host-node-id>","clientNodeId":"<authoritative-client-node-id>","features":["multi_streams.v1","conversation_streams.v1","working_directories.v1"],"workspaceDiscovery":{"purpose":"list_sessions"}}
+```
+
+`child` is an implementation label for the host-side runtime and may be omitted. Failure responses include `hostNodeId` when the host identity is known. Failures after target resolution may include `workspace`, `sessionId`, and `retryAfterMs`; `error` is diagnostic text and should not drive app state.
+
+Host handshake failure outcomes:
+
+| Outcome | Meaning |
+| --- | --- |
+| `invalid_workspace` | The workspace field is malformed. |
+| `invalid_conversation_target` | The stream mode, target, purpose, or session ID syntax is malformed or unsupported. |
+| `conversation_streams_unsupported` | Reserved for hosts that cannot provide conversation-bound mobile streams. Current daemon builds are conversation-only. |
+| `pairing_secret_expired` | The supplied pairing secret matches an expired pending ticket or retained expired tombstone. |
+| `pairing_secret_consumed` | The supplied pairing secret matches a retained consumed tombstone and this client is not the paired recovery node. |
+| `client_unknown` | The host does not know this client node ID and no active, expired, or consumed pairing secret applies. |
+| `client_revoked` | The client node ID has a retained revocation tombstone and has not completed an approved re-pair. |
+| `workspace_unregistered` | The requested workspace name is not registered in this host state. |
+| `workspace_unavailable` | The requested workspace is registered but its local directory is not usable. |
+| `workspace_authorization_removed` | The workspace exists but this client is no longer authorized for it. |
+| `workspace_forbidden` | The workspace exists but this client is not allowed to use it. This is reserved for legacy or future per-client workspace restrictions. |
+| `session_unavailable` | A strict `conversation.target:"session"` target does not resolve to an available session. |
+| `duplicate_conversation_connection` | The same authoritative client already has an active stream for the resolved workspace/session. |
+| `conversation_in_use` | The active or retained daemon runtime permits tools outside the attaching client's persisted grant, so the client cannot safely co-attach. |
+
+Client-local reconnect outcomes are not sent by the host: `host_unreachable` means no usable transport/handshake could be opened, `host_identity_mismatch` means the reached Iroh node or handshake `hostNodeId` differs from the saved host identity, and `saved_host_invalid` means the local saved record is malformed or missing required v1 fields.
+
+`client_revoked` remains authoritative for a revoked client node ID. A generic new pairing ticket does not let that same node silently return. The desktop host must first approve re-pair for the revoked node ID, then issue a fresh active pairing ticket; successful re-pair creates a new active client record and clears the revocation tombstone.
+
+A successful pairing stores the client as authorized for the workstation represented by the host state file. That paired client can use any registered workspace name in that state file, including workspaces registered later, without scanning another QR. Revocation blocks that client node ID from every registered workspace. The client's persisted `allowedTools` value is a **headless agent tool grant** that applies to daemon-owned runtimes across all selected workspaces; registering a workspace does not add built-in tools. The default built-in grant is `read,bash,edit,write,web_search,grep,find,ls,subagent,mcp`. When the persisted grant is the default built-in list, the host also exposes active tools registered by loaded extensions in the selected workspace. A TUI-owned conversation continues to use the TUI session's full local tool set; `review` and `chat` pairing presets do not narrow that local runtime.
+
+A paired client may open multiple conversation streams, including multiple sessions in the same registered workspace. The identity key is authoritative client node ID, workspace name, and resolved session ID. If the same authoritative client opens the same workspace/session twice on one live Iroh connection, the host rejects the new stream and preserves the existing stream:
+
+```json
+{"type":"volt_iroh_handshake","success":false,"outcome":"duplicate_conversation_connection","hostNodeId":"<authoritative-host-node-id>","workspace":"volt","sessionId":"abc123","retryAfterMs":500,"error":"duplicate conversation connection"}
+```
+
+If the duplicate is the first conversation stream on a new Iroh connection from the same authoritative client, the host treats the previous active stream as stale, closes it with reason `replaced`, and accepts the new stream as the subscriber to the existing integrated runtime. Distinct authoritative clients may co-attach when the existing runtime's tool policy is within the attaching client's effective grant. Otherwise the host rejects with `conversation_in_use` and includes the resolved workspace/session identity.
+
+## Stream feature compatibility
+
+`multi_streams.v1` and `conversation_streams.v1` are optional host features, not a protocol version bump. Mobile pinned-agent clients require both features on successful stream-mode handshakes. Missing or malformed feature metadata for those modes means the host is incompatible with conversation streams. Clients should keep the saved host and surface an update/integrated-host-required state rather than asking for another QR scan.
+
+`session_runtime_state.v1` is an optional discovery feature. Hosts advertising it may add `runtimeState` to `list_sessions` entries. Older clients must ignore the field; clients must not assume its absence means a session is stopped when the feature is not advertised.
+
+`worktrees.v1` is an additional optional host feature. Clients must check for it before sending `worktreeId` in a conversation hello or opening a `manage_worktrees` management stream; hosts without the feature reject both with `invalid_conversation_target`. Conversation successes for worktree-bound sessions echo `conversation.worktreeId`.
+
+`working_directories.v1` is an additional optional host feature for starting a new conversation in a workspace-relative subfolder while keeping project configuration rooted at the registered workspace (or at the matching worktree checkout root for worktree sessions). Conversation successes echo `conversation.workingDirectory` when the effective cwd is not the root. The wire value is always relative; host-local absolute paths never cross the protocol.
+
+Missing stream features, `conversation_streams_unsupported`, `workspace_unavailable`, `workspace_unregistered`, `workspace_has_worktrees`, `workspace_authorization_removed`, `session_unavailable`, `duplicate_conversation_connection`, and `conversation_in_use` are not QR re-pair requirements by themselves. `workspace_has_worktrees` means the user must explicitly remove each child worktree first; it is not an authorization or connectivity failure. `host_identity_mismatch`, malformed saved-host data, `client_unknown`, and `client_revoked` still require explicit Pair Again or Forget Host style UX.
+
+## Reconnect and session selection
+
+A reconnecting paired client with the same authoritative Iroh node ID selects a conversation in the handshake. `target:last` resumes the last recorded session for that workspace when the remembered ID is valid and the session file still exists; if the remembered ID is invalid or missing, the host creates a new session and reports `conversation.selection:"created_missing_last"` or `created`. `target:new` always creates a fresh session. `target:session` resumes a strict session ID, fails with `session_unavailable`, or returns `conversation.selection:"session_rekeyed"` with `conversation.requestedSessionId` when a live runtime has moved from the requested session to a canonical replacement session. Clients must validate state/transcript against the returned canonical `sessionId` and update the selected pin only after that validation commits.
+
+Saved-host clients must verify that the native endpoint ticket node ID and the handshake `hostNodeId` match the saved host's `nodeId` before trusting authorization failures or refreshing non-secret discovery fields. If the reached identity differs, clients should treat the attempt as `host_identity_mismatch` and leave the saved host identity and discovery data unchanged.
+
+Remote UI clients should request `get_state` followed by `get_transcript` after a conversation stream is accepted. New Agent and Resume Agent are not post-handshake mutations; clients open a new conversation stream with `target:new` or `target:session`. For older history, clients use `get_transcript` pagination (`hasMore` and `nextBeforeEntryId`) and request pages with `beforeEntryId`.
+
+`get_state` responses for Iroh sessions include remote host metadata with the current workspace and the registered workspace names visible to the saved host:
+
+```json
+{
+  "remoteHost": {
+    "workspace": "volt",
+    "workspaceNames": ["volt", "other-project"],
+    "features": ["multi_streams.v1", "conversation_streams.v1", "working_directories.v1"],
+    "hostNodeId": "<authoritative-host-node-id>",
+    "relayMode": "default",
+    "hostName": "macstudio",
+    "userName": "jordan",
+    "cwd": "/workspace"
+  }
+}
+```
+
+`remoteHost.workspaceNames` contains names only, never host-local paths. `remoteHost.features` repeats the safe host feature strings advertised during handshake. Conversation clients must validate that the response `sessionId` and `remoteHost.workspace` match the handshake-bound stream identity. Selecting another pinned agent opens another conversation stream; v1 does not switch the cwd or session of an active stream in place.
+
+## Lifecycle: detach versus cancel
+
+An Iroh stream close, stream EOF, QUIC connection close, input half-close, or remote write failure is a detach signal. It has no RPC payload and the host must not translate it into an `abort` command. Mobile clients do not need to send a best-effort detach command before background suspension or process loss.
+
+User-visible stop/cancel controls must send the allowed `abort` RPC command:
+
+```json
+{"id":"cancel-1","type":"abort"}
+```
+
+The successful response uses the normal RPC response shape:
+
+```json
+{"id":"cancel-1","type":"response","command":"abort","success":true}
+```
+
+`abort` is the only direct remote cancellation command in v1. Command names such as `cancel`, `cancel_run`, `detach`, and `disconnect` are not forwarded by the remote command allowlist. App-level disconnect without stop should close the stream only; clients reconnect by opening a new authorized stream, then calling `get_state` and `get_transcript`.
+
+The daemon's integrated runtime treats an authorized stream as a subscriber to host-owned session state. When the only subscriber detaches during active work, the prompt continues on the host. The same authoritative Iroh node ID, workspace, and session can reconnect to the detached runtime; `get_state.isStreaming` reports an active provider run or continuation, `get_state.isBusy` additionally covers prompt preflight and standalone session operations, and `get_transcript` recovers persisted output. Idle detached runtimes are retained for 30 minutes by default, configurable with the `remote.detachedRuntimeTtlMs` setting. Distinct paired devices may co-attach to one runtime, and when a desktop TUI owns the conversation lease the daemon transparently relays the stream to it; `remote_terminal` reasons `lease_transferred` and `session_rekeyed_reconnect` signal expected closures the client should reconnect through immediately. Prompt-class commands during an ownership drain fail with the transient error code `lease_draining` (with `retryAfterMs`).
+
+Host process exit, host crash, or explicit host shutdown are separate from client detach and can stop in-memory work because the runtime is gone. A reconnect after host exit requires a new host process and can recover only persisted session state.
+
+## JSONL framing
+
+All post-handshake traffic is Volt RPC JSONL:
+
+- Each message is one JSON value encoded as UTF-8 and terminated by LF (`\n`).
+- Split only on LF byte `0x0a`. Do not treat CR, Unicode line separator U+2028, or Unicode paragraph separator U+2029 as frame terminators.
+- Bytes after the hello LF are preserved as initial RPC input. Clients may pipeline the first RPC request immediately after the hello line.
+- Overlong or unterminated handshake lines are rejected before any RPC is forwarded.
+
+## Remote RPC command allowlist
+
+The host filters inbound RPC command `type` values by stream mode.
+
+Conversation streams forward or handle these remote commands:
+
+- `prompt`
+- `steer`
+- `follow_up`
+- `abort`
+- `get_state`
+- `get_transcript`
+- `get_ui_capabilities`
+- `get_ui_actions`
+- `get_ui_action_completions`
+- `invoke_ui_action`
+- `register_push_target`
+- `register_live_activity`
+- `unregister_live_activity`
+- `list_sessions`
+- `create_worktree` (worktrees.v1)
+- `list_worktrees` (worktrees.v1)
+- `upload_device_logs`
+- `extension_ui_response`
+- `get_available_models`
+- `set_model`
+- `set_thinking_level`
+
+Conversation streams reject `new_session`, `switch_session_by_id`, and raw `get_messages` with `unsupported_remote_command`. Command-level `workspace`, `workspaceName`, or `sessionId` values on conversation commands are assertions only; values that do not match the stream-bound workspace/session fail with `session_mismatch`.
+
+Conversation streams on `worktrees.v1` hosts also accept `create_worktree` and `list_worktrees` (same shapes and validation as the `manage_worktrees` stream, scoped to the stream-bound workspace), so a client can create a worktree and open a new isolated conversation without a separate management stream. `remove_worktree` remains management-stream-only. Hosts without a daemon backend answer both with `unsupported_remote_command`.
+
+`list_sessions` entries include an optional `worktreeId` when the session is bound to a daemon-managed worktree, so clients can badge worktree sessions without a `list_worktrees` join. Entries also include optional `workingDirectory` when the session cwd is below the workspace/worktree root. Worktree attribution may be absent while a desktop TUI owns the conversation lease.
+
+On hosts advertising `session_runtime_state.v1`, an entry may also include `runtimeState` with one of `tui-owned`, `daemon-active`, `daemon-detached`, or `daemon-draining`. The field is omitted when the session has no live lease/runtime. `tui-owned` means a desktop TUI process currently owns the conversation. `daemon-active` means a daemon runtime has at least one attached phone stream. `daemon-detached` means the daemon still retains the runtime with no attached streams and may represent idle warm retention rather than active work. `daemon-draining` means the daemon runtime is handing ownership to a TUI. Clients should therefore use the exact state, not mere field presence, when deciding which hidden sessions to auto-connect.
+
+Workspace discovery streams accept only `list_sessions`. Any other valid RPC command receives `unsupported_on_workspace_discovery_stream`. Discovery streams create no conversation runtime and do not update last-session state.
+
+Workspace management streams with purpose `unregister_workspace` accept `unregister_workspace` and `list_workspace_directories`. The directory-listing RPC takes `workspaceName` plus optional relative `path`, and returns `directories:[{name,path}]` with relative paths only. Unregister refuses with `workspace_has_worktrees` while any persisted child worktree remains; clients must remove each worktree through `remove_worktree`, using `force:true` only as the user's explicit destructive choice. Management streams with purpose `manage_worktrees` (worktrees.v1) accept only `create_worktree`, `list_worktrees`, and `remove_worktree`. Any other valid RPC command receives `unsupported_on_workspace_management_stream`. Every management command must include a `workspaceName` matching the stream workspace (`session_mismatch` otherwise) and may not include extra fields (`invalid_request`); inbound host-local filesystem paths are always rejected.
+
+All other command types receive a JSONL `response` with `success:false` and are not forwarded to the local Volt RPC process. This includes local-only subagent lifecycle commands such as `list_subagents`, `subagent_start`, `subagent_abort`, `subagent_get_state`, `subagent_get_transcript`, and `subagent_dispose`. Within the remote surface, only `abort` is a direct cancellation command.
+
+### Subagent delegation trees on conversation streams
+
+Remote clients observe subagent activity through the parent conversation's `subagent` tool call rather than through the local-only lifecycle commands. Live `tool_execution_update`/`tool_execution_end` frames, `transcript_entry` frames, and `get_transcript` items carry projected `subagent` details with per-task `status`, `subagentId`/`sessionId` attach targets, and — on hosts that stream delegation trees — bounded live fields per task: `task` (preview), `startedAt`, `durationMs`, `toolCalls`, `tokens`, `currentActivity`, and a recursive `children` array of the same node shape for nested delegation (children spawning their own subagents). Trees are depth-capped at 5 levels and all strings are length-bounded and path-sanitized. `get_state` additionally includes the newest projected details on the in-flight `subagent` entry in `activeTools`, so a client attaching mid-turn can paint the current tree without waiting for the next update frame. Clients must treat all of these fields as optional; older hosts omit them.
+
+`register_push_target` registers mobile-issued relay credentials with the host. The client must first register its raw FCM token with the Volt push relay; it must not send that raw FCM token to the desktop host. The host persists the relay target id and target-scoped auth token so it can notify the phone after the Iroh stream detaches. When an ActivityKit push token is available, the same command may include a `liveActivity` delivery channel containing the raw ActivityKit token plus its lowercase SHA-256 hash; the host stores that channel so it can ask the relay to update the Live Activity later. `relayUrl` is accepted as app registration metadata, but host delivery uses the desktop host's configured relay URL (`--push-relay-url` / `VOLT_PUSH_RELAY_URL`) and does not let clients redirect delivery:
+
+```json
+{
+  "id": "push-1",
+  "type": "register_push_target",
+  "args": {
+    "provider": "fcm",
+    "platform": "ios",
+    "pushTargetId": "<relay-target-id>",
+    "pushTargetAuthToken": "<relay-target-auth-token>",
+    "relayUrl": "https://us-central1-volt-3fae7.cloudfunctions.net/pushRelay",
+    "tokenHash": "sha256:<fcm-token-hash>",
+    "enabled": true,
+    "liveActivity": {
+      "activityId": "activity-one",
+      "pushToken": "<activitykit-push-token-hex>",
+      "tokenEnvironment": "production",
+      "tokenHash": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
+    }
+  }
+}
+```
+
+The successful response is:
+
+```json
+{"id":"push-1","type":"response","command":"register_push_target","success":true,"data":{"status":"registered","pushTargetId":"<relay-target-id>"}}
+```
+
+`register_live_activity` binds an ActivityKit Live Activity to the current conversation stream. The app sends the activity identity and a lowercase SHA-256 token hash that references the previously acknowledged `register_push_target.args.liveActivity` delivery channel. It does not repeat the raw ActivityKit push token in `register_live_activity`:
+
+```json
+{
+  "id": "live-1",
+  "type": "register_live_activity",
+  "workspaceName": "volt",
+  "sessionId": "abc123",
+  "activityId": "activity-one",
+  "platform": "ios",
+  "tokenEnvironment": "production",
+  "tokenHash": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
+}
+```
+
+The host validates that `workspaceName` and `sessionId` match the bound stream, validates the activity payload, resolves `tokenHash` through the existing ActivityKit delivery channel for the authoritative client, and returns stable errors such as `session_mismatch`, `invalid_live_activity_registration`, `invalid_live_activity_token`, or `unknown_live_activity_token`. `unregister_live_activity` uses the same stream-bound workspace/session/activity identity without a token hash and is idempotent for the matching registration.
+
+Completion notifications sent through the relay, or over JSONL as `notification_request` when no push target is available, include the safe workspace name when the host knows it:
+
+```json
+{"type":"notification_request","eventId":"conversation:session-one:run-one:completed","kind":"conversation_completed","title":"Volt finished in volt-app","body":"Your conversation is ready.","sessionId":"session-one","workspace":"volt-app"}
+```
+
+The `workspace` field is a registered workspace name only. It must never contain a host-local path.
+
+`unregister_workspace` on a workspace management stream removes a registered workspace name from the host state file without deleting files:
+
+```json
+{"id":"unregister-1","type":"unregister_workspace","workspaceName":"old-workspace"}
+```
+
+The host rejects missing or malformed names, names that do not match the management stream workspace, and unknown workspaces. If the workspace has any persisted daemon-managed worktree records, the response is `success:false` with `error:"workspace_has_worktrees"`; the workspace, records, dirty/unmerged work, active worktree sessions, and all checkout directories remain untouched. A successful response is possible only after the user explicitly removes every managed worktree, and includes refreshed safe workspace metadata when available:
+
+```json
+{"id":"unregister-1","type":"response","command":"unregister_workspace","success":true,"data":{"removedWorkspace":"old-workspace","workspaceNames":["volt"]}}
+```
+
+This command is host-state metadata management only. It does not create, rename, path-map, or delete host workspace or worktree directories, including unrecognized/orphan directories under the daemon worktree root. Response data must contain registered names and availability statuses only, never host-local paths. Folder browsing is a separate read-only `list_workspace_directories` RPC on the same management stream and returns relative paths only.
+
+### Worktree management (`manage_worktrees`, worktrees.v1)
+
+A `manage_worktrees` management stream drives daemon-managed git worktrees for the stream workspace. Checkout paths are computed host-side under the agent dir and never cross the wire in either direction; requests carry ids and git refs only. If `workingDirectory` is inside a nested git repository or submodule under the registered workspace, the daemon creates the worktree from that nested repository root while keeping the worktree record and sessions under the registered parent workspace.
+
+`create_worktree` runs `git worktree add` in the selected source checkout on a new branch (default `volt/<id>`; the base defaults to the source checkout's current branch and is recorded for later merge-back guidance):
+
+```json
+{"id":"1","type":"create_worktree","workspaceName":"myrepo","worktreeName":"fix-login","baseRef":"main"}
+```
+
+```json
+{"id":"1","type":"response","command":"create_worktree","success":true,"data":{"worktree":{"id":"fix-login","branch":"volt/fix-login","baseRef":"main","createdAt":1751900000000,"sessionIds":[]}}}
+```
+
+Failures use the standard error response with reasons such as `not_a_git_repository`, `worktree_exists`, `worktree_branch_conflict`, `worktree_limit_reached`, `invalid_worktree_id`, `invalid_working_directory`, or `git_failed`. The wire `workingDirectory` remains registered-workspace-relative for both root and nested-repo worktrees; host-local nested repo roots and checkout paths are never exposed.
+
+`list_worktrees` reports each worktree with availability, dirtiness, bound session ids, and merge-back counts (`aheadBehind` compares the worktree branch against its recorded base ref):
+
+```json
+{"id":"2","type":"list_worktrees","workspaceName":"myrepo"}
+```
+
+```json
+{"id":"2","type":"response","command":"list_worktrees","success":true,"data":{"worktrees":[{"id":"fix-login","branch":"volt/fix-login","baseRef":"main","createdAt":1751900000000,"sessionIds":["s-abc"],"available":true,"dirty":false,"aheadBehind":{"ahead":1,"behind":0}}]}}
+```
+
+`remove_worktree` refuses dirty or in-use worktrees unless `force:true`, which stops bound runtimes first:
+
+```json
+{"id":"3","type":"remove_worktree","workspaceName":"myrepo","worktreeId":"fix-login","force":false}
+```
+
+```json
+{"id":"3","type":"response","command":"remove_worktree","success":true,"data":{"worktreeId":"fix-login","removed":true,"stoppedRuntimeCount":0,"closedStreamCount":0}}
+```
+
+`create_worktree` and `list_worktrees` (but not `remove_worktree`) are also accepted on conversation streams — see the command allowlist above.
+
+A conversation hello with `{"target":"new","worktreeId":"fix-login"}` opens the new session with the worktree checkout as its working directory; `{"target":"new","workingDirectory":"packages/app"}` opens at `/workspace/packages/app` while project resources still load from the workspace root. Combining both maps the registered-workspace-relative `workingDirectory` into the worktree's source repo: for a nested source root `Volt` and selected folder `Volt/packages/coding-agent`, the checkout is created from the host's nested `Volt` repo and the agent cwd is `<worktree>/packages/coding-agent`, while the handshake/session-list `workingDirectory` remains `Volt/packages/coding-agent`. Worktree runtimes use the source checkout root as `projectCwd`, so `.volt`, settings, prompts, and MCP config are read from that isolated repo checkout; sessions are still stored under the parent registered workspace. The daemon persists the session→worktree binding so later `session`/`last` resumes land in the same checkout and subfolder. Worktree runtimes inherit the parent workspace's trust decision and tool allowlist — never wider — and their outbound frames sanitize the worktree path, the parent checkout path, and the worktrees root to `/workspace` (or `/workspace/<nested-source-root>` for nested repo worktrees).
+
+`upload_device_logs` on a conversation stream stores client diagnostic logs inside the stream-bound workspace so host-side tooling and agents can read them:
+
+```json
+{"id":"logs-1","type":"upload_device_logs","fileName":"volt-device.log","content":"+0.1s info app: App did finish launching\n"}
+```
+
+`content` must be a non-empty UTF-8 string of at most 4 MiB (and must fit the 16 MiB RPC line limit after JSON encoding). `fileName` is optional; when present it must be a single path component of letters, digits, `.`, `_`, or `-` that does not start with a dot, and when absent the host generates a UTC-timestamped `device-<timestamp>.log` name. The host writes the file atomically under `.volt/device-logs/` inside the workspace root, overwriting any file with the same name, and never writes outside the workspace. A successful response echoes the workspace-relative path only, never a host-local absolute path:
+
+```json
+{"id":"logs-1","type":"response","command":"upload_device_logs","success":true,"data":{"path":".volt/device-logs/volt-device.log","byteCount":42}}
+```
+
+`get_ui_capabilities`, `get_ui_actions`, `get_ui_action_completions`, and `invoke_ui_action` expose the v1 native UI action protocol for the narrow remote-safe action set. Remote `get_ui_capabilities` advertises `ui_action_invocation.v1` only when the host accepts invocation and `ui_action_completions.v1` when action argument completions are available. Descriptor responses omit prompt bodies, skill content, raw `sourceInfo`, extension source paths, prompt and skill file paths, skill base directories, host session files, provider metadata, and secrets. They still pass through the outbound path handling layer below before being written to the remote stream.
+
+Remote `get_ui_action_completions` and `invoke_ui_action` are allowlist-based. V1 forwards exact reviewed built-in ids `session.new`, `run.cancel`, `thinking.fast_mode`, `review.uncommitted`, and `review.branch`, plus projected prompt-template and skill ids. Extension commands are denied by default and are discovered or invoked remotely only when their registration explicitly sets `remoteSafe: true`; the same opt-in is rechecked for direct RPC prompts containing an extension slash command. The host still resolves the current action catalog, rechecks action availability and remote safety, validates arguments, confirms remote review requests, and applies streaming policy at invocation time. Local-only built-ins such as `context.compact` and `session.rename`, deferred review/model actions such as `review.pr`, `review.commit`, and `review.tools`, stale ids, malformed ids, and unreviewed action id prefixes receive a normal JSONL `response` with `success:false` and are not forwarded to the local Volt RPC process.
+
+Remote clients should use `get_ui_actions` rather than `get_commands` to build native Actions pages and command palettes. `primary` descriptors are the host-curated card/button/toggle surface. `palette` descriptors are searchable compatibility actions for extension commands, prompt templates, and skills. Slash aliases in descriptors are display hints and compatibility metadata; action ids are the invocation contract.
+
+Projected extension command, prompt-template, and skill actions execute through the host's existing prompt/command expansion path. Extension UI requests raised during those commands continue to use the existing `extension_ui_request` / `extension_ui_response` protocol. RPC-degraded extension UI methods keep the behavior documented in [RPC mode](rpc.md#extension-ui-protocol); Iroh does not add terminal-only UI support.
+
+Remote review descriptors expose only bounded card metadata. Review invocation responses do not include raw diffs, GitHub metadata, configured review model values, auth state, or raw tool output. While review runs, the host may emit `workflow_start`, sanitized workflow-scoped `tool_execution_start`/`tool_execution_end`, `workflow_update`, and `workflow_end` events so clients can render a live progress timeline. These activity events include bounded tool names and arguments only; raw read contents, grep output, review prompts, and diffs remain hidden. The remote review workflow uses the host-owned read-only review tool set (`read`, `grep`, `find`, `ls`) and creates a fresh session seeded with findings when the review completes.
+
+Remote Fast mode descriptors expose only bounded toggle metadata and current boolean state. `thinking.fast_mode` invocation accepts a boolean `enabled` argument, changes only the current session's thinking level without persisting defaults or switching models, and returns updated action state.
+
+Direct model and thinking RPC commands `get_available_models`, `set_model`, and `set_thinking_level` are forwarded on conversation streams so paired clients can render a native model picker and change the model or thinking level for the bound session:
+
+- `get_available_models` returns the auth-configured model catalog (`data.models`), the same objects local RPC clients receive, each enriched with `availableThinkingLevels` so clients can render per-model thinking choices without provider capability matrices. Custom-model API keys and custom request headers never reach these model objects, but the catalog does expose model ids, display names, providers, base URLs, costs, and capability metadata to the paired client. The host reloads `auth.json` and `models.json` from disk before answering, so logins, logouts, and API keys saved by other volt processes become selectable without restarting the host.
+- The host also watches `auth.json` and `models.json` and emits a payload-free `models_changed` event on conversation streams when the available catalog changes on disk (for example after `/login` or `/logout` in a desktop CLI). Clients should respond by re-requesting `get_available_models`; the event never carries credential material.
+- `set_model` preserves local RPC/CLI semantics: omitting `persistDefault` switches the bound session and persists the choice as the host default for future sessions. Remote app calls **must send `persistDefault: false`** so a phone selection stays parameter-scoped to the bound session and cannot rewrite desktop defaults. Unknown provider/model pairs fail with `Model not found: <provider>/<modelId>`. `set_model` also clears any active Fast mode overlay and re-clamps the session thinking level to the new model (emitting `thinking_level_changed` when it changes); its response echoes the model with `availableThinkingLevels`.
+- `set_thinking_level` accepts `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, or `max`. Remote app calls must send `persistDefault: false`; omission retains local RPC semantics and is reserved for callers authorized to change the host default. Levels the current model does not support are silently clamped, not rejected; the response `data.level` reports the effective post-clamp level, and a `thinking_level_changed` event fires only when the effective level actually changes. `get_state` reports the current model's valid levels in `availableThinkingLevels`.
+- `cycle_model` and `cycle_thinking_level` remain blocked remotely; native clients have the full catalog and select explicitly.
+
+First-class extension-provided native cards, persisted chat/global Fast mode defaults, profile switching, scoped-model editing, package management, provider login/logout, and project settings mutation are deferred. They require separate host-owned policy, storage, descriptor, and allowlist work before they can be exposed over Iroh.
+
+The preview RPC surface intentionally stays narrow. It excludes local tools such as `bash`, `edit`, and `write`; those tools can only be used through the normal model/tool flow and host-side permission policy. It also excludes read-only local RPC commands such as `get_messages`, `get_commands`, and `get_last_assistant_text` for v1 preview.
+
+The path-based `switch_session` command remains blocked remotely, and mobile conversation streams also reject direct `switch_session_by_id`; clients select another session by opening a new `conversation.target:"session"` stream. `get_transcript` is the remote-safe transcript read: it returns only the bound session's projected user, assistant, tool-summary, and compaction-summary items, ordered oldest-to-newest, with server-bounded page sizes. Host session file paths, raw `get_messages` payloads, thinking blocks, raw tool output, full file contents, provider payloads, and extension-private custom data are not returned. Transcript path and text fields still pass through the outbound redaction layer below.
+
+- `get_messages` can return the full raw transcript, including prompts, tool output, file excerpts, provider payloads, and extension content beyond the projected transcript needed for reconnect.
+- `get_commands` exposes installed extension, prompt-template, and skill metadata; remote clients must use the sanitized `get_ui_actions` discovery surface instead.
+- `get_last_assistant_text` duplicates streamed assistant output and is superseded remotely by the projected transcript surface.
+- `cycle_model` and `cycle_thinking_level` blind-cycle host state; remote clients use `get_available_models` plus explicit `set_model`/`set_thinking_level` instead.
+
+Headless agent tool access and RPC command access are separate surfaces. `allowedTools` controls which listed built-in or extension tools the model may invoke in daemon-owned headless runtimes; it is carried through TUI relay metadata for visibility but does not narrow a TUI-owned conversation's full local tools. Every active/revoked client and pending pairing ticket also carries an RPC grant with the strict shape `{"schemaVersion":1,"revision":<integer >= 1>,"capabilities":[...]}`. Missing grants, unknown or duplicate capability IDs, and malformed revisions fail closed; development pairings created before this schema must re-pair.
+
+The exact capability IDs are `conversation.observe.v1`, `conversation.control.v1`, `model.select.v1`, `integrations.manage.v1`, `worktrees.manage.v1`, `host.manage.v1`, `workspace.manage.v1`, and `diagnostics.upload.v1`. Command authorization is evaluated after the static remote command allowlist, which remains a hard ceiling. Capability denials use `error.code:"rpc_capability_denied"` and include `error.requiredCapability` where the response architecture supports structured errors. Session-only `set_model`/`set_thinking_level` (`persistDefault:false`) requires `model.select.v1`; persisting or omitting `persistDefault` additionally requires `host.manage.v1`.
+
+Pairing snapshots either an explicit headless-agent-tool/capability selection or one immutable preset: `coding` (default), `review`, and `chat` grant observe/control/model selection, while `full` grants every capability. For daemon-owned headless runtimes, `coding` and `full` use the default tool list, `review` uses `read,grep,find,ls`, and `chat` grants no model tools. These preset tool differences do not constrain TUI-owned conversations, which retain the TUI session's full local tools. A fresh re-pair ticket always supplies its newly selected grant. Local control clients may atomically update both access planes with an expected grant revision; successful updates increment the revision and close that device's existing streams, runtimes, connections, and relays so reconnects use the authoritative grant.
+
+## Outbound path handling
+
+Before host RPC output is sent to the remote stream, Volt normalizes remote-meaningful workspace paths and keeps generic host paths intact:
+
+- Paths under the selected stream's hosted workspace are rewritten under `/workspace`.
+- A multi-stream host applies this mapping independently per stream; sibling workspace paths are not rewritten to `/workspace` unless they are the selected workspace for that stream.
+- Host-local paths outside the workspace are left unchanged; Volt no longer emits a generic placeholder for them.
+- Export paths are redacted when recognized with `[redacted export path]`.
+- Session files are omitted or replaced with `[redacted session file]`.
+- Bash output file paths are omitted or replaced with `[redacted bash output path]`.
+- Path handling applies to responses, extension UI requests, assistant content, tool-call arguments, and plain-text fallback lines.
+- Opaque model/provider data such as image base64 payloads and signature fields are preserved, while adjacent text and structured arguments are still processed as above.
+
+The remaining dedicated placeholders are part of the v1 compatibility surface. Clients must display them as opaque strings and must not assume that a redacted path can be expanded locally.

package/docs/json.md

@@ -0,0 +1,87 @@
+# JSON Event Stream Mode
+
+```bash
+volt --mode json "Your prompt"
+```
+
+Outputs all session events as JSON lines to stdout. Useful for integrating volt into other tools or custom UIs.
+
+## Event Types
+
+Events are defined in [`AgentSessionEvent`](../src/core/agent-session.ts#L102):
+
+```typescript
+type AgentSessionEvent =
+  | Exclude<AgentEvent, { type: "agent_end" }>
+  | { type: "agent_end"; messages: AgentMessage[]; willRetry: boolean }
+  | { type: "agent_settled" }
+  | { type: "queue_update"; steering: readonly string[]; followUp: readonly string[] }
+  | { type: "compaction_start"; reason: "manual" | "threshold" | "overflow" }
+  | { type: "compaction_end"; reason: "manual" | "threshold" | "overflow"; result: CompactionResult | undefined; aborted: boolean; willRetry: boolean; errorMessage?: string }
+  | { type: "auto_retry_start"; attempt: number; maxAttempts: number; delayMs: number; errorMessage: string }
+  | { type: "auto_retry_end"; success: boolean; attempt: number; finalError?: string };
+```
+
+`queue_update` emits the full pending steering and follow-up queues whenever they change. `compaction_start` and `compaction_end` cover both manual and automatic compaction. Each low-level agent run emits `agent_end`; retries and compaction or queued-message continuations can produce additional runs. `agent_settled` is emitted once after all such work finishes and is the terminal event for the prompt.
+
+Base events from [`AgentEvent`](../../agent/src/types.ts#L179):
+
+```typescript
+type AgentEvent =
+  // Agent lifecycle
+  | { type: "agent_start" }
+  | { type: "agent_end"; messages: AgentMessage[] }
+  // Turn lifecycle
+  | { type: "turn_start" }
+  | { type: "turn_end"; message: AgentMessage; toolResults: ToolResultMessage[] }
+  // Message lifecycle
+  | { type: "message_start"; message: AgentMessage }
+  | { type: "message_update"; message: AgentMessage; assistantMessageEvent: AssistantMessageEvent }
+  | { type: "message_end"; message: AgentMessage }
+  // Tool execution
+  | { type: "tool_execution_start"; toolCallId: string; toolName: string; args: any }
+  | { type: "tool_execution_update"; toolCallId: string; toolName: string; args: any; partialResult: any }
+  | { type: "tool_execution_end"; toolCallId: string; toolName: string; result: any; isError: boolean };
+```
+
+## Message Types
+
+Base messages from [`packages/ai/src/types.ts`](../../ai/src/types.ts#L134):
+- `UserMessage` (line 134)
+- `AssistantMessage` (line 140)
+- `ToolResultMessage` (line 152)
+
+Extended messages from [`packages/coding-agent/src/core/messages.ts`](../src/core/messages.ts#L29):
+- `BashExecutionMessage` (line 29)
+- `CustomMessage` (line 46)
+- `BranchSummaryMessage` (line 55)
+- `CompactionSummaryMessage` (line 62)
+
+## Output Format
+
+Each line is a JSON object. The first line is the session header:
+
+```json
+{"type":"session","version":3,"id":"uuid","timestamp":"...","cwd":"/path"}
+```
+
+Followed by events as they occur:
+
+```json
+{"type":"agent_start"}
+{"type":"turn_start"}
+{"type":"message_start","message":{"role":"assistant","content":[],...}}
+{"type":"message_update","message":{...},"assistantMessageEvent":{"type":"text_delta","delta":"Hello",...}}
+{"type":"message_end","message":{...}}
+{"type":"turn_end","message":{...},"toolResults":[]}
+{"type":"agent_end","messages":[...],"willRetry":false}
+{"type":"agent_settled"}
+```
+
+When `agent_end.willRetry` is true, another agent run will follow. Even when it is false, use `agent_settled` rather than `agent_end` as the prompt-completion signal.
+
+## Example
+
+```bash
+volt --mode json "List files" 2>/dev/null | jq -c 'select(.type == "message_end")'
+```