@bitkyc08/opencodex 2.89.0 → 2.91.0

package/src/claude/desktop-3p.ts

@@ -6,7 +6,7 @@ import { canonicalDirectory } from "./desktop-remote-store-io";
 import {
   resolveDesktop3pConfigLibraryPath, parseMetadata, SAFE_DESKTOP_PROFILE_ID, isRecord,
   isOwnedDesktopEntry, isOwnedDesktopGatewayEntry, profilePath, readDesktopProfileSnapshot, readDesktopLibraryText, readDesktopLibraryBytes,
-  readOptionalDesktopLibraryBytes,
+  readOptionalDesktopLibraryBytes, assertDesktopLibraryTextSize, serializeDesktopLibraryJson,
   type Desktop3pConfigLibraryOptions, type Desktop3pMetadata, type Desktop3pMetadataEntry,
 } from "./desktop-3p-library";
 export { resolveDesktop3pConfigLibraryPath, type Desktop3pConfigLibraryOptions } from "./desktop-3p-library";
@@ -642,13 +642,24 @@ function removeDesktop3pStandardPivotLocal(
     if (targetIds.length === 0) return { ok: true, changed: false, kind: "noop", libraryPath: inspected.libraryPath };
 
     let metadataAfterPivot = metadata;
+    let standardPath: string | undefined;
+    let pivotMetadataJson: string | undefined;
     if (selectedOwnedGatewayActive) {
       const standardId = randomUUID();
-      const standardPath = profilePath(inspected.libraryPath, standardId);
-      atomicWriteFile(standardPath, "{}\n");
+      standardPath = profilePath(inspected.libraryPath, standardId);
       const standardEntry: Desktop3pMetadataEntry = { id: standardId, name: "opencodex-standard" };
       metadataAfterPivot = { ...metadata, appliedId: standardId, entries: [...metadata.entries, standardEntry] };
-      atomicWriteFile(metadataPath, JSON.stringify(metadataAfterPivot, null, 2) + "\n");
+      pivotMetadataJson = serializeDesktopLibraryJson(metadataAfterPivot);
+    }
+    // Bound the final metadata before any unlink so a size refusal cannot strand
+    // a row pointing at an already-deleted profile.
+    const removalMetadataJson = serializeDesktopLibraryJson({
+      ...metadataAfterPivot,
+      entries: metadataAfterPivot.entries.filter(entry => !targetIds.includes(entry.id)),
+    });
+    if (standardPath !== undefined && pivotMetadataJson !== undefined) {
+      atomicWriteFile(standardPath, "{}\n");
+      atomicWriteFile(metadataPath, pivotMetadataJson);
     }
 
     const residualPaths: string[] = [];
@@ -674,10 +685,7 @@ function removeDesktop3pStandardPivotLocal(
     }
     // Do not leave a metadata row pointing at a deleted profile. For a foreign
     // selection this only removes proven opencodex residues; appliedId is kept.
-    atomicWriteFile(
-      metadataPath,
-      JSON.stringify({ ...metadataAfterPivot, entries: metadataAfterPivot.entries.filter(entry => !targetIds.includes(entry.id)) }, null, 2) + "\n",
-    );
+    atomicWriteFile(metadataPath, removalMetadataJson);
     return { ok: true, changed: true, kind: "removed", libraryPath: inspected.libraryPath };
   } catch (error) {
     return { ok: false, changed: false, kind: "write_failed", libraryPath: inspected.libraryPath, reason: desktopMutationFailureReason(error) };
@@ -831,7 +839,7 @@ function writeDesktop3pConfigWithGenerator(
 
     const generated = generate();
     const previous = readDesktopProfileSnapshot(configPath);
-    const configJson = JSON.stringify({ ...previous.foreign, ...generated }, null, 2) + "\n";
+    const configJson = serializeDesktopLibraryJson({ ...previous.foreign, ...generated });
     const fingerprint = createHash("sha256").update(configJson).digest("hex").slice(0, 16);
     if (refreshOnly) {
       atomicWriteFileNoFollow(configPath, configJson, undefined, {
@@ -849,9 +857,10 @@ function writeDesktop3pConfigWithGenerator(
       });
       return { written: true, path: configPath, fingerprint };
     }
+    const metadataJson = serializeDesktopLibraryJson({ ...metadata, appliedId: id, entries });
     atomicReplaceDesktopConfig(configPath, configJson, previous.bytes);
     try {
-      atomicWriteFile(metadataPath, JSON.stringify({ ...metadata, appliedId: id, entries }, null, 2) + "\n");
+      atomicWriteFile(metadataPath, metadataJson);
     } catch (metaError) {
       // Roll back from the verified bytes in memory: reopening the backup could meet a swapped
       // entry and leave the new profile beside the old metadata. A profile this call created is
@@ -895,6 +904,7 @@ export function atomicReplaceDesktopConfig(
   previous: Buffer | undefined,
   writer: typeof atomicWriteFileNoFollow = atomicWriteFileNoFollow,
 ): { backupPath?: string } {
+  assertDesktopLibraryTextSize(content);
   const validateBeforeRename = () => assertDesktopProfileUnchanged(path, previous);
   validateBeforeRename();
   const backupPath = `${path}.bak`;

package/src/claude/desktop-picker-profile.ts

@@ -19,6 +19,7 @@ import {
   readDesktopLibraryText,
   resolveDesktop3pConfigLibraryPath,
   SAFE_DESKTOP_PROFILE_ID,
+  serializeDesktopLibraryJson,
   type Desktop3pConfigLibraryOptions,
   type Desktop3pMetadata,
   type Desktop3pMetadataEntry,
@@ -48,7 +49,7 @@ function metadataPath(libraryPath: string): string {
 }
 
 function metadataJson(metadata: Desktop3pMetadata): string {
-  return JSON.stringify(metadata, null, 2) + "\n";
+  return serializeDesktopLibraryJson(metadata);
 }
 
 function isValidMetadata(metadata: Desktop3pMetadata): boolean {
@@ -190,6 +191,10 @@ function applyDesktopPickerProfileLocked(options: { proxyPort: number } & Deskto
     const changed = !alreadySelected || !oldProfile.exists || oldProfile.content !== target;
     if (!changed) return { ok: true, changed: false, path: profile };
 
+    const entries = existing
+      ? metadata.entries.map(entry => entry.id === entryId ? { ...entry, name: DESKTOP_PICKER_ENTRY_NAME } : entry)
+      : [...metadata.entries, { id: entryId, name: DESKTOP_PICKER_ENTRY_NAME }];
+    const nextMetadataJson = metadataJson({ ...metadata, appliedId: entryId, entries });
     mkdirSync(join(configDir, PICKER_DIRECTORY), { recursive: true, mode: 0o700 });
     try {
       // Keep the same backup convention as the existing Desktop writer. It is removed with the
@@ -199,10 +204,7 @@ function applyDesktopPickerProfileLocked(options: { proxyPort: number } & Deskto
       if (!alreadySelected) {
         atomicWriteFile(previousStatePath, JSON.stringify({ entryId, previousAppliedId }) + "\n");
       }
-      const entries = existing
-        ? metadata.entries.map(entry => entry.id === entryId ? { ...entry, name: DESKTOP_PICKER_ENTRY_NAME } : entry)
-        : [...metadata.entries, { id: entryId, name: DESKTOP_PICKER_ENTRY_NAME }];
-      atomicWriteFile(metaPath, metadataJson({ ...metadata, appliedId: entryId, entries }));
+      atomicWriteFile(metaPath, nextMetadataJson);
     } catch {
       try {
         restoreFile(metaPath, oldMeta);
@@ -246,6 +248,8 @@ function removeDesktopPickerProfileLocked(options: DesktopPickerProfileOptions):
     try { state = readPickerState(statePath); } catch { return { ok: false, reason: "profile_state_unreadable" }; }
 
     let metadataAfterPivot = metadata;
+    let standardPath: string | undefined;
+    let pivotMetadataJson: string | undefined;
     if (selected) {
       const previous = state?.entryId === picker.id ? state.previousAppliedId : null;
       const previousExists = previous !== null && previous !== picker.id && metadata.entries.some(entry => entry.id === previous);
@@ -253,16 +257,22 @@ function removeDesktopPickerProfileLocked(options: DesktopPickerProfileOptions):
         metadataAfterPivot = { ...metadata, appliedId: previous };
       } else {
         const standardId = randomUUID();
-        atomicWriteFile(profilePath(libraryPath, standardId), "{}\n");
+        standardPath = profilePath(libraryPath, standardId);
         metadataAfterPivot = {
           ...metadata,
           appliedId: standardId,
           entries: [...metadata.entries, { id: standardId, name: "opencodex-standard" }],
         };
       }
-      atomicWriteFile(metaPath, metadataJson(metadataAfterPivot));
+      pivotMetadataJson = metadataJson(metadataAfterPivot);
     }
 
+    const entries = metadataAfterPivot.entries.filter(entry => entry.id !== picker.id);
+    const finalMetadataJson = metadataJson({ ...metadataAfterPivot, entries });
+
+    if (standardPath !== undefined) atomicWriteFile(standardPath, "{}\n");
+    if (pivotMetadataJson !== undefined) atomicWriteFile(metaPath, pivotMetadataJson);
+
     const residualPaths: string[] = [];
     for (const path of [profilePath(libraryPath, picker.id), `${profilePath(libraryPath, picker.id)}.bak`]) {
       try { unlinkIfPresent(path); } catch { /* report the path without exposing file contents */ }
@@ -272,9 +282,8 @@ function removeDesktopPickerProfileLocked(options: DesktopPickerProfileOptions):
       return { ok: false, reason: "cleanup_incomplete", residualPaths };
     }
 
-    const entries = metadataAfterPivot.entries.filter(entry => entry.id !== picker.id);
     try {
-      atomicWriteFile(metaPath, metadataJson({ ...metadataAfterPivot, entries }));
+      atomicWriteFile(metaPath, finalMetadataJson);
       try { unlinkIfPresent(statePath); } catch { /* residual is reported below */ }
       if (existsSync(statePath)) return { ok: false, reason: "cleanup_incomplete", residualPaths: [statePath] };
     } catch {

package/src/claude/desktop-remote-store-io.ts

@@ -2,7 +2,7 @@ import { chmodSync, lstatSync, mkdirSync, realpathSync, unlinkSync } from "node:
 import { basename, dirname, join, resolve } from "node:path";
 import { atomicWriteFile, getConfigDir } from "../config";
 import { hardenSecretDir } from "../lib/windows-secret-acl";
-import { isRecord, readDesktopLibraryBytes, resolveDesktop3pConfigLibraryPath, SAFE_DESKTOP_PROFILE_ID, type Desktop3pMetadata } from "./desktop-3p-library";
+import { isRecord, MAX_DESKTOP_PROFILE_FILE_BYTES, readDesktopLibraryBytes, resolveDesktop3pConfigLibraryPath, SAFE_DESKTOP_PROFILE_ID, type Desktop3pMetadata } from "./desktop-3p-library";
 import { DesktopStoreError, digest } from "./desktop-remote-store-state";
 
 export const MAX_DESKTOP_METADATA_ENTRIES = 256;
@@ -45,7 +45,7 @@ export class StoreIO {
     try {
       // The shared verified regular-file read keeps a swapped FIFO from parking this
       // open before the post-read identity recheck below can run.
-      const bytes = readDesktopLibraryBytes(path);
+      const bytes = readDesktopLibraryBytes(path, Math.min(maxBytes, MAX_DESKTOP_PROFILE_FILE_BYTES));
       if (bytes.byteLength > maxBytes || identity(lstatSync(path)) !== identity(stat)) throw new DesktopStoreError("conflict");
       const value: unknown = JSON.parse(bytes.toString("utf8"));
       if (!isRecord(value)) throw new DesktopStoreError("unsafe");

package/src/cli/capabilities-agents-routing.ts

@@ -203,6 +203,56 @@ export const AGENT_ROUTING_CAPABILITIES: readonly Capability[] = [
     json: "payload",
     details: ["Without --list at least one setting is required. Stored settings and Codex application outcomes remain distinct.","Stream-routed-output belongs only to web. Timeout changes preserve siblings; native apply and saved state are distinct."],
   },
+  {
+    command: ["fallback"],
+    usage: "ocx fallback [status] [--json]",
+    summary: "Show which model and provider fallbacks are allowed, per-device local fallback, and the last fallback taken or refused.",
+    routes: [{"method": "GET", "path": "/api/fallback"}],
+    flags: [{"name": "--json", "value": "boolean", "summary": "Emit the ocx.fallback/1 state."}],
+    mutates: false,
+    json: "payload",
+    details: ["Reads the live proxy. On a Remote Link Child it reads the Home's state over the link (aliases omitted). The last event is in memory and resets on restart."],
+  },
+  {
+    command: ["fallback", "off"],
+    usage: "ocx fallback off [--kind model|provider|all] [--provider <name> | --route <selector> | --device <id|alias>] [--json]",
+    summary: "Refuse model or provider fallback globally or for one provider, route or device.",
+    routes: [{"method": "PUT", "path": "/api/fallback"}],
+    flags: [{"name": "--kind", "value": "string", "summary": "model, provider or all (default)."}, {"name": "--provider", "value": "string", "summary": "Scope to the provider a request started on."}, {"name": "--route", "value": "string", "summary": "Scope to an exact selector such as combo/<id> or policy/<id>."}, {"name": "--device", "value": "string", "summary": "Scope to a Remote Link id or alias, or a Hub data key id; device off always refuses."}, {"name": "--json", "value": "boolean", "summary": "Emit the resulting state."}],
+    mutates: true,
+    json: "payload",
+    details: ["A refused hop answers fallback_refused with the triggering failure's status. Rotation among accounts or keys of one provider pool is not a fallback and stays on."],
+  },
+  {
+    command: ["fallback", "on"],
+    usage: "ocx fallback on [--kind model|provider|all] [--provider <name> | --route <selector> | --device <id|alias>] [--json]",
+    summary: "Allow model or provider fallback at one scope, overriding a broader off.",
+    routes: [{"method": "PUT", "path": "/api/fallback"}],
+    flags: [{"name": "--kind", "value": "string", "summary": "model, provider or all (default)."}, {"name": "--provider", "value": "string", "summary": "Scope to a provider."}, {"name": "--route", "value": "string", "summary": "Scope to an exact selector."}, {"name": "--device", "value": "string", "summary": "Scope to a device."}, {"name": "--json", "value": "boolean", "summary": "Emit the resulting state."}],
+    mutates: true,
+    json: "payload",
+    details: ["Route beats provider beats global. A device setting can only refuse: on for a device records the value but never reopens a hop another scope refuses."],
+  },
+  {
+    command: ["fallback", "clear"],
+    usage: "ocx fallback clear [--kind model|provider|all] [--provider <name> | --route <selector> | --device <id|alias>] [--json]",
+    summary: "Remove a fallback override so the scope inherits again.",
+    routes: [{"method": "PUT", "path": "/api/fallback"}],
+    flags: [{"name": "--kind", "value": "string", "summary": "model, provider or all (default)."}, {"name": "--provider", "value": "string", "summary": "Scope to a provider."}, {"name": "--route", "value": "string", "summary": "Scope to an exact selector."}, {"name": "--device", "value": "string", "summary": "Scope to a device."}, {"name": "--json", "value": "boolean", "summary": "Emit the resulting state."}],
+    mutates: true,
+    json: "payload",
+    details: ["Clearing every override restores today's behavior: every fallback allowed."],
+  },
+  {
+    command: ["fallback", "local"],
+    usage: "ocx fallback local <on|off> --device <id|alias> [--json]",
+    summary: "Record whether a device may use its own providers while the Home is unreachable.",
+    routes: [{"method": "PUT", "path": "/api/fallback"}],
+    flags: [{"name": "--device", "value": "string", "summary": "Remote Link id or alias, or Hub data key id."}, {"name": "--json", "value": "boolean", "summary": "Emit the resulting state."}],
+    mutates: true,
+    json: "payload",
+    details: ["Run on the Home. A permission GOAT reads; OpenCodex itself keeps answering home_unreachable on the device and never serves it from local providers."],
+  },
   {
     command: ["effort"],
     usage: "ocx effort [status|low|medium|high|xhigh|max|ultra|->] [--json]",

package/src/cli/capabilities-base.ts

@@ -86,6 +86,16 @@ export const CAPABILITIES: readonly Capability[] = [
     usage: "ocx link reconnect --link-id <id> [--json]",
     details: ["Requires a valid link ID and loopback admin authority. Stops the current ssh child, clears any backoff or failed state and starts a fresh attempt; read ocx link status for the outcome.","A Child-initiated link is refused with link_not_home_initiated: its own computer owns and retries that tunnel.","Always emits {linkId} JSON."],
   },
+  {
+    command: ["link","cleanup"],
+    summary: "Find Windows Remote Link Children and explain how to move them to Hub mode.",
+    routes: [],
+    flags: [{"name":"--link-id","value":"string","summary":"Check only this link."},{"name":"--json","value":"boolean","summary":"Emit {links, changed:false} as JSON."}],
+    mutates: false,
+    json: "payload",
+    usage: "ocx link cleanup [--link-id <id>] [--json]",
+    details: ["Runs on the Home from its local link store. Asks each Home-initiated Child for uname -s over the link's pinned SSH trust; a Windows answer (Git Bash, MSYS, Cygwin, cmd or PowerShell) is reported with recovery steps.","Never revokes, disconnects or edits a link. A Windows Child needs ocx disconnect on itself, then ocx link revoke --force --yes on the Home, then ocx hub invite and ocx connect."],
+  },
   {
     command: ["remote-workspace","pair"],
     summary: "Enroll this executor with one Hub using a one-time code from stdin and locally approved roots.",
@@ -156,7 +166,7 @@ export const CAPABILITIES: readonly Capability[] = [
     flags: [{ name: "--json", value: "boolean", summary: "Emit the status envelope as JSON." }],
     mutates: false,
     json: "envelope",
-    details: ["Reads /healthz plus local config; drives no management API route."],
+    details: ["Reads /healthz plus local config; drives no management API route.", "--json includes install: {method: bun|npm|pnpm|mise|source|standalone|unknown, evidence: {basis, mise?, error?}} from the updater's install detector."],
   },
   {
     command: ["resolve"],
@@ -225,7 +235,10 @@ export const CAPABILITIES: readonly Capability[] = [
     flags: [{"name":"--json","value":"boolean","summary":"Emit the provider list as JSON."},{"name":"--jsonl","value":"boolean","summary":"Emit one configured provider per JSON line."}],
     mutates: false,
     json: "envelope",
-    details: ["Local config and registry read, not GET /api/providers. --json and --jsonl are mutually exclusive."],
+    details: [
+      "Local config and registry read, not GET /api/providers. --json and --jsonl are mutually exclusive.",
+      "Each configured row carries active: false while this device is linked to a Home (a Remote Link Child or a Hub-mode client), whose providers serve instead; true when the row serves. Credential values are never printed.",
+    ],
     usage: "ocx provider list [--json|--jsonl]",
   },
   {

package/src/cli/capabilities-observe-system.ts

@@ -621,11 +621,11 @@ export const OBSERVE_SYSTEM_CAPABILITIES: readonly Capability[] = [
   },
   {
     command: ["service", "status"], summary: "Inspect local service-manager status.",
-    usage: "ocx service status",
+    usage: "ocx service status [--json]",
     routes: [],
-    flags: [],
-    mutates: false, json: "none",
-    details: ["Local OS service manager: macOS launchd, Linux systemd, Windows Task Scheduler or WinSW. No management API or JSON mode.", "Backend options apply only to install; other verbs use the installed backend."],
+    flags: [{"name": "--json", "value": "boolean", "summary": "Emit the passive service status document as JSON."}],
+    mutates: false, json: "payload",
+    details: ["Local OS service manager: macOS launchd, Linux systemd, Windows Task Scheduler or WinSW. No management API.", "--json is passive: schemaVersion 1 with installed, running, enabled, viable, stale, conflict, backend (launchd|systemd|schtasks|winsw|none), label, serving {probed, ok, port}, summary, logPath, ownershipLease and desktopLogin. It starts, stops, installs and repairs nothing.", "Backend options apply only to install; other verbs use the installed backend."],
   },
   {
     command: ["service", "uninstall"], summary: "Uninstall the local service.",

package/src/cli/codex-shim-autorestore.ts

@@ -26,6 +26,11 @@ export function skipsCodexShimAutoRestore(command: string | undefined, args: str
   // `resolve` is read-only inspection for embedding shells: a lookup made to populate
   // a consent surface must not trigger a shim repair side effect first.
   if (command === "resolve") return true;
+  // `service status --json` is a passive inventory read for peers such as GOAT: a shim repair
+  // before dispatch would change the installation it was asked only to describe.
+  // Flags may precede the verb (`ocx service --json status`), exactly as parseServiceArgs reads it.
+  if (command === "service" && args.includes("--json")
+    && args.slice(1).find(arg => !arg.startsWith("--")) === "status") return true;
   // The desktop's approval-bound stop must validate its snapshot before any unrelated
   // CLI repair changes the installation it was approved against.
   if (command === "stop" && args.some(arg => arg.startsWith("--expect-"))) return true;

package/src/cli/dispatch.ts

@@ -437,6 +437,32 @@ const commandRunners: Record<string, CommandRunner> = {
           }
         }
         await handleConnectedSyncCatalogWrite(result, restartScope);
+        if (result.applyRecordFailed) {
+          console.error("The Home's Codex settings were applied, but the apply record could not be written; the client runtime was not restarted. Run 'ocx sync' again.");
+          process.exitCode = 1;
+        }
+        // OCX-6: a link Child's runtime must have started after the apply it serves under.
+        if (link && result.appliedRecord) {
+          const { applyRestartMessage, restartRuntimeAfterApply } = await import("./link-apply-restart");
+          const { sameClientConnectionOwner } = await import("../client/state");
+          const applied = clientState.value;
+          const outcome = await restartRuntimeAfterApply(result.appliedRecord, {
+            restart: startWhenStopped => deps.handleProxyRestart(startWhenStopped),
+            recoveryStart: recovering => deps.handleRestartStartWhenStopped(recovering),
+            connectionUnchanged: () => {
+              const current = readClientConnectionState();
+              return current.kind === "connected" && sameClientConnectionOwner(current.value, applied)
+                && current.value.link?.linkId === applied.link?.linkId;
+            },
+          });
+          const message = applyRestartMessage(outcome);
+          if (outcome.kind === "failed" || outcome.kind === "connection-changed") {
+            console.error(message);
+            process.exitCode = 1;
+          } else {
+            console.log(message);
+          }
+        }
         // `process.exitCode` rather than a literal 0, for the same reason every other
         // runner does it (tests/cli/cli-transport-honesty.test.ts): the catalog-write helper
         // drives app-server restarts, and one of those recording a failure must not be
@@ -876,6 +902,10 @@ const commandRunners: Record<string, CommandRunner> = {
     const { handleEffortCommand } = await import("./effort");
     return await handleEffortCommand(deps.args.slice(1), { findLiveProxy: deps.findLiveProxy });
   },
+  fallback: async deps => {
+    const { handleFallbackCommand } = await import("./fallback");
+    return await handleFallbackCommand(deps.args.slice(1), { findLiveProxy: deps.findLiveProxy });
+  },
   agent: async deps => {
     const { handleAgentCommand } = await import("./agent");
     return await handleAgentCommand(deps.args.slice(1));

package/src/cli/ensure-desktop-cold-start.ts

@@ -241,12 +241,12 @@ function consentedDesktopBundle(home: string, installId: string, run: Execute):
   const plistPath = realpathSync(join(home, "Library", "LaunchAgents", `${DESKTOP_PLIST_LABEL}.plist`));
   const registration = JSON.parse(
     run("/usr/bin/plutil", ["-convert", "json", "-o", "-", plistPath], 3_000),
-  ) as { Label?: unknown; ProgramArguments?: unknown; Program?: unknown };
+  ) as { Label?: unknown; RunAtLoad?: unknown; ProgramArguments?: unknown; Program?: unknown };
   const args = registration.ProgramArguments;
   // The shapes auto-launch writes: [program] or [program, "--autostart"]; see the migration
   // rules in desktop/src-tauri/src/login_registration.rs, which classify anything else Leave.
   // This is a macOS plist path, regardless of the host running an injected launch probe.
-  if (registration.Label !== DESKTOP_PLIST_LABEL || !Array.isArray(args)
+  if (registration.Label !== DESKTOP_PLIST_LABEL || registration.RunAtLoad !== true || !Array.isArray(args)
     || (args.length !== 1 && args.length !== 2) || typeof args[0] !== "string" || !posix.isAbsolute(args[0])
     || (args.length === 2 && args[1] !== "--autostart")
     || (registration.Program !== undefined && registration.Program !== args[0])) return null;

package/src/cli/fallback.ts

@@ -0,0 +1,127 @@
+import {
+  CliUsageError,
+  printData,
+  rejectArgs,
+  runCliAction,
+  runtimeRequest,
+  takeFlag,
+  takeOption,
+  terminalSafeText,
+  type RuntimeApiDeps,
+} from "./runtime-api";
+
+export const FALLBACK_USAGE = `Usage:
+  ocx fallback status [--json]
+  ocx fallback off   [--kind model|provider|all] [--provider <name> | --route <selector> | --device <id|alias>] [--json]
+  ocx fallback on    [--kind model|provider|all] [--provider <name> | --route <selector> | --device <id|alias>] [--json]
+  ocx fallback clear [--kind model|provider|all] [--provider <name> | --route <selector> | --device <id|alias>] [--json]
+  ocx fallback local <on|off> --device <id|alias> [--json]`;
+
+type Switches = { model?: boolean; provider?: boolean };
+interface DeviceRow { id?: string; alias?: string; localFallback?: boolean; model?: boolean | null; provider?: boolean | null }
+interface EventRow { at?: string; site?: string; route?: string; kind?: string; from?: string; to?: string; trigger?: string; outcome?: string; scope?: string }
+interface FallbackState {
+  global?: { model?: boolean; provider?: boolean };
+  providers?: Record<string, Switches>;
+  routes?: Record<string, Switches>;
+  devices?: DeviceRow[];
+  last?: EventRow | null;
+}
+
+const onOff = (value: boolean | null | undefined): string => value === false ? "off" : value === true ? "on" : "inherit";
+
+function switchesLine(label: string, value: Switches): string {
+  const parts: string[] = [];
+  if (value.model !== undefined) parts.push("model " + onOff(value.model));
+  if (value.provider !== undefined) parts.push("provider " + onOff(value.provider));
+  return terminalSafeText(label) + ": " + parts.join(", ");
+}
+
+export function fallbackStatusLines(state: FallbackState): string[] {
+  const lines = [
+    "model fallback: " + (state.global?.model === false ? "off" : "on") + " (global)",
+    "provider fallback: " + (state.global?.provider === false ? "off" : "on") + " (global)",
+  ];
+  for (const [name, value] of Object.entries(state.providers ?? {})) lines.push(switchesLine("provider " + name, value));
+  for (const [name, value] of Object.entries(state.routes ?? {})) lines.push(switchesLine("route " + name, value));
+  for (const device of state.devices ?? []) {
+    const label = "device " + (device.id ?? "?") + (device.alias ? " (" + device.alias + ")" : "");
+    lines.push(terminalSafeText(label) + ": local fallback " + (device.localFallback ? "allowed" : "off")
+      + ", model " + onOff(device.model) + ", provider " + onOff(device.provider));
+  }
+  const last = state.last;
+  lines.push(last
+    ? terminalSafeText("last: " + last.at + " " + last.outcome + " " + last.kind + " fallback on " + last.route + ": "
+      + last.from + " -> " + last.to + " (" + last.trigger + ", " + last.scope + ")")
+    : "last: no fallback since this proxy started");
+  return lines;
+}
+
+function takeScope(args: string[]): { scope: "global" | "provider" | "route" | "device"; key?: string } {
+  const provider = takeOption(args, "--provider");
+  const route = takeOption(args, "--route");
+  const device = takeOption(args, "--device");
+  const given = [provider, route, device].filter(value => value !== undefined);
+  if (given.length > 1) throw new CliUsageError("use one of --provider, --route or --device", FALLBACK_USAGE);
+  if (provider !== undefined) return { scope: "provider", key: provider };
+  if (route !== undefined) return { scope: "route", key: route };
+  if (device !== undefined) return { scope: "device", key: device };
+  return { scope: "global" };
+}
+
+function takeKinds(args: string[]): Array<"model" | "provider"> {
+  const kind = takeOption(args, "--kind") ?? "all";
+  if (kind === "all") return ["model", "provider"];
+  if (kind === "model" || kind === "provider") return [kind];
+  throw new CliUsageError("--kind must be model, provider or all", FALLBACK_USAGE);
+}
+
+async function put(body: Record<string, unknown>, deps: RuntimeApiDeps): Promise<FallbackState> {
+  return await runtimeRequest<FallbackState>("/api/fallback", {
+    method: "PUT",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify(body),
+  }, deps);
+}
+
+async function status(argv: string[], deps: RuntimeApiDeps): Promise<void> {
+  const args = [...argv];
+  const wantsJson = takeFlag(args, "--json");
+  rejectArgs(args, FALLBACK_USAGE);
+  const state = await runtimeRequest<FallbackState>("/api/fallback", {}, deps);
+  printData(state, wantsJson, fallbackStatusLines(state));
+}
+
+async function setSwitch(argv: string[], value: boolean | null, deps: RuntimeApiDeps): Promise<void> {
+  const args = [...argv];
+  const wantsJson = takeFlag(args, "--json");
+  const kinds = takeKinds(args);
+  const scope = takeScope(args);
+  rejectArgs(args, FALLBACK_USAGE);
+  const state = await put({ writes: kinds.map(setting => ({ ...scope, setting, value })) }, deps);
+  printData(state, wantsJson, fallbackStatusLines(state));
+}
+
+async function local(argv: string[], deps: RuntimeApiDeps): Promise<void> {
+  const args = [...argv];
+  const wantsJson = takeFlag(args, "--json");
+  const mode = args.shift();
+  if (mode !== "on" && mode !== "off") throw new CliUsageError("fallback local needs on or off", FALLBACK_USAGE);
+  const device = takeOption(args, "--device");
+  if (!device) throw new CliUsageError("fallback local needs --device <id|alias>", FALLBACK_USAGE);
+  rejectArgs(args, FALLBACK_USAGE);
+  const state = await put({ scope: "device", key: device, setting: "localFallback", value: mode === "on" }, deps);
+  printData(state, wantsJson, fallbackStatusLines(state));
+}
+
+export async function handleFallbackCommand(argv: string[], deps: RuntimeApiDeps = {}): Promise<number> {
+  return runCliAction(async () => {
+    const [sub, ...rest] = argv;
+    if (sub === undefined || sub === "status") await status(rest, deps);
+    else if (sub === "off") await setSwitch(rest, false, deps);
+    else if (sub === "on") await setSwitch(rest, true, deps);
+    else if (sub === "clear") await setSwitch(rest, null, deps);
+    else if (sub === "local") await local(rest, deps);
+    else throw new CliUsageError("unknown fallback command: " + sub, FALLBACK_USAGE);
+  });
+}

package/src/cli/help.ts

@@ -81,6 +81,7 @@ Usage:
   ocx agent <sub>             Subagents, injection, effort caps, and sidecars
   ocx message <sub>           Codex queued messages, explicit SSH peers and foreground ownership
   ocx effort [sub]            Inspect and configure reasoning effort caps and defaults
+  ocx fallback <sub>          Turn model or provider fallback off per scope; per-device local fallback
   ocx observe <sub>           Logs, usage, storage, memory, and debug data
   ocx inspect <sub>           Effective config, catalog, analytics, pacing, client-config
   ocx route <sub>             Routing features (combo, policy)

package/src/cli/index.ts

@@ -167,7 +167,7 @@ import { startClientRuntimeUnderOwnershipLease } from "./client-start-fence";
 import { recoverStartStateUnderOwnershipLease } from "./start-owner-fence";
 import { handledSignalExitCode } from "../lib/handled-signal-exit";
 import { createLocalAttestationSecret } from "../lib/local-management-attestation";
-import { MEMORY_DRAIN_RESTART_MS, REPLACEMENT_READY_TIMEOUT_MS } from "../lib/system-restart-contract";
+import { MEMORY_DRAIN_RESTART_MS, REPLACEMENT_READY_TIMEOUT_MS, RESTART_REOBSERVE_RESERVE_MS } from "../lib/system-restart-contract";
 import { startServiceLogging } from "../service/logging";
 
 /**
@@ -941,7 +941,6 @@ async function handleTrayProxyStart(existingIsSuccess = true): Promise<boolean>
 const PROXY_RESTART_OBSERVE_MS = MEMORY_DRAIN_RESTART_MS + REPLACEMENT_READY_TIMEOUT_MS + 15_000;
 
 /** Reserve confirmation time within the shared restart deadline. */
-const RESTART_REOBSERVE_RESERVE_MS = 10_000;
 async function handleProxyRestart(
   startWhenStopped: (recoveringLiveRestart: boolean) => Promise<ProxyRestartStartOutcome>,
 ): Promise<boolean> {

package/src/cli/link-apply-restart.ts

@@ -0,0 +1,72 @@
+/**
+ * After `ocx sync` applies the Home's Codex settings on a Remote Link Child, restart the Child's
+ * runtime so it started after the apply (OCX-6, P5).
+ *
+ * Idempotent: the record keeps its apply time while the settings digest is unchanged, so a runtime
+ * that already started after it is left alone, and a sync after a failed restart retries it. The
+ * restart is `ocx restart`'s own (`handleProxyRestart`); this module only decides whether to call
+ * it and never starts a runtime that was not running, except to recover one an accepted restart
+ * left absent.
+ */
+import type { HomeCodexSettingsRecord } from "../client/link-home";
+import { findLiveProxy, probeHostname, type LiveProxy } from "../server/proxy-liveness";
+import type { ProxyRestartStartOutcome } from "./tray-proxy";
+
+export type ApplyRestartOutcome =
+  | { kind: "current" }
+  | { kind: "not-running" }
+  | { kind: "connection-changed" }
+  | { kind: "restarted" }
+  | { kind: "failed" };
+
+export interface ApplyRestartDeps {
+  findLive?: () => Promise<LiveProxy | null>;
+  /** Epoch ms the live client runtime reports as its start, or null when it reports none. */
+  readStartedAt?: (live: LiveProxy) => Promise<number | null>;
+  restart: (startWhenStopped: (recoveringLiveRestart: boolean) => Promise<ProxyRestartStartOutcome>) => Promise<boolean>;
+  recoveryStart: (recoveringLiveRestart: boolean) => Promise<ProxyRestartStartOutcome>;
+  /** Still the connection this sync applied for (rechecked right before the restart). */
+  connectionUnchanged: () => boolean;
+}
+
+export async function readClientRuntimeStartedAt(live: LiveProxy, fetchImpl: typeof fetch = fetch): Promise<number | null> {
+  try {
+    const response = await fetchImpl(`http://${probeHostname(live.hostname)}:${live.port}/healthz`, {
+      headers: { accept: "application/json" },
+      redirect: "manual",
+      signal: AbortSignal.timeout(2_000),
+    });
+    if (!response.ok) return null;
+    const body = await response.json() as { pid?: unknown; startedAt?: unknown } | null;
+    if (body?.pid !== live.pid || typeof body.startedAt !== "string") return null;
+    const startedAt = Date.parse(body.startedAt);
+    return Number.isFinite(startedAt) ? startedAt : null;
+  } catch {
+    return null;
+  }
+}
+
+export async function restartRuntimeAfterApply(record: HomeCodexSettingsRecord, deps: ApplyRestartDeps): Promise<ApplyRestartOutcome> {
+  const live = await (deps.findLive ?? (() => findLiveProxy()))();
+  if (!live || live.role !== "client") return { kind: "not-running" };
+  const appliedAt = Date.parse(record.appliedAt);
+  // A runtime that reports no start time predates OCX-6 and cannot prove it is current.
+  const startedAt = await (deps.readStartedAt ?? (target => readClientRuntimeStartedAt(target)))(live);
+  if (startedAt !== null && Number.isFinite(appliedAt) && startedAt >= appliedAt) return { kind: "current" };
+  if (!deps.connectionUnchanged()) return { kind: "connection-changed" };
+  const ok = await deps.restart(async recovering => recovering
+    ? deps.recoveryStart(true)
+    : { status: "skipped" });
+  return ok ? { kind: "restarted" } : { kind: "failed" };
+}
+
+/** One line for each outcome, printed by `ocx sync`. */
+export function applyRestartMessage(outcome: ApplyRestartOutcome): string {
+  switch (outcome.kind) {
+    case "current": return "Client runtime already started after this apply; no restart needed.";
+    case "not-running": return "No client runtime is running; the applied settings take effect when it starts.";
+    case "connection-changed": return "The connection changed during sync; the client runtime was not restarted. Run 'ocx sync' again.";
+    case "restarted": return "Client runtime restarted after applying the Home's settings.";
+    case "failed": return "The client runtime restart did not complete; the previous runtime keeps serving. If a background service or the desktop app owns it, restart it there; otherwise retry with 'ocx restart' or 'ocx sync'.";
+  }
+}

package/src/cli/link-child.ts

@@ -74,6 +74,7 @@ export async function readLinkHomeJson(
   context: LinkChildContext,
   path: string,
   deps: LinkHomeDeps = {},
+  init: { signal?: AbortSignal } = {},
 ): Promise<{ status: number; body: unknown }> {
   const token = readServiceApiTokenState();
   if (token.kind !== "present" || token.fingerprint !== context.connection.tokenFingerprint) {
@@ -81,12 +82,15 @@ export async function readLinkHomeJson(
   }
   let response: Response;
   try {
-    response = await fetchLinkHomeManagement(context.connection, token.token, path.startsWith("/") ? path : `/${path}`, {}, deps);
+    response = await fetchLinkHomeManagement(context.connection, token.token, path.startsWith("/") ? path : `/${path}`,
+      init.signal ? { signal: init.signal } : {}, deps);
   } catch (error) {
     const detail = error instanceof Error && error.name === "LinkRelayAuthenticationError" ? error.message : "the link tunnel did not answer";
     throw new Error(`Could not read ${context.homePhrase} over Remote Link (${context.linkId}): ${detail}.`);
   }
-  const result = await readBoundedResponseBytes(response, { maxBytes: RESPONSE_MAX_BYTES, signal: AbortSignal.timeout(30_000) });
+  // A caller's deadline (the status report's 2 s) bounds the body read as well as the request.
+  const readSignal = init.signal ? AbortSignal.any([init.signal, AbortSignal.timeout(30_000)]) : AbortSignal.timeout(30_000);
+  const result = await readBoundedResponseBytes(response, { maxBytes: RESPONSE_MAX_BYTES, signal: readSignal });
   if (result.oversized) throw new Error(`${context.homePhrase} returned a response larger than the CLI accepts.`);
   const text = new TextDecoder().decode(result.bytes);
   let body: unknown = null;