oh-my-opencode 4.13.0 → 4.14.1

package/packages/omo-codex/plugin/test/migrate-codex-config.test.mjs

@@ -1,12 +1,41 @@
+// allow: SIZE_OK - migration scenarios share one temp Codex-home harness across legacy TOML shapes; this release only adds config cases and future additions should split by migration family.
+
 import assert from "node:assert/strict";
+import { spawnSync } from "node:child_process";
 import { mkdir, mkdtemp, readFile, rm, symlink, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { dirname, join } from "node:path";
 import test from "node:test";
 
+import { removeUnsupportedRootMultiAgentMode } from "../scripts/migrate-codex-config/multi-agent-mode-guard.mjs";
 import { forceDisableMultiAgentV2 } from "../scripts/migrate-codex-config/multi-agent-v2-guard.mjs";
 import { ensureCodexReasoningConfig, migrateCodexConfig } from "../scripts/migrate-codex-config.mjs";
 
+function parseTomlWithPython(config) {
+	const python = resolvePython();
+	const result = spawnSync(
+		python,
+		[
+			"-c",
+			[
+				"import json, sys, tomllib",
+				"print(json.dumps(tomllib.loads(sys.stdin.read())))",
+			].join("; "),
+		],
+		{ encoding: "utf8", input: config },
+	);
+	assert.equal(result.status, 0, result.stderr);
+	return JSON.parse(result.stdout);
+}
+
+function resolvePython() {
+	for (const command of ["python3", "python"]) {
+		const result = spawnSync(command, ["-c", "import tomllib"], { encoding: "utf8" });
+		if (result.status === 0) return command;
+	}
+	assert.fail("Python with tomllib is required for TOML parse assertions");
+}
+
 test("#given stale root reasoning config #when ensuring config #then replaces stale values without duplicate keys", () => {
 	const result = ensureCodexReasoningConfig(
 		[
@@ -181,7 +210,7 @@ test("#given model catalog is malformed and stale config #when migrating #then f
 	assert.match(content, /model_context_window = 400000/);
 });
 
-test("#given user-customized Codex model config #when migrating #then user values are preserved", async () => {
+test("#given user-customized Codex model config #when migrating #then user values are preserved without root multi-agent mode", async () => {
 	const root = await mkdtemp(join(tmpdir(), "lazycodex-config-custom-"));
 	const codexHome = join(root, "codex-home");
 	await mkdir(codexHome, { recursive: true });
@@ -205,11 +234,16 @@ test("#given user-customized Codex model config #when migrating #then user value
 	});
 
 	const content = await readFile(join(codexHome, "config.toml"), "utf8");
-	assert.deepEqual(result.changed, []);
+	assert.deepEqual(result.changed, [join(codexHome, "config.toml")]);
+	assert.deepEqual(result.modeChanged, []);
 	assert.match(content, /model = "gpt-5\.4"/);
 	assert.match(content, /model_context_window = 123456/);
 	assert.match(content, /model_reasoning_effort = "medium"/);
 	assert.match(content, /plan_mode_reasoning_effort = "medium"/);
+	assert.doesNotMatch(content, /^\s*multi_agent_mode\s*=/m);
+	assert.match(content, /\[agents\][\s\S]*?max_threads = 1000/);
+	assert.match(content, /\[features\.multi_agent_v2\][\s\S]*?enabled = false/);
+	assert.match(content, /max_concurrent_threads_per_session = 1000/);
 });
 
 test("#given managed config state is malformed #when migrating #then migration ignores stale state safely", async () => {
@@ -328,6 +362,7 @@ test("#given config already matches current catalog #when catalog version advanc
 			"model_context_window = 400000",
 			'model_reasoning_effort = "high"',
 			'plan_mode_reasoning_effort = "xhigh"',
+			'multi_agent_mode = "proactive"',
 			"",
 			"[features.multi_agent_v2]",
 			"enabled = false",
@@ -363,9 +398,88 @@ test("#given config already matches current catalog #when catalog version advanc
 	});
 
 	const state = JSON.parse(await readFile(statePath, "utf8"));
-	assert.deepEqual(result.changed, []);
+	assert.deepEqual(result.changed, [configPath]);
+	assert.deepEqual(result.modeChanged, [configPath]);
 	assert.equal(state.files[configPath].managed, true);
 	assert.equal(state.files[configPath].catalogVersion, "test.role-only");
+	const content = await readFile(configPath, "utf8");
+	assert.doesNotMatch(content, /^\s*multi_agent_mode\s*=/m);
+	assert.match(content, /\[agents\][\s\S]*?max_threads = 1000/);
+	assert.match(content, /max_concurrent_threads_per_session = 1000/);
+});
+
+test("#given stale Context7 placeholder MCP config #when migrating #then removes it and keeps plugin policy", async () => {
+	const root = await mkdtemp(join(tmpdir(), "lazycodex-context7-placeholder-cleanup-"));
+	const codexHome = join(root, "codex-home");
+	const configPath = join(codexHome, "config.toml");
+	await mkdir(codexHome, { recursive: true });
+	await writeFile(
+		configPath,
+		[
+			'model = "gpt-5.5"',
+			"model_context_window = 400000",
+			'model_reasoning_effort = "high"',
+			'plan_mode_reasoning_effort = "xhigh"',
+			"",
+			"[mcp_servers.context7] # stale npx package from old docs",
+			'command = "npx"',
+			'args = ["-y", "@upstash/context7-mcp", "--api-key", "YOUR_API_KEY"]',
+			"startup_timeout_sec = 20",
+			"",
+			'[plugins."omo@sisyphuslabs".mcp_servers.context7]',
+			"enabled = true",
+			"",
+		].join("\n"),
+	);
+
+	const result = await migrateCodexConfig({
+		env: { CODEX_HOME: codexHome, LAZYCODEX_MODEL_CATALOG_STATE_PATH: join(root, "model-state.json") },
+		cwd: root,
+	});
+
+	const content = await readFile(configPath, "utf8");
+	assert.deepEqual(result.changed, [configPath]);
+	assert.doesNotMatch(content, /\[mcp_servers\.context7\]/);
+	assert.doesNotMatch(content, /@upstash\/context7-mcp/);
+	assert.doesNotMatch(content, /YOUR_API_KEY/);
+	assert.match(content, /\[plugins\."omo@sisyphuslabs"\.mcp_servers\.context7\][\s\S]*?enabled = true/);
+});
+
+test("#given real Context7 API key and placeholder comment #when migrating #then preserves user server settings", async () => {
+	const root = await mkdtemp(join(tmpdir(), "lazycodex-context7-real-key-"));
+	const codexHome = join(root, "codex-home");
+	const configPath = join(codexHome, "config.toml");
+	await mkdir(codexHome, { recursive: true });
+	await writeFile(
+		configPath,
+		[
+			'model = "gpt-5.5"',
+			"model_context_window = 400000",
+			'model_reasoning_effort = "high"',
+			'plan_mode_reasoning_effort = "xhigh"',
+			"",
+			"[mcp_servers.context7]",
+			'command = "npx"',
+			'args = ["-y", "@upstash/context7-mcp", "--api-key", "ctx7sk_live_example"] # replace YOUR_API_KEY in docs only',
+			"startup_timeout_sec = 20",
+			"",
+			'[plugins."omo@sisyphuslabs".mcp_servers.context7]',
+			"enabled = true",
+			"",
+		].join("\n"),
+	);
+
+	const result = await migrateCodexConfig({
+		env: { CODEX_HOME: codexHome, LAZYCODEX_MODEL_CATALOG_STATE_PATH: join(root, "model-state.json") },
+		cwd: root,
+	});
+
+	const content = await readFile(configPath, "utf8");
+	assert.deepEqual(result.changed, [configPath]);
+	assert.match(content, /\[mcp_servers\.context7\]/);
+	assert.match(content, /ctx7sk_live_example/);
+	assert.match(content, /replace YOUR_API_KEY in docs only/);
+	assert.match(content, /\[plugins\."omo@sisyphuslabs"\.mcp_servers\.context7\][\s\S]*?enabled = true/);
 });
 
 test("#given multi_agent_v2 enabled #when forcing disable #then flips the flag to false", () => {
@@ -470,18 +584,23 @@ test("#given an annotated managed section #when forcing disable runs again #then
 	assert.match(rerun, /enabled = false/);
 });
 
-test("#given [features] boolean shorthand multi_agent_v2 = false #when forcing disable #then returns config unchanged", () => {
+test("#given [features] boolean shorthand multi_agent_v2 = false #when forcing disable #then rewrites to the non-conflicting disabled table", () => {
 	const config = [
 		'model = "gpt-5.5"',
 		"",
 		"[features]",
 		"multi_agent_v2 = false",
+		"plugins = true",
 		"",
 	].join("\n");
 
 	const result = forceDisableMultiAgentV2(config);
+	const parsed = parseTomlWithPython(result);
 
-	assert.equal(result, config);
+	assert.doesNotMatch(result, /^\s*multi_agent_v2\s*=/m);
+	assert.equal((result.match(/\[features\.multi_agent_v2\]/g) ?? []).length, 1);
+	assert.equal(parsed.features.plugins, true);
+	assert.equal(parsed.features.multi_agent_v2.enabled, false);
 });
 
 test("#given multi_agent_v2 already disabled #when forcing disable #then returns config unchanged", () => {
@@ -520,8 +639,87 @@ test("#given global config without multi_agent_v2 section #when full migration r
 	});
 
 	assert.deepEqual(result.changed, [configPath]);
+	assert.deepEqual(result.modeChanged, []);
 	const content = await readFile(configPath, "utf8");
-	assert.match(content, /\[features\.multi_agent_v2\]\nenabled = false\n/);
+	assert.match(content, /\[features\.multi_agent_v2\][\s\S]*?enabled = false/);
+	assert.match(content, /max_concurrent_threads_per_session = 1000/);
+	assert.match(content, /\[agents\][\s\S]*?max_threads = 1000/);
+	assert.doesNotMatch(content, /^\s*multi_agent_mode\s*=/m);
+});
+
+test("#given global config starts with inline-comment features table #when full migration runs #then managed root settings stay at TOML root", async () => {
+	const root = await mkdtemp(join(tmpdir(), "lazycodex-root-settings-inline-features-"));
+	const codexHome = join(root, "codex-home");
+	await mkdir(codexHome, { recursive: true });
+	const configPath = join(codexHome, "config.toml");
+	await writeFile(
+		configPath,
+		[
+			"[features] # keep comment",
+			"plugins = true",
+			"",
+		].join("\n"),
+	);
+
+	const result = await migrateCodexConfig({
+		env: { CODEX_HOME: codexHome, LAZYCODEX_MODEL_CATALOG_STATE_PATH: join(root, "model-state.json") },
+		cwd: root,
+	});
+
+	assert.deepEqual(result.changed, [configPath]);
+	const content = await readFile(configPath, "utf8");
+	const parsed = parseTomlWithPython(content);
+	assert.equal("multi_agent_mode" in parsed, false);
+	assert.equal(parsed.model, "gpt-5.5");
+	assert.equal(parsed.model_context_window, 400000);
+	assert.equal(parsed.model_reasoning_effort, "high");
+	assert.equal(parsed.plan_mode_reasoning_effort, "xhigh");
+	assert.equal(parsed.features.plugins, true);
+	assert.equal("multi_agent_mode" in parsed.features, false);
+	assert.equal("model" in parsed.features, false);
+	assert.equal("model_context_window" in parsed.features, false);
+	assert.match(content, /^model = "gpt-5\.5"\nmodel_context_window = 400000/m);
+	assert.doesNotMatch(content, /^\s*multi_agent_mode\s*=/m);
+	assert.match(content, /\[features\] # keep comment\nplugins = true/);
+});
+
+test("#given queue multi-agent mode #when removing unsupported root key #then deletes root setting", () => {
+	const config = ['multi_agent_mode = "queue"', "", "[features]", "multi_agent = true", ""].join("\n");
+
+	const result = removeUnsupportedRootMultiAgentMode(config);
+
+	assert.doesNotMatch(result, /^\s*multi_agent_mode\s*=/m);
+	assert.doesNotMatch(result, /multi_agent_mode = "queue"/);
+	assert.match(result, /\[features\]/);
+});
+
+test("#given proactive multi-agent mode #when removing unsupported root key #then deletes root setting", () => {
+	const config = ['multi_agent_mode = "proactive" # user already opted in', "", "[features]", "multi_agent = true", ""].join("\n");
+
+	const result = removeUnsupportedRootMultiAgentMode(config);
+
+	assert.doesNotMatch(result, /^\s*multi_agent_mode\s*=/m);
+	assert.match(result, /\[features\]/);
+});
+
+test("#given inline-comment features table #when removing unsupported root key #then config stays unchanged", () => {
+	const config = ["[features] # keep comment", "multi_agent = true", ""].join("\n");
+
+	const result = removeUnsupportedRootMultiAgentMode(config);
+	const parsed = parseTomlWithPython(result);
+
+	assert.equal(result, config);
+	assert.equal("multi_agent_mode" in parsed, false);
+	assert.equal(parsed.features.multi_agent, true);
+});
+
+test("#given indented root proactive mode #when removing unsupported root key #then no root setting remains", () => {
+	const config = ['  multi_agent_mode = "proactive" # user already opted in', "", "[features] # keep comment", "multi_agent = true", ""].join("\n");
+
+	const result = removeUnsupportedRootMultiAgentMode(config);
+
+	assert.equal(result.match(/multi_agent_mode\s*=/g)?.length ?? 0, 0);
+	assert.match(result, /^\[features\] # keep comment$/m);
 });
 
 test("#given global config with forced multi_agent_v2 #when full migration runs #then disables it on disk", async () => {
@@ -551,6 +749,8 @@ test("#given global config with forced multi_agent_v2 #when full migration runs
 	const content = await readFile(configPath, "utf8");
 	assert.match(content, /enabled = false/);
 	assert.doesNotMatch(content, /enabled = true/);
+	assert.match(content, /max_concurrent_threads_per_session = 1000/);
+	assert.match(content, /\[agents\][\s\S]*?max_threads = 1000/);
 });
 
 test("#given enabled = true with an inline comment #when forcing disable #then flips to false and preserves the comment", () => {

package/packages/omo-codex/plugin/test/node-install-surface.test.mjs

@@ -25,5 +25,6 @@ test("#given Codex Light install docs #when inspected #then lazycodex is npm-fir
 	for (const [path, text] of docs) {
 		assert.match(text, /\bnpx lazycodex-ai install\b/, `${path} should document the Node/npm install command`);
 		assert.doesNotMatch(text, /\bbunx lazycodex-ai\b/, `${path} should not require Bun for lazycodex`);
+		assert.doesNotMatch(text, /npx\s+--package\s+oh-my-openagent\s+omo\s+install/, `${path} should not recommend the Windows-broken --package install command`);
 	}
 });

package/packages/omo-codex/plugin/test/subagent-limit-migration.test.mjs

@@ -0,0 +1,44 @@
+import assert from "node:assert/strict";
+import { mkdtemp, readFile, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import test from "node:test";
+
+import { migrateConfigFile } from "../scripts/migrate-codex-config.mjs";
+
+test("#given SessionStart config migration sees a low subagent cap #when migrating #then raises it to 1000", async () => {
+	const root = await mkdtemp(join(tmpdir(), "lazycodex-subagent-limit-migration-"));
+	const configPath = join(root, "config.toml");
+	await writeFile(
+		configPath,
+		[
+			'model = "gpt-5.4"',
+			"model_context_window = 123456",
+			'model_reasoning_effort = "medium"',
+			'plan_mode_reasoning_effort = "medium"',
+			"",
+			"[agents]",
+			"max_threads = 6",
+			"max_depth = 4",
+			"",
+			"[agents.explorer]",
+			'config_file = "./agents/explorer.toml"',
+			"",
+			"[features.multi_agent_v2]",
+			"enabled = false",
+			"max_concurrent_threads_per_session = 6",
+			"",
+		].join("\n"),
+	);
+
+	const result = await migrateConfigFile(configPath);
+
+	const content = await readFile(configPath, "utf8");
+	assert.equal(result.changed, true);
+	assert.match(content, /\[agents\][\s\S]*?max_threads = 1000/);
+	assert.match(content, /max_depth = 4/);
+	assert.match(content, /\[agents\.explorer\]\nconfig_file = "\.\/agents\/explorer\.toml"/);
+	assert.match(content, /\[features\.multi_agent_v2\][\s\S]*?enabled = false/);
+	assert.match(content, /max_concurrent_threads_per_session = 1000/);
+	assert.doesNotMatch(content, /^max_threads\s*=\s*6$/m);
+});

package/packages/omo-codex/plugin/test/sync-skills-orchestration.test.mjs

@@ -20,10 +20,19 @@ async function readSkill(skillName) {
 	return readFile(join(root, "skills", skillName, "SKILL.md"), "utf8");
 }
 
+async function readSharedSkill(skillName) {
+	return readFile(join(root, "../../shared-skills/skills", skillName, "SKILL.md"), "utf8");
+}
+
 function patternFromParts(parts, flags) {
 	return new RegExp(parts.join(""), flags);
 }
 
+const multiAgentV2RoleGuidance =
+	"On `multi_agent_v2` sessions the same `agent_type` applies (the OMO installer exposes it) with `fork_turns` instead of `fork_context`.";
+const loadSkillsGuidance =
+	"When translating `load_skills=[...]`, include the requested skill names in the spawned agent's `message`.";
+
 test("#given synced aggregate Codex skills #when they contain OpenCode orchestration examples #then Codex tool compatibility guidance is injected", async () => {
 	// given
 	const opencodeOnlyToolPattern = /\b(?:call_omo_agent|background_output|team_[a-z_]+|task)\s*\(/;
@@ -41,6 +50,8 @@ test("#given synced aggregate Codex skills #when they contain OpenCode orchestra
 			compatibilityIndex < content.search(opencodeOnlyToolPattern),
 			`${skillName} must explain Codex tool translation before OpenCode-only examples`,
 		);
+		assert.ok(content.includes(multiAgentV2RoleGuidance), `${skillName} missing multi_agent_v2 role guidance`);
+		assert.ok(content.includes(loadSkillsGuidance), `${skillName} missing load_skills guidance`);
 	}
 });
 
@@ -77,7 +88,7 @@ task(category="quick", prompt="verify")
 	assert.ok(compatibilityIndex < firstToolIndex);
 	assert.equal(adapted.match(/## Codex Harness Tool Compatibility/g)?.length, 1);
 	assert.doesNotMatch(adapted, /Older variant guidance/);
-	assert.doesNotMatch(adapted, /When translating `load_skills=\[\.\.\.\]`/);
+	assert.doesNotMatch(adapted, /name the skills inside the spawned agent's `message`/);
 	assert.match(adapted, /\n---\n\n## Next Section/);
 });
 
@@ -141,6 +152,25 @@ call_omo_agent(subagent_type="explore", prompt="inspect")
 	assert.doesNotMatch(adapted, /Obsolete generated compatibility prose/);
 });
 
+test("#given generated Codex compatibility guidance #when adapting a skill #then multi-agent role and load_skills guidance are both present", () => {
+	// given
+	const content = `---
+name: example
+---
+
+# Example Skill
+
+task(subagent_type="oracle", load_skills=["debugging"], prompt="verify")
+`;
+
+	// when
+	const adapted = insertCodexCompatibilityGuidance(content);
+
+	// then
+	assert.ok(adapted.includes(multiAgentV2RoleGuidance));
+	assert.ok(adapted.includes(loadSkillsGuidance));
+});
+
 test("#given generated guidance before a template export #when adapting a skill #then the export wrapper is preserved", () => {
 	// given
 	const content = `---
@@ -214,3 +244,22 @@ test("#given review-work skill #when some lanes do not finish #then aggregate re
 	assert.match(content, /Do not spin in repeated/);
 	assert.match(content, /Do not use `multi_agent_v1\.send_input` as an interrupt/);
 });
+
+test("#given PR and review skills #when synced for Codex #then worktree lifecycle is mandatory", async () => {
+	const startWork = await readSkill("start-work");
+	const reviewWork = await readSkill("review-work");
+	const sharedStartWork = await readSharedSkill("start-work");
+
+	assert.match(startWork, /PR creation, PR handoff, branch handoff, or merge/);
+	assert.match(startWork, /Finish the PR\/branch lifecycle from its task-owned worktree/);
+	assert.match(startWork, /merge by default unless explicitly opted out/);
+	assert.match(startWork, /No PR\/branch implementation or review in the main worktree/);
+
+	assert.match(sharedStartWork, /required for PR\/branch work/);
+	assert.match(sharedStartWork, /No PR\/branch implementation, review, or merge in the main worktree/);
+	assert.doesNotMatch(sharedStartWork, /If worktree mode was used/);
+	assert.doesNotMatch(sharedStartWork, /merge or hand off exactly as requested/);
+
+	assert.match(reviewWork, /dedicated review worktree attached to that branch/);
+	assert.match(reviewWork, /Never\s+checkout, test, or edit the review branch in the main worktree/);
+});

package/packages/omo-codex/plugin/test/sync-skills-test-support.mjs

@@ -6,6 +6,7 @@ export const CONTEXT_PRESSURE_SKILL_BUDGET_BYTES = 25_000;
 
 export const expectedSkills = [
 	"ast-grep",
+	"coding-agent-sessions",
 	"comment-checker",
 	"debugging",
 	"frontend",
@@ -27,6 +28,7 @@ export const expectedSkills = [
 	"ultraresearch",
 	"ulw-loop",
 	"ulw-plan",
+	"ulw-research",
 	"visual-qa",
 ];
 
@@ -41,6 +43,7 @@ export const componentSkillSources = [
 
 const codexCompatibilityEndMarkers = [
 	"For work likely to exceed one wait cycle, require the child to send `WORKING: <task> - <current phase>` before long passes and `BLOCKED: <reason>` only when progress stops. A `multi_agent_v1.wait_agent` timeout only means no new mailbox update arrived. Treat a running child as alive. Fallback only when the child is completed without the deliverable, ack-only after followup, explicitly `BLOCKED:`, or no longer running.\n\n",
+	"On `multi_agent_v2` sessions the same `agent_type` applies (the OMO installer exposes it) with `fork_turns` instead of `fork_context`. If a code block below conflicts with this section, this section wins.\n\n",
 	"Role-specific behavior must be described in a self-contained `message`. Use `fork_context: false` to start the child with only the initial prompt (no parent history); use `fork_context: true` only when full parent history is truly required. Include any required conversation context, files, diffs, constraints, and requested skill names directly in the spawned agent's `message`. If a code block below conflicts with this section, this section wins.\n\n",
 	"When translating `load_skills=[...]`, include the requested skill names in the spawned agent's `message`. If a code block below conflicts with this section, this section wins.\n\n",
 	"When translating `load_skills=[...]`, name the skills inside the spawned agent's `message`. If a code block below conflicts with this section, this section wins.\n\n",
@@ -64,29 +67,29 @@ export function removeCodexCompatibilityGuidance(content) {
 const startWorkOriginalCompletion = `When all top-level checkboxes in \`## TODOs\` and \`## Final Verification Wave\` are complete:
 
 1. Run the plan's final verification commands.
-2. If worktree mode was used, sync \`.omo/\` state back to the main repo, merge or hand off exactly as requested, and remove the worktree only after successful merge or explicit handoff.
+2. For PR/branch work, finish the lifecycle from the task-owned worktree: sync \`.omo/\` state back to the main repo, create or update the PR, wait for review/verification gates, merge by default unless explicitly opted out, and remove the worktree only after successful merge or explicit handoff.
 3. Remove or mark the Boulder work as completed.
 4. Print an \`ORCHESTRATION COMPLETE\` block with the plan path, verification commands, artifacts, and cleanup receipts.`;
 
 const startWorkCodexCompletion = `When all top-level checkboxes in \`## TODOs\` and \`## Final Verification Wave\` are complete:
 
 1. Run the plan's final verification commands.
-2. Complete the **Global Review and Debugging Gate** before any completion claim, PR handoff, or branch handoff:
+2. Complete the **Global Review and Debugging Gate** before any completion claim, PR creation, PR handoff, branch handoff, or merge:
    - Invoke the \`review-work\` skill with the final diff, changed files, user goal, constraints, run command, and verification evidence. All five review lanes must return PASS. A timeout, missing deliverable, ack-only child, \`BLOCKED:\`, or inconclusive lane is a gate failure, not approval.
    - Run a debugging-oriented runtime audit even when the review passes: name at least three plausible failure hypotheses for the changed surface, run the distinguishing checks against the actual artifact, and append the ruled-out or confirmed result to \`.omo/start-work/ledger.jsonl\`.
    - If any review lane or debugging hypothesis fails, invoke the \`debugging\` skill, confirm root cause with runtime evidence, add the minimal failing test or reproduction, fix it, rerun the affected verification, then rerun the Global Review and Debugging Gate.
    - Evidence hygiene is mandatory: redact or mask secrets and sensitive user data before writing \`.omo/start-work/ledger.jsonl\`, a PR body, or a handoff. Never include raw tokens, credentials, auth headers, cookies, API keys, env dumps, private logs, or PII; use concise summaries, lengths, hashes, or short non-sensitive prefixes instead.
-   - If the work includes creating, updating, or handing off a PR, refresh \`git status\` and the PR/branch state after the gate, and include only redacted review/debugging evidence in the PR body or handoff.
-3. If worktree mode was used, sync \`.omo/\` state back to the main repo, merge or hand off exactly as requested, and remove the worktree only after successful merge or explicit handoff.
+   - If the work includes creating, updating, or handing off a PR, refresh \`git status\` and the PR/branch state from the task-owned worktree after the gate, and include only redacted review/debugging evidence in the PR body or handoff.
+3. Finish the PR/branch lifecycle from its task-owned worktree: sync \`.omo/\` state back to the main repo, create or update the PR when requested, wait for CI/review/Cubic gates, merge by default unless explicitly opted out, and remove the worktree only after successful merge or explicit handoff.
 4. Remove or mark the Boulder work as completed.
 5. Print an \`ORCHESTRATION COMPLETE\` block with the plan path, verification commands, Global Review and Debugging Gate verdict, artifacts, and cleanup receipts.`;
 
-const startWorkOriginalHardRule = "- No completion claim while an applicable ultraqa adversarial class was never probed. Each applicable class needs a captured observable result; each skipped class needs a one-line not-applicable reason in the ledger.\n- No unprefixed session ids in Boulder state. Codex sessions are always `codex:<session_id>`.";
+const startWorkOriginalHardRule = "- No completion claim while an applicable ultraqa adversarial class was never probed. Each applicable class needs a captured observable result; each skipped class needs a one-line not-applicable reason in the ledger.\n- No PR/branch implementation, review, or merge in the main worktree; use the task-owned git worktree.\n- No unprefixed session ids in Boulder state. Codex sessions are always `codex:<session_id>`.";
 
-const startWorkCodexHardRule = "- No completion claim while an applicable ultraqa adversarial class was never probed. Each applicable class needs a captured observable result; each skipped class needs a one-line not-applicable reason in the ledger.\n- No `ORCHESTRATION COMPLETE`, final response, PR creation, or PR handoff before the Global Review and Debugging Gate passes with recorded evidence.\n- No unprefixed session ids in Boulder state. Codex sessions are always `codex:<session_id>`.";
+const startWorkCodexHardRule = "- No completion claim while an applicable ultraqa adversarial class was never probed. Each applicable class needs a captured observable result; each skipped class needs a one-line not-applicable reason in the ledger.\n- No `ORCHESTRATION COMPLETE`, final response, PR creation, PR handoff, or merge before the Global Review and Debugging Gate passes with recorded evidence.\n- No PR/branch implementation or review in the main worktree; create or use a task-owned git worktree first.\n- No unprefixed session ids in Boulder state. Codex sessions are always `codex:<session_id>`.";
 
 const reviewWorkCodexGatePattern =
-	/\nWhen `review-work` is used as a final implementation, PR, or `\$start-work`\ngate, it is blocking\. A timeout, missing deliverable, ack-only response,\nexplicit `BLOCKED:`, or inconclusive lane is not a pass\. Treat that lane as\nfailed, investigate the underlying uncertainty with the `debugging` skill when\nruntime behavior may be wrong, fix with evidence, and rerun the affected lane\nbefore claiming completion or handing off a PR\.\n\nReview evidence must be safe to share\. Redact or mask secrets and sensitive\nuser data before including evidence in logs, PR bodies, or handoffs\. Never\ninclude raw tokens, credentials, auth headers, cookies, API keys, env dumps,\nprivate logs, or PII; summarize with lengths, hashes, and short non-sensitive\nprefixes when identity is needed\.\n/;
+	/\nWhen `review-work` is used as a final implementation, PR, or `\$start-work`\ngate, it is blocking\. A timeout, missing deliverable, ack-only response,\nexplicit `BLOCKED:`, or inconclusive lane is not a pass\. Treat that lane as\nfailed, investigate the underlying uncertainty with the `debugging` skill when\nruntime behavior may be wrong, fix with evidence, and rerun the affected lane\nbefore claiming completion, creating or handing off a PR, or merging\.\n\nWhen reviewing a PR or branch, collect diff, file contents, and verification\nresults from a dedicated review worktree attached to that branch\. Never\ncheckout, test, or edit the review branch in the main worktree\.\n\nReview evidence must be safe to share\. Redact or mask secrets and sensitive\nuser data before including evidence in logs, PR bodies, or handoffs\. Never\ninclude raw tokens, credentials, auth headers, cookies, API keys, env dumps,\nprivate logs, or PII; summarize with lengths, hashes, and short non-sensitive\nprefixes when identity is needed\.\n/;
 
 export function removeCodexSkillOverlays(skillName, content) {
 	if (skillName === "start-work") {

package/packages/omo-codex/plugin/test/sync-skills.test.mjs

@@ -112,10 +112,22 @@ test("#given shared skill source tests #when aggregate Codex skills are synced #
 	const aggregateSkillsRoot = join(root, "skills");
 
 	// when
-	const visualQaFiles = await listSkillFiles(join(aggregateSkillsRoot, "visual-qa"));
+	const forbiddenFiles = [];
+	for (const skillName of expectedSkills) {
+		for (const file of await listSkillFiles(join(aggregateSkillsRoot, skillName))) {
+			const normalized = file.replaceAll("\\", "/");
+			const segments = normalized.split("/");
+			const scriptsIndex = segments.lastIndexOf("scripts");
+			const hasPythonTestDir = scriptsIndex !== -1 && segments[scriptsIndex + 1] === "tests";
+			const isSourceMetadata = normalized === ".gitignore" || normalized === ".npmignore" || normalized === "pyrightconfig.json";
+			if (normalized.endsWith(".test.ts") || hasPythonTestDir || segments.includes("__pycache__") || normalized.endsWith(".pyc") || isSourceMetadata) {
+				forbiddenFiles.push(`${skillName}/${normalized}`);
+			}
+		}
+	}
 
 	// then
-	assert.equal(visualQaFiles.some((file) => file.endsWith(".test.ts")), false);
+	assert.deepEqual(forbiddenFiles, []);
 });
 
 test("#given component skill sources #when aggregate Codex component skills are inspected #then generated copies have no hand-authored drift", async () => {
@@ -169,6 +181,20 @@ test("#given synced ulw-loop skill #when Codex hint metadata is inspected #then
 	assert.match(interfaceMetadata, /- "ulw-loop"/);
 });
 
+test("#given synced legacy ultraresearch alias #when inspected #then it points users at ulw-research", async () => {
+	// given
+	const skillRoot = join(root, "skills", "ultraresearch");
+
+	// when
+	const skill = await readFile(join(skillRoot, "SKILL.md"), "utf8");
+	const interfaceMetadata = await readFile(join(skillRoot, "agents", "openai.yaml"), "utf8");
+
+	// then
+	assert.match(skill, /^---\r?\nname: ultraresearch\r?\n/m);
+	assert.match(skill, /legacy name for `ulw-research`/);
+	assert.match(interfaceMetadata, /display_name: "\(OmO\) ultraresearch"/);
+});
+
 test("#given synced git-master skill #when inspected #then commits and git history route through it", async () => {
 	// given
 	const skillRoot = join(root, "skills", "git-master");

package/packages/omo-codex/plugin/test/teammode-archive-ambiguity.test.mjs

@@ -0,0 +1,102 @@
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import test from "node:test";
+
+import { root } from "./aggregate-plugin-fixture.mjs";
+import { cleanupTeamRoot, createTeamRoot, readTeamJson, runTeam } from "./teammode-safety-fixture.mjs";
+
+const teammodeSkillPath = join("components", "teammode", "skills", "teammode", "SKILL.md");
+
+test("#given Codex App thread ids can be ambiguous across hosts #when archive guidance is read #then it separates app-thread archival from team-state archival", () => {
+	const body = readFileSync(join(root, teammodeSkillPath), "utf8");
+
+	assert.match(
+		body,
+		/Ambiguous Codex thread id|ambiguous across hosts/i,
+		"archive guidance must name the Codex App multi-host ambiguity failure instead of only saying the archive tool is unavailable",
+	);
+	assert.match(
+		body,
+		/app-thread archival blocker/i,
+		"archive guidance must classify ambiguous app-thread ids as app-thread archival blockers",
+	);
+	assert.match(
+		body,
+		/record .*team log/i,
+		"archive guidance must require a durable team-log record when app-thread archival cannot be proven",
+	);
+	assert.match(
+		body,
+		/continue .*team-state archive/i,
+		"archive guidance must let the team-state archive proceed after recording the app-thread archival blocker",
+	);
+	assert.match(
+		body,
+		/archive --note/i,
+		"archive guidance must route ambiguous app-thread archive blockers into archive --note evidence",
+	);
+	assert.match(
+		body,
+		/Do not delete/i,
+		"archive guidance must keep evidence available until ambiguous app-thread archival is resolved",
+	);
+});
+
+test("#given app-thread archival is blocked by an ambiguous id #when archive runs with a note #then team state is archived and keeps the blocker in the log", () => {
+	const tempRoot = createTeamRoot("omo-codex-teammode-archive-ambiguity-");
+	try {
+		runTeam(tempRoot, "init", "--name", "ArchiveQA", "--session-name", "cleanup", "--session", "archive-ambiguity");
+		runTeam(
+			tempRoot,
+			"add-member",
+			"--team",
+			"archive-ambiguity",
+			"--id",
+			"A",
+			"--name",
+			"local",
+			"--focus",
+			"local host member",
+			"--lens",
+			"area",
+			"--deliverable",
+			"local notes",
+		);
+		runTeam(
+			tempRoot,
+			"add-member",
+			"--team",
+			"archive-ambiguity",
+			"--id",
+			"B",
+			"--name",
+			"remote",
+			"--focus",
+			"remote host member",
+			"--lens",
+			"perspective",
+			"--deliverable",
+			"remote notes",
+		);
+		runTeam(tempRoot, "bind-thread", "--team", "archive-ambiguity", "--id", "A", "--thread", "duplicate-thread-id");
+		runTeam(tempRoot, "bind-thread", "--team", "archive-ambiguity", "--id", "B", "--thread", "remote-thread-id");
+
+		const blocker = "app-thread archive blocker: Ambiguous Codex thread id duplicate-thread-id; matching hosts: local, remote-ssh-discovered:m5";
+		runTeam(tempRoot, "archive", "--team", "archive-ambiguity", "--note", blocker);
+		const team = readTeamJson(tempRoot, "archive-ambiguity");
+
+		assert.equal(team.status, "archived");
+		assert.deepEqual(
+			team.members.map((member) => member.status),
+			["archived", "archived"],
+		);
+		assert.equal(
+			team.log.some((entry) => entry.event === "archive" && entry.detail === blocker),
+			true,
+			"team log must preserve the app-thread archival blocker after durable team-state archival",
+		);
+	} finally {
+		cleanupTeamRoot(tempRoot);
+	}
+});