@bitkyc08/opencodex 2.90.0 → 2.92.0

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]",
@@ -335,13 +385,13 @@ export const AGENT_ROUTING_CAPABILITIES: readonly Capability[] = [
   },
   {
     command: ["combo","set"],
-    usage: "ocx combo set <id> [--targets <provider/model[:weight],...> | --targets-file <FILE|->] [--strategy <failover|round-robin|random|least-used|reset-window|jev>] [--sticky <1-100|->] [--effort <low|medium|high|xhigh|max|ultra|->] [--effort-mode <fallback|force|->] [--alias <name|->] [--native-alias [on|off]] [--allow-metered-targets <on|off>] [--display-name <label|->] [--description <text|->] [--decision-provider <provider|-> | --decision-model <route|->] [--decision-timeout <ms|->] [--decision-quota-signals <on|off|->] [--decision-quota-tiers <JSON|->] [--rename-from <id>] [--image-input <auto|disabled>] [--reasoning-effort-mode <strict|adaptive>] [--json]",
+    usage: "ocx combo set <id> [--targets <provider/model[:weight],...> | --targets-file <FILE|->] [--strategy <failover|round-robin|random|least-used|reset-window|jev>] [--sticky <1-100|->] [--effort <low|medium|high|xhigh|max|ultra|->] [--effort-mode <fallback|force|->] [--alias <name|->] [--native-alias [on|off]] [--allow-metered-targets <on|off>] [--display-name <label|->] [--description <text|->] [--decision-provider <provider|-> | --decision-model <route|->] [--decision-timeout <ms|->] [--decision-quota-signals <on|off|->] [--decision-quota-tiers <JSON|->] [--session-pin <duration|->] [--rename-from <id>] [--image-input <auto|disabled>] [--reasoning-effort-mode <strict|adaptive>] [--json]",
     summary: "Create, update or rename a combo.",
     routes: [{"method":"GET","path":"/api/combos"},{"method":"PUT","path":"/api/combos"}],
-    flags: [{"name":"--allow-metered-targets","value":"string","summary":"on grants operator consent to metered targets only on a loopback-only proxy; off clears it."},{"name":"--targets","value":"string","summary":"Ordered provider/model[:weight] list; required for creation."},{"name":"--strategy","value":"string","summary":"Routing strategy."},{"name":"--sticky","value":"string","summary":"Round-robin limit 1-100; - resets."},{"name":"--effort","value":"string","summary":"Default effort; - clears."},{"name":"--effort-mode","value":"string","summary":"fallback or force; - resets to fallback."},{"name":"--alias","value":"string","summary":"Alias; - clears."},{"name":"--display-name","value":"string","summary":"Label; - clears."},{"name":"--description","value":"string","summary":"Catalog row description; - clears."},{"name":"--decision-provider","value":"string","summary":"JEV provider; - clears."},{"name":"--decision-model","value":"string","summary":"JEV route; - clears; exclusive with provider."},{"name":"--decision-timeout","value":"string","summary":"JEV deadline 1000-120000 ms; - clears."},{"name":"--decision-quota-signals","value":"string","summary":"JEV advisory quota on/off; - clears."},{"name":"--decision-quota-tiers","value":"string","summary":"Partial JSON thresholds; - clears."},{"name":"--rename-from","value":"string","summary":"Existing combo ID to rename."},{"name":"--json","value":"boolean","summary":"Emit structured JSON."},{"name":"--native-alias","value":"string","summary":"Bare legacy flag means on; explicit on/off preserves presence, including false."},{"name":"--targets-file","value":"string","summary":"Bounded ordered target JSON array, exclusive with --targets; preserves effort/profile/last-resort metadata."},{"name":"--image-input","value":"string","summary":"auto or disabled; explicit auto clears the previous disabled choice."},{"name":"--reasoning-effort-mode","value":"string","summary":"strict or adaptive, distinct from --effort-mode fallback/force."}],
+    flags: [{"name":"--allow-metered-targets","value":"string","summary":"on grants operator consent to metered targets only on a loopback-only proxy; off clears it."},{"name":"--targets","value":"string","summary":"Ordered provider/model[:weight] list; required for creation."},{"name":"--strategy","value":"string","summary":"Routing strategy."},{"name":"--sticky","value":"string","summary":"Round-robin limit 1-100; - resets."},{"name":"--effort","value":"string","summary":"Default effort; - clears."},{"name":"--effort-mode","value":"string","summary":"fallback or force; - resets to fallback."},{"name":"--alias","value":"string","summary":"Alias; - clears."},{"name":"--display-name","value":"string","summary":"Label; - clears."},{"name":"--description","value":"string","summary":"Catalog row description; - clears."},{"name":"--decision-provider","value":"string","summary":"JEV provider; - clears."},{"name":"--decision-model","value":"string","summary":"JEV route; - clears; exclusive with provider."},{"name":"--decision-timeout","value":"string","summary":"JEV deadline 1000-120000 ms; - clears."},{"name":"--decision-quota-signals","value":"string","summary":"JEV advisory quota on/off; - clears."},{"name":"--decision-quota-tiers","value":"string","summary":"Partial JSON thresholds; - clears."},{"name":"--session-pin","value":"string","summary":"JEV session pin idle window 1m-24h (90s, 20m, 1h); - clears."},{"name":"--rename-from","value":"string","summary":"Existing combo ID to rename."},{"name":"--json","value":"boolean","summary":"Emit structured JSON."},{"name":"--native-alias","value":"string","summary":"Bare legacy flag means on; explicit on/off preserves presence, including false."},{"name":"--targets-file","value":"string","summary":"Bounded ordered target JSON array, exclusive with --targets; preserves effort/profile/last-resort metadata."},{"name":"--image-input","value":"string","summary":"auto or disabled; explicit auto clears the previous disabled choice."},{"name":"--reasoning-effort-mode","value":"string","summary":"strict or adaptive, distinct from --effort-mode fallback/force."}],
     mutates: true,
     json: "payload",
-    details: ["create and update are aliases of set. Existing fields are read before writing; --targets replaces targets.","force overrides valid client effort and may increase cost and latency.","Only the implemented target grammar is supported; full GUI target metadata and routing-profile writes are separate tasks.","New file/flag conflicts refuse before transport. Partial edits preserve target metadata; explicit false/default values override server carry. Turning a native alias off may also require clearing its incompatible alias.","Read/merge/write uses one target and remains an upsert without revision CAS. Saved-but-incomplete catalog outcomes return nonzero with their receipt."],
+    details: ["create and update are aliases of set. Existing fields are read before writing; --targets replaces targets. Without --strategy an existing combo keeps its stored strategy and JEV policy; a new combo defaults to failover.","force overrides valid client effort and may increase cost and latency.","Only the implemented target grammar is supported; full GUI target metadata and routing-profile writes are separate tasks.","New file/flag conflicts refuse before transport. Partial edits preserve target metadata; explicit false/default values override server carry. Turning a native alias off may also require clearing its incompatible alias.","Read/merge/write uses one target and remains an upsert without revision CAS. Saved-but-incomplete catalog outcomes return nonzero with their receipt."],
   },
   {
     command: ["combo", "remove"],

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-cli-update.ts

@@ -221,11 +221,19 @@ function inspectionDeps(commandDeps: CodexCliUpdateCommandDeps): CodexCliInstall
   return {
     env: {
       ...trusted.managerRoots,
+      ...trusted.transportEnv,
       CODEX_CLI_PATH: trusted.codexCliPath ?? undefined,
       PATH: trusted.path ?? undefined,
       PATHEXT: trusted.pathExt ?? undefined,
+      // The lookup seeds the inspection models against the launch-time
+      // capture; ambient values are never consulted.
+      HOME: trusted.home ?? undefined,
+      NODE_PATH: trusted.nodePath ?? undefined,
     },
     configDir: trusted.configDir,
+    // Content observation picks the platform backing by the Node launcher's
+    // arch, which can differ from this Bun process's under Rosetta.
+    arch: trusted.arch ?? undefined,
     // The snapshot is proof-bound to the launcher, but the report may only attest
     // the environment candidate when the resolver picks the same canonical path —
     // managed requires both.

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/combo-result.ts

@@ -1,4 +1,5 @@
 import { normalizeJevQuotaTiers } from "../combos/jev-quota-config";
+import { normalizeJevSessionPin } from "../combos/jev-session-pin-config";
 import { parseComboTargets } from "./combo-input";
 import { printCatalogResult } from "./catalog-command-result";
 
@@ -39,6 +40,11 @@ function publicCombo(value: unknown): Record<string, unknown> {
       if (!tiers) invalid();
       result[key] = tiers;
       continue;
+    } else if (key === "sessionPin") {
+      const pin = normalizeJevSessionPin(child);
+      if (!pin) invalid();
+      result[key] = pin;
+      continue;
     } else if (key === "nativeAlias" || key === "allowMeteredTargets" || key === "decisionQuotaSignals") {
       if (typeof child !== "boolean") invalid();
     } else invalid();

package/src/cli/combo-stats.ts

@@ -53,6 +53,8 @@ function projectStats(value: unknown, id: string, range: string) {
   const rawSummary = record(dto.summary);
   const summary = {
     ...counts(rawSummary, SUMMARY_COUNTS),
+    // Absent means zero: a proxy started before session pins (#7525) does not report the field.
+    pinnedRequests: Object.hasOwn(rawSummary, "pinnedRequests") ? number(rawSummary.pinnedRequests) : 0,
     averageLatencyMs: nullable(rawSummary.averageLatencyMs),
     averageConfidence: nullable(rawSummary.averageConfidence, 1),
     averageChosenProbability: nullable(rawSummary.averageChosenProbability, 1),
@@ -111,6 +113,7 @@ export async function handleComboStatsCommand(argv: string[], deps: RuntimeApiDe
       `Combo ${id} — JEV observations (${range})`,
       ...(summary.decisions === 0 ? ["No recorded JEV decisions in this window."] : []),
       `Decisions: ${summary.decisions}; applied: ${summary.appliedDecisions}; fail-open: ${summary.failOpenDecisions}`,
+      ...(summary.pinnedRequests > 0 ? [`Session-pinned requests (no decision call): ${summary.pinnedRequests}`] : []),
       `Successful requests: ${summary.successfulRequests}; requests with model fallback: ${summary.requestsWithModelFallback}`,
       `Model tokens: ${summary.modelTotalTokens}; measured attempts: ${summary.measuredModelAttempts}/${summary.modelAttempts}`,
       `Decision tokens: ${summary.decisionTotalTokens}; decisions reporting usage: ${summary.decisionUsageReported}/${summary.decisions}`,

package/src/cli/combo.ts

@@ -1,9 +1,11 @@
 import { normalizeJevQuotaTiers } from "../combos/jev-quota-config";
+import { parseJevSessionPinDuration } from "../combos/jev-session-pin-config";
 import { JEV_DECISION_TIMEOUT_MAX_MS, JEV_DECISION_TIMEOUT_MIN_MS } from "../combos/types";
 import {
   CliUsageError,
   printData,
   rejectArgs,
+  RuntimeApiError,
   runCliAction,
   runtimeRequest,
   runtimeBaseUrl,
@@ -29,6 +31,7 @@ const USAGE = `Usage:
       [--image-input <auto|disabled>] [--reasoning-effort-mode <strict|adaptive>]
       [--decision-provider <provider|-> | --decision-model <route|->] [--decision-timeout <ms|->]
       [--decision-quota-signals <on|off|->] [--decision-quota-tiers <JSON|->]
+      [--session-pin <duration|->] (e.g. 20m; keeps a session on JEV's target while active)
       (jev only; the provider must be a configured jev-decision row)
       [--rename-from <id>] [--json]
   ocx combo stats <id> [--range <7d|30d|all>] [--json]
@@ -39,6 +42,15 @@ const USAGE = `Usage:
   ocx combo discover [--query <text>] [--json]`;
 
 type ComboRow = Record<string, unknown> & { id?: string; model?: string; strategy?: string };
+const STRATEGIES = ["failover", "round-robin", "random", "least-used", "reset-window", "jev"] as const;
+const isComboStrategy = (value: string): value is typeof STRATEGIES[number] => (STRATEGIES as readonly string[]).includes(value);
+// Combo writes print fixed messages instead of server text. When --targets kept a stored JEV
+// strategy the user did not name, a refusal of the targets or a JEV setting says so (#7579).
+const KEPT_JEV_REJECTED = "combo_targets_rejected_by_kept_jev";
+const KEPT_JEV_FIELDS = new Set(["targets", "decisionProvider", "decisionModel", "decisionTimeoutMs", "decisionQuotaSignals", "decisionQuotaTiers", "sessionPin"]);
+const SET_ERRORS = {
+  [KEPT_JEV_REJECTED]: "The selected target rejected the new targets or the kept jev settings. Without --strategy, --targets keeps the stored jev strategy with its decision method, quota policy and session pin, and the save checks the new targets together with them. Inspect the combo with ocx combo show <id> --json, then fix the targets or those settings, or pass --strategy to change the strategy.",
+};
 
 function parseTargets(value: string): Array<{ provider: string; model: string; weight?: number }> {
   const targets = value.split(",").map(part => part.trim()).filter(Boolean).map(part => {
@@ -91,29 +103,17 @@ async function set(argv: string[], deps: RuntimeApiDeps): Promise<number> {
   if (!id) throw new CliUsageError("combo id is required", USAGE);
   const additional = await prepareComboInput(args, deps);
   const targetsRaw = takeOption(args, "--targets");
+  const parsedTargets = targetsRaw === undefined ? undefined : parseTargets(targetsRaw);
   const renameFrom = takeOption(args, "--rename-from");
-  const replacingTargets = targetsRaw !== undefined || additional.targets !== undefined;
-  deps = { ...deps, baseUrl: await runtimeBaseUrl(deps) };
-  // A structured target file replaces the target list, not unrelated combo settings.
-  const partialCurrent = targetsRaw === undefined
-    ? await runtimeRequest<{ combos?: ComboRow[] }>("/api/combos", { redirect: "error" }, deps)
-    : undefined;
-  const partialExisting = partialCurrent?.combos?.find(row => row.id === (renameFrom ?? id));
-  if (!replacingTargets && !partialExisting) {
-    throw new CliUsageError("--targets is required when creating a combo", USAGE);
-  }
+  const replacingTargets = parsedTargets !== undefined || additional.targets !== undefined;
   const strategyRaw = takeOption(args, "--strategy");
-  const strategy = strategyRaw ?? partialExisting?.strategy ?? "failover";
-  if (strategy !== "failover" && strategy !== "round-robin" && strategy !== "random" && strategy !== "least-used" && strategy !== "reset-window" && strategy !== "jev") throw new CliUsageError("--strategy must be failover, round-robin, random, least-used, reset-window, or jev", USAGE);
+  if (strategyRaw !== undefined && !isComboStrategy(strategyRaw)) throw new CliUsageError("--strategy must be failover, round-robin, random, least-used, reset-window, or jev", USAGE);
   const stickyRaw = takeOption(args, "--sticky");
   const stickyLimit = stickyRaw === undefined ? undefined : stickyRaw === "-" ? 1 : Number(stickyRaw);
   if (stickyLimit !== undefined && (!Number.isInteger(stickyLimit) || stickyLimit < 1)) {
     throw new CliUsageError("--sticky must be an integer from 1 to 100, or -", USAGE);
   }
-  if (stickyLimit !== undefined) {
-    if (stickyLimit > 100) throw new CliUsageError("--sticky must be <= 100", USAGE);
-    if (strategy !== "round-robin") throw new CliUsageError("--sticky applies only to round-robin", USAGE);
-  }
+  if (stickyLimit !== undefined && stickyLimit > 100) throw new CliUsageError("--sticky must be <= 100", USAGE);
   const effort = takeOption(args, "--effort");
   const effortMode = takeOption(args, "--effort-mode");
   if (effortMode !== undefined && effortMode !== "fallback" && effortMode !== "force" && effortMode !== "-") {
@@ -128,19 +128,17 @@ async function set(argv: string[], deps: RuntimeApiDeps): Promise<number> {
   if (decisionModel !== undefined && decisionModel !== "-" && decisionProvider !== undefined && decisionProvider !== "-") {
     throw new CliUsageError("--decision-model cannot be combined with --decision-provider", USAGE);
   }
-  if (decisionModel !== undefined && decisionModel !== "-" && strategy !== "jev") {
-    throw new CliUsageError("--decision-model applies only to the jev strategy", USAGE);
-  }
-  if (decisionProvider !== undefined && decisionProvider !== "-" && strategy !== "jev") {
-    throw new CliUsageError("--decision-provider applies only to the jev strategy", USAGE);
-  }
   const quotaSignals = takeOption(args, "--decision-quota-signals");
   const quotaTiers = takeOption(args, "--decision-quota-tiers");
   if (quotaSignals !== undefined && !["on", "off", "-"].includes(quotaSignals)) throw new CliUsageError("--decision-quota-signals must be on, off or -", USAGE);
   let parsedQuotaTiers: ReturnType<typeof normalizeJevQuotaTiers> | null;
   try { parsedQuotaTiers = quotaTiers === undefined || quotaTiers === "-" ? null : normalizeJevQuotaTiers(JSON.parse(quotaTiers)); } catch { throw new CliUsageError("invalid --decision-quota-tiers JSON", USAGE); }
   if (quotaTiers !== undefined && quotaTiers !== "-" && !parsedQuotaTiers) throw new CliUsageError("quota tiers must be finite 0..100 and strictly ascending", USAGE);
-  if (strategy !== "jev" && (quotaSignals !== undefined && quotaSignals !== "-" || quotaTiers !== undefined && quotaTiers !== "-")) throw new CliUsageError("quota settings apply only to jev", USAGE);
+  const sessionPinRaw = takeOption(args, "--session-pin");
+  const sessionPinMs = sessionPinRaw === undefined || sessionPinRaw === "-" ? undefined : parseJevSessionPinDuration(sessionPinRaw);
+  if (sessionPinRaw !== undefined && sessionPinRaw !== "-" && sessionPinMs === undefined) {
+    throw new CliUsageError("--session-pin must be a duration from 1m to 24h (for example 90s, 20m, 1h, or milliseconds), or -", USAGE);
+  }
   const decisionTimeout = takeOption(args, "--decision-timeout");
   let decisionTimeoutMs: number | null | undefined;
   if (decisionTimeout !== undefined) {
@@ -154,19 +152,38 @@ async function set(argv: string[], deps: RuntimeApiDeps): Promise<number> {
         USAGE,
       );
     }
-    if (decisionTimeoutMs !== null && strategy !== "jev") {
-      throw new CliUsageError("--decision-timeout applies only to the jev strategy", USAGE);
-    }
   }
   rejectArgs(args, USAGE);
+  // Flags that belong to one strategy. An explicit --strategy is checked before any request; an
+  // omitted one is the stored strategy, so it is checked once the row has been read.
+  const requireStrategyFlags = (strategy: string): void => {
+    if (stickyLimit !== undefined && strategy !== "round-robin") throw new CliUsageError("--sticky applies only to round-robin", USAGE);
+    if (strategy === "jev") return;
+    if (decisionModel !== undefined && decisionModel !== "-") throw new CliUsageError("--decision-model applies only to the jev strategy", USAGE);
+    if (decisionProvider !== undefined && decisionProvider !== "-") throw new CliUsageError("--decision-provider applies only to the jev strategy", USAGE);
+    if (quotaSignals !== undefined && quotaSignals !== "-" || quotaTiers !== undefined && quotaTiers !== "-") throw new CliUsageError("quota settings apply only to jev", USAGE);
+    if (sessionPinMs !== undefined) throw new CliUsageError("--session-pin applies only to the jev strategy", USAGE);
+    if (decisionTimeoutMs != null) throw new CliUsageError("--decision-timeout applies only to the jev strategy", USAGE);
+  };
+  if (strategyRaw !== undefined) requireStrategyFlags(strategyRaw);
+  deps = { ...deps, baseUrl: await runtimeBaseUrl(deps) };
+  // Replacing targets keeps every other stored setting, including the strategy and its policy (#7579).
+  const current = await runtimeRequest<{ combos?: ComboRow[] }>("/api/combos", { redirect: "error" }, deps);
+  const existing = current.combos?.find(row => row.id === (renameFrom ?? id));
+  if (!replacingTargets && !existing) {
+    throw new CliUsageError("--targets is required when creating a combo", USAGE);
+  }
+  const strategy = strategyRaw ?? existing?.strategy ?? "failover";
+  if (!isComboStrategy(strategy)) throw new CliUsageError(`combo ${renameFrom ?? id} has an unsupported stored strategy; pass --strategy`, USAGE);
+  if (strategyRaw === undefined) requireStrategyFlags(strategy);
   // Listing-only nulls must not be resent as explicit clears (alias rejects null).
-  const combo: Record<string, unknown> = partialExisting
-    ? Object.fromEntries(Object.entries(partialExisting).filter(([, value]) => value !== null))
-    : { strategy, stickyLimit: stickyLimit ?? 1, targets: additional.targets ?? parseTargets(targetsRaw!) };
+  const combo: Record<string, unknown> = existing
+    ? Object.fromEntries(Object.entries(existing).filter(([, value]) => value !== null))
+    : { strategy, stickyLimit: stickyLimit ?? 1 };
   delete combo.id;
   delete combo.model;
-  if (additional.targets !== undefined) combo.targets = additional.targets;
-  if (strategyRaw !== undefined) combo.strategy = strategy;
+  if (replacingTargets) combo.targets = additional.targets ?? parsedTargets;
+  combo.strategy = strategy;
   if (stickyLimit !== undefined) combo.stickyLimit = stickyLimit;
   if (effort !== undefined) combo.defaultEffort = effort === "-" ? null : effort;
   if (effortMode !== undefined) combo.defaultEffortMode = effortMode === "-" ? "fallback" : effortMode;
@@ -184,26 +201,33 @@ async function set(argv: string[], deps: RuntimeApiDeps): Promise<number> {
   if (decisionTimeoutMs !== undefined) combo.decisionTimeoutMs = decisionTimeoutMs;
   if (quotaSignals !== undefined) combo.decisionQuotaSignals = quotaSignals === "-" ? null : quotaSignals === "on";
   if (quotaTiers !== undefined) combo.decisionQuotaTiers = parsedQuotaTiers;
+  if (sessionPinRaw !== undefined) combo.sessionPin = sessionPinMs === undefined ? null : { ttlMs: sessionPinMs };
   if (strategy !== "jev") {
     delete combo.decisionProvider;
     delete combo.decisionModel;
     delete combo.decisionTimeoutMs;
     delete combo.decisionQuotaSignals;
     delete combo.decisionQuotaTiers;
-  }
-  const current = partialCurrent ?? await runtimeRequest<{ combos?: ComboRow[] }>("/api/combos", { redirect: "error" }, deps);
-  const existing = (current.combos ?? []).find(row => row.id === (renameFrom ?? id));
-  if (additional.imageInput === undefined && existing?.imageInput === "disabled") combo.imageInput = "disabled";
-  if (effort === undefined && existing?.defaultEffort != null && combo.defaultEffort === undefined) {
-    combo.defaultEffort = existing.defaultEffort;
+    delete combo.sessionPin;
   }
   if (effortMode === undefined && existing?.defaultEffortMode === "force") {
     combo.defaultEffortMode = effort === "-" ? "fallback" : "force";
   }
-  const result = await runtimeRequest("/api/combos", {
-    method: "PUT", redirect: "error",
-    body: serializeManagementJson({ id, combo, ...(renameFrom ? { renameFrom } : {}) }),
-  }, deps);
+  let result: unknown;
+  try {
+    result = await runtimeRequest("/api/combos", {
+      method: "PUT", redirect: "error",
+      body: serializeManagementJson({ id, combo, ...(renameFrom ? { renameFrom } : {}) }),
+    }, deps);
+  } catch (error) {
+    const field = error instanceof RuntimeApiError && error.body !== null && typeof error.body === "object"
+      ? (error.body as Record<string, unknown>).field : undefined;
+    if (error instanceof RuntimeApiError && error.status === 400 && typeof field === "string" && KEPT_JEV_FIELDS.has(field)
+      && replacingTargets && strategyRaw === undefined && strategy === "jev") {
+      throw new RuntimeApiError(error.message, error.status, { code: KEPT_JEV_REJECTED });
+    }
+    throw error;
+  }
   return printComboWriteResult(result, id, wantsJson);
 }
 
@@ -286,7 +310,7 @@ async function discover(argv: string[], deps: RuntimeApiDeps): Promise<void> {
 
 export async function handleComboCommand(argv: string[], deps: RuntimeApiDeps = {}): Promise<number> {
   const [subcommand, ...writeArgs] = argv;
-  if (subcommand === "set" || subcommand === "create" || subcommand === "update") return runCatalogAction(() => set(writeArgs, deps));
+  if (subcommand === "set" || subcommand === "create" || subcommand === "update") return runCatalogAction(() => set(writeArgs, deps), SET_ERRORS);
   if (subcommand === "stats") {
     const { handleComboStatsCommand } = await import("./combo-stats");
     return handleComboStatsCommand(writeArgs, deps);

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/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> {