feat(link): sync route intent and materialize clients per device (re-land #8276)

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

@@ -32,6 +32,8 @@ La página **Conectar** escribe el bloque de proveedor de opencodex en el archiv
 | Factory Droid | `~/.factory/settings.json` ( `%USERPROFILE%\.factory\settings.json` en Windows) | JSON | inmediatamente a través de la observación de archivos | ninguno: bucle local sin clave |
 | T3 Code | `$T3CODE_HOME/userdata/settings.json` (por defecto `~/.t3/userdata/settings.json`) | JSON | inmediatamente — T3 Code observa el archivo | marcador loopback no secreto |
 
+Desde la CLI, `ocx integration client enable|disable --client <id>` cambia solo esta máquina, igual que el interruptor del panel. En un Home de Remote Link que usa la intención de ruta, el cambio se registra como decisión propia del Home, de modo que `ocx sync` la conserva y los Children enlazados mantienen sus valores predeterminados. Para cambiar lo que heredan los Children, usa `ocx route to <client> on|off`. En un Child de Remote Link, un interruptor simple se rechaza e imprime el comando del Home para ese dispositivo; usa allí `ocx route to <client> off --local` para excluir ese Child. Consulta [Remote Link](/es/guides/remote-link/#route-clients-per-device).
+
 <a id="gentle-shell"></a>
 
 ## Gentle Shell

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-clients.json

@@ -76,6 +76,7 @@
   "link-ssh-argv-discovery.test.ts": "clients",
   "link-ssh-config.test.ts": "clients",
   "link-store.test.ts": "clients",
+  "link-retirement.test.ts": "clients",
   "link-tunnel-state.test.ts": "clients",
   "link-routes-store.test.ts": "clients",
   "link-routes-argv.test.ts": "clients",

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

@@ -0,0 +1,65 @@
+{
+  "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-capabilities.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",
+  "service-scheduler-restart-respawn-refusal.test.ts": "service",
+  "client-restart-sync-fence.test.ts": "clients",
+  "route-intent-connect-post-commit.test.ts": "clients",
+  "route-to-home-sync-review.test.ts": "routing"
+}

scripts/test-layout/layout.json

@@ -1,8 +1,8 @@
 {
   "version": 1,
   "root": "tests",
-  "explicitShards": ["layout-file-identity.json", "layout-clients.json", "layout-codex-collision.json", "layout-native-profiles.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", "layout-docs-guides.json", "layout-docs.json", "layout-claude-keychain.json"],
-  "explicit": { "cli-message-mcp-resume.test.ts": "cli", "messaging-mcp-resume.test.ts": "codex-integration", "pr-gates-workflow.test.ts": "ci-workflows", "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",
+  "explicitShards": ["layout-route-intent.json", "layout-file-identity.json", "layout-clients.json", "layout-codex-collision.json", "layout-native-profiles.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", "layout-docs-guides.json", "layout-docs.json", "layout-claude-keychain.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", "cli-message-mcp-resume.test.ts": "cli", "messaging-mcp-resume.test.ts": "codex-integration", "pr-gates-workflow.test.ts": "ci-workflows",
     "stop-restore-history-ownership.test.ts": "service",
     "cli-stop-refusal-transport.test.ts": "cli",
     "service-proxy-env.test.ts": "service", "openai-chat-standalone-bare-block.test.ts": "adapters/openai",

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) | 53 |
 | [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) | 105 |
 | [access-remote](01_surface_access-remote.md) | 51 |
@@ -1631,8 +1631,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: 396
-- of those, state-changing: 248
+- declared capabilities: 399
+- of those, state-changing: 250
 - head-resolved invocations: 2

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

@@ -91,6 +91,7 @@ State-changing: yes. JSON mode: `payload`.
 
 | Flag | Value | Meaning |
 |---|---|---|
+| `--clients` | string | Initial device selection: listed clients start on for this device, and Codex and Claude Code start off unless listed; other clients inherit Home defaults. Omitted, the device inherits every Home default, including an off Codex or Claude Code. |
 | `--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. |
@@ -386,7 +387,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.
 
@@ -397,8 +398,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.