pi-remote-control 1.0.0

package/README.md

@@ -0,0 +1,46 @@
+# Pi Remote Control
+
+Private relay daemon for iOS remote control of explicitly enabled Pi TUI sessions.
+
+## Run
+
+Install as a Pi package:
+
+```bash
+pi install https://github.com/zerray/pi-remote-control
+```
+
+After installation, edit `~/.pi/remote-control/config.json` so iOS can reach the daemon. Use a LAN IP or Tailscale address. Exposing the daemon on a public IP is at your own risk.
+
+LAN example:
+
+```json
+{
+  "bindAddress": "192.168.1.23:17373",
+  "advertisedBaseUrl": "http://192.168.1.23:17373"
+}
+```
+
+Tailscale example:
+
+```json
+{
+  "bindAddress": "100.86.12.34:17373",
+  "advertisedBaseUrl": "http://100.86.12.34:17373"
+}
+```
+
+Then open a Pi TUI session and run:
+
+```text
+/remote-control-pair  # display QR code for iOS pairing
+/remote-control       # toggle this TUI session for remote control
+```
+
+## Directory overview
+
+- `scripts/http-smoke-test.sh` — curl/WebSocket smoke test for daemon HTTP endpoints.
+- `docs/architecture.md` — daemon architecture, Pi package shape, and lifecycle boundaries.
+- `docs/interfaces.md` — daemon public API and TUI control integration contract.
+- `docs/data-model.md` — daemon state, pairing, device, active session, and stream structures.
+- `docs/adr/` — accepted daemon decisions.

package/docs/adr/0001-package-extension-as-control-shim.md

@@ -0,0 +1,19 @@
+# Title
+
+Package the Pi extension as a control shim
+
+# Status
+
+Accepted
+
+# Context
+
+The daemon should be installable as part of a Pi package so users can manage it from Pi. Pi extensions are loaded for Pi processes and are rebound across session replacement flows. A long-lived HTTP/WebSocket daemon should not be tied to that per-process or per-session lifecycle.
+
+# Decision
+
+Distribute `pi-remote-control` as a Pi package containing both a daemon binary and a Pi extension. The extension is a thin control shim that registers commands for status, start, stop, and pairing. The daemon server runs as a separate singleton process started by an OS service, manual CLI, or explicit extension command.
+
+# Consequences
+
+Installing the Pi package makes the control extension available but does not automatically start one daemon per Pi session. Multiple Pi sessions can load the extension safely because daemon startup goes through singleton health checks and lock acquisition. The daemon remains available even when no Pi TUI session is open.

package/docs/adr/0002-use-sqlite-for-daemon-state.md

@@ -0,0 +1,19 @@
+# Title
+
+Use SQLite for daemon-owned state
+
+# Status
+
+Accepted
+
+# Context
+
+The daemon needs durable state for paired devices, token hashes, short-lived pairing codes, allowed projects, daemon metadata, and stable app-facing session IDs. Full Pi transcripts are already persisted by Pi as JSONL session files and should not be duplicated by the daemon.
+
+# Decision
+
+Store daemon-owned durable state in a SQLite database named `daemon.sqlite` under the daemon state directory. Store human-editable daemon configuration in `config.json` in the same directory. Keep Pi session transcripts in Pi's own session files and store only daemon IDs, references, and cached summary fields for sessions.
+
+# Consequences
+
+The daemon gets transactional updates, simple backup behavior, and easy local inspection without running an external database. The daemon must manage schema migrations and filesystem permissions. If the SQLite session index is lost, it can be rebuilt from Pi session files, but device pairing state must be restored from backup or paired again.

package/docs/adr/0003-use-lock-file-as-process-state.md

@@ -0,0 +1,19 @@
+# Title
+
+Use daemon lock file as process state
+
+# Status
+
+Accepted
+
+# Context
+
+The daemon needs singleton enforcement and enough process metadata for `status` and `stop`. Earlier design mentioned both `daemon.lock` and `daemon.pid`, which duplicated process state and could become inconsistent.
+
+# Decision
+
+Use only `daemon.lock` for daemon process state. The daemon creates it atomically on startup, writes its PID into it, and removes it on normal shutdown. `status` and `stop` read the PID from `daemon.lock`.
+
+# Consequences
+
+There is a single process-state file to reason about. Duplicate starts are rejected by atomic lock creation. Stale lock handling is not yet implemented; if the daemon exits without releasing the lock, the user must remove `daemon.lock` manually before starting again.

