[the-non-expert]

Summary

Adds a Remote Control toggle to the live-session header so you can turn Claude Code Remote Control on/off for a session straight from the Karma dashboard — no need to switch to its terminal to reach it from your phone.

Claude Code exposes no local API for Remote Control; the only lever is the /remote-control slash command typed inside the session. Karma runs on the same machine as the tracked terminal, so it drives Remote Control by typing into the session's terminal tab (tmux / macOS Terminal.app / iTerm2), reusing the tty / iTerm-session targeting from services.terminal_focus.

/remote-control is not a symmetric toggle, so the two directions differ:

• ON is fully automated — the bare command turns it on; the endpoint types it and confirms from the transcript.
• OFF opens Claude Code's interactive "Disconnect Remote Control" menu. Nothing drives that menu reliably from outside the process (do script can't deliver arrow keys; System Events needs a machine-wide Accessibility grant that misfires). So Karma types the command to open the menu, raises the terminal, and returns method:"menu-open" — the user picks "Disconnect this session" themselves, and the next liveStatus poll flips the pill.

State is read back from the session JSONL transcript, where Claude Code writes {"type":"system","subtype":"bridge_status", …} lines on connect/disconnect. No line anywhere → off; a line that can't be classified → unknown (endpoint 409s rather than blind-toggle).

The endpoint is honest by construction: sent=false means nothing was typed; sent=true, confirmed=false means keys went but the transcript hasn't caught up yet.

Changes

