[ymote]

Lets a web client or a terminal UI talk to the same Octos system agent that the native apps use, without starting a second kernel. Talk to Octos is off by default. This revision reworks the first version after two security reviews.

octos pin: every octos crate is pinned at octos main e6223efc, the merge of octos#2591 (serve --host-managed, UPCR-2026-036), which contains 3b5d17a4 from #107. This branch is rebased on OctoSense main b89cd52.

What changed, by review finding

1. Off by default. The kernel stays the private octos serve --stdio child. AI providers → Talk to Octos → Turn on restarts it as octos serve --host-managed and mints the external token. Revoke all clients rotates that token. Turn off returns to the pipe, so nothing listens and the connection file is removed. The setting is saved; the token lives only for the shell's lifetime.
2. Upstream, no overlay. tools/runtime-patches/octos-host-managed.patch and octos-runtime-patches.lock.json are gone. serve --host-managed is octos code (#2591). The native feature list now comes from octos (octos_core::ui_protocol::UI_PROTOCOL_STDIO_DEFAULT_FEATURES, pinned by an octos test) instead of a hand copy.
3. Two tokens and pairing. Native consumers use a host token that never leaves the shell. The kernel gets both tokens as its first two stdin lines, never in its environment. External clients get a separate token that opens /api/ui-protocol/ws only, and there only an allowlist of methods: sessions and turns of non-peer sessions, message paging, answers on sessions the connection opened, and read-only capability/status. Everything else is refused (external_method_denied): provider, key and skill configuration, snapshots, fork and delete, peer methods, and server/shutdown. Any call naming an app peer's peer-…/peerctx-… session is refused too. Turns an external client starts keep only a fixed allowlist of built-in tools, filtered on the finished registry (no shell, git, spawn, peer_*, send_file, task, MCP or plugin tools). External calls name no profile but _main, set no topic, cwd or sandbox, and steer, interrupt or answer only their own turns (approvals once-only). "Copy access token" is removed. A web client pairs with octos's one-time code: 8 characters, 5 minutes, rate-limited, audited and single use. The sheet shows the code with a QR of the web link, and pairing is enabled only while that sheet is open, including the phone's Back, which calls cancel(). Pairing on/off is serialized, so a late off never cancels a newer code. No copy action remains.
4. validate_origin. https is required. On a desktop http is also accepted for localhost, 127.0.0.1 or [::1]; on Android, https only.
5. Port squatting. The shell binds the listener once and passes it to each kernel generation (--listen-fd 3, Unix). A restart keeps the port, and no other app can take it in between. Without descriptor passing (Windows), a restart reuses the port when it is free and otherwise falls back to port 0, rotates the external token and rewrites the connection file.
6. Desktop orphan. The child's stdin is its lifeline, and octos stops on stdin EOF (plus PR_SET_PDEATHSIG on Linux/Android). The new crates/kernel test a_host_that_dies_takes_its_kernel_with_it SIGKILLs a host process and checks that its kernel exits, in both modes.
7. Windows descriptor. The connection file is kept in %LOCALAPPDATA%\OctoSense\, whose default ACL admits this user, SYSTEM and administrators; this is documented. It holds only the external token (mode 0600 elsewhere).
8. web-client-origin.txt. It is written atomically (temp file, then rename). A malformed file reads as no origin, and the kernel stays available (tested).
9. CI --offline. The host-patch step is gone. The remaining desktop build step (kernel-artifact.py --host) passes --offline in offline plans, with a test assertion.
10. ADR 0003 is rewritten. It now has a threat model (other APKs and local users reach loopback; browsers; shell death; port races), a table of what each token grants, the peer-approval rule, the opt-in listener and stdin-EOF shutdown. The false claim that a desktop crash stops the kernel is corrected: it now does, through stdin EOF, and a test covers it.
11. Docs. The kernel README (EN and zh-CN, bilingual per the repo rules), the app/desktop/phone READMEs and the llm service docs are updated.

Validation (local, macOS; rerun on the head 6eee96d with octos e6223efc, including the services toolbox with --features octos-engine)

• cargo test --locked -p octosense-kernel: 19 unit and 11 core tests pass. They include off-by-default, the toggle switching the launch, a malformed origin, and shutdown during startup.
• Real kernel (OCTOS_CORE_TEST_KERNEL = release octos built from #2591): all 5 pass.
  • The providers/restart test runs with Talk to Octos off.
  • With it on: the external token gets 401/403 on admin and REST routes, cannot call or see server/shutdown, and cannot answer a peer approval. A bad Host gets 421. No token, a spoofed profile header, solo login and untrusted origins are all refused. Restart keeps the port and token, and rotation kills the old token. After Turn off nothing listens.
  • Pairing is single use and returns the external token.
  • Native and browser clients share the system conversation.
  • The killed-host test passes in both modes.
• App-peer real-kernel tests (6) pass with Talk to Octos off (cargo test -p octosense-app-peers --features octos-core --test real_kernel), covering peer memory namespaces.
• octosense-llm-service --features octos-core: all pass (21 unit, 8 image, 19 service tests; the sheet-control, timer and pairing-sheet tests are new).
• octosense-ai-host --features octos-core,llm tests pass and its clippy is clean. octosense-app-peers passes with default features and with octos-core,ws.
• python3 -m unittest discover -s tools -p 'test_*.py': 28 OK. rom/tests/test_home_build.py: 14 OK.
• tools/setup.py --check --cargo passes. check-shell-graph.sh passes for -p octosense and -p octosense-home (one octos). cargo check --locked -p octosense-home --features mobile-apps passes, and so does clippy (-D warnings) on the kernel and llm service.
• Hidden-window desktop run (on 74a6fe3 with octos 2cd29e44; the later pin adds only the peer control-plane gate, which the real-kernel test covers; MAKEPAD_HIDE_WINDOWS=1 MAKEPAD_REMOTE, temp OCTOSENSE_HOME and core dir, ended with /gq):
  • With Talk to Octos off, no kernel listens.
  • Turn on started octos serve --host-managed --listen-fd 3 and wrote a 0600 connection file.
  • A probe with the external token got: 401 on /api/admin/{overview,stop-all,token/rotate,host/pairing}; 403 on /api/my/profile; server_shutdown_unavailable (not advertised); host_owned_peer_answer_denied for peer- and peerctx-; 421 for a rebinding Host; 401 on WS without a token; 101 with octos-ui selected for the bearer subprotocol.
  • Pair a web client showed the code and the QR. /pair/info answered 200 while the code's sheet was open and 404 after Back/Done. A claim returned the external token, and a second claim got 400.
  • Saving the origin restarted the kernel on the same inherited socket.
  • Turn off stopped the kernel, and the port was closed in both processes.

Unverified: Android packaging and device behavior, adb forward tunnels, a terminal UI reading the connection file, Windows.

Re-review fixes

• H1/M1 (octos e6223efc): the allowlist, peer-session refusal and external-turn tool restriction above; enumerated by an octos test over the dispatch table.
• M2: cancel() in the connect, pairing and export sheets, and a test that every service sheet defines it.
• M3: tokens on stdin; octos refuses env tokens, fences /proc/*/environ|cmdline in file tools and the shell policy; ADR 0003 states the profile's tools and sandbox. The live desktop probe found the external token absent from the kernel's environment (ps eww).
• L1 (octos): claims rate-limited, Origin-checked and audited. L2: pairing epochs. L3: Android https only. L4: apps.yml job kernel-security runs the real-kernel tests against octos built at the pin, plus a test that Revoke all ends a live session. L5: restart warnings on the sheet.

Overlaps

• Desktop release packages (macOS .app/.dmg, Windows NSIS, Linux .deb/.AppImage) and release-desktop workflow #94 builds octos without the overlay. Once #2591 merges and the pin moves, Desktop release packages (macOS .app/.dmg, Windows NSIS, Linux .deb/.AppImage) and release-desktop workflow #94 needs only that octos pin. A note is posted on Desktop release packages (macOS .app/.dmg, Windows NSIS, Linux .deb/.AppImage) and release-desktop workflow #94.
• Package the desktop Octos kernel and update hosted Rinx #85 and Desktop release packages (macOS .app/.dmg, Windows NSIS, Linux .deb/.AppImage) and release-desktop workflow #94 already conflict with current main in Cargo.toml/Cargo.lock, because the pins moved. Beyond that, they both touch Cargo.toml/Cargo.lock, crates/kernel/src/{launch,lib}.rs, crates/kernel/tests/core.rs, crates/kernel/README.md, crates/ai-host/src/lib.rs and the desktop READMEs. git merge-tree against this head shows no conflicts beyond the Cargo.toml/Cargo.lock ones main already causes. Semantically, the packaged octos-kernel sibling from Package the desktop Octos kernel and update hosted Rinx #85 must be built from the pinned octos with --host-managed; any build of the pin qualifies once it moves.

🤖 Generated with Claude Code