package/docs/adr/0004-allow-loopback-pair-code-without-token.md

@@ -0,0 +1,19 @@
+# Title
+
+Allow loopback pair code creation without token
+
+# Status
+
+Accepted
+
+# Context
+
+Pairing is the bootstrap path that creates the first device bearer token. Requiring an existing bearer token for every `POST /v1/pair/code` request creates a circular dependency for first-time setup. At the same time, allowing unauthenticated pair code creation on Tailscale-reachable or public bind addresses would let any network peer initiate device pairing.
+
+# Decision
+
+Allow unauthenticated `POST /v1/pair/code` only when the daemon is bound to a loopback address: `127.0.0.1`, `localhost`, or `::1`. For non-loopback bind addresses, pair code creation requires bearer authentication. `POST /v1/pair/claim` remains unauthenticated because the pair code itself is the short-lived proof.
+
+# Consequences
+
+First-time setup works from the host through the CLI or Pi extension without a pre-existing token. Remote pair-code creation is still protected when the daemon is reachable over Tailscale or other non-loopback interfaces. Users who bind directly to a Tailscale IP need an existing token or must temporarily create the pair code through a loopback-bound daemon session.

package/docs/adr/0005-defer-os-service-installation.md

@@ -0,0 +1,19 @@
+# Title
+
+Defer OS service installation
+
+# Status
+
+Accepted
+
+# Context
+
+The daemon can be started manually through the CLI or from Pi with `/remote-control start`. OS service installation through launchd or systemd would make the daemon persistent across logins and reboots, but it adds platform-specific service files, permissions, logging behavior, uninstall logic, and debugging surface.
+
+# Decision
+
+Do not implement OS service installation for the MVP. Keep manual CLI start and Pi extension start as the supported startup paths.
+
+# Consequences
+
+The MVP has fewer platform-specific moving parts. Users must start the daemon explicitly before using the iOS app. If repeated manual startup becomes a real usability problem, service installation can be added later with a new decision record.

package/docs/adr/0006-use-tui-activated-remote-control-sessions.md

@@ -0,0 +1,24 @@
+# Title
+
+Use TUI-activated remote-control sessions
+
+# Status
+
+Accepted
+
+# Context
+
+The daemon previously treated Pi sessions as daemon-owned resources: it would discover projects and sessions with Pi SDK `SessionManager`, then open, prompt, stream, and abort sessions with Pi SDK runtime or Pi RPC. That model can expose saved sessions that the user did not explicitly enable for mobile control and can conflict with a live Pi TUI process that already owns the active runtime.
+
+# Decision
+
+For the MVP, the Pi TUI extension owns remote-controlled sessions. The daemon lists only sessions that have been activated by the user from a Pi TUI command. The daemon does not use Pi SDK or RPC to discover, open, prompt, stream, or abort sessions. It stores pairing state and device tokens, tracks currently activated TUI sessions, relays iOS prompt and abort requests to the owning TUI extension, and broadcasts TUI-forwarded events to iOS clients.
+
+The Pi command surface changes to two explicit commands:
+
+- `/remote-control`: toggle remote control for the current TUI session. It starts the daemon if needed; when enabling, it registers the current session with the daemon; when disabling, it unregisters it.
+- `/remote-control-pair`: start the daemon if needed and create a short-lived pairing code from the TUI.
+
+# Consequences
+
+The remote API reflects user-selected live TUI sessions rather than all saved Pi sessions or configured project roots. The daemon no longer competes with the TUI for session file ownership or runtime control. If a TUI process exits, reloads, or disables remote control, that session disappears from the iOS app. The previous `/remote-control` control-shim command shape and daemon-owned Pi runtime model are superseded.

package/docs/adr/0007-require-tui-originated-pairing.md

@@ -0,0 +1,19 @@
+# Title
+
+Require TUI-originated pairing
+
+# Status
+
+Accepted
+
+# Context
+
+Pairing creates bearer tokens for remote devices. Earlier design allowed unauthenticated pair-code creation from loopback and authenticated pair-code creation from remote clients. The new user flow is centered on explicit actions inside the Pi TUI, where the user is already present at the host-side control surface.
+
+# Decision
+
+Pair-code creation is only available from the Pi TUI extension through `/remote-control-pair`. The remote HTTP API does not provide a pair-code creation endpoint. The iOS app may claim a short-lived pair code, but it cannot request a new code remotely.
+
+# Consequences
+
+Pairing requires local intent from an active Pi TUI session and no longer depends on daemon bind address or remote address classification. Remote peers cannot initiate pairing-code generation. ADR 0004's loopback pair-code creation rule is superseded.

