fix(link): verify Child runtime relay and add fingerprint-bound CLI enrollment

docs-site/src/content/docs/fr/guides/remote-link.md

@@ -78,14 +78,21 @@ Child utilise les fournisseurs et les identifiants de fournisseur de l’ordinat
 ## Référence CLI
 
 ```text
+ocx link probe <alias> [--json]
+ocx link add <alias> [--expect-fingerprint SHA256:…] [--json]
 ocx link port [--json]
 ocx link issue --alias <alias> --tunnel-port <port> [--json]
 ocx link status [--json]
 ocx link revoke --link-id <id> [--json]
 ocx link reconnect --link-id <id> [--json]
 ```
 
+Sans terminal interactif (TTY), `--expect-fingerprint` est obligatoire. Dans un terminal interactif, vous pouvez l’omettre si vous confirmez explicitement l’empreinte proposée.
+
 ## Guides associés
 
 - [Déploiement Remote Hub](/fr/guides/remote-hub/)
 - [Remote Workspace](/fr/guides/remote-workspace/)
+
+
+`ocx link probe <alias> --json` · `ocx link add <alias> --expect-fingerprint SHA256:… --json` — [CLI, restart, relay verification and recovery](/guides/remote-link/#add-a-child-from-the-terminal).

docs-site/src/content/docs/guides/remote-link.md

@@ -93,6 +93,8 @@ The Child uses the Home computer's providers and provider credentials through th
 ## CLI reference
 
 ```text
+ocx link probe <alias> [--json]
+ocx link add <alias> [--expect-fingerprint SHA256:…] [--json]
 ocx link port [--json]
 ocx link issue --alias <alias> --tunnel-port <port> [--json]
 ocx link status [--json]
@@ -123,3 +125,13 @@ If a process is interrupted during pairing, rerun the command to obtain a new au
 On Windows, pairing fails closed if the intent folder or record is not private to the serving account, or its owner and permissions cannot be verified. Both entries must be owned by that account; Administrators ownership is accepted only when Administrators is the serving token's default owner and its administrator role is enabled. The permission list must be protected from inheritance and contain an ordinary Full Control allow entry for the serving account. Besides that, only plain allow entries for SYSTEM and the Administrators group are accepted, because SYSTEM and an elevated administrator can already take ownership of any file; a non-elevated administrator gains nothing from that entry. Child inheritance is allowed on the folder only. This is the list as Windows reports it: compatible duplicate entries for the same account count as one, and entries that grant nothing are ignored. The check leaves refused records in place and does not repair their permissions or change ownership. Restore a private configuration home, then run a fresh pairing command.
 
 The check covers the intent folder and record. It does not protect against replacement of ancestor folders, deletion rights on a parent folder, privileged restore operations or access through handles opened before permissions became private. A request with a matching commitment can block the server during a verification subprocess bounded at five seconds, even if its folder later fails the permission check. Executable lookup and process launch setup precede that timeout. CLI cleanup may perform one more verification. The five-second subprocess budget leaves room within the command's ten-second request timeout, but slow verification can still refuse pairing.
+
+## Add a Child from the terminal
+
+On the Home, run `ocx link probe child-a --json` to inspect the offered SSH fingerprint, key type and OpenCodex version. Verify the fingerprint through a trusted source. Then run `ocx link add child-a --expect-fingerprint SHA256:… --json`. The command probes again and refuses a mismatch before storing trust or issuing a key. Without the fingerprint flag, it requires an interactive terminal and an explicit `yes` after showing the fingerprint. It never prints the link key.
+
+Home-initiated connections now restart the Child after saving its connection, including capable older Child installations. The Child must already serve standalone OpenCodex on its configured port, expose bound restart support, and have curl installed. Update or disconnect a Child that fails this preflight. Desktop and system OpenCodex installations take precedence over generic PATH shims; broken candidates are skipped. Windows Children remain unsupported.
+
+Restart waits for running turns and may take several minutes. Success requires the restarted Child to serve the client role and relay a fresh complete catalog to this Home. SSH setup has a bounded allowance derived from measured latency; relay verification starts after restart with its own 15-second window. Errors name the failing phase. If an error reports residual Child configuration, run `ocx disconnect` and `ocx restart` on that Child before retrying. Home cleanup alone does not restore Child configuration. A CLI timeout reports an uncertain outcome; inspect Home `ocx link status` and Child `ocx connect status` first.
+
+On a Home-initiated Child, `ocx link status` reports role `child`, link identity and tunnel port from its saved connection even though its Home-side link store is empty. Locally unobserved tunnel state is `idle`. `ocx status` calls the peer a Remote Link Home. When Home runs in Hub mode, status reads its supported projection through the local Child relay. A standalone Home reports that it does not publish Hub state. Child-initiated tunnel identity comes from its valid sidecar; unreadable evidence does not claim a direction.

docs-site/src/content/docs/ja/guides/remote-link.md

@@ -78,14 +78,21 @@ Child はリンクを通じて Home コンピューターのプロバイダー
 ## CLI リファレンス
 
 ```text
+ocx link probe <alias> [--json]
+ocx link add <alias> [--expect-fingerprint SHA256:…] [--json]
 ocx link port [--json]
 ocx link issue --alias <alias> --tunnel-port <port> [--json]
 ocx link status [--json]
 ocx link revoke --link-id <id> [--json]
 ocx link reconnect --link-id <id> [--json]
 ```
 
+対話型端末（TTY）でない場合、`--expect-fingerprint` は必須です。対話型端末では省略できますが、提示されたフィンガープリントを明示的に承認する必要があります。
+
 ## 関連ガイド
 
 - [Remote Hub のデプロイ](/ja/guides/remote-hub/)
 - [リモートワークスペース](/ja/guides/remote-workspace/)
+
+
+端末では `ocx link probe <alias> --json` で指紋とバージョンを確認し、`ocx link add <alias> --expect-fingerprint SHA256:… --json` で接続できます。指紋を省略すると対話端末で明示的な確認が必要です。Home は Child の再起動サポートと curl を事前確認し、接続後に再起動と実際のリレーを検証します。Child 設定が残った場合は Child で `ocx disconnect` と `ocx restart` を実行してください。[詳細（英語）](/guides/remote-link/#add-a-child-from-the-terminal)。

docs-site/src/content/docs/ko/guides/remote-link.md

@@ -78,13 +78,17 @@ Child는 링크를 통해 Home 컴퓨터의 프로바이더와 프로바이더 
 ## CLI 레퍼런스
 
 ```text
+ocx link probe <alias> [--json]
+ocx link add <alias> [--expect-fingerprint SHA256:…] [--json]
 ocx link port [--json]
 ocx link issue --alias <alias> --tunnel-port <port> [--json]
 ocx link status [--json]
 ocx link revoke --link-id <id> [--json]
 ocx link reconnect --link-id <id> [--json]
 ```
 
+비대화형 실행(TTY 없음)에서는 `--expect-fingerprint`가 필수입니다. 대화형 터미널에서는 옵션을 생략할 수 있지만, 제시된 지문을 명시적으로 확인해야 합니다.
+
 ## 관련 가이드
 
 - [Remote Hub 배포](/ko/guides/remote-hub/)
@@ -102,3 +106,6 @@ CLI는 짧게 유효한 일회용 승인 정보를 만들고, 사용하거나 
 Windows에서는 승인 폴더나 기록이 서버 실행 계정만 사용할 수 있도록 보호되지 않았거나, 소유자와 권한을 확인할 수 없으면 페어링을 거부합니다. 두 항목 모두 해당 계정이 소유해야 합니다. Administrators 그룹 소유는 이 그룹이 서버 실행 토큰의 기본 소유자이고 관리자 역할도 활성화된 경우에만 허용합니다. 권한 목록은 상위 항목의 권한을 상속하지 않도록 보호되어야 하며, 서버 실행 계정에 대한 일반적인 모든 권한 허용 항목을 포함해야 합니다. 그 밖에는 SYSTEM과 Administrators 그룹의 일반 허용 항목만 허용합니다. SYSTEM과 권한이 상승된 관리자는 이미 모든 파일의 소유권을 가져올 수 있고, 권한이 상승되지 않은 관리자는 이 항목으로 아무 권한도 얻지 못하기 때문입니다. 하위 항목으로의 상속은 폴더에만 허용합니다. 이 기준은 Windows가 보고하는 권한 목록에 적용되며, 같은 계정의 호환되는 중복 항목은 하나로 보고 아무 권한도 주지 않는 항목은 무시합니다. 거부된 기록은 그대로 두며 권한이나 소유자를 자동으로 수정하지 않습니다. 설정 폴더를 개인 전용으로 보호한 뒤 새 페어링 명령을 실행하세요.
 
 이 검사는 승인 폴더와 기록에만 적용됩니다. 상위 폴더의 교체, 부모 폴더의 삭제 권한, 특권을 사용하는 복원 작업, 권한을 보호하기 전에 열린 핸들을 통한 접근까지 막지는 않습니다. 승인 정보가 일치하는 요청은 이후 폴더 권한 검사에서 거부되더라도 최대 5초로 제한된 검증 프로세스가 실행되는 동안 서버 처리를 막을 수 있습니다. 실행 파일 조회와 프로세스 시작 준비는 이 제한 시간이 시작되기 전에 이루어집니다. CLI 정리 과정에서 검증을 한 번 더 수행할 수도 있습니다. 검증 프로세스의 5초 제한은 명령의 10초 요청 제한 시간 안에 여유를 두지만, 검증이 느리면 페어링이 거부될 수 있습니다.
+
+
+터미널에서도 `ocx link probe <alias> --json`으로 지문과 버전을 확인하고 `ocx link add <alias> --expect-fingerprint SHA256:… --json`으로 연결할 수 있습니다. 지문 옵션이 없으면 대화형 터미널에서 명시적으로 확인해야 합니다. Home은 Child의 재시작 지원과 curl을 먼저 확인한 뒤 연결하고 재시작하여 실제 릴레이를 검증합니다. 실패 후 Child 설정이 남았다는 안내가 나오면 Child에서 `ocx disconnect`와 `ocx restart`를 실행하세요. 자세한 조건은 [영문 안내](/guides/remote-link/#add-a-child-from-the-terminal)를 참조하세요.

docs-site/src/content/docs/ru/guides/remote-link.md

@@ -78,14 +78,21 @@ Child использует через связь провайдеров и уч
 ## Справочник CLI
 
 ```text
+ocx link probe <alias> [--json]
+ocx link add <alias> [--expect-fingerprint SHA256:…] [--json]
 ocx link port [--json]
 ocx link issue --alias <alias> --tunnel-port <port> [--json]
 ocx link status [--json]
 ocx link revoke --link-id <id> [--json]
 ocx link reconnect --link-id <id> [--json]
 ```
 
+Без интерактивного терминала (TTY) параметр `--expect-fingerprint` обязателен. В интерактивном терминале его можно опустить, если явно подтвердить предложенный отпечаток.
+
 ## Связанные руководства
 
 - [Развёртывание Remote Hub](/ru/guides/remote-hub/)
 - [Удалённое рабочее пространство](/ru/guides/remote-workspace/)
+
+
+`ocx link probe <alias> --json` · `ocx link add <alias> --expect-fingerprint SHA256:… --json` — [CLI, restart, relay verification and recovery](/guides/remote-link/#add-a-child-from-the-terminal).

docs-site/src/content/docs/tr/guides/remote-link.md

@@ -78,14 +78,21 @@ Child, bağlantı üzerinden Home bilgisayarının sağlayıcılarını ve sağl
 ## CLI başvurusu
 
 ```text
+ocx link probe <alias> [--json]
+ocx link add <alias> [--expect-fingerprint SHA256:…] [--json]
 ocx link port [--json]
 ocx link issue --alias <alias> --tunnel-port <port> [--json]
 ocx link status [--json]
 ocx link revoke --link-id <id> [--json]
 ocx link reconnect --link-id <id> [--json]
 ```
 
+TTY olmayan kullanımda `--expect-fingerprint` zorunludur. Etkileşimli bir terminalde sunulan parmak izini açıkça onaylayarak bu seçeneği atlayabilirsiniz.
+
 ## İlgili kılavuzlar
 
 - [Remote Hub Dağıtımı](/tr/guides/remote-hub/)
 - [Uzak Çalışma Alanı](/tr/guides/remote-workspace/)
+
+
+`ocx link probe <alias> --json` · `ocx link add <alias> --expect-fingerprint SHA256:… --json` — [CLI, restart, relay verification and recovery](/guides/remote-link/#add-a-child-from-the-terminal).

docs-site/src/content/docs/zh-cn/guides/remote-link.md

@@ -78,14 +78,21 @@ ocx disconnect
 ## CLI 参考
 
 ```text
+ocx link probe <alias> [--json]
+ocx link add <alias> [--expect-fingerprint SHA256:…] [--json]
 ocx link port [--json]
 ocx link issue --alias <alias> --tunnel-port <port> [--json]
 ocx link status [--json]
 ocx link revoke --link-id <id> [--json]
 ocx link reconnect --link-id <id> [--json]
 ```
 
+非交互式终端（非 TTY）必须提供 `--expect-fingerprint`。交互式终端中可省略该参数，但必须明确确认所提供的指纹。
+
 ## 相关指南
 
 - [Remote Hub 部署](/zh-cn/guides/remote-hub/)
 - [远程工作区](/zh-cn/guides/remote-workspace/)
+
+
+`ocx link probe <alias> --json` · `ocx link add <alias> --expect-fingerprint SHA256:… --json` — [CLI, restart, relay verification and recovery](/guides/remote-link/#add-a-child-from-the-terminal).

docs-site/src/content/docs/zh-tw/guides/remote-link.md

@@ -78,14 +78,21 @@ Child 會透過連結使用 Home 電腦上的供應商與供應商憑證。Home
 ## CLI 參考
 
 ```text
+ocx link probe <alias> [--json]
+ocx link add <alias> [--expect-fingerprint SHA256:…] [--json]
 ocx link port [--json]
 ocx link issue --alias <alias> --tunnel-port <port> [--json]
 ocx link status [--json]
 ocx link revoke --link-id <id> [--json]
 ocx link reconnect --link-id <id> [--json]
 ```
 
+非互動式終端（非 TTY）必須提供 `--expect-fingerprint`。互動式終端中可省略此參數，但必須明確確認提供的指紋。
+
 ## 相關指南
 
 - [Remote Hub 部署](/zh-tw/guides/remote-hub/)
 - [遠端工作區](/zh-tw/guides/remote-workspace/)
+
+
+`ocx link probe <alias> --json` · `ocx link add <alias> --expect-fingerprint SHA256:… --json` — [CLI, restart, relay verification and recovery](/guides/remote-link/#add-a-child-from-the-terminal).

gui/tests/remote-link.test.tsx

@@ -51,10 +51,15 @@ async function mount(props: Partial<React.ComponentProps<typeof RemoteLink>> = {
   return host;
 }
 
-test("LINK_ERROR_CODES stays in exact parity with link-routes.ts", async () => {
-  const source = await Bun.file("../src/server/management/link-routes.ts").text();
-  const fromRoutes = [...source.matchAll(/fail\("([a-z_]+)"/g)].map(match => match[1]).filter((value, index, all) => all.indexOf(value) === index).sort();
-  expect([...LINK_ERROR_CODES].sort()).toEqual(fromRoutes);
+test("current translated link errors remain implemented across route and enrollment owners", async () => {
+  const source = (await Promise.all(["link-routes", "link-enrollment", "link-route-state"].map(name =>
+    Bun.file(`../src/server/management/${name}.ts`).text()))).join("\n");
+  const fromRoutes = [...source.matchAll(/(?:fail\(|remoteFailure\([^,\n]+,\s*)"([a-z_]+)"/g)].map(match => match[1]).filter((value, index, all) => all.indexOf(value) === index).sort();
+  // New phase errors use generic text. These two old-server translations remain compatible
+  // although enrollment now reports child_relay_timeout and phase-specific failures instead.
+  const legacyOnly = new Set(["admission_timeout", "link_apply_failed"]);
+  expect(fromRoutes.filter(code => (LINK_ERROR_CODES as readonly string[]).includes(code))).toEqual(
+    LINK_ERROR_CODES.filter(code => !legacyOnly.has(code)).sort());
 });
 
 test("parses every wire state without changing the DTO", () => {

scripts/test-layout/layout.json

@@ -754,7 +754,7 @@
     "gui-desktop-sidecar-signing.test.ts": "gui",
     "linux-desktop-packaged-ci.test.ts": "ci-workflows",
     "link-boundary.test.ts": "clients",
-    "link-ssh-argv.test.ts": "clients",
+    "link-ssh-argv.test.ts": "clients", "link-ssh-runner.test.ts": "clients", "link-ssh-argv-discovery.test.ts": "clients",
     "link-ssh-config.test.ts": "clients",
     "link-store.test.ts": "clients",
     "link-tunnel-state.test.ts": "clients",
@@ -1986,8 +1986,8 @@
     "link-status-projection.test.ts": "clients",
     "link-admission-wait.test.ts": "clients",
     "link-fingerprint.test.ts": "clients",
-    "cli-link.test.ts": "cli",
-    "link-management-routes.test.ts": "server",
+    "cli-link.test.ts": "cli", "cli-link-enrollment.test.ts": "cli",
+    "link-management-routes.test.ts": "server", "link-enrollment.test.ts": "server",
     "link-compensation.test.ts": "clients",
     "web-search-run-turn-loop.test.ts": "web-search",
     "responses-run-turn-web-search.test.ts": "responses",

skills/ocx/references/01_management_surface.md

@@ -31,7 +31,7 @@ These answer in the CLI head and never reach the proxy, so they work with nothin
 | [agents-routing](01_surface_agents-routing.md) | 50 |
 | [integrations](01_surface_integrations.md) | 41 |
 | [observe-system](01_surface_observe-system.md) | 92 |
-| [access-remote](01_surface_access-remote.md) | 30 |
+| [access-remote](01_surface_access-remote.md) | 32 |
 | [lab](01_surface_lab.md) | 21 |
 
 ## Read-only capabilities
@@ -51,6 +51,14 @@ Original invocation order. These headings preserve links to the previous single-
 
 [State-changing task](01_surface_lifecycle.md#ocx-chatgpt)
 
+### `ocx link probe`
+
+[State-changing task](01_surface_access-remote.md#ocx-link-probe)
+
+### `ocx link add`
+
+[State-changing task](01_surface_access-remote.md#ocx-link-add)
+
 ### `ocx link port`
 
 [Read-oriented task](01_surface_access-remote.md#ocx-link-port)
@@ -1381,6 +1389,6 @@ Original invocation order. These headings preserve links to the previous single-
 
 ## Counts
 
-- declared capabilities: 333
-- of those, state-changing: 202
+- declared capabilities: 335
+- of those, state-changing: 204
 - head-resolved invocations: 2

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

@@ -8,7 +8,51 @@
 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: 30.
+Declared capabilities: 32.
+
+### `ocx link probe`
+
+Usage: `ocx link probe <alias> [--json]`
+
+Probe an SSH host fingerprint and OpenCodex version without trusting it.
+
+State-changing: yes.
+
+| Method | Route |
+|---|---|
+| POST | `/api/link/probe` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--json` | boolean | Emit alias, fingerprint, key type and version as JSON. |
+
+JSON mode: `payload`.
+
+- Requires loopback admin authority on the Home. Stores only a temporary pending offer; does not persist host trust or issue a link key.
+
+### `ocx link add`
+
+Usage: `ocx link add <alias> [--expect-fingerprint SHA256:…] [--json]`
+
+Connect an SSH Child to this Home after confirming its fingerprint.
+
+State-changing: yes.
+
+| Method | Route |
+|---|---|
+| POST | `/api/link/probe` |
+| POST | `/api/link/confirm-host` |
+| POST | `/api/link/apply` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--expect-fingerprint` | string | Exact SHA256 host fingerprint; required without an interactive TTY. |
+| `--json` | boolean | Emit the verified link result as JSON. |
+
+JSON mode: `payload`.
+
+- Requires loopback admin authority on the Home. Without a fingerprint, requires a TTY and explicit yes after showing the offered fingerprint. Never prints the link key.
+- Preflights bound Child restart support and curl, connects, restarts once and verifies a fresh authenticated catalog relay before success. Post-connect failures can leave Child config; run ocx disconnect and ocx restart there before retrying.
 
 ### `ocx link port`