oh-my-opencode 5.1.12 → 5.1.14

package/dist/index.js

@@ -4689,7 +4689,11 @@ var init_tool_name = __esm(() => {
 
 // packages/utils/src/replace-tool-args.ts
 function replaceToolArgs(output, patch) {
-  output.args = { ...output.args, ...patch };
+  if (Object.isFrozen(output.args)) {
+    output.args = { ...output.args, ...patch };
+    return;
+  }
+  Object.assign(output.args, patch);
 }
 
 // packages/utils/src/format-duration.ts
@@ -27784,7 +27788,7 @@ var UNSPECIFIED_HIGH_CATEGORY_PROMPT_APPEND = `<Category_Context>
 You are working on tasks that don't fit specific categories but require substantial effort.
 </Category_Context>`;
 var UNSPECIFIED_HIGH_CATEGORY_CALLER_GUIDANCE = `<Selection_Gate>Use only when no specialist category fits and substantial effort spans systems/modules with broad impact. Use unspecified-low for contained moderate work.</Selection_Gate>`;
-var DEEP_LOW_CATEGORY_CALLER_GUIDANCE = `<Selection_Gate>Route here when one subsystem plus its callers holds the mechanism and the evidence, once read, leaves one right answer. Wide but mechanical work belongs here or in a quick batch. When unsure, choose deep-low: a misrouted child returns \`ESCALATE: deep-high\` after one cheap attempt; re-spawn the same brief as deep-high with its findings.</Selection_Gate>`;
+var DEEP_LOW_CATEGORY_CALLER_GUIDANCE = `<Selection_Gate>Of the two deep lanes this is the default: the child settles its decisions from what it reads. When unsure, choose deep-low; a misrouted child returns \`ESCALATE: deep-high\` after one cheap attempt, and you re-spawn the same brief as deep-high with its findings.</Selection_Gate>`;
 var DEEP_HIGH_CATEGORY_CALLER_GUIDANCE = `<Selection_Gate>Route here only when you can name the decision evidence cannot settle: a trade-off with no single right answer, a contract change crossing a package or process boundary, a mechanism with no in-repo pattern to copy, or correctness argued from invariants rather than observed in a test. Wide scope with easy decisions is deep-low or unspecified-high; reasoning as the deliverable is ultrabrain.</Selection_Gate>`;
 var DEEP_LOW_GATE_MODELS = ["gpt-6.1-sol", "gpt-6.1-sol-fast", "gpt-5.6-sol-fast", "gpt-5.6-sol"];
 var DEEP_HIGH_GATE_MODEL = "gpt-6-astra";
@@ -27799,7 +27803,7 @@ var OPENAI_CATEGORIES = [
   {
     name: "deep-low",
     config: { model: "openai/gpt-6.1-sol", variant: "medium" },
-    description: "Default deep lane: one goal, one deliverable, decisions the child can settle from what it reads. **3D graphics, computer/browser use, CAPTCHA, multimodal, backend, logic, and algorithm work is routed here.** Multiple goals fan out as parallel calls.",
+    description: "Default deep lane: one goal, one deliverable, decisions the child can settle from what it reads; preferred over deep-high for 3D graphics, computer/browser use, CAPTCHA, multimodal, backend, logic, and algorithm work. Multiple goals fan out as parallel calls.",
     callerGuidance: DEEP_LOW_CATEGORY_CALLER_GUIDANCE,
     promptAppend: DEEP_LOW_CATEGORY_PROMPT_APPEND,
     resolvePromptAppend: resolveDeepLowCategoryPromptAppend,
@@ -98582,7 +98586,7 @@ function getCachedVersion(options = {}) {
 // package.json
 var package_default = {
   name: "oh-my-opencode",
-  version: "5.1.12",
+  version: "5.1.14",
   description: "The Best AI Agent Harness - Batteries-Included OpenCode Plugin with Multi-Model Orchestration, Parallel Background Agents, and Crafted LSP/AST Tools",
   main: "./dist/index.js",
   types: "dist/index.d.ts",
@@ -98759,7 +98763,7 @@ var package_default = {
   },
   devDependencies: {
     "@clack/prompts": "^1.8.1",
-    "@code-yeongyu/senpi": "2026.10.2",
+    "@code-yeongyu/senpi": "2026.10.5",
     "@modelcontextprotocol/sdk": "^1.30.0",
     "@oh-my-opencode/agents-md-core": "workspace:*",
     "@oh-my-opencode/ast-grep-mcp": "workspace:*",
@@ -98817,18 +98821,18 @@ var package_default = {
     typescript: "^7.0.2"
   },
   optionalDependencies: {
-    "oh-my-opencode-darwin-arm64": "5.1.12",
-    "oh-my-opencode-darwin-x64": "5.1.12",
-    "oh-my-opencode-darwin-x64-baseline": "5.1.12",
-    "oh-my-opencode-linux-arm64": "5.1.12",
-    "oh-my-opencode-linux-arm64-musl": "5.1.12",
-    "oh-my-opencode-linux-x64": "5.1.12",
-    "oh-my-opencode-linux-x64-baseline": "5.1.12",
-    "oh-my-opencode-linux-x64-musl": "5.1.12",
-    "oh-my-opencode-linux-x64-musl-baseline": "5.1.12",
-    "oh-my-opencode-windows-arm64": "5.1.12",
-    "oh-my-opencode-windows-x64": "5.1.12",
-    "oh-my-opencode-windows-x64-baseline": "5.1.12"
+    "oh-my-opencode-darwin-arm64": "5.1.14",
+    "oh-my-opencode-darwin-x64": "5.1.14",
+    "oh-my-opencode-darwin-x64-baseline": "5.1.14",
+    "oh-my-opencode-linux-arm64": "5.1.14",
+    "oh-my-opencode-linux-arm64-musl": "5.1.14",
+    "oh-my-opencode-linux-x64": "5.1.14",
+    "oh-my-opencode-linux-x64-baseline": "5.1.14",
+    "oh-my-opencode-linux-x64-musl": "5.1.14",
+    "oh-my-opencode-linux-x64-musl-baseline": "5.1.14",
+    "oh-my-opencode-windows-arm64": "5.1.14",
+    "oh-my-opencode-windows-x64": "5.1.14",
+    "oh-my-opencode-windows-x64-baseline": "5.1.14"
   },
   overrides: {
     hono: "^4.13.8",
@@ -107944,11 +107948,17 @@ var TOAST_MESSAGE = [
   "For other GPT models, always use Hephaestus."
 ].join(`
 `);
-function showToast(ctx, sessionID) {
+var HEPHAESTUS_UNAVAILABLE_TOAST_MESSAGE = [
+  "Sisyphus is running with a GPT model it has no native prompt for.",
+  "Hephaestus is not available in this session (disabled, or its configured model is not a supported GPT model), so the agent was not switched.",
+  "Use a Claude, Kimi, or GLM model for Sisyphus, or enable Hephaestus with a supported GPT model."
+].join(`
+`);
+function showToast(ctx, sessionID, message) {
   ctx.client.tui.showToast({
     body: {
       title: TOAST_TITLE,
-      message: TOAST_MESSAGE,
+      message,
       variant: "error",
       duration: 1e4
     }
@@ -107984,10 +107994,19 @@ function createNoSisyphusGptHook(ctx) {
         }
       }
       if (agentKey === "sisyphus" && modelID && isGptModel(modelID) && !isGptNativeSisyphusModel(modelID) && !isGpt6Model(modelID)) {
-        showToast(ctx, input.sessionID);
-        input.agent = resolveRegisteredAgentName("hephaestus") ?? "hephaestus";
+        if (!isAgentRegistered("hephaestus")) {
+          showToast(ctx, input.sessionID, HEPHAESTUS_UNAVAILABLE_TOAST_MESSAGE);
+          log2("[no-sisyphus-gpt] Hephaestus is not registered; keeping Sisyphus instead of redirecting", {
+            sessionID: input.sessionID,
+            modelID
+          });
+          return;
+        }
+        const hephaestusAgent = resolveRegisteredAgentName("hephaestus") ?? "hephaestus";
+        showToast(ctx, input.sessionID, TOAST_MESSAGE);
+        input.agent = hephaestusAgent;
         if (output?.message) {
-          output.message.agent = resolveRegisteredAgentName("hephaestus") ?? "hephaestus";
+          output.message.agent = hephaestusAgent;
         }
         updateSessionAgent(input.sessionID, "hephaestus");
       }
@@ -108472,11 +108491,18 @@ var SCOPE_PRIORITY = {
   config: 1,
   builtin: 1
 };
+function compareCodeUnits(left, right) {
+  if (left < right)
+    return -1;
+  if (left > right)
+    return 1;
+  return 0;
+}
 function sortByScopePriority(items) {
   return [...items].sort((left, right) => {
     const leftPriority = SCOPE_PRIORITY[left.scope] || 0;
     const rightPriority = SCOPE_PRIORITY[right.scope] || 0;
-    return rightPriority - leftPriority;
+    return rightPriority - leftPriority || compareCodeUnits(left.name, right.name);
   });
 }
 
@@ -129572,6 +129598,7 @@ function resolveModelAndFallbackChain(args) {
   const agentOverride = agentOverrides?.[agentConfigKey] ?? (agentOverrides ? Object.entries(agentOverrides).find(([key]) => key.toLowerCase() === agentConfigKey)?.[1] : undefined);
   const agentCategoryModel = agentOverride?.category ? userCategories?.[agentOverride.category]?.model : undefined;
   const agentCategoryVariant = agentOverride?.category ? userCategories?.[agentOverride.category]?.variant : undefined;
+  const hasExplicitUserModel = Boolean(agentOverride?.model ?? agentCategoryModel);
   let model;
   if (agentOverride?.model) {
     const normalized = parseModelString(agentOverride.model);
@@ -129614,7 +129641,7 @@ function resolveModelAndFallbackChain(args) {
   const configuredFallbackChain = buildFallbackChainFromModels(normalizedFallbackModels, defaultProviderID);
   return {
     model,
-    fallbackChain: configuredFallbackChain ?? agentRequirement?.fallbackChain
+    fallbackChain: configuredFallbackChain ?? (hasExplicitUserModel ? undefined : agentRequirement?.fallbackChain)
   };
 }
 function createCallOmoAgent(ctx, backgroundManager, disabledAgents = [], agentOverrides, userCategories, modelFallbackControllerAccessor) {
@@ -137200,6 +137227,31 @@ function isEmptyNoProgressAssistantTurnInfo(info) {
   return !!infoRecord && infoRecord.role === "assistant" && infoRecord.finish === "unknown" && allTokenCountsIndicateNoProgress(infoRecord.tokens);
 }
 
+// packages/omo-opencode/src/features/background-agent/fallback-provider-model-filter.ts
+function canonicalizeModelID2(modelID) {
+  return modelID.toLowerCase().replace(/\./g, "-");
+}
+function providerListsModel(providerModels, modelID) {
+  const wanted = canonicalizeModelID2(modelID);
+  return providerModels.some((entry) => {
+    const id = typeof entry === "string" ? entry : entry.id;
+    return canonicalizeModelID2(id) === wanted;
+  });
+}
+function filterProvidersServingModel(args) {
+  const { providers, model, connectedSet, modelsByProvider, transformModelForProvider } = args;
+  if (!connectedSet || !modelsByProvider)
+    return providers;
+  return providers.filter((provider) => {
+    if (!connectedSet.has(provider.toLowerCase()))
+      return true;
+    const providerModels = modelsByProvider[provider];
+    if (!providerModels || providerModels.length === 0)
+      return true;
+    return providerListsModel(providerModels, transformModelForProvider(provider, model));
+  });
+}
+
 // packages/omo-opencode/src/features/background-agent/fallback-retry-handler.ts
 class TeamModeFallbackError extends Error {
   constructor(message) {
@@ -137207,7 +137259,7 @@ class TeamModeFallbackError extends Error {
     this.name = "TeamModeFallbackError";
   }
 }
-function canonicalizeModelID2(modelID) {
+function canonicalizeModelID3(modelID) {
   return modelID.toLowerCase().replace(/\./g, "-");
 }
 var defaultFallbackRetryHandlerDeps = {
@@ -137255,9 +137307,25 @@ async function tryFallbackRetry(args) {
       });
       continue;
     }
-    const candidateProviderID = deps.selectFallbackProvider(candidate.providers, task.model?.providerID);
+    const servingProviders = filterProvidersServingModel({
+      providers: candidate.providers,
+      model: candidate.model,
+      connectedSet,
+      modelsByProvider: providerModelsCache?.models,
+      transformModelForProvider: deps.transformModelForProvider
+    });
+    if (!isReachable({ ...candidate, providers: servingProviders })) {
+      deps.log("[background-agent] Skipping fallback no connected provider serves:", {
+        taskId: task.id,
+        source,
+        model: candidate.model,
+        providers: candidate.providers
+      });
+      continue;
+    }
+    const candidateProviderID = deps.selectFallbackProvider(servingProviders, task.model?.providerID);
     const candidateModelID = deps.transformModelForProvider(candidateProviderID, candidate.model);
-    const isNoOpFallback = !!task.model && candidateProviderID.toLowerCase() === task.model.providerID.toLowerCase() && canonicalizeModelID2(candidateModelID) === canonicalizeModelID2(task.model.modelID);
+    const isNoOpFallback = !!task.model && candidateProviderID.toLowerCase() === task.model.providerID.toLowerCase() && canonicalizeModelID3(candidateModelID) === canonicalizeModelID3(task.model.modelID);
     if (isNoOpFallback) {
       deps.log("[background-agent] Skipping no-op fallback:", {
         taskId: task.id,
@@ -138862,6 +138930,29 @@ async function verifySessionExists(client, sessionID, directory) {
   return await checkSessionExistence(client, sessionID, directory) !== "missing";
 }
 
+// packages/omo-opencode/src/features/background-agent/session-stopped-on-error.ts
+var MIN_ERRORED_IDLE_POLLS = 10;
+function describeSessionError(error) {
+  if (!isRecord9(error)) {
+    return String(error);
+  }
+  const data = isRecord9(error.data) ? error.data : undefined;
+  const message = typeof data?.message === "string" ? data.message : typeof error.message === "string" ? error.message : undefined;
+  const name = typeof error.name === "string" ? error.name : undefined;
+  return [name, message].filter((value) => Boolean(value)).join(": ") || "unknown error";
+}
+function getStoppedSessionError(messages) {
+  const latest = messages[messages.length - 1];
+  if (latest?.info?.role !== "assistant") {
+    return;
+  }
+  const error = latest.info.error;
+  if (error === undefined || error === null) {
+    return;
+  }
+  return describeSessionError(error);
+}
+
 // packages/omo-opencode/src/features/background-agent/session-idle-event-handler.ts
 function handleSessionIdleBackgroundEvent(args) {
   const {
@@ -141466,6 +141557,18 @@ The task was re-queued on a fallback model after a retryable failure.
       return true;
     }
   }
+  async readStoppedSessionError(sessionID) {
+    try {
+      const response = await messagesInDirectory(this.client, {
+        path: { id: sessionID }
+      }, this.directory);
+      const messages = normalizeSDKResponse(response, [], { preferResponseOnMissingData: true });
+      return getStoppedSessionError(messages);
+    } catch (error) {
+      log2("[background-agent] Error reading session messages for stopped-session check:", error);
+      return;
+    }
+  }
   clearNotificationsForTask(taskId) {
     for (const [sessionID, tasks] of this.notifications.entries()) {
       const filtered = tasks.filter((t) => t.id !== taskId);
@@ -142036,6 +142139,7 @@ The task was re-queued on a fallback model after a retryable failure.
             }
           }
           if (sessionStatus && isActiveSessionStatus2(sessionStatus.type)) {
+            task.consecutiveErroredIdlePolls = 0;
             log2("[background-agent] Session still running, relying on event-based progress:", {
               taskId: task.id,
               sessionID,
@@ -142072,6 +142176,21 @@ The task was re-queued on a fallback model after a retryable failure.
               }
               task.consecutiveMissedPolls = 0;
             }
+            const stoppedError = await this.readStoppedSessionError(sessionID);
+            if (stoppedError) {
+              task.consecutiveErroredIdlePolls = (task.consecutiveErroredIdlePolls ?? 0) + 1;
+              if (task.consecutiveErroredIdlePolls >= MIN_ERRORED_IDLE_POLLS) {
+                log2("[background-agent] Session stopped on an error with no output and was not resumed, marking task as error:", {
+                  taskId: task.id,
+                  sessionID,
+                  error: stoppedError.slice(0, 200)
+                });
+                await this.failCrashedTask(task, `Subagent session stopped on an error without producing output: ${stoppedError}`);
+                continue;
+              }
+            } else {
+              task.consecutiveErroredIdlePolls = 0;
+            }
             log2("[background-agent] Polling idle/gone but no valid output yet, waiting:", task.id);
             continue;
           }
@@ -186629,10 +186748,14 @@ function resolveOsProvider() {
 function resolveTransportFactory() {
   return transportFactoryOverride ?? createDefaultPostHogTransport;
 }
+var PLUGIN_TRANSPORT_OPTIONS = { flushAt: 20 };
 var NO_OP_POSTHOG = {
   trackActive: () => {
     return;
   },
+  flush: async () => {
+    return;
+  },
   shutdown: async () => {
     return;
   }
@@ -186669,6 +186792,16 @@ function logTelemetryDiagnostic(input) {
     source: input.source
   });
 }
+function createProductConfig(source) {
+  const product = createOpencodeTelemetryProductConfig();
+  if (source !== "plugin") {
+    return product;
+  }
+  return {
+    ...product,
+    transportOptions: { ...product.transportOptions, ...PLUGIN_TRANSPORT_OPTIONS }
+  };
+}
 function createPostHogClient(source, options = {}) {
   const env = process.env;
   if (shouldDisablePostHog(env, options.configEnabled)) {
@@ -186678,7 +186811,7 @@ function createPostHogClient(source, options = {}) {
     diagnostics: logTelemetryDiagnostic,
     env: createCoreCompatibleTelemetryEnv(env),
     osProvider: resolveOsProvider(),
-    product: createOpencodeTelemetryProductConfig(),
+    product: createProductConfig(source),
     source,
     transportFactory: resolveTransportFactory()
   });
@@ -186697,6 +186830,17 @@ function createPostHogClient(source, options = {}) {
         reason
       });
     },
+    flush: async () => {
+      try {
+        await client.flush();
+      } catch (error) {
+        log2("[posthog] telemetry flush failed", {
+          error: String(error),
+          errorKind: error instanceof Error ? "error" : "non_error",
+          source
+        });
+      }
+    },
     shutdown: async () => {
       await client.shutdown();
     }
@@ -186712,7 +186856,7 @@ function recordPluginTelemetry(input) {
   const posthog = createPluginPostHog({ configEnabled: input.configEnabled });
   const distinctId = getPostHogDistinctId();
   posthog.trackActive(distinctId, "plugin_loaded");
-  posthog.shutdown();
+  posthog.flush();
 }
 
 // packages/omo-opencode/src/testing/create-plugin-module.ts

package/dist/oh-my-opencode.schema.json

@@ -8898,10 +8898,6 @@
                   "maximum": 10
                 }
               },
-              "required": [
-                "enabled",
-                "turns"
-              ],
               "additionalProperties": false
             },
             "protected_tools": {
@@ -8930,9 +8926,6 @@
                       "type": "boolean"
                     }
                   },
-                  "required": [
-                    "enabled"
-                  ],
                   "additionalProperties": false
                 },
                 "supersede_writes": {
@@ -8947,10 +8940,6 @@
                       "type": "boolean"
                     }
                   },
-                  "required": [
-                    "enabled",
-                    "aggressive"
-                  ],
                   "additionalProperties": false
                 },
                 "purge_errors": {
@@ -8967,21 +8956,12 @@
                       "maximum": 20
                     }
                   },
-                  "required": [
-                    "enabled",
-                    "turns"
-                  ],
                   "additionalProperties": false
                 }
               },
               "additionalProperties": false
             }
           },
-          "required": [
-            "enabled",
-            "notification",
-            "protected_tools"
-          ],
           "additionalProperties": false
         },
         "task_system": {
@@ -9146,11 +9126,6 @@
           "maximum": 1000
         }
       },
-      "required": [
-        "enabled",
-        "auto_start",
-        "default_max_iterations"
-      ],
       "additionalProperties": false
     },
     "ralph_loop": {
@@ -9366,10 +9341,6 @@
                 "type": "number"
               }
             },
-            "required": [
-              "type",
-              "method"
-            ],
             "additionalProperties": false
           }
         },
