Re-land #8276 (draft: blocked by review)

docs-site/src/content/docs/guides/integrations.md

@@ -33,6 +33,8 @@ file, and removes it again. Each client below has its own switch:
 | Factory Droid | `~/.factory/settings.json` (`%USERPROFILE%\.factory\settings.json` on Windows) | JSON | immediately via file watching | none — keyless loopback |
 | T3 Code | `$T3CODE_HOME/userdata/settings.json` (default `~/.t3/userdata/settings.json`) | JSON | immediately — T3 Code watches the file | non-secret loopback marker |
 
+From the CLI, `ocx integration client enable|disable --client <id>` changes this machine only, like the dashboard toggle. On a Remote Link Home that uses route intent, the change is recorded as the Home's own decision, so `ocx sync` keeps it, and linked Children keep their defaults. To change what Children inherit, use `ocx route to <client> on|off`. On a Remote Link Child a plain toggle is refused and prints the Home command for that device; use `ocx route to <client> off --local` there to opt that Child out. See [Remote Link](/guides/remote-link/#route-clients-per-device).
+
 ## Gentle Shell
 
 Choose **Connect → Gentle Shell**, or use the same managed-integration commands:

docs-site/src/content/docs/ko/guides/integrations.md

@@ -76,6 +76,8 @@ OpenClaw에는 역할이 서로 다른 여러 설정이 있습니다. `OPENCLAW_
 
 opencodex는 자체 환경에서 이 값을 읽습니다. 게이트웨이가 프로필이나 옮겨진 홈에서 실행된다면 opencodex도 같은 변수를 설정해 시작하세요. 그렇지 않으면 다른 설치를 올바르게 따라가게 됩니다.
 
+CLI의 `ocx integration client enable|disable --client <id>`는 대시보드 토글처럼 이 컴퓨터만 바꿉니다. route 의도를 쓰는 Remote Link Home에서는 이 변경을 Home 자신의 결정으로 기록하므로 `ocx sync`가 유지하고, 연결된 Child는 기본값을 그대로 따릅니다. Child가 상속하는 값을 바꾸려면 `ocx route to <client> on|off`를 사용하세요. Remote Link Child에서는 일반 토글을 거부하고 그 기기용 Home 명령을 출력합니다. 해당 Child만 제외하려면 그곳에서 `ocx route to <client> off --local`을 사용하세요. [Remote Link](/ko/guides/remote-link/)를 참고하세요.
+
 ## 스위치가 아닌 다른 다섯 서피스
 
 **API Keys**는 클라이언트가 아니라 opencodex 자체 자격 증명을 관리합니다. **Codex CLI**는 프록시 서비스가 직접 연결합니다. opencodex를 시작하면 적용되고 멈추면 네이티브 라우팅이 복원되므로 파일별 스위치가 없습니다. **Claude**는 자체 활성화 플래그와 Desktop의 Save/Apply 흐름을 유지하고, **Grok Build**는 모델을 선택한 뒤 적용하는 경계를 유지합니다. 모두 이 기능보다 먼저 있던 동작이며 바뀌지 않았습니다. **Cursor**는 아무 파일도 쓰지 않습니다. 탭에서 탐지 결과, 게이트웨이 값, 마지막 요청을 보여주고 나머지는 Cursor Private Inference 안에서 처리합니다.

native/ocx-child/src/parity.rs

@@ -69,7 +69,11 @@ fn json_safe_nonneg_int(val: &serde_json::Value) -> Option<u64> {
     None
 }
 
-/// Strict exact-key parser matching `parseLinkChildParityReport` in `src/link/child-parity.ts`.
+/// Strict exact-key parser for the five-key base report `ocx-child` sends, capped at
+/// `LINK_CHILD_PARITY_MAX_BYTES` (1 KiB). It is narrower than the Home's TypeScript parser
+/// (`parseLinkChildParityReport` in `src/link/child-parity.ts`), which also accepts the extended
+/// report carrying `appliedRouteIntentDigest` and `routeClientOutcomes` and caps the body at 8 KiB.
+/// `ocx-child` never reads route intent, so it never sends those fields.
 pub fn parse_link_child_parity_report(raw_json: &str) -> Option<LinkChildParityReport> {
     if raw_json.len() > LINK_CHILD_PARITY_MAX_BYTES {
         return None;

scripts/test-layout/layout-route-intent.json

@@ -0,0 +1,60 @@
+{
+  "cli-link-route-intent.test.ts": "cli",
+  "cli-route-to-aliases.test.ts": "cli",
+  "cli-route-to-confirmation.test.ts": "cli",
+  "cli-route-to.test.ts": "cli",
+  "client-disconnect-config-recovery.test.ts": "clients",
+  "client-disconnect-edited-codex.test.ts": "clients",
+  "client-disconnect-field-snapshot.test.ts": "clients",
+  "codex-disconnect-fields.test.ts": "codex-integration",
+  "codex-disconnect-owned-recovery.test.ts": "codex-integration",
+  "codex-journal-provider-reserialization.test.ts": "codex-integration",
+  "home-route-intent-upgrade.test.ts": "clients",
+  "link-home-route-intent.test.ts": "clients",
+  "link-route-intent.test.ts": "server",
+  "management-route-intent-native-errors.test.ts": "server",
+  "management-route-intent-native-review.test.ts": "server",
+  "route-intent-aside.test.ts": "clients",
+  "route-intent-claude-surface.test.ts": "clients",
+  "route-intent-codex-connect-disabled.test.ts": "clients",
+  "route-intent-codex-transitions.test.ts": "clients",
+  "route-intent-connect-recovery.test.ts": "clients",
+  "route-intent-connected-review.test.ts": "clients",
+  "route-intent-connected.test.ts": "clients",
+  "route-intent-desktop.test.ts": "clients",
+  "route-intent-file-originals.test.ts": "clients",
+  "route-intent-home-consent.test.ts": "clients",
+  "route-intent-local-receipt.test.ts": "clients",
+  "route-intent-materializer.test.ts": "clients",
+  "route-intent-native-originals.test.ts": "clients",
+  "route-intent-native-review.test.ts": "clients",
+  "route-intent-offline-mode-switch.test.ts": "clients",
+  "route-intent-overwrite.test.ts": "clients",
+  "route-intent-parity-fallback.test.ts": "clients",
+  "route-intent-parity-withdrawal.test.ts": "clients",
+  "route-intent-parity.test.ts": "clients",
+  "route-intent-reporter.test.ts": "clients",
+  "route-intent-runtime-stop.test.ts": "clients",
+  "route-intent-scheduler.test.ts": "clients",
+  "route-intent-state.test.ts": "clients",
+  "route-intent-watch-boundary.test.ts": "server",
+  "route-intent-watch-client.test.ts": "clients",
+  "route-intent-watch-waiters.test.ts": "server",
+  "route-intent.test.ts": "clients",
+  "route-to-child-defaults.test.ts": "routing",
+  "route-to-home-live-flags.test.ts": "routing",
+  "link-pinned-sync-overwrite.test.ts": "clients",
+  "route-to-ephemeral.test.ts": "server",
+  "route-to-home-decisions.test.ts": "routing",
+  "cli-sync-fanout-ephemeral.test.ts": "cli",
+  "route-to-home-native-truth.test.ts": "routing",
+  "route-to-home-off-review.test.ts": "routing",
+  "route-to-live-settings.test.ts": "server",
+  "route-to-policy-review.test.ts": "server",
+  "route-to-retirement-review.test.ts": "server",
+  "route-to-routes.test.ts": "server",
+  "route-to-sync-child.test.ts": "routing",
+  "service-disconnected-client-restart.test.ts": "service",
+  "service-restart-registration-guard.test.ts": "service",
+  "service-scheduler-restart-cleanup.test.ts": "service"
+}

scripts/test-layout/layout.json

@@ -1,7 +1,7 @@
 {
   "version": 1,
   "root": "tests",
-  "explicitShards": ["layout-file-identity.json", "layout-clients.json", "layout-codex-collision.json", "layout-agent-assertion.json", "layout-chat.json", "layout-replay.json", "layout-adapters.json", "layout-jev.json", "layout-workbuddy.json", "layout-combos.json", "layout-credit-renewal.json", "layout-server-inbound.json", "layout-providers.json", "layout-responses.json", "layout-exec-boundary.json", "layout-persistent-dashboard.json", "layout-start-ownership.json", "layout-config.json", "layout-kiro-usage.json", "layout-usage.json"],
+  "explicitShards": ["layout-route-intent.json", "layout-file-identity.json", "layout-clients.json", "layout-codex-collision.json", "layout-agent-assertion.json", "layout-chat.json", "layout-replay.json", "layout-adapters.json", "layout-jev.json", "layout-workbuddy.json", "layout-combos.json", "layout-credit-renewal.json", "layout-server-inbound.json", "layout-providers.json", "layout-responses.json", "layout-exec-boundary.json", "layout-persistent-dashboard.json", "layout-start-ownership.json", "layout-config.json", "layout-kiro-usage.json", "layout-usage.json"],
   "explicit": { "kimi-monthly-quota.test.ts": "providers", "sync-fanout.test.ts": "cli", "sync-command-fanout.test.ts": "cli", "link-pinned-sync-argv.test.ts": "clients", "sync-link-status.test.ts": "cli", "sync-fanout-process.test.ts": "cli", "codex-installation-acl.test.ts": "codex-integration", "codex-installation-id.test.ts": "codex-integration", "codex-installation-wire.test.ts": "codex-integration", "codex-installation-failover.test.ts": "responses", "service-desktop-recovery.test.ts": "service", "catalog-omit-disabled-native.test.ts": "codex-integration", "provider-input-modalities.test.ts": "providers", "combo-description.test.ts": "routing", "combo-description-catalog.test.ts": "codex-integration", "codex-provider-routing.test.ts": "codex-integration", "config-native-reasoning-retention.test.ts": "config", "server-native-reasoning-retention-merge.test.ts": "server", "server-native-reasoning-retention.test.ts": "server", "config-workflow-budget.test.ts": "config", "server-workflow-budget-settings.test.ts": "server", "responses-retained-reasoning-stream-recovery.test.ts": "responses", "openai-native-hosted-search-history.test.ts": "adapters/openai", "responses-native-compact-search-history.test.ts": "responses", "config-hosted-search-projection.test.ts": "config", "gcp-credential-boundary.test.ts": "adapters/google", "gcp-sa-marker.test.ts": "adapters/google", "gcp-sa-adapter.test.ts": "adapters/google", "management-gcp-credential-input.test.ts": "server", "codex-preserve-signed-in.test.ts": "codex-integration", "cli-account-preservation.test.ts": "cli", "cli-provider-list-active.test.ts": "cli", "service-state-isolation.test.ts": "service", "compaction-history-framing.test.ts": "responses", "catalog-native-max-context.test.ts": "codex-integration", "protocol-argon-thought-boundary.test.ts": "responses", "service-log.test.ts": "service", "messages-native-empty-inline.test.ts": "claude-integration", "catalog-auto-review-override.test.ts": "codex-integration", "management-auto-review-settings.test.ts": "server", "management-auto-review-auth.test.ts": "server", "prefer-model-alias-ids.test.ts": "server", "responses-mimo-envelope.test.ts": "responses", "responses-call-id-linkage.test.ts": "responses", "bridge-terminal-refusal.test.ts": "adapters", "loop-terminal-refusal.test.ts": "images", "web-search-terminal-refusal.test.ts": "web-search", "combo-terminal-refusal.test.ts": "routing", "server-terminal-refusal-wiring.test.ts": "server", "incomplete-reason-normalization.test.ts": "responses", "advisor-retention.test.ts": "advisor", "responses-native-key-cooldown.test.ts": "responses", "responses-run-turn-key-readmission.test.ts": "responses", "qoder-spawn-readmission.test.ts": "adapters", "api-key-selection-cooldown.test.ts": "providers", "api-key-auto-pause-distribution.test.ts": "providers", "explicit-key-pause-oauth-boundary.test.ts": "providers", "server-chat-native-key-selection.test.ts": "server", "compact-key-selection.test.ts": "responses", "messages-native-key-selection.test.ts": "claude-integration", "coding-agent-windows-dispatch.test.ts": "adapters", "coding-agent-native-empty-argv.test.ts": "windows",
     "stop-restore-history-ownership.test.ts": "service",
     "cli-stop-refusal-transport.test.ts": "cli",

skills/ocx/references/01_management_surface.md

@@ -28,7 +28,7 @@ These answer in the CLI head and never reach the proxy, so they work with nothin
 | [lifecycle](01_surface_lifecycle.md) | 14 |
 | [providers-models](01_surface_providers-models.md) | 50 |
 | [accounts](01_surface_accounts.md) | 43 |
-| [agents-routing](01_surface_agents-routing.md) | 68 |
+| [agents-routing](01_surface_agents-routing.md) | 71 |
 | [integrations](01_surface_integrations.md) | 41 |
 | [observe-system](01_surface_observe-system.md) | 99 |
 | [access-remote](01_surface_access-remote.md) | 34 |
@@ -1527,8 +1527,20 @@ Original invocation order. These headings preserve links to the previous single-
 
 [State-changing task](01_surface_lab.md#ocx-lab-run)
 
+### `ocx route to`
+
+[State-changing task](01_surface_agents-routing.md#ocx-route-to)
+
+### `ocx route to status`
+
+[Read-oriented task](01_surface_agents-routing.md#ocx-route-to-status)
+
+### `ocx route to sync`
+
+[State-changing task](01_surface_agents-routing.md#ocx-route-to-sync)
+
 ## Counts
 
-- declared capabilities: 370
-- of those, state-changing: 228
+- declared capabilities: 373
+- of those, state-changing: 230
 - head-resolved invocations: 2

skills/ocx/references/01_surface_access-remote.md

@@ -81,6 +81,7 @@ State-changing: yes. JSON mode: `payload`.
 
 | Flag | Value | Meaning |
 |---|---|---|
+| `--clients` | string | Initial device selection; defaults to Codex and Claude Code. Other Home client defaults remain inherited. |
 | `--alias` | string | SSH host alias for the linked machine. |
 | `--tunnel-port` | number | Remote loopback port for the reverse tunnel. |
 | `--json` | boolean | Emit the issue result as JSON. |
@@ -328,7 +329,7 @@ State-changing: yes. JSON mode: `payload`.
 
 ### `ocx disconnect`
 
-Usage: `ocx disconnect [--keep-catalog] [--json] | ocx disconnect --orphaned-token --yes [--json]`
+Usage: `ocx disconnect [--keep-catalog] [--recover-config --yes] [--json] | ocx disconnect --orphaned-token --yes [--json]`
 
 Disconnect a client or preserve orphaned token files for recovery.
 
@@ -339,8 +340,9 @@ Drives no management route.
 | Flag | Value | Meaning |
 |---|---|---|
 | `--keep-catalog` | boolean | Keep the connected client's catalog during ordinary disconnect. |
+| `--recover-config` | boolean | With --yes, snapshot current Codex artifacts and recover only evidenced owned keys; unknown ownership still refuses. |
 | `--orphaned-token` | boolean | Preserve unowned service-token files in a private backup when disconnected. |
-| `--yes` | boolean | Explicitly confirm orphan-token recovery; requires --orphaned-token. |
+| `--yes` | boolean | Explicitly confirm --recover-config or --orphaned-token recovery. |
 | `--json` | boolean | Emit the local result and backup location as JSON. |
 
 - Orphan recovery requires a disconnected durable state, no pending connect or disconnect, no Hub or admission-secret use, no installed or unverified service, and verified absence of a client runtime. It preserves rather than deletes token files and does not establish their ownership.

skills/ocx/references/01_surface_agents-routing.md

@@ -8,7 +8,7 @@
 Use these declarations to choose a task, then check its flags and authority before execution.
 Non-mutating probes may still contact providers, consume quota or refresh caches.
 
-Declared capabilities: 68.
+Declared capabilities: 71.
 
 ### `ocx agent subagents force`
 
@@ -1339,3 +1339,69 @@ State-changing: no. JSON mode: `payload`.
 | `--json` | boolean | Emit the result as JSON. |
 
 - Alias of observe memory.
+
+### `ocx route to`
+
+Usage: `ocx route to <client> <on|off|inherit> [--device <alias|id|this>] [--accounts <all|none|userId,...>] [--model-names <alias|routed>] [--overwrite-conflict] [--local] [--json]`
+
+Set Home-default or per-device route intent, or opt out locally on a Child.
+
+State-changing: yes. JSON mode: `payload`.
+
+| Method | Route |
+|---|---|
+| PUT | `/api/route-to` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--device` | string | Home: alias, id, all or this. Child: this or its own link id only. |
+| `--json` | boolean | Emit the ocx.route-to/1 status matrix. |
+| `--overwrite-conflict` | boolean | Explicitly permit replacing conflicting managed blocks. |
+| `--local` | boolean | Child only: opt out with off, or clear the opt-out with inherit. |
+| `--accounts` | string | Aside on only: all, none, or comma-separated stable userIds; never u/N slots. |
+| `--model-names` | string | Hermes/Command Code on only: alias or routed model names. |
+
+- Clients: codex, claude, claude-desktop, grok and the supported file integrations. Without --device a Home updates its default and materializes itself; all is only for status/sync.
+- inherit requires --device unless clearing a Child --local opt-out. Child writes print the exact Home command with the Child link id; --local supports off/inherit only. --overwrite-conflict applies only to on or sync.
+- On the Home, codex, claude, grok and claude-desktop follow the Home's own native switches: a Home default or --device home write for them writes that switch (Home inherit sets it to the default).
+
+### `ocx route to status`
+
+Usage: `ocx route to status [--device <alias|id|all|this>] [--json]`
+
+Read per-device route intent, its source and actual client apply outcomes.
+
+State-changing: no. JSON mode: `payload`.
+
+| Method | Route |
+|---|---|
+| GET | `/api/route-to` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--device` | string | Home: alias, id, all or this. Child: this or its own link id only. |
+| `--json` | boolean | Emit the ocx.route-to/1 status matrix. |
+
+- On a Child this reads local receipts without a Home management relay. Intent and applied state are distinct; null applied means no recorded outcome.
+- Sources: builtin, default, device, local (Child opt-out) and native (a Home row governed by the Home's own switch). An outcome recorded for an earlier intent reads stale.
+
+### `ocx route to sync`
+
+Usage: `ocx route to sync [--device <alias|id|all|this>] [--overwrite-conflict] [--json]`
+
+Reapply route intent on selected devices, or locally on a Child.
+
+State-changing: yes. JSON mode: `payload`.
+
+| Method | Route |
+|---|---|
+| POST | `/api/route-to/sync` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--device` | string | Home: alias, id, all or this. Child: this or its own link id only. |
+| `--overwrite-conflict` | boolean | Explicitly permit replacing conflicting managed blocks. |
+| `--json` | boolean | Emit the ocx.route-to/1 status matrix. |
+
+- No conflict retry or implicit overwrite. Child sync calls its local materializer and sends no Home management write.
+- Home sync never changes the Home's native switches for codex, claude, grok or claude-desktop; it refreshes what each switch says.