package/docs/adr/0008-use-qr-pairing-links.md

@@ -0,0 +1,21 @@
+# Title
+
+Use QR pairing links
+
+# Status
+
+Accepted
+
+# Context
+
+Pair-code creation is restricted to the Pi TUI via `/remote-control-pair`, but a mobile device also needs the daemon endpoint to claim the code. The daemon bind address may be `127.0.0.1` or `0.0.0.0`, neither of which is a usable mobile endpoint. Manual entry of a Tailscale URL plus a short-lived code is poor setup UX.
+
+# Decision
+
+`/remote-control-pair` displays a QR code in the Pi TUI. The QR code encodes a `pi-remote://pair` link containing the advertised daemon base URL, pair code, and expiration time. The same information is also shown as text fallback.
+
+The daemon config supports `advertisedBaseUrl`, which is the URL iOS should use when claiming a pair code and making future API calls.
+
+# Consequences
+
+The iOS app can pair by scanning one QR code. Users must configure `advertisedBaseUrl` when automatic endpoint inference would produce a loopback or wildcard address. Pair-code creation remains TUI-originated only; the QR link does not grant access beyond the short-lived claim proof.

package/docs/adr/0009-rename-package-to-remote-control.md

@@ -0,0 +1,19 @@
+# Title
+
+Rename package to Pi Remote Control
+
+# Status
+
+Accepted
+
+# Context
+
+The package originally used a daemon-centered name. The current design exposes `/remote-control` and `/remote-control-pair`, with the daemon acting as the relay behind a remote-control user experience.
+
+# Decision
+
+Rename the package, CLI binary, daemon display name, default state directory, environment variables, logs, tests, and documentation references to `pi-remote-control` / Pi Remote Control.
+
+# Consequences
+
+The naming matches the TUI command surface. Existing users of previous local builds may need to move state into `~/.pi/remote-control` and update environment variables to `PI_REMOTE_CONTROL_*`.

package/docs/adr/0010-clean-stale-lock-on-status.md

@@ -0,0 +1,19 @@
+# Title
+
+Clean stale lock on status
+
+# Status
+
+Accepted
+
+# Context
+
+The Pi TUI command surface intentionally keeps `/remote-control` focused on toggling the current session. It no longer exposes daemon maintenance subcommands. The daemon still uses `daemon.lock` as the single process-state file, and stale locks can remain after crashes or forced exits.
+
+# Decision
+
+`pi-remote-control status` removes `daemon.lock` when the lock PID is not running. The command reports the daemon as stopped after removing the stale lock. Manual daemon termination remains an operator task outside the TUI command surface.
+
+# Consequences
+
+Users do not need a TUI daemon maintenance command solely to recover from stale locks. A later `/remote-control` invocation can start the daemon normally after `status` has cleaned the stale lock. `status` now has a small side effect, but only when the lock file no longer represents a live process.

package/docs/adr/0011-use-loopback-tui-control.md

@@ -0,0 +1,19 @@
+# Use loopback TUI control
+
+## Status
+
+Accepted
+
+## Context
+
+The daemon may bind to a Tailscale-reachable address so iOS can access it. The Pi TUI extension runs on the same host as the daemon and should not need a paired device token to register or control its own explicitly enabled session. If the extension derives its control URL from a Tailscale bind address, package-internal TUI calls can be treated like remote traffic and fail with `401`.
+
+## Decision
+
+The daemon listens on the configured bind address and, when that address is not loopback or wildcard, also listens on `127.0.0.1` on the same port. The Pi TUI extension uses `127.0.0.1:<configured-port>` for package-internal control calls unless `PI_REMOTE_CONTROL_LOCAL_URL` overrides it.
+
+Package-internal `/v1/tui/*` endpoints accept unauthenticated requests from loopback clients. Non-loopback callers must still provide a valid bearer token. iOS-facing endpoints continue to require paired-device bearer authentication.
+
+## Consequences
+
+TUI activation works without distributing device tokens to the local extension, even when iOS reaches the daemon through Tailscale. Remote peers cannot use the TUI control endpoints without authentication. The configured port must be available on both the selected remote-facing interface and loopback when binding to a specific non-loopback address.

