oh-my-opencode 4.16.0 → 4.16.2

package/packages/omo-codex/plugin/scripts/migrate-codex-config/multi-agent-v2-guard.mjs

@@ -1,20 +1,31 @@
 /**
- * Runtime migration: force `[features.multi_agent_v2]` to `enabled = false`.
+ * Runtime migration for `[features.multi_agent_v2]`.
  *
- * Runs on every Codex SessionStart (via auto-update's config migration) so
- * multi-agent V2 stays off regardless of how it was turned on: an
- * installer-forced `enabled = true`, a missing `enabled` key the runtime
- * would resolve per model, or the `[features]` boolean shorthand
- * `multi_agent_v2 = true` (removed here because a boolean key and a
- * `[features.multi_agent_v2]` table for the same name are conflicting TOML).
+ * Historical behavior (openai/codex#26753): force `enabled = false` on every
+ * SessionStart because enabling V2 made every turn 400 with encrypted
+ * spawn_agent parameters on models that were not configured for encrypted
+ * tool use. OpenAI closed that as NOT_PLANNED (V2 under development).
  *
- * Upstream basis: openai/codex#26753 — with the flag on, EVERY turn fails
- * with a 400 ("spawn_agent declares encrypted parameters but is not
- * configured for encrypted tool use by this model"), even on prompts that
- * never touch subagents. OpenAI closed it NOT_PLANNED stating V2 is under
- * development, not recommended, and bug reports are not accepted. Same
- * failure class still being reported (openai/codex#27205).
+ * GPT-5.6 models that declare `multi_agent_version: "v2"` in the Codex model
+ * catalog invert that failure mode: forcing `enabled = false` makes every
+ * turn 400 with a reserved `collaboration.spawn_agent` schema mismatch
+ * (lazycodex#118 / oh-my-openagent#6002 / openai/codex#31097), and
+ * `hide_spawn_agent_metadata = false` (written by OMO installers <= 4.15.x)
+ * mismatches the same reserved schema by re-adding agent_type/model
+ * properties to spawn_agent. For those models this guard clears the managed
+ * disable and the stale metadata override, leaving V2 unset so Codex can
+ * follow model metadata.
+ *
+ * When the selected model is unknown or declares V1, keep the #26753
+ * force-disable path.
+ *
+ * Opt out of the whole migration with LAZYCODEX_CONFIG_MIGRATION_DISABLED=1
+ * (or OMO_CODEX_CONFIG_MIGRATION_DISABLED=1).
  */
