Merge pull request #3309 from code-yeongyu/fix/pre-publish-blocking-issues

fix: resolve pre-publish blocking issues for v3.17.0

src/agents/builtin-agents/hephaestus-agent.ts

@@ -7,6 +7,7 @@ import { createHephaestusAgent } from "../hephaestus"
 import { applyEnvironmentContext } from "./environment-context"
 import { applyCategoryOverride, mergeAgentConfig } from "./agent-overrides"
 import { applyModelResolution, getFirstFallbackModel } from "./model-resolution"
+import { getGptApplyPatchPermission } from "../gpt-apply-patch-guard"
 
 export function maybeCreateHephaestusConfig(input: {
   disabledAgents: string[]
@@ -86,5 +87,12 @@ export function maybeCreateHephaestusConfig(input: {
   if (hephaestusOverride) {
     hephaestusConfig = mergeAgentConfig(hephaestusConfig, hephaestusOverride, directory)
   }
+
+  const resolvedModel = hephaestusConfig.model ?? ""
+  const gptDeny = getGptApplyPatchPermission(resolvedModel)
+  if (Object.keys(gptDeny).length > 0 && hephaestusConfig.permission) {
+    Object.assign(hephaestusConfig.permission, gptDeny)
+  }
+
   return hephaestusConfig
 }

src/agents/builtin-agents/sisyphus-agent.test.ts

@@ -0,0 +1,109 @@
+import { describe, expect, test } from "bun:test";
+import { maybeCreateSisyphusConfig } from "./sisyphus-agent";
+import type { AgentOverrides } from "../types";
+import type { CategoryConfig } from "../../config/schema";
+
+describe("maybeCreateSisyphusConfig", () => {
+  describe("#given GPT model with user override allowing apply_patch", () => {
+    test("#when config is created #then apply_patch is still denied", () => {
+      // given
+      const agentOverrides: AgentOverrides = {
+        sisyphus: {
+          model: "openai/gpt-5.4",
+          permission: {
+            apply_patch: "allow",
+          },
+        },
+      };
+      const mergedCategories: Record<string, CategoryConfig> = {};
+
+      // when
+      const config = maybeCreateSisyphusConfig({
+        disabledAgents: [],
+        agentOverrides,
+        availableModels: new Set(["openai/gpt-5.4"]),
+        systemDefaultModel: "openai/gpt-5.4",
+        isFirstRunNoCache: false,
+        availableAgents: [],
+        availableSkills: [],
+        availableCategories: [],
+        mergedCategories,
+        useTaskSystem: false,
+      });
+
+      // then
+      expect(config).toBeDefined();
+      expect(config?.model).toBe("openai/gpt-5.4");
+      expect(config?.permission).toHaveProperty("apply_patch", "deny");
+    });
+  });
+
+  describe("#given non-GPT model with user override", () => {
+    test("#when config is created #then apply_patch is not forced to deny", () => {
+      // given
+      const agentOverrides: AgentOverrides = {
+        sisyphus: {
+          model: "anthropic/claude-opus-4-6",
+          permission: {
+            apply_patch: "allow",
+          },
+        },
+      };
+      const mergedCategories: Record<string, CategoryConfig> = {};
+
+      // when
+      const config = maybeCreateSisyphusConfig({
+        disabledAgents: [],
+        agentOverrides,
+        availableModels: new Set(["anthropic/claude-opus-4-6"]),
+        systemDefaultModel: "anthropic/claude-opus-4-6",
+        isFirstRunNoCache: false,
+        availableAgents: [],
+        availableSkills: [],
+        availableCategories: [],
+        mergedCategories,
+        useTaskSystem: false,
+      });
+
+      // then
+      expect(config).toBeDefined();
+      expect(config?.model).toBe("anthropic/claude-opus-4-6");
+      // Claude models should allow the user override
+      expect(config?.permission).toHaveProperty("apply_patch", "allow");
+    });
+  });
+
+  describe("#given generic GPT model with user override allowing apply_patch", () => {
+    test("#when config is created #then apply_patch is still denied", () => {
+      // given
+      const agentOverrides: AgentOverrides = {
+        sisyphus: {
+          model: "openai/gpt-4o",
+          permission: {
+            apply_patch: "allow",
+          },
+        },
+      };
+      const mergedCategories: Record<string, CategoryConfig> = {};
+
+      // when
+      const config = maybeCreateSisyphusConfig({
+        disabledAgents: [],
+        agentOverrides,
+        availableModels: new Set(["openai/gpt-4o"]),
+        systemDefaultModel: "openai/gpt-4o",
+        isFirstRunNoCache: false,
+        availableAgents: [],
+        availableSkills: [],
+        availableCategories: [],
+        mergedCategories,
+        useTaskSystem: false,
+      });
+
+      // then
+      expect(config).toBeDefined();
+      expect(config?.model).toBe("openai/gpt-4o");
+      expect(config?.permission).toHaveProperty("apply_patch", "deny");
+    });
+  });
+});

src/agents/builtin-agents/sisyphus-agent.ts

@@ -7,6 +7,7 @@ import { applyEnvironmentContext } from "./environment-context"
 import { applyOverrides } from "./agent-overrides"
 import { applyModelResolution, getFirstFallbackModel } from "./model-resolution"
 import { createSisyphusAgent } from "../sisyphus"
+import { getGptApplyPatchPermission } from "../gpt-apply-patch-guard"
 
 export function maybeCreateSisyphusConfig(input: {
   disabledAgents: string[]
@@ -80,6 +81,13 @@ export function maybeCreateSisyphusConfig(input: {
   }
 
   sisyphusConfig = applyOverrides(sisyphusConfig, sisyphusOverride, mergedCategories, directory)
+
+  const resolvedModel = sisyphusConfig.model ?? ""
+  const gptDeny = getGptApplyPatchPermission(resolvedModel)
+  if (Object.keys(gptDeny).length > 0 && sisyphusConfig.permission) {
+    Object.assign(sisyphusConfig.permission, gptDeny)
+  }
+
   sisyphusConfig = applyEnvironmentContext(sisyphusConfig, directory, {
     disableOmoEnv,
   })

src/agents/hephaestus/agent.test.ts

@@ -277,3 +277,111 @@ describe("createHephaestusAgent", () => {
     expect(config.prompt).not.toContain("task_create");
   });
 });
+
+import { maybeCreateHephaestusConfig } from "../builtin-agents/hephaestus-agent";
+import type { AgentOverrides } from "../types";
+import type { CategoryConfig } from "../../config/schema";
+
+describe("maybeCreateHephaestusConfig GPT apply_patch guard", () => {
+  describe("#given GPT model with user override allowing apply_patch", () => {
+    test("#when config is created #then apply_patch is still denied", () => {
+      // given
+      const agentOverrides: AgentOverrides = {
+        hephaestus: {
+          model: "openai/gpt-5.4",
+          permission: {
+            apply_patch: "allow",
+          },
+        },
+      };
+      const mergedCategories: Record<string, CategoryConfig> = {};
+
+      // when
+      const config = maybeCreateHephaestusConfig({
+        disabledAgents: [],
+        agentOverrides,
+        availableModels: new Set(["openai/gpt-5.4"]),
+        systemDefaultModel: "openai/gpt-5.4",
+        isFirstRunNoCache: false,
+        availableAgents: [],
+        availableSkills: [],
+        availableCategories: [],
+        mergedCategories,
+        useTaskSystem: false,
+      });
+
+      // then
+      expect(config).toBeDefined();
+      expect(config?.model).toBe("openai/gpt-5.4");
+      expect(config?.permission).toHaveProperty("apply_patch", "deny");
+    });
+  });
+
+  describe("#given non-GPT model with user override allowing apply_patch", () => {
+    test("#when config is created #then user override is respected", () => {
+      // given
+      const agentOverrides: AgentOverrides = {
+        hephaestus: {
+          model: "anthropic/claude-opus-4-6",
+          permission: {
+            apply_patch: "allow",
+          },
+        },
+      };
+      const mergedCategories: Record<string, CategoryConfig> = {};
+
+      // when
+      const config = maybeCreateHephaestusConfig({
+        disabledAgents: [],
+        agentOverrides,
+        availableModels: new Set(["anthropic/claude-opus-4-6"]),
+        systemDefaultModel: "anthropic/claude-opus-4-6",
+        isFirstRunNoCache: false,
+        availableAgents: [],
+        availableSkills: [],
+        availableCategories: [],
+        mergedCategories,
+        useTaskSystem: false,
+      });
+
+      // then
+      expect(config).toBeDefined();
+      expect(config?.model).toBe("anthropic/claude-opus-4-6");
+      expect(config?.permission).toHaveProperty("apply_patch", "allow");
+    });
+  });
+
+  describe("#given generic GPT model with user override allowing apply_patch", () => {
+    test("#when config is created #then apply_patch is still denied", () => {
+      // given
+      const agentOverrides: AgentOverrides = {
+        hephaestus: {
+          model: "openai/gpt-4o",
+          permission: {
+            apply_patch: "allow",
+          },
+        },
+      };
+      const mergedCategories: Record<string, CategoryConfig> = {};
+
+      // when
+      const config = maybeCreateHephaestusConfig({
+        disabledAgents: [],
+        agentOverrides,
+        availableModels: new Set(["openai/gpt-4o"]),
+        systemDefaultModel: "openai/gpt-4o",
+        isFirstRunNoCache: false,
+        availableAgents: [],
+        availableSkills: [],
+        availableCategories: [],
+        mergedCategories,
+        useTaskSystem: false,
+      });
+
+      // then
+      expect(config).toBeDefined();
+      expect(config?.model).toBe("openai/gpt-4o");
+      expect(config?.permission).toHaveProperty("apply_patch", "deny");
+    });
+  });
+});

src/hooks/keyword-detector/index.test.ts

@@ -1,4 +1,5 @@
 import { describe, expect, test, beforeEach, afterEach, spyOn } from "bun:test"
+import type { PluginInput } from "@opencode-ai/plugin"
 import { createKeywordDetectorHook } from "./index"
 import { setMainSession, updateSessionAgent, clearSessionAgent, _resetForTesting } from "../../features/claude-code-session-state"
 import { ContextCollector } from "../../features/context-injector"
@@ -31,7 +32,7 @@ describe("keyword-detector message transform", () => {
           showToast: async () => {},
         },
       },
-    } as any
+    } as unknown as PluginInput
   }
 
   test("should prepend ultrawork message to text part", async () => {
@@ -119,12 +120,12 @@ describe("keyword-detector session filtering", () => {
     return {
       client: {
         tui: {
-          showToast: async (opts: any) => {
+          showToast: async (opts: { body: { title: string } }) => {
             toastCalls.push(opts.body.title)
           },
         },
       },
-    } as any
+    } as unknown as PluginInput
   }
 
   test("should skip non-ultrawork keywords in non-main session (using mainSessionID check)", async () => {
@@ -264,12 +265,12 @@ describe("keyword-detector word boundary", () => {
     return {
       client: {
         tui: {
-          showToast: async (opts: any) => {
+          showToast: async (opts: { body: { title: string } }) => {
             toastCalls.push(opts.body.title)
           },
         },
       },
-    } as any
+    } as unknown as PluginInput
   }
 
   test("should NOT trigger ultrawork on partial matches like 'StatefulWidget' containing 'ulw'", async () => {
@@ -363,7 +364,7 @@ describe("keyword-detector system-reminder filtering", () => {
           showToast: async () => {},
         },
       },
-    } as any
+    } as unknown as PluginInput
   }
 
   test("should NOT trigger search mode from keywords inside <system-reminder> tags", async () => {
@@ -554,7 +555,7 @@ describe("keyword-detector agent-specific ultrawork messages", () => {
           showToast: async () => {},
         },
       },
-    } as any
+    } as unknown as PluginInput
   }
 
   test("should skip ultrawork injection when agent is prometheus", async () => {
@@ -771,7 +772,7 @@ describe("keyword-detector non-OMO agent skipping", () => {
           showToast: async () => {},
         },
       },
-    } as any
+    } as unknown as PluginInput
   }
 
   test("should skip all keyword injection for OpenCode-Builder agent", async () => {

src/hooks/keyword-detector/ultrawork-edge-trigger.test.ts

@@ -1,4 +1,5 @@
 import { afterEach, beforeEach, describe, expect, test } from "bun:test"
+import type { PluginInput } from "@opencode-ai/plugin"
 
 import { createKeywordDetectorHook } from "./index"
 import { _resetForTesting, setMainSession } from "../../features/claude-code-session-state"
@@ -18,7 +19,7 @@ function createMockPluginInput(toastCalls: string[] = []) {
         },
       },
     },
-  } as any
+  } as unknown as PluginInput
 }
 
 function createMockRalphLoop(startLoopCalls: StartLoopCall[]) {

src/hooks/stop-continuation-guard/index.test.ts

@@ -2,6 +2,7 @@ import { afterEach, describe, expect, test } from "bun:test"
 import { mkdtempSync, rmSync } from "node:fs"
 import { join } from "node:path"
 import { tmpdir } from "node:os"
+import type { PluginInput } from "@opencode-ai/plugin"
 import type { BackgroundManager, BackgroundTask } from "../../features/background-agent"
 import { readContinuationMarker } from "../../features/run-continuation-state"
 import { createStopContinuationGuardHook } from "./index"
@@ -37,7 +38,7 @@ describe("stop-continuation-guard", () => {
         },
       },
       directory: createTempDir(),
-    } as any
+    } as unknown as PluginInput
   }
 
   function createBackgroundTask(status: BackgroundTask["status"], id: string): BackgroundTask {

src/plugin-handlers/agent-config-handler.test.ts

@@ -9,11 +9,11 @@ import type { OhMyOpenCodeConfig } from "../config"
 import * as agentLoader from "../features/claude-code-agent-loader"
 import * as skillLoader from "../features/opencode-skill-loader"
 import type { LoadedSkill } from "../features/opencode-skill-loader"
-import { getAgentDisplayName, getAgentListDisplayName } from "../shared/agent-display-names"
+import { getAgentDisplayName } from "../shared/agent-display-names"
 import { applyAgentConfig } from "./agent-config-handler"
 import type { PluginComponents } from "./plugin-components-loader"
 
-const BUILTIN_SISYPHUS_DISPLAY_NAME = getAgentListDisplayName("sisyphus")
+const BUILTIN_SISYPHUS_DISPLAY_NAME = getAgentDisplayName("sisyphus")
 const BUILTIN_SISYPHUS_JUNIOR_DISPLAY_NAME = getAgentDisplayName("sisyphus-junior")
 const BUILTIN_MULTIMODAL_LOOKER_DISPLAY_NAME = getAgentDisplayName("multimodal-looker")
 
@@ -38,6 +38,11 @@ function createBaseConfig(): Record<string, unknown> {
 
 function createPluginConfig(): OhMyOpenCodeConfig {
   return {
+    git_master: {
+      commit_footer: true,
+      include_co_authored_by: true,
+      git_env_prefix: "GIT_MASTER=1",
+    },
     sisyphus_agent: {
       planner_enabled: false,
     },

src/plugin-handlers/agent-config-handler.ts

@@ -2,8 +2,8 @@ import { createBuiltinAgents } from "../agents";
 import { createSisyphusJuniorAgentWithOverrides } from "../agents/sisyphus-junior";
 import type { OhMyOpenCodeConfig } from "../config";
 import { isTaskSystemEnabled, log, migrateAgentConfig } from "../shared";
-import { AGENT_NAME_MAP } from "../shared/migration";
 import { getAgentDisplayName } from "../shared/agent-display-names";
+import { AGENT_NAME_MAP } from "../shared/migration";
 import { registerAgentName } from "../features/claude-code-session-state";
 import {
   discoverConfigSourceSkills,
@@ -24,7 +24,6 @@ import {
 } from "./agent-override-protection";
 import { buildPrometheusAgentConfig } from "./prometheus-agent-config-builder";
 import { buildPlanDemoteConfig } from "./plan-model-inheritance";
-import { getAgentListDisplayName } from "../shared/agent-display-names";
 
 type AgentConfigRecord = Record<string, Record<string, unknown> | undefined> & {
   build?: Record<string, unknown>;
@@ -160,10 +159,10 @@ export async function applyAgentConfig(params: {
   if (isSisyphusEnabled && builtinAgents.sisyphus) {
     if (configuredDefaultAgent) {
       (params.config as { default_agent?: string }).default_agent =
-        getAgentListDisplayName(configuredDefaultAgent);
+        getAgentDisplayName(configuredDefaultAgent);
     } else {
       (params.config as { default_agent?: string }).default_agent =
-        getAgentListDisplayName("sisyphus");
+        getAgentDisplayName("sisyphus");
     }
 
     // Assembly order: Sisyphus -> Hephaestus -> Prometheus -> Atlas

src/plugin-handlers/agent-key-remapper.test.ts

@@ -1,6 +1,6 @@
 import { describe, it, expect } from "bun:test"
 import { remapAgentKeysToDisplayNames } from "./agent-key-remapper"
-import { getAgentDisplayName, getAgentListDisplayName } from "../shared/agent-display-names"
+import { getAgentDisplayName } from "../shared/agent-display-names"
 
 describe("remapAgentKeysToDisplayNames", () => {
   it("remaps known agent keys to display names", () => {
@@ -14,7 +14,7 @@ describe("remapAgentKeysToDisplayNames", () => {
     const result = remapAgentKeysToDisplayNames(agents)
 
     // then known agents get display name keys only
-    expect(result[getAgentListDisplayName("sisyphus")]).toBeDefined()
+    expect(result[getAgentDisplayName("sisyphus")]).toBeDefined()
     expect(result["oracle"]).toBeDefined()
     expect(result["sisyphus"]).toBeUndefined()
   })
@@ -49,13 +49,13 @@ describe("remapAgentKeysToDisplayNames", () => {
     const result = remapAgentKeysToDisplayNames(agents)
 
     // then all get display name keys
-    expect(result[getAgentListDisplayName("sisyphus")]).toBeDefined()
+    expect(result[getAgentDisplayName("sisyphus")]).toBeDefined()
     expect(result["sisyphus"]).toBeUndefined()
-    expect(result[getAgentListDisplayName("hephaestus")]).toBeDefined()
+    expect(result[getAgentDisplayName("hephaestus")]).toBeDefined()
     expect(result["hephaestus"]).toBeUndefined()
-    expect(result[getAgentListDisplayName("prometheus")]).toBeDefined()
+    expect(result[getAgentDisplayName("prometheus")]).toBeDefined()
     expect(result["prometheus"]).toBeUndefined()
-    expect(result[getAgentListDisplayName("atlas")]).toBeDefined()
+    expect(result[getAgentDisplayName("atlas")]).toBeDefined()
     expect(result["atlas"]).toBeUndefined()
     expect(result[getAgentDisplayName("athena")]).toBeDefined()
     expect(result["athena"]).toBeUndefined()
@@ -77,12 +77,12 @@ describe("remapAgentKeysToDisplayNames", () => {
     const result = remapAgentKeysToDisplayNames(agents)
 
     // then only display key is emitted
-    expect(Object.keys(result)).toEqual([getAgentListDisplayName("sisyphus")])
+    expect(Object.keys(result)).toEqual([getAgentDisplayName("sisyphus")])
-    expect(result[getAgentListDisplayName("sisyphus")]).toBeDefined()
+    expect(result[getAgentDisplayName("sisyphus")]).toBeDefined()
     expect(result["sisyphus"]).toBeUndefined()
   })
 
-  it("keeps the four core agents in canonical order under opencode name sorting", () => {
+  it("returns clean core agent display names without ZWSP prefixes", () => {
     // given
     const result = remapAgentKeysToDisplayNames({
       atlas: {},
@@ -92,14 +92,17 @@ describe("remapAgentKeysToDisplayNames", () => {
     })
 
     // when
-    const sortedNames = Object.keys(result).sort()
+    const remappedNames = Object.keys(result)
 
     // then
-    expect(sortedNames).toEqual([
+    expect(remappedNames).toEqual([
-      getAgentListDisplayName("sisyphus"),
+      getAgentDisplayName("atlas"),
-      getAgentListDisplayName("hephaestus"),
+      getAgentDisplayName("prometheus"),
-      getAgentListDisplayName("prometheus"),
+      getAgentDisplayName("hephaestus"),
-      getAgentListDisplayName("atlas"),
+      getAgentDisplayName("sisyphus"),
     ])
+    for (const name of remappedNames) {
+      expect(name).not.toContain("\u200B")
+    }
   })
 })

src/plugin-handlers/agent-key-remapper.ts

@@ -1,4 +1,4 @@
-import { getAgentListDisplayName } from "../shared/agent-display-names"
+import { getAgentDisplayName } from "../shared/agent-display-names"
 
 export function remapAgentKeysToDisplayNames(
   agents: Record<string, unknown>,
@@ -6,7 +6,7 @@ export function remapAgentKeysToDisplayNames(
   const result: Record<string, unknown> = {}
 
   for (const [key, value] of Object.entries(agents)) {
-    const displayName = getAgentListDisplayName(key)
+    const displayName = getAgentDisplayName(key)
     if (displayName && displayName !== key) {
       result[displayName] = value
       // Regression guard: do not also assign result[key].

src/plugin-handlers/agent-priority-order.test.ts

@@ -1,15 +1,17 @@
+/// <reference types="bun-types" />
+
 import { describe, expect, test } from "bun:test"
 
 import { reorderAgentsByPriority } from "./agent-priority-order"
-import { getAgentDisplayName, getAgentListDisplayName } from "../shared/agent-display-names"
+import { getAgentDisplayName } from "../shared/agent-display-names"
 
 describe("reorderAgentsByPriority", () => {
   test("moves core agents to canonical order and injects runtime order fields", () => {
     // given
-    const sisyphus = getAgentListDisplayName("sisyphus")
+    const sisyphus = getAgentDisplayName("sisyphus")
-    const hephaestus = getAgentListDisplayName("hephaestus")
+    const hephaestus = getAgentDisplayName("hephaestus")
-    const prometheus = getAgentListDisplayName("prometheus")
+    const prometheus = getAgentDisplayName("prometheus")
-    const atlas = getAgentListDisplayName("atlas")
+    const atlas = getAgentDisplayName("atlas")
     const oracle = getAgentDisplayName("oracle")
 
     const agents: Record<string, unknown> = {
@@ -59,8 +61,8 @@ describe("reorderAgentsByPriority", () => {
 
   test("leaves non-object agent configs untouched while still reordering keys", () => {
     // given
-    const sisyphus = getAgentListDisplayName("sisyphus")
+    const sisyphus = getAgentDisplayName("sisyphus")
-    const atlas = getAgentListDisplayName("atlas")
+    const atlas = getAgentDisplayName("atlas")
 
     const agents: Record<string, unknown> = {
       [atlas]: "atlas-config",

src/plugin-handlers/agent-priority-order.ts

@@ -1,10 +1,10 @@
-import { getAgentListDisplayName } from "../shared/agent-display-names";
+import { getAgentDisplayName } from "../shared/agent-display-names";
 
 const CORE_AGENT_ORDER: ReadonlyArray<{ displayName: string; order: number }> = [
-  { displayName: getAgentListDisplayName("sisyphus"), order: 1 },
+  { displayName: getAgentDisplayName("sisyphus"), order: 1 },
-  { displayName: getAgentListDisplayName("hephaestus"), order: 2 },
+  { displayName: getAgentDisplayName("hephaestus"), order: 2 },
-  { displayName: getAgentListDisplayName("prometheus"), order: 3 },
+  { displayName: getAgentDisplayName("prometheus"), order: 3 },
-  { displayName: getAgentListDisplayName("atlas"), order: 4 },
+  { displayName: getAgentDisplayName("atlas"), order: 4 },
 ];
 
 function injectOrderField(

src/plugin-handlers/command-config-handler.test.ts

@@ -1,3 +1,5 @@
+/// <reference types="bun-types" />
+
 import { afterEach, beforeEach, describe, expect, spyOn, test } from "bun:test";
 import * as builtinCommands from "../features/builtin-commands";
 import * as commandLoader from "../features/claude-code-command-loader";
@@ -7,7 +9,6 @@ import type { PluginComponents } from "./plugin-components-loader";
 import { applyCommandConfig } from "./command-config-handler";
 import {
   getAgentDisplayName,
-  getAgentListDisplayName,
 } from "../shared/agent-display-names";
 
 function createPluginComponents(): PluginComponents {
@@ -23,7 +24,13 @@ function createPluginComponents(): PluginComponents {
 }
 
 function createPluginConfig(): OhMyOpenCodeConfig {
-  return {};
+  return {
+    git_master: {
+      commit_footer: true,
+      include_co_authored_by: true,
+      git_env_prefix: "GIT_MASTER=1",
+    },
+  };
 }
 
 describe("applyCommandConfig", () => {
@@ -100,7 +107,7 @@ describe("applyCommandConfig", () => {
     expect(commandConfig["agents-global-skill"]?.description).toContain("Agents global skill");
   });
 
-  test("normalizes Atlas command agents to the exported list key used by opencode command routing", async () => {
+  test("normalizes Atlas command agents to the clean display name used by opencode command routing", async () => {
     // given
     loadBuiltinCommandsSpy.mockReturnValue({
       "start-work": {
@@ -122,10 +129,10 @@ describe("applyCommandConfig", () => {
 
     // then
     const commandConfig = config.command as Record<string, { agent?: string }>;
-    expect(commandConfig["start-work"]?.agent).toBe(getAgentListDisplayName("atlas"));
+    expect(commandConfig["start-work"]?.agent).toBe(getAgentDisplayName("atlas"));
   });
 
-  test("normalizes legacy display-name command agents to the exported list key", async () => {
+  test("normalizes legacy display-name command agents to the clean display name", async () => {
     // given
     loadBuiltinCommandsSpy.mockReturnValue({
       "start-work": {
@@ -147,6 +154,6 @@ describe("applyCommandConfig", () => {
 
     // then
     const commandConfig = config.command as Record<string, { agent?: string }>;
-    expect(commandConfig["start-work"]?.agent).toBe(getAgentListDisplayName("atlas"));
+    expect(commandConfig["start-work"]?.agent).toBe(getAgentDisplayName("atlas"));
   });
 });

src/plugin-handlers/command-config-handler.ts

@@ -1,7 +1,7 @@
 import type { OhMyOpenCodeConfig } from "../config";
 import {
   getAgentConfigKey,
-  getAgentListDisplayName,
+  getAgentDisplayName,
 } from "../shared/agent-display-names";
 import {
   loadUserCommands,
@@ -99,7 +99,7 @@ export async function applyCommandConfig(params: {
 function remapCommandAgentFields(commands: Record<string, Record<string, unknown>>): void {
   for (const cmd of Object.values(commands)) {
     if (cmd?.agent && typeof cmd.agent === "string") {
-      cmd.agent = getAgentListDisplayName(getAgentConfigKey(cmd.agent));
+      cmd.agent = getAgentDisplayName(getAgentConfigKey(cmd.agent));
     }
   }
 }

src/plugin-handlers/config-handler.test.ts

@@ -3,7 +3,7 @@
 import { describe, test, expect, spyOn, beforeEach, afterEach, mock } from "bun:test"
 import type { CategoryConfig } from "../config/schema"
 import type { OhMyOpenCodeConfig } from "../config"
-import { getAgentDisplayName, getAgentListDisplayName } from "../shared/agent-display-names"
+import { getAgentDisplayName } from "../shared/agent-display-names"
 import { resolveCategoryConfig } from "./category-config-resolver"
 
 import * as agents from "../agents"
@@ -260,10 +260,10 @@ describe("Plan agent demote behavior", () => {
     // #then
     const keys = Object.keys(config.agent as Record<string, unknown>)
     const coreAgents = [
-      getAgentListDisplayName("sisyphus"),
+      getAgentDisplayName("sisyphus"),
-      getAgentListDisplayName("hephaestus"),
+      getAgentDisplayName("hephaestus"),
-      getAgentListDisplayName("prometheus"),
+      getAgentDisplayName("prometheus"),
-      getAgentListDisplayName("atlas"),
+      getAgentDisplayName("atlas"),
     ]
     const ordered = keys.filter((key) => coreAgents.includes(key))
     expect(ordered).toEqual(coreAgents)
@@ -308,10 +308,10 @@ describe("Plan agent demote behavior", () => {
       reorderSpy.mock.calls.at(0)?.[0] as Record<string, unknown>
     )
     expect(assembledAgentKeys.slice(0, 4)).toEqual([
-      getAgentListDisplayName("sisyphus"),
+      getAgentDisplayName("sisyphus"),
-      getAgentListDisplayName("hephaestus"),
+      getAgentDisplayName("hephaestus"),
-      getAgentListDisplayName("prometheus"),
+      getAgentDisplayName("prometheus"),
-      getAgentListDisplayName("atlas"),
+      getAgentDisplayName("atlas"),
     ])
   })
 
@@ -350,7 +350,7 @@ describe("Plan agent demote behavior", () => {
     expect(agents.plan).toBeDefined()
     expect(agents.plan.mode).toBe("subagent")
     expect(agents.plan.prompt).toBeUndefined()
-    expect(agents[getAgentListDisplayName("prometheus")]?.prompt).toBeDefined()
+    expect(agents[getAgentDisplayName("prometheus")]?.prompt).toBeDefined()
   })
 
   test("plan agent remains unchanged when planner is disabled", async () => {
@@ -384,7 +384,7 @@ describe("Plan agent demote behavior", () => {
 
     // #then - plan is not touched, prometheus is not created
     const agents = config.agent as Record<string, { mode?: string; name?: string; prompt?: string }>
-    expect(agents[getAgentListDisplayName("prometheus")]).toBeUndefined()
+    expect(agents[getAgentDisplayName("prometheus")]).toBeUndefined()
     expect(agents.plan).toBeDefined()
     expect(agents.plan.mode).toBe("primary")
     expect(agents.plan.prompt).toBe("original plan prompt")
@@ -415,7 +415,7 @@ describe("Plan agent demote behavior", () => {
 
     // then
     const agents = config.agent as Record<string, { mode?: string }>
-    const prometheusKey = getAgentListDisplayName("prometheus")
+    const prometheusKey = getAgentDisplayName("prometheus")
     expect(agents[prometheusKey]).toBeDefined()
     expect(agents[prometheusKey].mode).toBe("all")
   })
@@ -451,7 +451,7 @@ describe("Agent permission defaults", () => {
 
     // #then
     const agentConfig = config.agent as Record<string, { permission?: Record<string, string> }>
-    const hephaestusKey = getAgentListDisplayName("hephaestus")
+    const hephaestusKey = getAgentDisplayName("hephaestus")
     expect(agentConfig[hephaestusKey]).toBeDefined()
     expect(agentConfig[hephaestusKey].permission?.task).toBe("allow")
   })
@@ -479,7 +479,7 @@ describe("default_agent behavior with Sisyphus orchestration", () => {
     await handler(config)
 
     // then
-    expect(config.default_agent).toBe(getAgentListDisplayName("hephaestus"))
+    expect(config.default_agent).toBe(getAgentDisplayName("hephaestus"))
   })
 
   test("canonicalizes configured default_agent when key uses mixed case", async () => {
@@ -503,7 +503,7 @@ describe("default_agent behavior with Sisyphus orchestration", () => {
     await handler(config)
 
     // then
-    expect(config.default_agent).toBe(getAgentListDisplayName("hephaestus"))
+    expect(config.default_agent).toBe(getAgentDisplayName("hephaestus"))
   })
 
   test("canonicalizes configured default_agent key to display name", async () => {
@@ -527,13 +527,13 @@ describe("default_agent behavior with Sisyphus orchestration", () => {
     await handler(config)
 
     // #then
-    expect(config.default_agent).toBe(getAgentListDisplayName("hephaestus"))
+    expect(config.default_agent).toBe(getAgentDisplayName("hephaestus"))
   })
 
   test("preserves existing display-name default_agent", async () => {
     // #given
     const pluginConfig = createPluginConfig({})
-    const displayName = getAgentListDisplayName("hephaestus")
+    const displayName = getAgentDisplayName("hephaestus")
     const config: Record<string, unknown> = {
       model: "anthropic/claude-opus-4-6",
       default_agent: displayName,
@@ -575,7 +575,7 @@ describe("default_agent behavior with Sisyphus orchestration", () => {
     await handler(config)
 
     // #then
-    expect(config.default_agent).toBe(getAgentListDisplayName("sisyphus"))
+    expect(config.default_agent).toBe(getAgentDisplayName("sisyphus"))
   })
 
   test("sets default_agent to sisyphus when configured default_agent is empty after trim", async () => {
@@ -599,7 +599,7 @@ describe("default_agent behavior with Sisyphus orchestration", () => {
     await handler(config)
 
     // then
-    expect(config.default_agent).toBe(getAgentListDisplayName("sisyphus"))
+    expect(config.default_agent).toBe(getAgentDisplayName("sisyphus"))
   })
 
   test("preserves custom default_agent names while trimming whitespace", async () => {
@@ -793,7 +793,7 @@ describe("Prometheus direct override priority over category", () => {
 
     // then - direct override's reasoningEffort wins
     const agents = config.agent as Record<string, { reasoningEffort?: string }>
-    const pKey = getAgentListDisplayName("prometheus")
+    const pKey = getAgentDisplayName("prometheus")
     expect(agents[pKey]).toBeDefined()
     expect(agents[pKey].reasoningEffort).toBe("low")
   })
@@ -834,7 +834,7 @@ describe("Prometheus direct override priority over category", () => {
 
     // then - category's reasoningEffort is applied
     const agents = config.agent as Record<string, { reasoningEffort?: string }>
-    const pKey = getAgentListDisplayName("prometheus")
+    const pKey = getAgentDisplayName("prometheus")
     expect(agents[pKey]).toBeDefined()
     expect(agents[pKey].reasoningEffort).toBe("high")
   })
@@ -876,7 +876,7 @@ describe("Prometheus direct override priority over category", () => {
 
     // then - direct temperature wins over category
     const agents = config.agent as Record<string, { temperature?: number }>
-    const pKey = getAgentListDisplayName("prometheus")
+    const pKey = getAgentDisplayName("prometheus")
     expect(agents[pKey]).toBeDefined()
     expect(agents[pKey].temperature).toBe(0.1)
   })
@@ -912,7 +912,7 @@ describe("Prometheus direct override priority over category", () => {
 
     // #then - prompt_append is appended to base prompt, not overwriting it
     const agents = config.agent as Record<string, { prompt?: string }>
-    const pKey = getAgentListDisplayName("prometheus")
+    const pKey = getAgentDisplayName("prometheus")
     expect(agents[pKey]).toBeDefined()
     expect(agents[pKey].prompt).toContain("Prometheus")
     expect(agents[pKey].prompt).toContain(customInstructions)
@@ -1137,7 +1137,7 @@ describe("Deadlock prevention - fetchAvailableModels must not receive client", (
 
     // then - regression guard: handler completes and still assembles planner config
     const agentConfig = config.agent as Record<string, unknown>
-    expect(agentConfig[getAgentListDisplayName("prometheus")]).toBeDefined()
+    expect(agentConfig[getAgentDisplayName("prometheus")]).toBeDefined()
   })
 })
 
@@ -1303,17 +1303,17 @@ describe("command agent routing coherence", () => {
     //#then
     const agentConfig = config.agent as Record<string, unknown>
     const commandConfig = config.command as Record<string, { agent?: string }>
-    expect(Object.keys(agentConfig)).toContain(getAgentListDisplayName("atlas"))
+    expect(Object.keys(agentConfig)).toContain(getAgentDisplayName("atlas"))
-    expect(commandConfig["start-work"]?.agent).toBe(getAgentListDisplayName("atlas"))
+    expect(commandConfig["start-work"]?.agent).toBe(getAgentDisplayName("atlas"))
   })
 })
 
 describe("per-agent todowrite/todoread deny when task_system enabled", () => {
   const AGENTS_WITH_TODO_DENY = new Set([
-    getAgentListDisplayName("sisyphus"),
+    getAgentDisplayName("sisyphus"),
-    getAgentListDisplayName("hephaestus"),
+    getAgentDisplayName("hephaestus"),
-    getAgentListDisplayName("prometheus"),
+    getAgentDisplayName("prometheus"),
-    getAgentListDisplayName("atlas"),
+    getAgentDisplayName("atlas"),
     getAgentDisplayName("sisyphus-junior"),
   ])
 
@@ -1394,10 +1394,10 @@ describe("per-agent todowrite/todoread deny when task_system enabled", () => {
     expect(lastCall?.[11]).toBe(false)
 
     const agentResult = config.agent as Record<string, { permission?: Record<string, unknown> }>
-    expect(agentResult[getAgentListDisplayName("sisyphus")]?.permission?.todowrite).toBeUndefined()
+    expect(agentResult[getAgentDisplayName("sisyphus")]?.permission?.todowrite).toBeUndefined()
-    expect(agentResult[getAgentListDisplayName("sisyphus")]?.permission?.todoread).toBeUndefined()
+    expect(agentResult[getAgentDisplayName("sisyphus")]?.permission?.todoread).toBeUndefined()
-    expect(agentResult[getAgentListDisplayName("hephaestus")]?.permission?.todowrite).toBeUndefined()
+    expect(agentResult[getAgentDisplayName("hephaestus")]?.permission?.todowrite).toBeUndefined()
-    expect(agentResult[getAgentListDisplayName("hephaestus")]?.permission?.todoread).toBeUndefined()
+    expect(agentResult[getAgentDisplayName("hephaestus")]?.permission?.todoread).toBeUndefined()
   })
 
   test("does not deny todowrite/todoread when task_system is undefined", async () => {
@@ -1433,8 +1433,8 @@ describe("per-agent todowrite/todoread deny when task_system enabled", () => {
     expect(lastCall?.[11]).toBe(false)
 
     const agentResult = config.agent as Record<string, { permission?: Record<string, unknown> }>
-    expect(agentResult[getAgentListDisplayName("sisyphus")]?.permission?.todowrite).toBeUndefined()
+    expect(agentResult[getAgentDisplayName("sisyphus")]?.permission?.todowrite).toBeUndefined()
-    expect(agentResult[getAgentListDisplayName("sisyphus")]?.permission?.todoread).toBeUndefined()
+    expect(agentResult[getAgentDisplayName("sisyphus")]?.permission?.todoread).toBeUndefined()
   })
 })
 

src/plugin-handlers/tool-config-handler.test.ts

@@ -1,7 +1,7 @@
 import { describe, it, expect, beforeEach, afterEach } from "bun:test"
 import { applyToolConfig } from "./tool-config-handler"
 import type { OhMyOpenCodeConfig } from "../config"
-import { getAgentListDisplayName } from "../shared/agent-display-names"
+import { getAgentDisplayName } from "../shared/agent-display-names"
 
 function createParams(overrides: {
   taskSystem?: boolean
@@ -251,9 +251,9 @@ describe("applyToolConfig", () => {
     })
   })
 
-  describe("#given agentResult uses exported list display keys", () => {
+  describe("#given agentResult uses clean display keys", () => {
-    it("#then should still resolve atlas permissions through the prefixed key", () => {
+    it("#then should still resolve atlas permissions through the display key", () => {
-      const atlasKey = getAgentListDisplayName("atlas")
+      const atlasKey = getAgentDisplayName("atlas")
       const params = createParams({ agents: [atlasKey] })
 
       applyToolConfig(params)

src/plugin-handlers/tool-config-handler.ts

@@ -1,5 +1,5 @@
 import type { OhMyOpenCodeConfig } from "../config";
-import { getAgentDisplayName, getAgentListDisplayName } from "../shared/agent-display-names";
+import { getAgentDisplayName } from "../shared/agent-display-names";
 import { isTaskSystemEnabled } from "../shared";
 
 type AgentWithPermission = { permission?: Record<string, unknown> };
@@ -16,7 +16,7 @@ function getConfigQuestionPermission(): string | null {
 }
 
 function agentByKey(agentResult: Record<string, unknown>, key: string): AgentWithPermission | undefined {
-  return (agentResult[getAgentListDisplayName(key)] ?? agentResult[getAgentDisplayName(key)] ?? agentResult[key]) as
+  return (agentResult[getAgentDisplayName(key)] ?? agentResult[key]) as
     | AgentWithPermission
     | undefined;
 }

src/plugin/command-execute-before.test.ts

@@ -0,0 +1,114 @@
+import { describe, expect, mock, test } from "bun:test"
+
+import { createCommandExecuteBeforeHandler } from "./command-execute-before"
+
+describe("createCommandExecuteBeforeHandler", () => {
+  test("#given stopped session and /ulw-loop #when command.execute.before runs #then clear is called", async () => {
+    // given
+    const clear = mock(() => {})
+    const isStopped = mock(() => true)
+    const startLoop = mock(() => true)
+    const handler = createCommandExecuteBeforeHandler({
+      hooks: {
+        ralphLoop: {
+          startLoop,
+          cancelLoop: mock(() => true),
+        },
+        stopContinuationGuard: {
+          isStopped,
+          clear,
+        },
+      },
+    })
+
+    // when
+    await handler(
+      {
+        command: "ulw-loop",
+        sessionID: "ses-stopped",
+        arguments: "Ship feature",
+      },
+      {
+        parts: [],
+      },
+    )
+
+    // then
+    expect(startLoop).toHaveBeenCalledTimes(1)
+    expect(isStopped).toHaveBeenCalledWith("ses-stopped")
+    expect(clear).toHaveBeenCalledTimes(1)
+    expect(clear).toHaveBeenCalledWith("ses-stopped")
+  })
+
+  test("#given stopped session and /start-work #when command.execute.before runs #then clear is called", async () => {
+    // given
+    const clear = mock(() => {})
+    const isStopped = mock(() => true)
+    const startWorkHook = mock(async () => {})
+    const handler = createCommandExecuteBeforeHandler({
+      hooks: {
+        startWork: {
+          "command.execute.before": startWorkHook,
+        },
+        stopContinuationGuard: {
+          isStopped,
+          clear,
+        },
+      },
+    })
+
+    // when
+    await handler(
+      {
+        command: "start-work",
+        sessionID: "ses-stopped",
+        arguments: "",
+      },
+      {
+        parts: [],
+      },
+    )
+
+    // then
+    expect(startWorkHook).toHaveBeenCalledTimes(1)
+    expect(isStopped).toHaveBeenCalledWith("ses-stopped")
+    expect(clear).toHaveBeenCalledTimes(1)
+    expect(clear).toHaveBeenCalledWith("ses-stopped")
+  })
+
+  test("#given non-stopped session and /ulw-loop #when command.execute.before runs #then clear is not called", async () => {
+    // given
+    const clear = mock(() => {})
+    const isStopped = mock(() => false)
+    const startLoop = mock(() => true)
+    const handler = createCommandExecuteBeforeHandler({
+      hooks: {
+        ralphLoop: {
+          startLoop,
+          cancelLoop: mock(() => true),
+        },
+        stopContinuationGuard: {
+          isStopped,
+          clear,
+        },
+      },
+    })
+
+    // when
+    await handler(
+      {
+        command: "ulw-loop",
+        sessionID: "ses-running",
+        arguments: "Ship feature",
+      },
+      {
+        parts: [],
+      },
+    )
+
+    // then
+    expect(startLoop).toHaveBeenCalledTimes(1)
+    expect(isStopped).toHaveBeenCalledWith("ses-running")
+    expect(clear).not.toHaveBeenCalled()
+  })
+})

src/plugin/command-execute-before.ts

@@ -1,5 +1,6 @@
 import type { CreatedHooks } from "../create-hooks"
 import { parseRalphLoopArguments } from "../hooks/ralph-loop/command-arguments"
+import { log } from "../shared/logger"
 
 type CommandExecuteBeforeInput = {
   command: string
@@ -45,6 +46,13 @@ export function createCommandExecuteBeforeHandler(args: {
         })
         output.message ??= {}
         output.message[NATIVE_LOOP_TRIGGERED_FLAG] = true
+        if (hooks.stopContinuationGuard?.isStopped(sessionID)) {
+          hooks.stopContinuationGuard.clear(sessionID)
+          log("[stop-continuation] Stop state cleared by native command", {
+            sessionID,
+            command: normalizedCommand,
+          })
+        }
       } else if (normalizedCommand === "cancel-ralph") {
         hooks.ralphLoop.cancelLoop(sessionID)
         output.message ??= {}
@@ -58,6 +66,13 @@ export function createCommandExecuteBeforeHandler(args: {
       && hasPartsOutput(output)
     ) {
       await hooks.startWork["command.execute.before"]?.(input, output)
+      if (hooks.stopContinuationGuard?.isStopped(sessionID)) {
+        hooks.stopContinuationGuard.clear(sessionID)
+        log("[stop-continuation] Stop state cleared by native command", {
+          sessionID,
+          command: normalizedCommand,
+        })
+      }
     }
   }
 }

src/plugin/event.test.ts

@@ -590,7 +590,8 @@ describe("createEventHandler - event forwarding", () => {
 		expect(createdSessions).toHaveLength(0)
 	})
 
-	it("dispatches OpenClaw after session.created using tracked pane metadata", async () => {
+	it("dispatches OpenClaw after session.created for main sessions (no parentID)", async () => {
+		//#given
 		const openClawSpy = spyOn(openclawRuntimeDispatch, "dispatchOpenClawEvent").mockResolvedValue(null)
 		const eventHandler = createEventHandler({
 			ctx: asEventHandlerContext({ directory: "/tmp/project-created" }),
@@ -620,13 +621,15 @@ describe("createEventHandler - event forwarding", () => {
 			hooks: createEventHandlerHooks({}),
 		})
 
+		//#when - main session created (no parentID)
 		await eventHandler(asEventHandlerInput({
 			event: {
 				type: "session.created",
-				properties: { info: { id: "ses_openclaw_created", parentID: "ses_parent" } },
+				properties: { info: { id: "ses_openclaw_created" } },
 			},
 		}))
 
+		//#then - OpenClaw dispatch called for main session
 		const [call] = openClawSpy.mock.calls[0] ?? []
 		expect(call).toMatchObject({
 			rawEvent: "session.created",
@@ -638,6 +641,49 @@ describe("createEventHandler - event forwarding", () => {
 		})
 	})
 
+	it("does NOT dispatch OpenClaw for subagent sessions (with parentID)", async () => {
+		//#given
+		const openClawSpy = spyOn(openclawRuntimeDispatch, "dispatchOpenClawEvent").mockResolvedValue(null)
+		const eventHandler = createEventHandler({
+			ctx: asEventHandlerContext({ directory: "/tmp/project-created" }),
+			pluginConfig: asPluginConfig({
+				openclaw: { enabled: true, gateways: {}, hooks: {} },
+				tmux: {
+					enabled: true,
+					layout: "main-vertical",
+					main_pane_size: 60,
+					main_pane_min_width: 120,
+					agent_pane_min_width: 40,
+					isolation: "inline",
+				},
+			}),
+			firstMessageVariantGate: {
+				markSessionCreated: () => {},
+				clear: () => {},
+			},
+			managers: createEventHandlerManagers({
+				skillMcpManager: { disconnectSession: async () => {} },
+				tmuxSessionManager: {
+					onSessionCreated: async () => {},
+					onSessionDeleted: async () => {},
+					getTrackedPaneId: (sessionID: string) => (sessionID === "ses_subagent" ? "%10" : undefined),
+				},
+			}),
+			hooks: createEventHandlerHooks({}),
+		})
+
+		//#when - subagent session created (with parentID)
+		await eventHandler(asEventHandlerInput({
+			event: {
+				type: "session.created",
+				properties: { info: { id: "ses_subagent", parentID: "ses_parent" } },
+			},
+		}))
+
+		//#then - OpenClaw dispatch NOT called for subagent session (handled by specialized callbacks)
+		expect(openClawSpy.mock.calls.length).toBe(0)
+	})
+
 	it("forwards session.deleted to write-existing-file-guard hook", async () => {
 		//#given
 		const forwardedEvents: EventInput[] = []

src/plugin/event.ts

@@ -382,7 +382,10 @@ export function createEventHandler(args: {
         );
       }
 
-      if (pluginConfig.openclaw && sessionInfo?.id) {
+      // Skip subagent sessions — they are dispatched by specialized callbacks
+      // in create-managers.ts (async) and tool-registry.ts (sync)
+      const isSubagentSession = !!sessionInfo?.parentID;
+      if (pluginConfig.openclaw && sessionInfo?.id && !isSubagentSession) {
         await dispatchOpenClawEvent({
           config: pluginConfig.openclaw,
           rawEvent: event.type,

src/shared/migration.test.ts

@@ -1469,4 +1469,63 @@ describe("migrateConfigFile with migration tracking via sidecar (#3263)", () =>
       "model-version:anthropic/claude-opus-4-5->anthropic/claude-opus-4-6",
     ]))
   })
+
+  test("preserves _migrations in config when sidecar write fails", () => {
+    // given: Config with _migrations field and a read-only directory that will cause sidecar write to fail
+    const testConfigPath = tempConfigPath("sidecar-fail")
+    const rawConfig: Record<string, unknown> = {
+      agents: {
+        oracle: { model: "anthropic/claude-opus-4-5" },
+      },
+      _migrations: ["model-version:openai/gpt-5.3-codex->openai/gpt-5.4"],
+    }
+    fs.writeFileSync(testConfigPath, JSON.stringify(rawConfig, null, 2))
+
+    // Make the directory read-only to cause sidecar write to fail
+    const workdir = path.dirname(testConfigPath)
+    fs.chmodSync(workdir, 0o555)
+
+    // when: Migrate config file (sidecar write will fail)
+    const needsWrite = migrateConfigFile(testConfigPath, rawConfig)
+
+    // then: _migrations should contain full set (existing + new) as fallback
+    expect(needsWrite).toBe(true)
+    const migrations = rawConfig._migrations as string[]
+    expect(Array.isArray(migrations)).toBe(true)
+    expect(migrations).toContain("model-version:openai/gpt-5.3-codex->openai/gpt-5.4")
+    expect(migrations.length).toBeGreaterThanOrEqual(1)
+    expect((rawConfig.agents as Record<string, Record<string, unknown>>).oracle.model).toBe("anthropic/claude-opus-4-6")
+
+    // Sidecar should not exist because write failed
+    expect(fs.existsSync(sidecarPath(testConfigPath))).toBe(false)
+
+    // cleanup: restore permissions for cleanup
+    fs.chmodSync(workdir, 0o755)
+  })
+
+  test("writes _migrations into config as fallback when sidecar write fails and no prior _migrations existed", () => {
+    // given: config WITHOUT _migrations field and a read-only dir
+    const testConfigPath = tempConfigPath("sidecar-fail-no-prior")
+    const rawConfig: Record<string, unknown> = {
+      agents: {
+        oracle: { model: "anthropic/claude-opus-4-5" },
+      },
+    }
+    fs.writeFileSync(testConfigPath, JSON.stringify(rawConfig, null, 2))
+    const workdir = path.dirname(testConfigPath)
+    fs.chmodSync(workdir, 0o555)
+
+    // when: migrate runs (sidecar write will fail)
+    const needsWrite = migrateConfigFile(testConfigPath, rawConfig)
+
+    // then: _migrations should be injected into config as fallback
+    expect(needsWrite).toBe(true)
+    expect(rawConfig._migrations).toBeDefined()
+    expect(Array.isArray(rawConfig._migrations)).toBe(true)
+    expect((rawConfig._migrations as string[]).length).toBeGreaterThan(0)
+    expect(fs.existsSync(sidecarPath(testConfigPath))).toBe(false)
+
+    // cleanup
+    fs.chmodSync(workdir, 0o755)
+  })
 })

src/shared/migration/config-migration.ts

@@ -74,12 +74,13 @@ export function migrateConfigFile(
   // the first place. The in-memory `rawConfig` never re-exposes
   // `_migrations` to downstream schema validation.
   const newMigrationsToRecord = allNewMigrations.filter(mKey => !existingMigrations.has(mKey))
+  let sidecarWriteSucceeded = false
+  const fullMigrationSet = new Set<string>([
+    ...existingMigrations,
+    ...newMigrationsToRecord,
+  ])
   if (newMigrationsToRecord.length > 0 || hadLegacyInConfigMigrations) {
-    const fullMigrationSet = new Set<string>([
+    sidecarWriteSucceeded = writeAppliedMigrations(configPath, fullMigrationSet)
-      ...existingMigrations,
-      ...newMigrationsToRecord,
-    ])
-    writeAppliedMigrations(configPath, fullMigrationSet)
   }
   if (newMigrationsToRecord.length > 0) {
     needsWrite = true
@@ -88,8 +89,12 @@ export function migrateConfigFile(
     // Migrating state out of the config body is itself a config write.
     needsWrite = true
   }
-  if ("_migrations" in copy) {
+  if (sidecarWriteSucceeded && "_migrations" in copy) {
     delete copy._migrations
+  } else if (!sidecarWriteSucceeded && newMigrationsToRecord.length > 0) {
+    // Sidecar write failed — persist migration tracking in-config as fallback
+    ;(copy as Record<string, unknown>)._migrations = Array.from(fullMigrationSet)
+    needsWrite = true
   }
 
   if (copy.omo_agent) {