@@ -9394,7 +9365,6 @@
               }
             },
             "required": [
-              "enabled",
               "gateway",
               "instruction"
             ],
@@ -9443,21 +9413,9 @@
               "type": "boolean"
             }
           },
-          "required": [
-            "authorizedDiscordUserIds",
-            "pollIntervalMs",
-            "rateLimitPerMinute",
-            "maxMessageLength",
-            "includePrefix"
-          ],
           "additionalProperties": false
         }
       },
-      "required": [
-        "enabled",
-        "gateways",
-        "hooks"
-      ],
       "additionalProperties": false
     },
     "i18n": {
@@ -9535,18 +9493,6 @@
           "maximum": 9007199254740991
         }
       },
-      "required": [
-        "enabled",
-        "live_mode_enabled",
-        "max_monitors_per_session",
-        "max_runtime_ms",
-        "batch_max_lines",
-        "batch_max_bytes",
-        "flush_interval_ms",
-        "ring_max_lines",
-        "line_max_bytes",
-        "pattern_max_length"
-      ],
       "additionalProperties": false
     },
     "team_mode": {
@@ -9612,18 +9558,6 @@
           "maximum": 9007199254740991
         }
       },
-      "required": [
-        "enabled",
-        "tmux_visualization",
-        "max_parallel_members",
-        "max_members",
-        "max_messages_per_run",
-        "max_wall_clock_minutes",
-        "max_member_turns",
-        "message_payload_max_bytes",
-        "recipient_unread_max_bytes",
-        "mailbox_poll_interval_ms"
-      ],
       "additionalProperties": false
     },
     "keyword_detector": {
@@ -9664,9 +9598,6 @@
           "type": "number"
         }
       },