• POST /live-sessions/{id}/remote-control {desired} — async, process-wide asyncio.Lock so button-mashing can't pile up keystroke sequences, bounded confirm-poll (6 × 0.5s).
• services/remote_control.py (new) — read_remote_control_state, type_remote_control_command, can_send_remote_control. Whole-transcript scan (48 MB cap) for the last bridge_status, memoized on (path, st_mtime_ns, st_size); strict type==system && subtype==bridge_status match so ordinary text containing the string is ignored.
• RemoteControlToggle.svelte (new) — the pill: off / on (+ ↗ open to claude.ai/code) / unknown / busy / staged / menu / retry / ok. Never dims; only the button disables. role="switch", live-region announcements, reduced-motion.
• remote_control + can_remote_control on LiveSessionSummary — computed only on the single-session GET (they open the JSONL — too costly for the 1s-polled list endpoints).
• CSRF gate — rc_trusted_origins (default :5180 only, deliberately narrower than cors_origins which also trusts :5173/:3000) + an X-Karma-RC request header, and Origin must be present. This required adding X-Karma-RC to cors_allow_headers so the browser's CORS preflight passes.
• Status gate — blocked only for WAITING_INPUT (a dialog is open; the trailing Enter could answer it), STARTING (no REPL yet) and ENDED. Everything else, including ACTIVE, is allowed — a slash command typed during a tool run just queues.
• Hardening from a blind-review pass (visible as review #N comments): ~/.claude/projects path confinement against symlink escape, https://claude.ai/ filter on the URL handed to <a href>, session_id regex, live-pid + supported-terminal gate.
• .gitignore — ignores .storygraph.db and its -wal/-shm sidecars. An external tool drops them in the repo root, nothing here references them, and they were showing up as untracked noise in every git status. (Unrelated to Remote Control, folded in as a drive-by.)
• api-types.ts carries two incidental Prettier line-collapses (PermissionMode, CronStateTriggerEvent) alongside the new RC types; prettier --check passes with them.

Review round 2 — all five inline comments addressed

Rebased onto main (now includes #99, #100, #102); merges clean.

Review comment	Resolution
ConversationHeader.svelte — conflicts with #100, copiedTarget === 'resume' becomes a type error	Kept #100's ResumeSessionButton outright and dropped this branch's copy-resume block. Taking the reviewer's note: #100's button focuses the terminal when live, which is useful, so this branch's "hide on live" was the wrong instinct and is gone. CopyTarget stays narrowed to 'uuid'.
live_sessions.py — full-transcript scan on the 1s-polled single-session GET	Scan result memoized on (path, st_mtime_ns, st_size). A JSONL transcript is append-only, so unchanged mtime+size ⇒ unchanged content and a quiet session is scanned exactly once. LRU-bounded at 256 entries, lock-guarded. Measured — see Testing.
live_sessions.py — a request with no Origin passes the gate	Missing Origin now 403s. For a keystroke-injecting endpoint it isn't worth the benefit of the doubt: this closes DNS-rebinding and the no-Origin-on-same-origin-POST corner. The dashboard always sends one; scripted callers can pass Origin: http://localhost:5180.
remote_control.py — "Esc-dismisses" overclaims; a stale-off ON click leaves the Disconnect menu open in an unfocused terminal	Took both options offered. The docstring no longer claims an Esc that nothing sends, and unconfirmed-ON now raises the terminal exactly like the OFF path, with a detail that says the disconnect menu may be showing. The frontend's menu-open method stays reserved for the OFF click, so the ON path reports the honest "sent, unconfirmed".
remote_control.py — tmux gate passes on pid liveness alone; recycled pid + recycled pane could enable RC on the wrong session	Implemented the suggested check: tmux display-message -p -t <pane> '#{pane_pid}' must be the recorded pid or one of its ancestors (walk capped at 8, 5s TTL cache). Unverifiable — no tmux, pane gone — is treated as not owned. Verified against real tmux 3.7c — see below.

The reviewer's follow-up (moving #100's resume-in-terminal to rc_trusted_origins) is deliberately not in this PR — it hardens a different endpoint from a different feature, and was flagged as "follow-up once this lands". It'll be its own PR.

tmux gate — verified on real tmux ✅

The pane-ownership check was initially mocked-only, which was called out as the one unproven claim in this PR. It is now verified end to end against tmux 3.7c, and the verification is committed as an integration test (test_pane_ownership_against_real_tmux, skipif when tmux is absent so CI and non-tmux machines are unaffected):

Case	Expected	Result
_tmux_pane_pid() agrees with tmux display-message	equal	✅
The pane's own process	owned	✅
A descendant of the pane process — the real shape, since claude runs under the pane's shell	owned	✅
init (pid 1)	not owned	✅
An unrelated process outside tmux	not owned	✅
A nonexistent pane (%99999)	not owned	✅

Run it yourself with pytest tests/api/test_live_sessions_remote_control.py::test_pane_ownership_against_real_tmux -v — it creates and destroys its own throwaway session and never touches your own. Locally it reports PASSED, not SKIPPED.

Component

• API (FastAPI backend)
• Frontend (SvelteKit dashboard)
• Captain Hook (hook models)
• Hook Scripts
• Documentation
• CI / Build

Type

• Feature (new functionality)

Testing

• API tests pass — test_live_sessions_remote_control.py 40 pass (33 + 7 new: pane-ownership accept/reject/unverifiable, a real-tmux integration test, scan memoization, per-path isolation, unconfirmed-ON raises vs confirmed-ON doesn't). Full tests/api/ 1885 pass (the 6 test_background_shells_router failures are pre-existing, unrelated, and local-only: that test's fixture doesn't stub the router's _maybe_sync(), so each test ingests the developer's real ~/.claude/projects history into its temp DB and gets 200 rows where it expects a handful. Green on CI, which has no such history. An earlier revision of this description blamed a stale .storygraph.db — that was wrong; karma's DB is ~/.claude_karma/metadata.db.).

• Frontend type-checks (npm run check, 0 errors) and lints clean (npm run lint, 0 errors)

• Captain Hook tests pass — N/A (no hook changes)

• Memoization measured, not asserted. A/B across two detached worktrees (pre-fix vs post-fix), each a real uvicorn server hit over real HTTP with an isolated $HOME, against a 40 MB transcript containing zero bridge_status lines (the worst case: every byte scanned, nothing found). 100 sequential requests:

  	pre-fix	post-fix
  Server CPU, read from ps (the OS, not the app)	4.06 s	0.06 s	68× less
  Wall clock, measured by the external request loop	4.71 s	0.63 s	7.5× faster

  That's 40.6 ms → 0.6 ms of CPU per request. Both variants returned remote_control: {'state': 'off'}, confirming the scan path actually ran rather than an early-out. The regression test was mutation-checked: disabling the memo makes it fail assert 3 == 1 for the right reason, so it detects the real defect instead of passing vacuously. (The endpoint's @cacheable(max_age=5) throttles how often a browser triggers this; it doesn't change the per-scan cost, which is what was measured.)

• Manually tested — ON and OFF both verified end-to-end against a throwaway Terminal.app claude session:

  • ON → {sent:true, confirmed:true, state:"on", url:"https://claude.ai/code/session_…"}; confirmed three ways (endpoint response, a bridge_status "is active" line Claude Code wrote to the throwaway's own transcript, and a fresh Karma GET re-reading it as on).
  • OFF → {sent:true, method:"menu-open", state:"on"}; focus_terminal raised the window for the user to finish in the menu.

Screenshots

Pill states (off / on+open / menu / retry) render via npm run check + component review; no static screenshots attached.

Related Issues

Separate feature branch off main; independent of #99 (settings / schema-drift). Rebased onto main after #99/#100/#102 merged.

🤖 Generated with Claude Code

[JayantDevkar]

The security design here is solid and I'd like to land this — but it needs a rebase and one perf fix first.

Checked and clean

• The typed payload is the constant RC_COMMAND; nothing request- or session-derived reaches it. All subprocess calls are list-form, AppleScript interpolation goes through _applescript_str, tmux uses send-keys -l --.
• The origin gate is exact-match and enforced server-side independent of CORS, so adding X-Karma-RC to cors_allow_headers doesn't let :5173/:3000 through (they pass preflight, then get 403). Desktop app uses :5180, so it's covered.
• Transcript paths are realpath-confined under projects_dir; the href is filtered to https://claude.ai/ on both sides. Blocking calls in the async handler are all in asyncio.to_thread.

Needs to change before merge

1. Rebase: #100 just merged and this now conflicts in ConversationHeader.svelte and api/schemas.py (see inline).
2. The full-transcript scan on the polled single-session GET (see inline).

Follow-up once this lands: #100's resume-in-terminal endpoint should move to this PR's narrower rc_trusted_origins gate — it spawns a process and currently trusts all of cors_origins.

Not checked: real toggle against a live terminal, Claude Code's actual bridge_status wording vs _ON_MARKERS/_OFF_MARKERS (a wording change degrades to unknown → 409, which is the safe direction).

[JayantDevkar]

Re-reviewed: all five fixes from the last round are real, and I found no semantic conflict with current main. Pushed two commits on top so this can land now: the terminal gate (can_send_remote_control) runs via asyncio.to_thread since a cache miss can shell out to ps/tmux several times with 5 s timeouts; the real-tmux integration test runs on a private server (TMUX_TMPDIR in a short temp dir, TMUX unset, kill-server in finally) and polls for the pane shell before asserting ownership, since it flaked about 1 in 30 locally; the toggle uses aria-disabled instead of disabled so the reason text stays reachable by keyboard; the OFF docstring no longer claims to navigate the menu; and the multi-line comment blocks are one line each. Merged current main in. Locally: 1952 passed, 6 skipped on the full API suite, npm run check 0 errors, the tmux test ran 10/10. Merging once CI agrees.