package/docs/adr/0012-use-paginated-session-transcript-loading.md

@@ -0,0 +1,37 @@
+# Use paginated session transcript loading
+
+## Title
+
+Use paginated session transcript loading
+
+## Status
+
+Accepted
+
+## Context
+
+Pi session histories can be long. Sending the full transcript in one session snapshot or one WebSocket message can exceed iOS WebSocket message limits and can make session detail loading slow or memory-heavy.
+
+Raising the iOS WebSocket message-size limit treats the symptom rather than the protocol problem. The daemon needs a contract that bounds initial payload size and lets Pi Relay fetch older history only when the user asks for it by scrolling.
+
+## Decision
+
+The daemon-to-iOS API will expose bounded transcript windows instead of unbounded session histories.
+
+`GET /v1/sessions/{sessionId}` will return session metadata, compact tool state, streaming state, and only the most recent messages up to a requested `messageLimit`, subject to a daemon maximum.
+
+Older messages will be loaded through `GET /v1/sessions/{sessionId}/messages?before={cursor}&limit={limit}`. Cursors are daemon values based on the oldest loaded message's `createdAt` timestamp. The encoded cursor remains opaque to the app, but it represents an exclusive timestamp upper bound for the next older page. Responses return messages in chronological order plus an optional cursor for the next older page.
+
+The session WebSocket stream must not use an unbounded initial transcript message. Any initial session state sent over the stream follows the same bounded-message rule, and live events after subscription are incremental.
+
+Pi Relay will initially request the latest N messages for the session detail view. When the user scrolls to the top of the loaded transcript and an older cursor is available, the app requests the next older page and prepends it to the in-memory transcript. The app de-duplicates all HTTP page and live stream merges by `ChatMessage.id`.
+
+## Consequences
+
+Initial session detail loads remain bounded even for long Pi histories.
+
+The app can show recent context quickly and progressively load older history on demand.
+
+The daemon must maintain a stable transcript paging model over Pi session history and must enforce a maximum page size.
+
+The app must track transcript loading state, older-page cursors, and de-duplicate messages by `ChatMessage.id` when HTTP pages and live stream events overlap.

package/docs/adr/0013-require-manual-reactivation-after-tui-entry.md

@@ -0,0 +1,31 @@
+# Require manual remote-control reactivation after TUI entry
+
+## Title
+
+Require manual remote-control reactivation after TUI entry
+
+## Status
+
+Accepted
+
+## Context
+
+Remote control is explicitly enabled from a live Pi TUI session with `/remote-control`. If the TUI exits without cleanly unregistering, the daemon can temporarily retain an active session registration and the iOS app can continue to show that session until the daemon observes that the TUI control channel is gone.
+
+Automatically restoring remote control when a user resumes a Pi session would make remote visibility persist across TUI process lifecycles, which weakens the explicit opt-in model.
+
+## Decision
+
+Entering or resuming a Pi TUI session does not automatically enable or restore remote control.
+
+On TUI session start, the extension clears local remote-control state. The user must run `/remote-control` to activate remote visibility for that TUI process.
+
+The daemon treats missing TUI heartbeats as an inactive control channel, removes the active session registration, and notifies iOS subscribers with `session_closed`.
+
+## Consequences
+
+Exiting the TUI is effectively a remote-control deactivation, even if shutdown cleanup is missed.
+
+Stale sessions disappear from the iOS app after the heartbeat timeout.
+
+Users must explicitly run `/remote-control` after entering or resuming a TUI session before the session is remotely visible or controllable again.

package/docs/adr/0014-read-transcripts-from-session-files.md