-      "required": [
-        "timeout_ms"
-      ],
       "additionalProperties": false
     },
     "git_master": {
@@ -9693,11 +9624,6 @@
           "type": "string"
         }
       },
-      "required": [
-        "commit_footer",
-        "include_co_authored_by",
-        "git_env_prefix"
-      ],
       "additionalProperties": false
     },
     "browser_automation_engine": {
@@ -9719,9 +9645,6 @@
           }
         }
       },
-      "required": [
-        "provider"
-      ],
       "additionalProperties": false
     },
     "websearch": {
@@ -9781,14 +9704,6 @@
           ]
         }
       },
-      "required": [
-        "enabled",
-        "layout",
-        "main_pane_size",
-        "main_pane_min_width",
-        "agent_pane_min_width",
-        "isolation"
-      ],
       "additionalProperties": false
     },
     "tui": {
@@ -9810,15 +9725,9 @@
               "type": "boolean"
             }
           },
-          "required": [
-            "enabled"
-          ],
           "additionalProperties": false
         }
       },
-      "required": [
-        "sidebar"
-      ],
       "additionalProperties": false
     },
     "sisyphus": {
@@ -9838,9 +9747,6 @@
               "type": "boolean"
             }
           },
-          "required": [
-            "claude_code_compat"
-          ],
           "additionalProperties": false
         }
       },