+import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
 const MANAGED_COMMENT_MARKER = "openai/codex#26753";
 const MANAGED_DISABLE_COMMENT = [
 	"# Managed by LazyCodex: multi_agent_v2 is re-disabled on every Codex session start",
@@ -23,26 +34,157 @@ const MANAGED_DISABLE_COMMENT = [
 	"",
 ].join("\n");
 
-export function forceDisableMultiAgentV2(config) {
-	let result = removeFeaturesShorthand(config);
+/**
+ * @param {string} config
+ * @param {{
+ *   multiAgentVersion?: string | null,
+ *   sessionModel?: string | null,
+ *   requireSessionModel?: boolean,
+ *   env?: NodeJS.ProcessEnv,
+ *   modelsCachePath?: string,
+ * }} [options]
+ */
+export function forceDisableMultiAgentV2(config, options = {}) {
+	// Always normalize the legacy `[features]` boolean shorthand first: leaving
+	// `multi_agent_v2 = true|false` in place while a later guard appends the
+	// `[features.multi_agent_v2]` table would define the same name as both a
+	// scalar and a table, which Codex rejects as invalid TOML.
+	const normalized = removeFeaturesShorthand(config);
+	const sessionModel = normalizeModel(options.sessionModel);
+	const multiAgentVersion =
+		options.multiAgentVersion !== undefined
+			? options.multiAgentVersion
+			: resolveMultiAgentVersionFromConfig(normalized, options);
+
+	if (prefersMultiAgentV2(multiAgentVersion, sessionModel)) {
+		return clearMultiAgentV2DisableForReservedSchema(normalized);
+	}
+
+	// SessionStart can run with an override model (`codex -m gpt-5.6-terra`) while
+	// config.toml still lists a different default. If we cannot see the effective
+	// session model, do not force-disable — writing enabled=false would break a
+	// GPT-5.6 reserved collaboration.spawn_agent session.
+	if (options.requireSessionModel === true && !sessionModel) {
+		return normalized;
+	}
+
+	// Unknown catalog entry for an explicit session model: skip force-disable
+	// rather than assume the legacy encrypted-V2 failure mode.
+	if (sessionModel && multiAgentVersion == null) {
+		return normalized;
+	}
+
+	return forceDisableLegacyEncryptedV2(normalized);
+}
+
+/**
+ * True when the effective model should run MultiAgentV2: the catalog says
+ * "v2", or the catalog is unavailable but the model is a GPT-5.6 family
+ * model (which reserves the collaboration.spawn_agent schema).
+ * @param {"v1" | "v2" | null | undefined} multiAgentVersion
+ * @param {string | null | undefined} sessionModel
+ */
+export function prefersMultiAgentV2(multiAgentVersion, sessionModel) {
+	return multiAgentVersion === "v2" || (multiAgentVersion == null && isGpt56Family(normalizeModel(sessionModel)));
+}
+
+/**
+ * Resolve the effective model against Codex `models_cache.json`.
+ * Prefers SessionStart `model` over the root `model` in config.toml.
+ * @param {string} config
+ * @param {{ sessionModel?: string | null, env?: NodeJS.ProcessEnv, modelsCachePath?: string }} [options]
+ * @returns {"v1" | "v2" | null}
+ */
+export function resolveMultiAgentVersionFromConfig(config, options = {}) {
+	const model = normalizeModel(options.sessionModel) || readRootModel(config);
+	if (!model) return null;
+	return resolveMultiAgentVersionForModel(model, options);
+}
+
+/**
+ * @param {string} model
+ * @param {{ env?: NodeJS.ProcessEnv, modelsCachePath?: string }} [options]
+ * @returns {"v1" | "v2" | null}
+ */
+export function resolveMultiAgentVersionForModel(model, options = {}) {
+	const cachePath =
+		options.modelsCachePath?.trim() ||
+		join(options.env?.CODEX_HOME?.trim() || join(homedir(), ".codex"), "models_cache.json");
+
+	try {
+		const cache = JSON.parse(readFileSync(cachePath, "utf8"));
+		const models = Array.isArray(cache?.models) ? cache.models : [];
+		const entry = models.find((item) => item?.slug === model || item?.id === model);
+		const version = entry?.multi_agent_version;
+		if (version === "v1" || version === "v2") return version;
+		return null;
+	} catch {
+		return null;
+	}
+}
+
+export function readRootModel(config) {
+	const double = config.match(/^\s*model\s*=\s*"([^"]+)"/m);
+	if (double) return double[1];
+	const single = config.match(/^\s*model\s*=\s*'([^']+)'/m);
+	return single?.[1] ?? null;
+}
+
+function normalizeModel(value) {
+	if (typeof value !== "string") return null;
+	const trimmed = value.trim();
+	return trimmed.length > 0 ? trimmed : null;
+}
+
+function isGpt56Family(model) {
+	return typeof model === "string" && /^gpt-5\.6\b/i.test(model);
+}
+
+function clearMultiAgentV2DisableForReservedSchema(config) {
+	// `config` arrives shorthand-normalized from forceDisableMultiAgentV2.
+	const result = removeManagedDisableComments(config);
+
 	const section = findSection(result, "[features.multi_agent_v2]");
+	if (!section) return result;
+
+	// Two settings poison the reserved collaboration.spawn_agent schema on V2
+	// models (verified against codex-cli 0.144.1 + gpt-5.6-sol):
+	// - `enabled = false` forces the legacy V1 tool surface on some Codex
+	//   versions (#6002's failure shape);
+	// - `hide_spawn_agent_metadata = false` (written by OMO installers
+	//   <= 4.15.x to expose agent_type) re-adds agent_type/model/... to
+	//   spawn_agent, mismatching the reserved schema -> HTTP 400 every turn.
+	// Remove both; `hide_spawn_agent_metadata = true` matches the Codex
+	// default and is left alone.
+	const cleared = section.text
+		.replace(/^\s*enabled\s*=\s*false[ \t]*(?:#[^\n]*)?\n?/gm, "")
+		.replace(/^\s*hide_spawn_agent_metadata\s*=\s*false[ \t]*(?:#[^\n]*)?\n?/gm, "");
+	if (cleared === section.text) return result;
+	return result.slice(0, section.start) + cleared + result.slice(section.end);
+}
+
+// `config` arrives shorthand-normalized from forceDisableMultiAgentV2.
+function forceDisableLegacyEncryptedV2(config) {
+	const section = findSection(config, "[features.multi_agent_v2]");
 
 	if (!section) {
-		return ensureManagedComment(appendDisabledSection(result));
+		return ensureManagedComment(appendDisabledSection(config));
 	}
 
 	const enabledTruePattern = /^(\s*)enabled\s*=\s*true[ \t]*(#[^\n]*)?$/m;
 	if (enabledTruePattern.test(section.text)) {
-		const patched = section.text.replace(enabledTruePattern, (_match, indent, comment) => comment ? `${indent}enabled = false ${comment}` : `${indent}enabled = false`);
-		return ensureManagedComment(result.slice(0, section.start) + patched + result.slice(section.end));
+		const patched = section.text.replace(enabledTruePattern, (_match, indent, comment) =>
+			comment ? `${indent}enabled = false ${comment}` : `${indent}enabled = false`,
+		);
+		return ensureManagedComment(config.slice(0, section.start) + patched + config.slice(section.end));
 	}
 
-	if (/^\s*enabled\s*=\s*false[ \t]*(?:#[^\n]*)?$/m.test(section.text)) return result;
+	if (/^\s*enabled\s*=\s*false[ \t]*(?:#[^\n]*)?$/m.test(section.text)) return config;
 
 	const headerEnd = section.text.indexOf("\n");
 	const insertAt = headerEnd === -1 ? section.text.length : headerEnd + 1;
 	const patched = `${section.text.slice(0, insertAt)}${headerEnd === -1 ? "\n" : ""}enabled = false\n${section.text.slice(insertAt)}`;
-	return ensureManagedComment(result.slice(0, section.start) + patched + result.slice(section.end));
+	return ensureManagedComment(config.slice(0, section.start) + patched + config.slice(section.end));
 }
 
 function ensureManagedComment(config) {
@@ -52,6 +194,30 @@ function ensureManagedComment(config) {
 	return config.slice(0, section.start) + MANAGED_DISABLE_COMMENT + config.slice(section.start);
 }
 
+function removeManagedDisableComments(config) {
+	if (!config.includes(MANAGED_COMMENT_MARKER) && !config.includes("Managed by LazyCodex: multi_agent_v2")) {
+		return config;
+	}
+
+	const lines = config.split("\n");
+	const kept = [];
+	for (const line of lines) {
+		const trimmed = line.trim();
+		if (
+			trimmed.startsWith("#") &&
+			(trimmed.includes(MANAGED_COMMENT_MARKER) ||
+				trimmed.includes("Managed by LazyCodex: multi_agent_v2") ||
+				trimmed.includes("because enabling it fails every turn with HTTP 400") ||
+				trimmed.includes("LAZYCODEX_CONFIG_MIGRATION_DISABLED=1") ||
+				trimmed.includes("OMO_CODEX_CONFIG_MIGRATION_DISABLED=1"))
+		) {
+			continue;
+		}
+		kept.push(line);
+	}
+	return kept.join("\n").replace(/\n{3,}/g, "\n\n");
+}
+
 function removeFeaturesShorthand(config) {
 	const section = findSection(config, "[features]");
 	if (!section) return config;

package/packages/omo-codex/plugin/scripts/migrate-codex-config/subagent-limit-guard.mjs

@@ -1,9 +1,39 @@
+import { prefersMultiAgentV2, resolveMultiAgentVersionFromConfig } from "./multi-agent-v2-guard.mjs";
+
 const CODEX_AGENTS_HEADER = "[agents]";
 const CODEX_MULTI_AGENT_V2_HEADER = "[features.multi_agent_v2]";
 const CODEX_SUBAGENT_THREAD_LIMIT = "1000";
 
-export function ensureSubagentConcurrencyLimit(config) {
-	return ensureMultiAgentV2ThreadLimit(ensureAgentsMaxThreads(config));
+/**
+ * Ensure subagent concurrency limits without writing settings that conflict
+ * with MultiAgentV2. When the selected model prefers V2 (catalog `v2`, or a
+ * GPT-5.6 family session model with the catalog unavailable) or V2 is already
+ * enabled in config, skip `agents.max_threads` because Codex rejects that key
+ * while features.multi_agent_v2 is enabled.
+ *
+ * @param {string} config
+ * @param {{ multiAgentVersion?: string | null, sessionModel?: string | null, env?: NodeJS.ProcessEnv, modelsCachePath?: string }} [options]
+ */
+export function ensureSubagentConcurrencyLimit(config, options = {}) {
+	const multiAgentVersion =
+		options.multiAgentVersion !== undefined
+			? options.multiAgentVersion
+			: resolveMultiAgentVersionFromConfig(config, options);
+	const v2Preferred = prefersMultiAgentV2(multiAgentVersion, options.sessionModel) || isMultiAgentV2Enabled(config);
+
+	let result = config;
+	if (!v2Preferred) {
+		result = ensureAgentsMaxThreads(result);
+	} else {
+		result = removeAgentsMaxThreads(result);
+	}
+	return ensureMultiAgentV2ThreadLimit(result);
+}
+
+function isMultiAgentV2Enabled(config) {
+	const section = findSection(config, CODEX_MULTI_AGENT_V2_HEADER);
+	if (!section) return false;
+	return /^\s*enabled\s*=\s*true[ \t]*(?:#[^\n]*)?$/m.test(section.text);
 }
 
 function ensureAgentsMaxThreads(config) {
@@ -12,6 +42,22 @@ function ensureAgentsMaxThreads(config) {
 	return replaceOrInsertSetting(config, section, "max_threads", CODEX_SUBAGENT_THREAD_LIMIT);
 }
 
+function removeAgentsMaxThreads(config) {
+	const section = findSection(config, CODEX_AGENTS_HEADER);
+	if (!section) return config;
+	if (!/^\s*max_threads\s*=/m.test(section.text)) return config;
+
+	const patched = section.text.replace(/^\s*max_threads\s*=\s*[^\n]*\n?/m, "");
+	const bodyLines = patched
+		.split("\n")
+		.slice(1)
+		.filter((line) => line.trim() !== "");
+	if (bodyLines.length === 0) {
+		return config.slice(0, section.start) + config.slice(section.end).replace(/^\n+/, "");
+	}
+	return config.slice(0, section.start) + patched + config.slice(section.end);
+}
+
 function ensureMultiAgentV2ThreadLimit(config) {
 	const section = findSection(config, CODEX_MULTI_AGENT_V2_HEADER);
 	if (!section) {
@@ -26,7 +72,9 @@ function ensureMultiAgentV2ThreadLimit(config) {
 function replaceOrInsertSetting(config, section, key, value) {
 	const pattern = new RegExp(`^(\\s*)${escapeRegExp(key)}\\s*=\\s*[^\\n#]*(#[^\\n]*)?$`, "m");
 	if (pattern.test(section.text)) {
-		const patched = section.text.replace(pattern, (_match, indent, comment) => comment ? `${indent}${key} = ${value} ${comment}` : `${indent}${key} = ${value}`);
+		const patched = section.text.replace(pattern, (_match, indent, comment) =>
+			comment ? `${indent}${key} = ${value} ${comment}` : `${indent}${key} = ${value}`,
+		);
 		return config.slice(0, section.start) + patched + config.slice(section.end);
 	}
 

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

@@ -8,7 +8,10 @@ import { FALLBACK_CATALOG, readModelCatalog } from "./migrate-codex-config/catal
 import { configPaths } from "./migrate-codex-config/config-paths.mjs";
 import { removeStaleContext7PlaceholderMcpServer } from "./migrate-codex-config/context7-placeholder-guard.mjs";
 import { removeUnsupportedRootMultiAgentMode } from "./migrate-codex-config/multi-agent-mode-guard.mjs";
-import { forceDisableMultiAgentV2 } from "./migrate-codex-config/multi-agent-v2-guard.mjs";
+import {
+	forceDisableMultiAgentV2,
+	resolveMultiAgentVersionFromConfig,
+} from "./migrate-codex-config/multi-agent-v2-guard.mjs";
 import { ensureCodexReasoningConfig as applyReasoningProfile, readRootSettings } from "./migrate-codex-config/root-settings.mjs";
 import { readState, resolveStatePath, writeState } from "./migrate-codex-config/state.mjs";
 import { ensureSubagentConcurrencyLimit } from "./migrate-codex-config/subagent-limit-guard.mjs";
@@ -19,7 +22,12 @@ export function ensureCodexReasoningConfig(config, profile = FALLBACK_CATALOG.cu
 	return applyReasoningProfile(config, profile);
 }
 
-export async function migrateCodexConfig({ env = process.env, cwd = process.cwd() } = {}) {
+export async function migrateCodexConfig({
+	env = process.env,
+	cwd = process.cwd(),
+	sessionModel = null,
+	requireSessionModel = false,
+} = {}) {
 	const catalog = await readModelCatalog(env);
 	const statePath = resolveStatePath(env);
 	const state = await readState(statePath);
@@ -31,6 +39,9 @@ export async function migrateCodexConfig({ env = process.env, cwd = process.cwd(
 		const result = await migrateConfigFile(configPath, {
 			catalog,
 			previousState: state.files?.[configPath],
+			env,
+			sessionModel,
+			requireSessionModel,
 		});
 		if (result.changed) changed.push(configPath);
 		if (result.multiAgentModeChanged) modeChanged.push(configPath);
@@ -44,7 +55,16 @@ export async function migrateCodexConfig({ env = process.env, cwd = process.cwd(
 	return { changed, modeChanged };
 }
 
-export async function migrateConfigFile(configPath, { catalog = FALLBACK_CATALOG, previousState } = {}) {
+export async function migrateConfigFile(
+	configPath,
+	{
+		catalog = FALLBACK_CATALOG,
+		previousState,
+		env = process.env,
+		sessionModel = null,
+		requireSessionModel = false,
+	} = {},
+) {
 	const before = await readConfig(configPath);
 	const decision = shouldApplyCatalog(before, catalog, previousState);
 
@@ -56,7 +76,12 @@ export async function migrateConfigFile(configPath, { catalog = FALLBACK_CATALOG
 		reasoningApplied = config !== before;
 	}
 
-	const afterMultiAgentGuard = forceDisableMultiAgentV2(config);
+	const multiAgentOptions = { env, sessionModel, requireSessionModel };
+	const multiAgentVersion = resolveMultiAgentVersionFromConfig(config, multiAgentOptions);
+	const afterMultiAgentGuard = forceDisableMultiAgentV2(config, {
+		...multiAgentOptions,
+		multiAgentVersion,
+	});
 	const multiAgentChanged = afterMultiAgentGuard !== config;
 	if (multiAgentChanged) config = afterMultiAgentGuard;
 
@@ -68,7 +93,10 @@ export async function migrateConfigFile(configPath, { catalog = FALLBACK_CATALOG
 	const context7PlaceholderChanged = afterContext7PlaceholderGuard !== config;
 	if (context7PlaceholderChanged) config = afterContext7PlaceholderGuard;
 
-	const afterSubagentLimit = ensureSubagentConcurrencyLimit(config);
+	const afterSubagentLimit = ensureSubagentConcurrencyLimit(config, {
+		...multiAgentOptions,
+		multiAgentVersion,
+	});
 	const subagentLimitChanged = afterSubagentLimit !== config;
 	if (subagentLimitChanged) config = afterSubagentLimit;
 

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

@@ -52,7 +52,7 @@ This skill may include examples copied from the OpenCode harness. In Codex, do 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\`. OMO installs these selectable agent roles into \`~/.codex/agents/\`: \`explorer\`, \`librarian\`, \`plan\`, \`momus\`, \`metis\`, \`lazycodex-code-reviewer\`, \`lazycodex-qa-executor\`, and \`lazycodex-gate-reviewer\` - pass the matching name as \`agent_type\` so the child gets that role's model and instructions. If the spawn tool exposes no \`agent_type\` parameter, omit it and describe the role inside \`message\`. If a code block below conflicts with this section, this section wins.
 
-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.
+Codex exposes ONE of two subagent tool surfaces per session; check your own tool list and route accordingly. If \`multi_agent_v1.*\` tools exist, use the table above as written. If instead a flat \`spawn_agent\` with a required \`task_name\` exists (\`multi_agent_v2\`), rewrite every \`multi_agent_v1.*\` example: \`multi_agent_v1.spawn_agent({...,"fork_context":false})\` becomes \`spawn_agent({"task_name":"<lowercase_digits_underscores>","message":...,"agent_type":...,"fork_turns":"none"})\` (\`"all"\` only when full parent history is truly required); \`send_input\` becomes \`send_message\`; do not call \`close_agent\`/\`resume_agent\` (finished agents end on their own; \`followup_task\` re-tasks one, \`interrupt_agent\` stops one); \`wait_agent\` takes only \`timeout_ms\` and returns on any child mailbox activity. \`agent_type\` works the same on both surfaces. If a code block below conflicts with this section, this section wins.
 
 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.
 

package/packages/omo-codex/plugin/skills/frontend/SKILL.md

@@ -16,7 +16,7 @@ This file is a router, not a rulebook. The rules live in four rulesets under `re
 | ANY UI implementation, styling, redesign, mockup, or visual decision | `references/design/README.md` FIRST. It enforces two mandatory gates — the Design System Gate (a `DESIGN.md` must exist before any component is written) and the React Dev Tooling Gate (react-grab / react-scan / react-doctor installed by default) — then routes to the taste and brand references below. |
 | Writing or modifying frontend code, OR auditing performance / SEO / accessibility / quality | ALSO `references/perfection/README.md`. Lighthouse 100 in every category, measured on real Playwright Chromium (never the `lighthouse` CLI), achieved through architecture — never by dropping animations or hiding content. |
 | Looking up a concrete style, color palette, font pairing, chart type, landing-page structure, or UX guideline — or generating a project design system from keywords | `references/ui-ux-db/README.md`. A searchable CSV database with a CLI; a lookup tool, not a posture. Load on demand; `design` stays the source of truth for taste and the `DESIGN.md` contract. |
-| Design operating-layer work: personas, cognitive accessibility, design critique, design debt, handoff, synthetic user testing, or designpowers-style guidance | `references/designpowers/README.md`. This is an internal frontend ruleset, not a separate skill. It enriches `/frontend` routing with design brief, role-reference, accessibility, evidence, and debt language while preserving the `design` and `perfection` gates. |
+| ANY implementation or redesign that creates or updates `DESIGN.md` — plus explicit operating-layer asks (personas, critique, debt, handoff, synthetic user testing) | `references/designpowers/README.md` + `references/designpowers/lane-c-review.md`. An internal frontend ruleset, not a separate skill: lane-c is the Phase Final flatness/critique reviewer, and its accessibility-constraints and accepted-debt language fills the required `DESIGN.md` sections. Load other lanes only when their phase applies. |
 
 **For implementation work, design + perfection load together.** A page that hits Lighthouse 100 but looks like AI slop has failed; a page that looks beautiful but ships a 2 MB bundle has failed. Both win or neither does.
 
@@ -28,15 +28,15 @@ Every implementation must choose one of these branches before UI code changes:
    - **Static visual reference** (screenshot, generated mockup, Stitch/Imagen output, Figma export, overview, or annotated packet): load `references/design/image-to-code-skill.md` plus the relevant design/perfection files, extract the reference's exact tokens, layout geometry, copy, spacing, states, and responsive intent into `DESIGN.md`, then implement reusable primitives against that contract.
    - **Live site or URL reference** (the user names a site to clone or gives a URL): load `references/design/clone-from-url.md`. Drive a real browser and extract the runtime truth via `getComputedStyle` — tokens, layout geometry, default/hover/focus/active states, transitions and keyframes, and downloaded assets — into `DESIGN.md`, then clone-code reusable primitives against that contract.
    Final QA for both runs `/visual-qa` in reference-fidelity mode: compare the actual UI against the reference pixel-by-pixel and verify the code is an extensible design-system implementation, not a screenshot-matched one-off.
-2. **Greenfield or fresh setup:** if the user gave no concrete visual reference, design direction is a research deliverable, not a vibe. Fire every available research lane IN PARALLEL before `DESIGN.md` is written; skip a lane only when its tool or network is genuinely unavailable, and name the skip in `DESIGN.md`:
-   - **Embedded references:** use `references/design/_INDEX.md` to shortlist 2-3 plausible Layer B references, then deeply load exactly one Layer A style skill and one Layer B brand/design-system reference; use `open-design` only when the curated set has no fit; add `ui-ux-db` lookups for palette/type/domain questions.
-   - **Lazyweb real-product screens:** run the curl-only recipe in `references/design/lazyweb.md` to see how shipped products in the target domain actually look; harvest layout grammar and component patterns, never pixel copies.
-   - **Imagen concept drafts:** generate 2-3 imagen concept drafts, each seeded with the loaded Layer A + Layer B tokens (palette, type, material); pick the strongest and treat the chosen draft as the reference-fidelity contract.
-   Synthesize every lane into `DESIGN.md`. Treat sources as source material, not mood labels: extract tokens, layout grammar, component anatomy, interaction states, motion, and taste decisions, then recombine them into project-specific primitives. Never freestyle past the selected references, never copy logos or brand-specific copy. Define Section 5 primitives and their default/hover/active/focus/disabled/loading/empty/error states before code, and pass each through mobile/tablet/desktop visual QA before product screens.
+2. **Greenfield or fresh setup:** if the user gave no concrete visual reference, design research is a build step with named deliverables — not exploration to be budgeted. Exploration-stop instincts ("enough exploration", two-wave caps) do not apply here. Fire every research lane IN PARALLEL before `DESIGN.md` is written, and open `DESIGN.md` with a `## 0. Research Log` section recording each lane's deliverable — a lane with no Research Log line did not run. Skip a lane only when its tool or network is genuinely unavailable, and name the skip in `DESIGN.md`:
+   - **Embedded references:** use `references/design/_INDEX.md` to shortlist 2-3 plausible Layer B references, then read exactly one Layer A style skill and one Layer B reference in full — every line, no partial reads (they are 200-500 lines; a sliced read produces the flattened token set this gate exists to prevent). Log the shortlist, the pick, and why. Use `open-design` only when the curated set has no fit; add `ui-ux-db` lookups for palette/type/domain questions.
+   - **Lazyweb real-product screens:** READ `references/design/lazyweb.md` FIRST and run its recipe verbatim — do not improvise curl calls against lazyweb.com; the recipe mints its own anonymous token. Log the queries run, how many screens you actually VIEWED, and the layout grammar harvested — never pixel copies.
+   - **Imagen concept drafts:** generate 2-3 imagen concept drafts, each seeded with the loaded Layer A + Layer B tokens (palette, type, material); pick the strongest and treat the chosen draft as the reference-fidelity contract. Log the draft paths and the pick.
+   Synthesize every lane into `DESIGN.md`. Treat sources as source material, not mood labels: extract tokens, layout grammar, component anatomy, interaction states, motion, and taste decisions, then recombine them into project-specific primitives. Never freestyle past the selected references, never copy logos or brand-specific copy. Then run the Primitive Showcase Gate (`references/design/README.md` Phase 0) before any product screen.
 3. **Existing project with `DESIGN.md` or a component system:** read it, follow it, and update it before implementation only when the requested work needs a new token, primitive, state, motion rule, accessibility constraint, accepted debt, or reference-fidelity requirement.
 4. **Existing project with UI but no `DESIGN.md` and no reusable component layer:** STOP and ask the user one focused question: should you preserve the current look with copy-nearby styling, or extract a real `DESIGN.md` plus reusable components before continuing? Do not silently choose.
 
-When `references/designpowers/README.md` is loaded for implementation, redesign, or design-system work, feed its personas, accessibility, critique, debt, handoff, and role-reference guidance into the branch above. The resulting `DESIGN.md` is the implementation contract: tokens, typography, spacing, primitives, motion, responsive behavior, accessibility constraints, and accepted debt must be named there before code uses them. Verify component primitives, states, and final screens with real visual QA evidence; pass design-system decisions, implementation evidence, and unresolved debt into `/review-work` for significant implementation work.
+For implementation, redesign, or design-system work that creates or updates `DESIGN.md`, `references/designpowers/README.md` + `lane-c-review.md` are part of the default load — feed their personas, accessibility, critique, debt, handoff, and role-reference guidance into the branch above. The resulting `DESIGN.md` is the implementation contract: tokens, typography, spacing, primitives, motion, responsive behavior, accessibility constraints, and accepted debt must be named there before code uses them. Verify component primitives, states, and final screens with real visual QA evidence; pass design-system decisions, implementation evidence, and unresolved debt into `/review-work` for significant implementation work.
 
 ## Ruleset 1 — design (`references/design/`)
 
@@ -46,7 +46,7 @@ The reference library has one architecture file, 12 taste skills (Layer A — *h
 
 | File | Read when |
 |---|---|
-| `design-system-architecture.md` | The project has no `DESIGN.md` (defines the 7-section structure you must create first), or you are extracting a design system from existing UI code. |
+| `design-system-architecture.md` | The project has no `DESIGN.md` (defines the structure you must create first — 8 sections plus a greenfield-only `## 0. Research Log`), or you are extracting a design system from existing UI code. |
 
 ### Layer A — taste skills (pick AT MOST ONE style skill; they encode opposing philosophies)
 
@@ -102,7 +102,7 @@ Domains: `product` `style` `typography` `color` `landing` `chart` `ux` `react` `
 
 ## Ruleset 4 — designpowers (`references/designpowers/`)
 
-`README.md` routes design operating-layer guidance from the pinned `Owl-Listener/designpowers` reference corpus into the existing frontend workflow. Load it when a frontend task needs explicit personas, accessibility and cognitive constraints, design critique, design debt, handoff, synthetic user testing, motion guidance, or role-reference prompts. It does not replace this frontend skill, `/visual-qa`, `/ulw-plan`, `/start-work`, or `/review-work`; it supplies richer design context that must first be distilled into the project `DESIGN.md`, then used as the design-system contract for implementation and verification.
+`README.md` routes design operating-layer guidance from the pinned `Owl-Listener/designpowers` reference corpus into the existing frontend workflow. Load it — together with `lane-c-review.md` — for every implementation or redesign that creates or updates `DESIGN.md`, and additionally when a task needs explicit personas, accessibility and cognitive constraints, design critique, design debt, handoff, synthetic user testing, motion guidance, or role-reference prompts. It does not replace this frontend skill, `/visual-qa`, `/ulw-plan`, `/start-work`, or `/review-work`; it supplies richer design context that must first be distilled into the project `DESIGN.md`, then used as the design-system contract for implementation and verification.
 
 ## Quick routes — most common requests
 

package/packages/omo-codex/plugin/skills/frontend/references/design/README.md

@@ -38,12 +38,12 @@ Before touching any UI code, before routing to any reference, before even thinki
 
 1. Read `design-system-architecture.md` — it defines the exact structure.
 2. Identify the branch: greenfield setup, existing UI with implicit patterns/components, or existing UI with no reusable component layer.
-3. **Greenfield setup:** if the user gave no concrete visual reference, use `_INDEX.md` to shortlist 2-3 plausible Layer B references, then deeply load exactly one Layer A style skill and one Layer B brand/design-system reference; use `open-design` only when the curated set has no fit. Treat those references as source material, not mood labels: extract tokens, layout grammar, component anatomy, interaction states, motion, and taste decisions into `DESIGN.md`, then recombine them into project-specific primitives. Customize for the user's product and content, but do not freestyle past the selected references; never copy logos, trademarked assets, or brand-specific copy.
+3. **Greenfield setup:** if the user gave no concrete visual reference, use `_INDEX.md` to shortlist 2-3 plausible Layer B references, then read exactly one Layer A style skill and one Layer B brand/design-system reference in full — every line, no partial reads; use `open-design` only when the curated set has no fit. Open `DESIGN.md` with a `## 0. Research Log` recording each research lane's deliverable (embedded-reference shortlist + pick, lazyweb screens viewed, imagen drafts — see the SKILL.md workflow); a lane with no line did not run. Treat those references as source material, not mood labels: extract tokens, layout grammar, component anatomy, interaction states, motion, and taste decisions into `DESIGN.md`, then recombine them into project-specific primitives. Customize for the user's product and content, but do not freestyle past the selected references; never copy logos, trademarked assets, or brand-specific copy.
    - **Commit a distinctive direction BEFORE extracting tokens.** In 1-2 sentences, name the atmosphere, the signature material, the color story, and the one moment a visitor will remember. For an expressive brief, sketch 2-3 genuinely different directions and pick the boldest one you can defend with the loaded reference; do not average them, because the average IS the generic default this skill exists to beat. A locked, never-revisited one-shot decision is how a page ends up flat.
    - **The reference's distinctive material MUST survive extraction (expressive briefs).** The common failure is loading a rich reference and then distilling it into a generic dark-SaaS token set. Your `DESIGN.md` must carry the *non-default* decisions forward and name which reference each came from: the actual elevation recipe (the specific layers that make a surface read as glass/glossy, not a single blur), a multi-stop perceptual color ramp (not one brand hex reused at varied opacity), the explicit display/body/mono type choices, and one signature interaction. Self-check before writing code: if your `DESIGN.md` could describe any generic dark SaaS, you flattened the reference — go back and put the specific material in.
 4. **Existing UI with implicit patterns/components:** extract the colors, typography, spacing, primitives, states, and motion already in use. Write `DESIGN.md` to codify what exists before changing UI code.
 5. **Existing UI with no reusable component layer:** STOP and ask whether to preserve the current style with copy-nearby edits or extract a `DESIGN.md` plus reusable components first. Do not silently choose the cheaper path or the larger refactor.
-6. **Do not proceed to product screens until `DESIGN.md` exists, Section 5 names the reusable primitives and their states, and each primitive plus required state passes mobile/tablet/desktop visual QA in a component showcase or equivalent state harness.**
+6. Finish the triage at the Primitive Showcase Gate below.
 
 #### If YES design system exists → READ IT, FOLLOW IT
 
@@ -52,7 +52,11 @@ Before touching any UI code, before routing to any reference, before even thinki
 3. If you need a token that doesn't exist, **add it to `DESIGN.md` first**, then use it.
 4. Never introduce raw hex codes, arbitrary px values, or ad-hoc component patterns that bypass the system.
 
-**This gate is non-negotiable. No design system = no UI work. Period.**
+**The Design System Gate is non-negotiable. No design system = no UI work. Period.**
+
+### Primitive Showcase Gate (MANDATORY)
+
+**Do not proceed to product screens until `DESIGN.md` exists, Section 5 names the reusable primitives and their states, and each primitive plus required state passes mobile/tablet/desktop visual QA in a component showcase or equivalent state harness.** Skipping this gate ships ad-hoc-styled product screens and re-enters the redesign loop.
 
 
 ## Phase 0.5 — React Dev Tooling Gate (MANDATORY for React projects)

package/packages/omo-codex/plugin/skills/frontend/references/design/_INDEX.md

@@ -13,7 +13,7 @@ All reference files live flat in this directory. Three layers:
 
 | File | Purpose | Load when |
 |---|---|---|
-| `design-system-architecture.md` | Defines the 7-section `DESIGN.md` structure (atmosphere, color tokens, typography scale, spacing system, components, motion, depth). Creation workflow for new and existing projects. Validation rules and memory management. | Phase 0 fires and no `DESIGN.md` exists in the project. Also load when extracting a design system from existing code. |
+| `design-system-architecture.md` | Defines the `DESIGN.md` structure — 8 sections plus a greenfield-only `## 0. Research Log` (atmosphere, color tokens, typography scale, spacing system, components, motion, depth, accessibility constraints & accepted debt). Creation workflow for new and existing projects. Validation rules and memory management. | Phase 0 fires and no `DESIGN.md` exists in the project. Also load when extracting a design system from existing code. |
 
 ---
 

package/packages/omo-codex/plugin/skills/frontend/references/design/design-system-architecture.md

@@ -16,11 +16,19 @@ Every frontend project MUST have a `DESIGN.md` at its root. This file is the sin
 
 ## DESIGN.md Structure
 
-The file has 7 sections. Every section is mandatory. Skip nothing.
+The file has 8 sections plus a greenfield-only `## 0. Research Log`. Every section is mandatory. Skip nothing.
 
 ```markdown
 # [Project Name] Design System
 
+## 0. Research Log (greenfield only)
+
+One line per research lane, written before the sections below — a lane with no line did not run:
+- Embedded refs: shortlisted [2-3 Layer B candidates] → picked [Layer A] + [Layer B] because [reason]
+- Lazyweb: [N] queries, [M] screens viewed → [layout grammar taken]
+- Imagen drafts: [paths] → picked [draft] as the reference-fidelity contract
+- Skipped lanes: [lane] — [tool/network reason]
+
 ## 1. Atmosphere & Identity
 
 One paragraph. What this product FEELS like. Not what it does — how it feels to use.
@@ -165,6 +173,19 @@ If borders:
 
 If tonal-shift:
 Surfaces use progressively lighter/darker shades. No borders, no shadows.
+
+## 8. Accessibility Constraints & Accepted Debt
+
+### Constraints
+- WCAG target: [e.g. 2.2 AA] — contrast floor [4.5:1 body / 3:1 large text], visible focus on every
+  interactive element, full keyboard reachability, `prefers-reduced-motion` respected (Section 6).
+
+### Accepted Debt
+| Item | Location | Why accepted | Owner / Exit |
+|------|----------|--------------|--------------|
+| [debt] | [file/screen] | [reason + user sign-off] | [when it gets fixed] |
+
+New debt is recorded here at the moment it is accepted — never silently.
 ```
 
 ## Creation Workflow
@@ -173,7 +194,7 @@ Surfaces use progressively lighter/darker shades. No borders, no shadows.
 
 1. **Select references before taste** — no visual reference means `_INDEX.md` shortlist of 2-3 Layer B candidates, then exactly one Layer A style skill and one Layer B brand/design-system reference. Use `open-design` only when the curated set has no fit.
 2. **Assemble from references** — extract tokens, layout grammar, component anatomy, states, motion, and taste decisions, then recombine them into project-specific primitives. Customize for the user's product; never copy logos, trademarked assets, or brand-specific copy.
-3. **Define the system** — atmosphere, palette, typography, spacing, and one depth strategy, grounded in the selected references and product semantics.
+3. **Define the system** — atmosphere, palette, typography, spacing, and one depth strategy, grounded in the selected references and product semantics. Sanity-check the palette and type pairing with one `ui-ux-db` domain search (CLI in `references/ui-ux-db/README.md`).
 4. **Document initial primitives** — only components you are about to build, including variants and states.
 5. **Write it to `DESIGN.md`** at project root.
 6. **Build a primitive showcase first** — exercise each primitive's default, hover, active, focus, disabled, loading, empty, and error states at mobile/tablet/desktop widths before composing product screens.
@@ -199,6 +220,7 @@ After every component implementation, check:
 - [ ] Component reused 2+ times? Documented in Section 5.
 - [ ] Motion follows the timing table. No arbitrary durations.
 - [ ] Component visual QA passed for each primitive and required state before product screens were composed.
+- [ ] Section 8 accessibility constraints hold for the new component; any new debt is recorded in Section 8, not silently accepted.
 
 ## Memory Management
 

package/packages/omo-codex/plugin/skills/frontend/references/designpowers/README.md

@@ -2,7 +2,7 @@
 
 This is an internal frontend ruleset, not a standalone skill. `/frontend` remains the only public activation point for web UI, UX, visual design, accessibility, design QA, and frontend implementation routing.
 
-Load this reference from the frontend router when a task needs design operating-layer guidance: personas, cognitive accessibility, critique, design debt, handoff, synthetic user testing, motion guidance, or designpowers-style role references.
+Load this reference from the frontend router for EVERY implementation or redesign that creates or updates `DESIGN.md`, and whenever a task needs design operating-layer guidance: personas, cognitive accessibility, critique, design debt, handoff, synthetic user testing, motion guidance, or designpowers-style role references.
 
 The purpose of this ruleset is to enrich the existing frontend workflow while preserving its gates:
 
@@ -18,7 +18,7 @@ Read these files before applying designpowers guidance:
 1. `README.md` - this frontend integration contract.
 2. `routing.md` - how designpowers context feeds existing frontend, planning, execution, visual QA, and review routes.
 3. `orchestration.md` - shared state, Direct/Auto prompt semantics, safeguards, and role-reference rules.
-4. Phase lane docs, loaded only when relevant:
+4. Phase lane docs — `lane-c-review.md` loads with this README for every implementation or redesign heading into Phase Final review (it is the flatness/critique reviewer); the other lanes load only when their phase applies:
    - `lane-a-direction.md` for planning, direction, discovery, personas, taste, and accessibility constraints.
    - `lane-b-execution.md` for execution, UI build prompts, frontend handoff, and implementation evidence.
    - `lane-c-review.md` for visual QA, design critique, review gates, and objective evidence before judgment.

package/packages/omo-codex/plugin/skills/frontend/references/designpowers/lane-b-execution.md

@@ -44,7 +44,7 @@ Lane B worker DoneClaims must include:
 
 - Exact changed files and the `frontend` references loaded.
 - The real-surface QA invocation required by `start-work` for the UI surface, with captured artifact path.
-- Screenshot, browser, HTTP, or tmux artifacts appropriate to the visible surface.
+- Screenshot, browser, HTTP, or xterm.js web-terminal artifacts appropriate to the visible surface.
 - Accessibility evidence from the existing OpenAgent frontend path, such as Lighthouse, react-doctor, keyboard checks, or other plan-required checks.
 - A short design trace: which persona, design principle, token, or state requirement each major UI decision satisfies.
 - Cleanup receipts for any browser session, server, tmux session, temporary artifact, or process used during QA.

package/packages/omo-codex/plugin/skills/init-deep/SKILL.md

@@ -18,7 +18,7 @@ This skill may include examples copied from the OpenCode harness. In Codex, do 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`. OMO installs these selectable agent roles into `~/.codex/agents/`: `explorer`, `librarian`, `plan`, `momus`, `metis`, `lazycodex-code-reviewer`, `lazycodex-qa-executor`, and `lazycodex-gate-reviewer` - pass the matching name as `agent_type` so the child gets that role's model and instructions. If the spawn tool exposes no `agent_type` parameter, omit it and describe the role inside `message`. If a code block below conflicts with this section, this section wins.
 
-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.
+Codex exposes ONE of two subagent tool surfaces per session; check your own tool list and route accordingly. If `multi_agent_v1.*` tools exist, use the table above as written. If instead a flat `spawn_agent` with a required `task_name` exists (`multi_agent_v2`), rewrite every `multi_agent_v1.*` example: `multi_agent_v1.spawn_agent({...,"fork_context":false})` becomes `spawn_agent({"task_name":"<lowercase_digits_underscores>","message":...,"agent_type":...,"fork_turns":"none"})` (`"all"` only when full parent history is truly required); `send_input` becomes `send_message`; do not call `close_agent`/`resume_agent` (finished agents end on their own; `followup_task` re-tasks one, `interrupt_agent` stops one); `wait_agent` takes only `timeout_ms` and returns on any child mailbox activity. `agent_type` works the same on both surfaces. If a code block below conflicts with this section, this section wins.
 
 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.
 

package/packages/omo-codex/plugin/skills/refactor/SKILL.md

@@ -19,7 +19,7 @@ This skill may include examples copied from the OpenCode harness. In Codex, do 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`. OMO installs these selectable agent roles into `~/.codex/agents/`: `explorer`, `librarian`, `plan`, `momus`, `metis`, `lazycodex-code-reviewer`, `lazycodex-qa-executor`, and `lazycodex-gate-reviewer` - pass the matching name as `agent_type` so the child gets that role's model and instructions. If the spawn tool exposes no `agent_type` parameter, omit it and describe the role inside `message`. If a code block below conflicts with this section, this section wins.
 
-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.
+Codex exposes ONE of two subagent tool surfaces per session; check your own tool list and route accordingly. If `multi_agent_v1.*` tools exist, use the table above as written. If instead a flat `spawn_agent` with a required `task_name` exists (`multi_agent_v2`), rewrite every `multi_agent_v1.*` example: `multi_agent_v1.spawn_agent({...,"fork_context":false})` becomes `spawn_agent({"task_name":"<lowercase_digits_underscores>","message":...,"agent_type":...,"fork_turns":"none"})` (`"all"` only when full parent history is truly required); `send_input` becomes `send_message`; do not call `close_agent`/`resume_agent` (finished agents end on their own; `followup_task` re-tasks one, `interrupt_agent` stops one); `wait_agent` takes only `timeout_ms` and returns on any child mailbox activity. `agent_type` works the same on both surfaces. If a code block below conflicts with this section, this section wins.
 
 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.