@@ -0,0 +1,33 @@
+# Read transcripts from session files
+
+## Title
+
+Read transcripts from session files
+
+## Status
+
+Accepted
+
+## Context
+
+The daemon currently keeps active-session process state and can derive transcript messages from the TUI registration payload. That makes HTTP session snapshots depend on daemon memory that can become stale after new TUI messages arrive.
+
+Pi session JSONL files are already the persisted source of truth for transcript history. Maintaining a second full transcript projection in the daemon duplicates Pi's state and requires event-specific update logic for message starts, deltas, ends, and tool output.
+
+## Decision
+
+The daemon will read transcript history from the active session's `sessionFile` when serving HTTP session snapshots and transcript pages.
+
+The active session registry will store control metadata, ownership, heartbeat state, command queues, compact live state, and the `sessionFile` path. It will not be the source of truth for completed transcript history.
+
+`GET /v1/sessions/{sessionId}` and `GET /v1/sessions/{sessionId}/messages` will derive their bounded message windows from the Pi session JSONL file at request time. The WebSocket stream remains the live incremental channel for in-progress events; HTTP transcript reads represent persisted transcript state from the session file.
+
+## Consequences
+
+HTTP snapshots and older pages reflect the latest transcript data that Pi has persisted to disk, even after daemon restarts or after messages arrive following remote-control activation.
+
+The daemon avoids maintaining a duplicate full transcript state machine in memory.
+
+In-progress streaming deltas that Pi has not yet persisted may only be visible through WebSocket live events until the session file is updated.
+
+Long transcript reads must remain bounded by the API's `messageLimit` and page `limit` contracts.

package/docs/adr/0015-normalize-transcript-messages-and-stream-events.md

@@ -0,0 +1,35 @@
+# Normalize transcript messages and stream events
+
+## Title
+
+Normalize transcript messages and stream events
+
+## Status
+
+Accepted
+
+## Context
+
+HTTP transcript snapshots are derived from Pi session JSONL files, while WebSocket streams currently forward raw Pi TUI extension events. Pi session messages contain structured content blocks such as text, thinking, and tool calls. Raw stream events contain lifecycle and delta events for the same assistant messages plus tool execution events.
+
+Keeping different public shapes for historical transcript messages and live updates forces the iOS app to maintain separate rendering paths and causes fields such as thinking and tool calls to be lost when the daemon flattens transcript history to plain text.
+
+## Decision
+
+The daemon-to-iOS API will use `TranscriptMessage` as the public transcript message shape for both HTTP transcript reads and WebSocket live updates.
+
+HTTP session snapshots and transcript pages will return persisted `TranscriptMessage` values parsed from the Pi session JSONL `sessionFile`. The parser will preserve structured content blocks including text, thinking, tool calls, images, and tool-result metadata.
+
+The WebSocket stream will not broadcast raw Pi extension events to iOS. The daemon will normalize TUI-forwarded Pi events into daemon-owned stream events that create, patch, replace, or close `TranscriptMessage` values and update tool execution state. The stream remains incremental and bounded; it does not replay unbounded history.
+
+The Pi extension may continue to send raw Pi events to the daemon over the package-internal TUI control interface. Raw Pi event shapes are not part of the public iOS API.
+
+## Consequences
+
+The iOS app renders historical transcript pages and live updates with one transcript model.
+
+Thinking and tool-call content are preserved in HTTP snapshots, HTTP pages, and live stream updates.
+
+The daemon owns the compatibility boundary between Pi event formats and the public iOS protocol.
+
+The WebSocket protocol changes incompatibly for clients that consume raw Pi events.

package/docs/adr/0016-expose-turn-lifecycle-events.md

@@ -0,0 +1,31 @@
+# Expose turn lifecycle events
+
+## Title
+
+Expose turn lifecycle events
+
+## Status
+
+Accepted
+
+## Context
+
+The normalized transcript stream exposes message lifecycle events, tool execution events, and session closure. Clients can infer some progress from `transcript_message_end`, but a Pi turn can include assistant output, tool calls, tool results, and follow-up assistant output. The app needs an explicit daemon-owned signal for turn boundaries instead of relying on raw Pi events or session snapshots.
+
+Pi emits `turn_start` and `turn_end` extension events for each turn. These events are package-internal inputs today and are not part of the public iOS stream protocol.
+
+## Decision
+
+The daemon-to-iOS WebSocket protocol will include normalized `turn_start` and `turn_end` stream events.
+
+The Pi extension will forward Pi `turn_start` and `turn_end` events to the daemon while remote control is active. The daemon will normalize them and broadcast only the public lifecycle fields needed by the app. Raw Pi turn event payloads are not exposed to iOS.
+
+`turn_start` marks that a model/tool turn is active. `turn_end` marks that the turn is complete. Transcript content remains represented by `TranscriptMessage` and tool execution events.
+
+## Consequences
+
+The iOS app can update per-turn loading state without waiting for a new session snapshot.
+
+The stream protocol remains incremental and normalized.
+
+Turn lifecycle events do not replace `transcript_message_end`; clients should still use message events to update transcript content.