@@ -9854,9 +9760,6 @@
           "type": "boolean"
         }
       },
-      "required": [
-        "auto_commit"
-      ],
       "additionalProperties": false
     },
     "start_work": {
@@ -9867,9 +9770,6 @@
           "type": "boolean"
         }
       },
-      "required": [
-        "auto_commit"
-      ],
       "additionalProperties": false
     },
     "default_mode": {
@@ -9884,10 +9784,6 @@
           "type": "boolean"
         }
       },
-      "required": [
-        "ultrawork",
-        "goal"
-      ],
       "additionalProperties": false
     },
     "_migrations": {
@@ -9897,8 +9793,5 @@
       }
     }
   },
-  "required": [
-    "git_master"
-  ],
   "additionalProperties": false
 }

package/dist/shared/posthog.d.ts

@@ -14,6 +14,7 @@ export type PostHogSource = "cli" | "plugin";
 export type PostHogActivityReason = "run_started" | "plugin_loaded";
 export type PostHogClient = {
     readonly trackActive: (distinctId: string, reason: PostHogActivityReason) => void;
+    readonly flush: () => Promise<void>;
     readonly shutdown: () => Promise<void>;
 };
 type CreatePostHogOptions = {

package/dist/skills/browser/SKILL.md

@@ -18,7 +18,31 @@ one where a human is a single call away. Never substitute one engine for the oth
 the attached engine is not set up, run the onboarding script and tell the user its one remaining
 step.
 
-## Step 0 — load omowright and prove the stack
+## Step 0 — which engine this session is allowed to use
+
+When `OMO_BROWSER_ENGINE` is set (the OmO desktop app sets it for every session), it wins over the table above:
+
+| Value | What you do |
+|---|---|
+| `connected` | Use `connectBrowserSkill()` only. If the user's browser is not connected you get a "Connect your browser" error: relay it and stop. Never open another browser |
+| `builtin` | Do not call `connectBrowserSkill()`; use the app's in-app browser tools |
+| `none` | Do not do browser work. Say that agent browser access is off for this project |
+| unset | The table above, as before (terminal use) |
+
+While any engine is set, `loadOmowright()` returns a guarded library. The owned engine (`connectPipe`,
+`connectCloakProfile`, `connect`) and every other export that acts on a browser is refused, so the table above
+does not apply: do not look for a way around it, and tell the user what the session allows. Under `connected`
+the app sees what the browser is doing, and before a click, Enter or script that sends, posts, pays, orders,
+subscribes, deletes or closes an account, and before Enter in a message box, it asks the user first. A "No" fails the action with
+`BrowserActionDeclinedError`: report that, never retry it or go around it (`session.tool()` lets only reads
+through; `evaluate` is guarded too). If the user presses Stop, the next call throws `BrowserUserStoppedError`: tell
+the user browser use was stopped and start no new session this turn.
+
+The guard prevents mistakes by a cooperating agent. It is not a security boundary: code that imports the raw
+entry (`resolveOmowrightEntry()`) is not guarded, and a host without the `omo_browser_bridge` tool cannot show state or
+honor Stop, though questions are still asked.
+
+## Step 1 — load omowright and prove the stack
 
 ```js
 const { loadOmowright } = await import("<skill-root>/scripts/omowright.mjs")
@@ -94,7 +118,7 @@ changing the extension's automation settings.
   out everywhere. No flow here needs it.
 - **`focused: false` by default.** The browser belongs to someone who is probably using it.
 - **One short, named session per task,** always stopped.
-- **Bot-scored or WAF targets go to the owned engine.** The attached engine's daemon enables console
+- **Bot-scored or WAF targets go to the owned engine** (not while `OMO_BROWSER_ENGINE` is set: then say the site needs a browser the session does not allow). The attached engine's daemon enables console
   capture on every tab it drives, which is a known automation signal; CloakBrowser through
   `connectCloakProfile()` is the stealth path.