oh-my-opencode 4.12.1 → 4.14.0

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/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",
@@ -23,9 +24,11 @@ export const expectedSkills = [
 	"rules",
 	"start-work",
 	"teammode",
+	"ultimate-browsing",
 	"ultraresearch",
 	"ulw-loop",
 	"ulw-plan",
+	"ulw-research",
 	"visual-qa",
 ];
 
@@ -40,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",
@@ -63,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-communication.test.mjs

@@ -0,0 +1,107 @@
+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, runTeam, teamDir } from "./teammode-safety-fixture.mjs";
+
+// The teammode guide.md is what every member actually reads. The real run of leader session
+// 019eed1e- proved members default to silence: 10 members, ~6 min, 4 end-of-work reports, zero
+// peer messages, zero mid-task reports, zero send_message_to_thread calls - because the prose said
+// "over-communicate relentlessly" (aspirational, no trigger) and never named the tool or targets.
+// These tests pin the fix: a concrete push-communication protocol is the default the manual renders.
+
+function buildTwoMemberTeam(tempRoot, sessionId) {
+	runTeam(tempRoot, "init", "--name", "Comms", "--session-name", "frequent", "--session", sessionId);
+	runTeam(tempRoot, "add-member", "--team", sessionId, "--id", "A", "--name", "alpha", "--focus", "slice one", "--lens", "area", "--deliverable", "x");
+	runTeam(tempRoot, "add-member", "--team", sessionId, "--id", "B", "--name", "beta", "--focus", "slice two", "--lens", "area", "--deliverable", "y");
+	runTeam(tempRoot, "bind-thread", "--team", sessionId, "--id", "A", "--thread", "thread-A");
+	runTeam(tempRoot, "bind-thread", "--team", sessionId, "--id", "B", "--thread", "thread-B");
+}
+
+function readGuide(tempRoot, sessionId) {
+	return readFileSync(join(teamDir(tempRoot, sessionId), "guide.md"), "utf8");
+}
+
+test("#given a bound team #when the member field manual renders #then it names the cross-thread tool and the team.json address book", () => {
+	const tempRoot = createTeamRoot("omo-codex-teammode-comms-");
+	try {
+		buildTwoMemberTeam(tempRoot, "comms-tool");
+		const guide = readGuide(tempRoot, "comms-tool");
+
+		// then - members are told the concrete TOOL to reach leader+peers, not left to narrate
+		assert.match(guide, /codex_app\.send_message_to_thread/, "guide must name the cross-thread messaging tool");
+		// then - members are pointed at the concrete address book in team.json
+		assert.match(guide, /leader\.sessionId/, "guide must say the leader thread id is team.json leader.sessionId");
+		assert.match(guide, /members\[\]\.threadId/, "guide must say peer thread ids are team.json members[].threadId");
+	} finally {
+		cleanupTeamRoot(tempRoot);
+	}
+});
+
+test("#given a bound team #when the member field manual renders #then it gives concrete per-moment cadence triggers, not aspirational 'constantly'", () => {
+	const tempRoot = createTeamRoot("omo-codex-teammode-comms-");
+	try {
+		buildTwoMemberTeam(tempRoot, "comms-cadence");
+		const guide = readGuide(tempRoot, "comms-cadence");
+
+		// then - a concrete heartbeat cadence the model can bind to
+		assert.match(guide, /every few tool calls/, "guide must give a concrete heartbeat trigger");
+		assert.match(guide, /WORKING:/, "guide must keep the WORKING heartbeat marker");
+		assert.match(guide, /BLOCKED:/, "guide must keep the BLOCKED marker");
+		// then - an explicit peer-notify rule so cross-cutting findings are pushed, not siloed
+		assert.match(guide, /to a \*\*peer\*\*/, "guide must have an explicit peer-notify rule");
+		assert.match(guide, /touches their slice/, "guide must trigger peer messages on slice-touching findings");
+		// then - the reassurance WHY that ties the two halves together: frequent reporting is what earns
+		// uninterrupted focus, so the leader has no reason to interrupt a member who keeps it informed
+		assert.match(guide, /uninterrupted focus/i, "guide must tell members frequent updates buy uninterrupted focus from the leader");
+		// then - the end-only directive that previously won is gone (it licensed batch-at-the-end reporting)
+		assert.doesNotMatch(guide, /the moment your work is complete/, "the standalone end-only report directive must be removed");
+	} finally {
+		cleanupTeamRoot(tempRoot);
+	}
+});
+
+test("#given a member bootstrap trigger #when it is generated #then it points at the push tool and a continuous cadence, not an end-of-work report", () => {
+	const tempRoot = createTeamRoot("omo-codex-teammode-comms-");
+	try {
+		buildTwoMemberTeam(tempRoot, "comms-bootstrap");
+		const prompt = runTeam(tempRoot, "member-prompt", "--team", "comms-bootstrap", "--id", "A").stdout;
+
+		// then - the first thing a member reads tells it to push via the tool as it works
+		assert.match(prompt, /codex_app\.send_message_to_thread/, "bootstrap must name the push tool");
+		assert.match(prompt, /never just one report at the end/, "bootstrap must reject end-only reporting");
+		// then - it no longer frames reporting as a one-shot completion event
+		assert.doesNotMatch(prompt, /report to the leader the moment you are done/, "the end-only bootstrap line must be removed");
+	} finally {
+		cleanupTeamRoot(tempRoot);
+	}
+});
+
+test("#given the leader-facing SKILL.md #when it describes communication #then it requires --session so members can reach the leader and frames members as pushing", () => {
+	const skill = readFileSync(join(root, "components", "teammode", "skills", "teammode", "SKILL.md"), "utf8");
+
+	// then - the leader is told members PUSH to it (not only that the leader sends)
+	assert.match(skill, /Members push to you/i, "SKILL.md must frame members as pushing to the leader");
+	// then - the --session requirement is stated WITH its reason (member->leader push needs a real leader thread)
+	assert.match(skill, /--session <your own thread id>/, "SKILL.md must require init --session <your own thread id>");
+	assert.match(skill, /stuck polling|cannot report to you/i, "SKILL.md must explain why --session matters");
+});
+
+// The leader (a GPT-5.5 main session) over-polls when nothing reframes silence as work: real jobdori
+// run 019f07a6- fired 6 leader->child pings, 4 pure "WORKING CHECK"/"NUDGE" nags that interrupted the
+// child mid-slice. The member guide already mandates frequent reporting; the missing half is telling the
+// leader to WAIT. These tests pin that the leader-facing skill reframes quiet-as-working and gates any
+// outbound ping behind concrete decision rules instead of letting anxiety drive a barrage.
+test("#given the leader-facing SKILL.md #when it covers waiting on members #then it reframes a quiet member as working and gates leader pings behind decision rules", () => {
+	const skill = readFileSync(join(root, "components", "teammode", "skills", "teammode", "SKILL.md"), "utf8");
+
+	// then - a quiet member between heartbeats is reframed as working, not a stall to chase
+	// (\s+ tolerates markdown line-wrapping between the two words)
+	assert.match(skill, /working,\s+not stalled/i, "SKILL.md must reframe a quiet member as working, not stalled");
+	// then - outbound leader messages are gated behind explicit decision rules, not anxiety
+	assert.match(skill, /Message a member only when/i, "SKILL.md must gate leader pings behind a concrete decision rule");
+	// then - the anti-pattern nag pings the real run produced are named as what NOT to send
+	assert.match(skill, /are you\s+done\?/i, "SKILL.md must name the 'are you done?' style nag as forbidden");
+});