package/docs/adr/0017-bound-initial-websocket-session-state.md

@@ -0,0 +1,31 @@
+# Bound initial WebSocket session state
+
+## Title
+
+Bound initial WebSocket session state
+
+## Status
+
+Accepted
+
+## Context
+
+The WebSocket stream sends an initial `session_state` event when an iOS client subscribes to a session. That state currently follows the transcript page default and can contain many `TranscriptMessage` values. After transcript normalization, a single message can include large structured payloads such as `write.arguments.content`, `edit.arguments.edits[].oldText`, `edit.arguments.edits[].newText`, or large tool-result text.
+
+Large initial WebSocket messages can exceed iOS WebSocket message limits and fail with `NSPOSIXErrorDomain Code=40 "Message too long"`. The immediate observed failure is the initial `session_state`, not live incremental events.
+
+## Decision
+
+The daemon will bound only the initial WebSocket `session_state` payload for now.
+
+When a WebSocket subscriber connects, the daemon will request at most 20 recent transcript messages for the initial `session_state`. HTTP session snapshots and explicit transcript-page endpoints keep their existing requested-limit behavior.
+
+Before sending the initial WebSocket `session_state`, the daemon will truncate oversized string payloads inside transcript messages to their first 10 KiB of UTF-8 data. Truncated fields will be marked so clients can display that the value is a preview. The daemon will not add a generic WebSocket bounded sender in this decision, and live incremental stream events are not changed by this decision.
+
+## Consequences
+
+Initial WebSocket subscription is less likely to exceed iOS message-size limits while still giving the app recent context.
+
+Clients that need older or fuller transcript data should load it through HTTP session snapshot and transcript-page endpoints.
+
+Large live events may still need a later protocol decision if they exceed client limits.

package/docs/adr/0018-reregister-active-tui-session-on-heartbeat-miss.md

@@ -0,0 +1,33 @@
+# Re-register active TUI session on heartbeat miss
+
+## Title
+
+Re-register active TUI session on heartbeat miss
+
+## Status
+
+Accepted
+
+## Context
+
+The daemon tracks active TUI sessions in process memory and removes registrations when heartbeats stop. System sleep pauses the TUI heartbeat timer and the daemon sweep timer, but wall-clock time still advances. After wake, the daemon can prune the active session before the TUI extension sends another heartbeat.
+
+The iOS app then correctly sees no active projects because the daemon registration is gone. The TUI can still show `Remote Control Active` because that status is local extension state and the polling heartbeat currently does not repair a missing daemon registration.
+
+## Decision
+
+Keep the daemon's simple heartbeat timeout and in-memory active-session registry behavior.
+
+When a TUI extension still considers a session locally remote-control active, but its heartbeat command poll receives `session_not_found` from the daemon, the extension re-registers the current TUI session with the daemon.
+
+If re-registration succeeds, the extension keeps local remote control active and continues polling. If re-registration fails, the extension clears local remote-control state, removes the status indicator, stops polling, and notifies the user that remote control disconnected.
+
+This recovery only applies to a session that was already locally active in the current TUI process. Entering or resuming a TUI session still does not automatically enable remote control.
+
+## Consequences
+
+System sleep, daemon restart, or daemon in-memory state loss can be repaired by the next TUI heartbeat without requiring daemon sleep detection.
+
+The iOS app may briefly show no active projects after wake until the TUI heartbeat runs and re-registers the session. Remote prompts sent during that gap can still fail with `session_not_active`.
+
+The daemon remains simple and continues to remove stale sessions by heartbeat timeout and owner PID checks.

package/docs/adr/0019-display-only-pairing-qr-and-expiry.md

@@ -0,0 +1,25 @@
+# Display only pairing QR and expiry
+
+## Title
+
+Display only pairing QR and expiry
+
+## Status
+
+Accepted
+
+## Context
+
+`/remote-control-pair` previously displayed the numeric pair code and raw pairing link as text fallback in addition to the QR code. The app pairing flow uses the QR code, and showing the raw bootstrap code and full link in the TUI adds unnecessary sensitive and noisy output.
+
+## Decision
+
+`/remote-control-pair` displays only the QR code and its expiration time. The pair code and pairing link remain encoded inside the QR code but are not printed as separate TUI text lines.
+
+This supersedes the text-fallback display portion of ADR 0008.
+
+## Consequences
+
+The pairing output is shorter and exposes less bootstrap material in terminal text.
+
+Users pair by scanning the QR code before the displayed expiration time.

