From cffdbb6a1b767fa39e2651f782ffaa0324ec9d07 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Sat, 7 Nov 2026 14:53:55 +0000 Subject: [PATCH] chore: sync OCX skill from upstream --- skills/ocx/.upstream-revision | 2 +- .../ocx/references/01_management_surface.md | 16 +++++++++--- .../references/01_surface_access-remote.md | 22 +++++++++++++++- skills/ocx/references/01_surface_lifecycle.md | 10 ++++++-- .../references/01_surface_observe-system.md | 25 +++++++++++++++++-- .../references/01_surface_providers-models.md | 6 ++--- skills/ocx/references/04_failure_semantics.md | 2 ++ skills/ocx/references/05_remote_hub.md | 16 ++++++++++++ 8 files changed, 86 insertions(+), 13 deletions(-) diff --git a/skills/ocx/.upstream-revision b/skills/ocx/.upstream-revision index 47cef04..86a5819 100644 --- a/skills/ocx/.upstream-revision +++ b/skills/ocx/.upstream-revision @@ -1 +1 @@ -684ad75d254ae96a9971387d09ae428b96ada9c2 +36aa9e8f7933807dc2c873bb93051c7c9c00f4e6 diff --git a/skills/ocx/references/01_management_surface.md b/skills/ocx/references/01_management_surface.md index 45326e7..148dd2e 100644 --- a/skills/ocx/references/01_management_surface.md +++ b/skills/ocx/references/01_management_surface.md @@ -30,8 +30,8 @@ These answer in the CLI head and never reach the proxy, so they work with nothin | [accounts](01_surface_accounts.md) | 42 | | [agents-routing](01_surface_agents-routing.md) | 68 | | [integrations](01_surface_integrations.md) | 41 | -| [observe-system](01_surface_observe-system.md) | 98 | -| [access-remote](01_surface_access-remote.md) | 33 | +| [observe-system](01_surface_observe-system.md) | 99 | +| [access-remote](01_surface_access-remote.md) | 34 | | [lab](01_surface_lab.md) | 21 | ## Read-only capabilities @@ -127,6 +127,10 @@ Original invocation order. These headings preserve links to the previous single- [State-changing task](01_surface_access-remote.md#ocx-connect-rotate) +### `ocx update` + +[State-changing task](01_surface_observe-system.md#ocx-update) + ### `ocx capabilities` [Read-oriented task](01_surface_lifecycle.md#ocx-capabilities) @@ -1363,6 +1367,10 @@ Original invocation order. These headings preserve links to the previous single- [Read-oriented task](01_surface_observe-system.md#ocx-companion-timeline) +### `ocx disconnect` + +[State-changing task](01_surface_access-remote.md#ocx-disconnect) + ### `ocx hub disable` [State-changing task](01_surface_access-remote.md#ocx-hub-disable) @@ -1517,6 +1525,6 @@ Original invocation order. These headings preserve links to the previous single- ## Counts -- declared capabilities: 367 -- of those, state-changing: 225 +- declared capabilities: 369 +- of those, state-changing: 227 - head-resolved invocations: 2 diff --git a/skills/ocx/references/01_surface_access-remote.md b/skills/ocx/references/01_surface_access-remote.md index 64a16ac..3a9df27 100644 --- a/skills/ocx/references/01_surface_access-remote.md +++ b/skills/ocx/references/01_surface_access-remote.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: 33. +Declared capabilities: 34. ### `ocx link probe` @@ -326,6 +326,26 @@ State-changing: yes. JSON mode: `payload`. - A bare invocation reads and never writes. - A setting flag changes the operator's config; run it only when the operator asks for that change. +### `ocx disconnect` + +Usage: `ocx disconnect [--keep-catalog] [--json] | ocx disconnect --orphaned-token --yes [--json]` + +Disconnect a client or preserve orphaned token files for recovery. + +State-changing: yes. JSON mode: `payload`. + +Drives no management route. + +| Flag | Value | Meaning | +|---|---|---| +| `--keep-catalog` | boolean | Keep the connected client's catalog during ordinary disconnect. | +| `--orphaned-token` | boolean | Preserve unowned service-token files in a private backup when disconnected. | +| `--yes` | boolean | Explicitly confirm orphan-token recovery; requires --orphaned-token. | +| `--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. +- If refused, inspect the bind, API keys, token environment and service status; manage a Hub secret through its service. Stop OpenCodex and move saved files back only when their original names are absent. Never print their contents. + ### `ocx hub disable` Usage: `ocx hub disable [--revoke-clients --client-key ...] [--json]` diff --git a/skills/ocx/references/01_surface_lifecycle.md b/skills/ocx/references/01_surface_lifecycle.md index 5ea0ee4..ce7372e 100644 --- a/skills/ocx/references/01_surface_lifecycle.md +++ b/skills/ocx/references/01_surface_lifecycle.md @@ -77,6 +77,7 @@ Drives no management route. | Flag | Value | Meaning | |---|---|---| | `--json` | boolean | Emit the full capability table as JSON. | +| `--contracts` | boolean | List supported versioned contracts. | | `--mutating-only` | boolean | Restrict output to capabilities that mutate state. | | `--route` | string | Show which capabilities drive a management route. | @@ -84,11 +85,11 @@ Drives no management route. ### `ocx sync` -Usage: `ocx sync [--expect-link | --expect-hub-key ] [--restart-codex] [--restart-app-server-only]` +Usage: `ocx sync [--expect-link | --expect-hub-key ] [--local-only] [--json] [--restart-codex] [--restart-app-server-only]` Synchronize client catalogs, including Aside profiles through the running server's mutation owner. -State-changing: yes. JSON mode: `none`. +State-changing: yes. JSON mode: `payload`. | Method | Route | |---|---| @@ -96,6 +97,8 @@ State-changing: yes. JSON mode: `none`. | Flag | Value | Meaning | |---|---|---| +| `--local-only` | boolean | Do not fan out the Home sync to linked Children. | +| `--json` | boolean | Emit the sync fan-out result as JSON. | | `--restart-codex` | boolean | Restart the Codex app-servers and fully quit and relaunch the Codex desktop app after a catalog, cache, or changed configuration write, on macOS, Linux and Windows. | | `--restart-app-server-only` | boolean | Restart only the Codex app-servers and leave the desktop app running; wins over --restart-codex when both are given. | | `--restart-desktop-app` | boolean | Deprecated alias of --restart-codex. | @@ -103,6 +106,9 @@ State-changing: yes. JSON mode: `none`. | `--expect-hub-key` | string | Sync only when this machine is a hub client connected with this API key id; otherwise exit 5 with nothing changed. | - The Aside refresh uses the live server; other catalog synchronization also performs local work. +- An update in flight or an unavailable update/sync mutex refuses without changes: update-in-flight, exit 7. Another sync reports sync-in-progress, exit 1. +- A current Home catalog fans out to linked Children. Fan-out never requests a Codex app or app-server restart on a Child; use GOAT or ocx sync --restart-codex there. Applying changed Home settings may restart the Child's own OpenCodex client runtime. +- After a successful Home sync, a connected Child skipped during fan-out, a failed or timed-out Child, or an unreadable link store yields partial exit 6. Skipped connected Children include an actionable hint; update an outdated ocx through its owning installer, with the Desktop tray as an option for Desktop installs. Intentional skips, including client-initiated links and --local-only, keep their existing exit behavior. - --expect-link/--expect-hub-key are checked under the lock that selects the sync path. A mismatch writes nothing, never falls back to local providers, exits 5, and ends stderr with {"phase":"child_link_mismatch"|"hub_client_mismatch","reason":...}; reasons are disconnected, invalid_state, disconnect_pending, pending_operation, hub_client, link_client, other_link and other_key. Usage errors exit 2. ### `ocx stop` diff --git a/skills/ocx/references/01_surface_observe-system.md b/skills/ocx/references/01_surface_observe-system.md index d3cea04..363e5d2 100644 --- a/skills/ocx/references/01_surface_observe-system.md +++ b/skills/ocx/references/01_surface_observe-system.md @@ -8,7 +8,27 @@ 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: 98. +Declared capabilities: 99. + +### `ocx update` + +Plan or apply an OpenCodex update. + +State-changing: yes. JSON mode: `envelope`. + +Drives no management route. + +| Flag | Value | Meaning | +|---|---|---| +| `--plan` | boolean | Preview an orchestrated update with --json. | +| `--yes` | boolean | Apply an orchestrated update with --json. | +| `--json` | boolean | Emit a versioned plan or result. | +| `--tag` | string | Select latest or preview for the legacy update or plan. | +| `--version` | string | Select an exact version for a plan or apply. | +| `--expect-plan` | string | Require the apply plan to match this planToken. | +| `--not-after` | string | Refuse mutation after this Unix millisecond deadline. | + +- Orchestrated exit codes: 0 verified or up-to-date; 10 refused; 11 previous version verified; 12 uncertain; 64 usage. ### `ocx companion` @@ -417,7 +437,8 @@ Drives no management route. | `--request-id` | string | Optional stable retry key. | | `--json` | boolean | Emit the public job status. | -- Local counterpart of POST /api/codex/cli-update/apply: invokes the same durable job owner with --yes confirmation; HTTP admission separately requires a trusted loopback GUI session. +- Local counterpart of POST /api/codex/cli-update/apply: invokes the same durable job owner with --yes confirmation; HTTP admission separately requires a current paired dashboard session on trusted loopback ingress, matching origin, CSRF and confirmed: true. +- Standalone HTTP pairing requires the configured literal 127.0.0.1 or ::1 origin; localhost aliases, wildcard binds and connected-client roles use the local CLI --yes path instead. - Admission is stored under the protected current-user config root before the installer can run. - Exit 0 requires an applied job; refused, not_applied, ambiguous and pending duplicate jobs exit 1, including with --json. - Only POSIX npm-global managed installs are currently supported; Windows, shims and other managers remain refused. diff --git a/skills/ocx/references/01_surface_providers-models.md b/skills/ocx/references/01_surface_providers-models.md index 5f9804e..75571fe 100644 --- a/skills/ocx/references/01_surface_providers-models.md +++ b/skills/ocx/references/01_surface_providers-models.md @@ -385,7 +385,7 @@ Drives no management route. Usage: `ocx models list [--provider ] [--json]` -List static configured models locally. +List local configured and router-known models. State-changing: no. JSON mode: `envelope`. @@ -394,9 +394,9 @@ Drives no management route. | Flag | Value | Meaning | |---|---|---| | `--provider` | string | Limit to a configured provider. | -| `--json` | boolean | Emit models and the static-catalog note. | +| `--json` | boolean | Emit models and the local-catalog note. | -- A bare models invocation is equivalent. Reads local config, never the live catalog; use models live for runtime discovery. +- A bare models invocation is equivalent. Includes saved IDs, registry seeds, custom models and this process's discovery cache; use models live for the running catalog. ### `ocx models add` diff --git a/skills/ocx/references/04_failure_semantics.md b/skills/ocx/references/04_failure_semantics.md index 642b83e..66a3ad3 100644 --- a/skills/ocx/references/04_failure_semantics.md +++ b/skills/ocx/references/04_failure_semantics.md @@ -14,6 +14,8 @@ exit contract. Its common mappings and the main exceptions are: | 64 | usage validation in `capabilities`, `ready`, `resolve` | fix arguments; no discovery/request for invalid input | | 4 | HTTP 404 — the named account, provider, key, or route does not exist | no | | 5 | HTTP 409 — conflict; a lock is held or state moved under you | inspect first; stale baselines require review | +| 6 | `ocx sync` completed the Home step but a Child failed or timed out, or the link store was unreadable | inspect the fan-out result | +| 7 | reserved for an update in flight during sync | wait for the update, then retry | | 1 | everything else: transport failure, 5xx, unexpected errors | depends on `reason` | Two consequences worth internalizing: diff --git a/skills/ocx/references/05_remote_hub.md b/skills/ocx/references/05_remote_hub.md index 14e89f9..153136d 100644 --- a/skills/ocx/references/05_remote_hub.md +++ b/skills/ocx/references/05_remote_hub.md @@ -321,6 +321,12 @@ To sync only while that reading still holds, pass what you read back to sync: relinked in between, the sync changes nothing and exits 5 with a JSON `phase` line on stderr ([04_failure_semantics.md](04_failure_semantics.md#a-pinned-sync-that-refuses-exit-5)). +On the Home, `ocx sync` fans out only after it commits a current catalog. Use `--local-only` +to suppress propagation and `--json` to inspect Home and Child results. Fan-out never asks a Child +to restart a Codex app or app-server; use GOAT or `ocx sync --restart-codex` on that Child. Its +pinned sync can still restart its own OpenCodex client runtime after applying changed Home settings. +A Child sync already running can continue after the Home times out its local SSH process. + ## Key rotation is a two-step commit Starting a rotation issues the new key while **the old key stays valid**. The dashboard @@ -364,6 +370,16 @@ It ends a browser session; it does not disconnect a client or revoke a key. ### When `disconnect` refuses, that is the safety property +When the operator has explicitly authorized recovery of a disconnected installation with a +leftover token, `ocx disconnect --orphaned-token --yes` preserves the service-token files in a +private backup. It refuses pending or connected client state, a Hub, admission-token use, +installed or unverified service definitions, and live or unverified client runtimes. Inspect the +bind, API keys, token environment and `ocx service status`; manage a Hub credential through the +Hub service. It does not prove the tokens belonged to a link or restore lost connection settings. +Report the printed backup location; to restore, stop OpenCodex and move the saved files back only +if their original names are absent. Never read or print their contents. Do not add `--yes` without +the operator's explicit authorization. + Do not work around these. Each one means unwinding would damage state that `disconnect` cannot prove is safe to touch.