package/docs/adr/0020-expose-session-status-snapshots.md

@@ -0,0 +1,31 @@
+# Expose session status snapshots
+
+## Title
+
+Expose session status snapshots
+
+## Status
+
+Accepted
+
+## Context
+
+The iOS app needs to display the same kind of session status currently shown in the Pi TUI footer: model, thinking level, token/cache usage, cost, and context window usage.
+
+The Pi extension API exposes enough structured data to compute this status from the live TUI session context, including `ctx.model`, `pi.getThinkingLevel()`, `ctx.sessionManager`, and `ctx.getContextUsage()`. The daemon cannot compute the live TUI status by itself because active sessions are owned by the TUI extension and the daemon does not use Pi SDK session runtime APIs.
+
+## Decision
+
+Add a package-level `session_status` snapshot for active remote-control sessions.
+
+The TUI extension computes the snapshot from the live session context when a session is registered and whenever relevant status inputs change. The daemon stores the latest snapshot in the active-session registry, includes it in HTTP session snapshots and initial WebSocket session state, and broadcasts a `session_status` WebSocket event when the snapshot changes.
+
+The status snapshot is structured data, not rendered TUI footer text. It includes current model metadata, thinking level, cumulative usage and cost, and context usage. Context token and percentage values may be `null` when Pi reports them as unknown.
+
+## Consequences
+
+The iOS app can render session status without parsing terminal UI output.
+
+The app's displayed status is eventually consistent with the TUI and updates when the live TUI extension reports changes.
+
+The daemon remains independent of Pi SDK session runtime APIs and only relays status produced by the owning TUI extension.

package/docs/adr/0021-support-remote-compact-action.md

@@ -0,0 +1,31 @@
+# Support remote compact action
+
+## Title
+
+Support remote compact action
+
+## Status
+
+Accepted
+
+## Context
+
+The iOS app needs to trigger the same operation as the Pi TUI `/compact` command for an active remote-control session.
+
+Pi's extension API exposes `ctx.compact()` for triggering compaction from the live TUI extension context. Pi does not expose all built-in interactive slash commands as a stable generic command registry suitable for remote passthrough, and many interactive commands require local TUI UI flows.
+
+## Decision
+
+Support `/compact` as an explicit allowlisted remote session action, not as generic remote slash-command passthrough.
+
+The daemon exposes an authenticated iOS endpoint for compacting an active session. The daemon enqueues a `remote_compact` command for the owning TUI extension. The TUI extension handles that command by calling `ctx.compact()` for the current live session.
+
+If the target session is not active, the daemon returns `409 session_not_active`, matching remote prompt and abort behavior.
+
+## Consequences
+
+The iOS app can request compaction for an active remote-control session with a small protocol addition.
+
+The implementation avoids exposing arbitrary TUI slash commands remotely and avoids having to reproduce interactive TUI command flows in the app.
+
+Additional remote slash-command-like operations require separate explicit protocol decisions.

package/docs/adr/0022-rename-session-status-to-runtime-status.md

@@ -0,0 +1,27 @@
+# Rename session status to runtime status
+
+## Title
+
+Rename session status to runtime status
+
+## Status
+
+Accepted
+
+## Context
+
+ADR 0020 introduced a `session_status` snapshot and WebSocket event for live model, usage, cost, and context information. The name is too similar to the existing initial WebSocket `session_state` event and can cause protocol confusion.
+
+## Decision
+
+Rename the snapshot concept to `RuntimeStatus`.
+
+Public session state uses the field `runtimeStatus`. The WebSocket update event is `runtime_status`. Package-internal TUI status reports use `{ "type": "runtime_status", "status": RuntimeStatus }`.
+
+This ADR supersedes only the naming chosen in ADR 0020. The underlying decision to expose live status snapshots is unchanged.
+
+## Consequences
+
+The protocol distinguishes initial full session state (`session_state`) from incremental runtime status updates (`runtime_status`).
+
+Clients can treat `runtimeStatus` as live metadata about the owning TUI runtime rather than as another session-state payload.