oh-my-opencode 4.14.0 → 4.14.1

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

@@ -68,7 +68,7 @@ node "<skill-root>/scripts/team.mjs" set-status   --team <session_id> --id A --s
 node "<skill-root>/scripts/team.mjs" worktree-add    --team <session_id> --id A [--base-branch <branch>]
 node "<skill-root>/scripts/team.mjs" worktree-remove --team <session_id> --id A [--force]
 node "<skill-root>/scripts/team.mjs" integrate       --team <session_id> [--id A]
-node "<skill-root>/scripts/team.mjs" archive      --team <session_id> [--id A]
+node "<skill-root>/scripts/team.mjs" archive      --team <session_id> [--id A] [--note "<...>"]
 node "<skill-root>/scripts/team.mjs" delete       --team <session_id> [--force]
 node "<skill-root>/scripts/team.mjs" status       --team <session_id>
 ```
@@ -80,6 +80,13 @@ space). `{session_id}` is the leader's Codex session id when you can pass it via
 otherwise the script generates a stable handle. Re-running `init` is a safe no-op. Every mutating
 subcommand rewrites `guide.md`, so the manual always matches the current team.
 
+Mutating subcommands take a per-team state lock before reading and rewriting `team.json`. It is
+safe to run independent `add-member`, `bind-thread`, `set-status`, `archive`, `delete`, `guide`,
+and worktree mutation commands concurrently against the same team: they serialize and each command
+reads the latest committed state before writing. If a command reports that team state is locked,
+do not treat the intended mutation as complete; retry after the named command finishes, or inspect
+`.omo/teams/{session_id}/.team.lock/owner.json` if the previous command crashed.
+
 ## Create the team and its threads
 
 1. `init` the team, then `add-member` once per member.
@@ -183,12 +190,17 @@ result against that todo's acceptance criteria before you integrate.
 
 DISBAND the team the moment it is no longer needed. A team exists only to do its work; once that
 work is done, or the user no longer wants it, do not leave it lying around - archive every member,
-then delete the team state. A finished team that is never disbanded is a leak.
+then delete the team state only after archival evidence is clean or preserved. A finished team that
+is never disbanded is a leak.
 
 - `archive` closes the team: notify each active member, copy anything useful into `artifacts/`,
-  archive each member thread with `codex_app.set_thread_archived`, then `archive` flips the team
-  and all members to archived. If a thread-archive tool is unavailable, record that in the team log
-  and tell the user - never pretend a member was archived.
+  then try to archive each member thread with `codex_app.set_thread_archived`. Treat Codex App
+  failures such as "Ambiguous Codex thread id" or a thread id that is ambiguous across hosts as an
+  app-thread archival blocker, not as a team-state blocker: record the failure in the team log,
+  tell the user which member thread was not proven archived, and continue the team-state archive
+  with `archive --note "<blocker>"`. Never pretend a member thread was archived. Do not delete the
+  team state after an app-thread archival blocker unless the evidence has been copied elsewhere or
+  the user explicitly accepts that evidence loss.
 - `delete` removes `.omo/teams/{session_id}` and refuses while the team is unarchived or any member
   is still active unless `--force`.
 - When the work wraps up, land it the way the user asked: `integrate --team <id>` for a direct merge

package/packages/omo-codex/plugin/skills/teammode/scripts/team-state.mjs

@@ -9,8 +9,9 @@
 // this file stays the state concern only.
 
 import { randomUUID } from "node:crypto";
-import { lstat, mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { lstat, mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
 import { dirname, isAbsolute, join, relative, resolve } from "node:path";
+import { setTimeout as delay } from "node:timers/promises";
 
 export const LENSES = ["area", "ownership", "perspective"];
 export const MEMBER_STATUSES = ["pending", "active", "reported", "blocked", "archived"];
@@ -24,6 +25,8 @@ export function isUnderstaffed(team) {
 // A team dir is a single child of .omo/teams. This pattern alone blocks "/", "\", and a
 // leading "." so ".." and "a/b" can never name a team dir (the escape guard).
 const SESSION_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+const LOCK_TIMEOUT_MS = Number.parseInt(process.env.OMO_TEAMMODE_LOCK_TIMEOUT_MS ?? "10000", 10);
+const LOCK_RETRY_MS = Number.parseInt(process.env.OMO_TEAMMODE_LOCK_RETRY_MS ?? "25", 10);
 
 function isoNow(now) {
 	return now ?? new Date().toISOString();
@@ -233,6 +236,65 @@ async function lstatOrNull(p) {
 	});
 }
 
+function positiveIntegerOrFallback(value, fallback) {
+	return Number.isInteger(value) && value > 0 ? value : fallback;
+}
+
+async function readLockOwner(lockDir) {
+	return readFile(join(lockDir, "owner.json"), "utf8")
+		.then((content) => JSON.parse(content))
+		.catch(() => null);
+}
+
+async function describeLockOwner(lockDir) {
+	const owner = await readLockOwner(lockDir);
+	if (!owner || typeof owner !== "object") return "another team.mjs command";
+	const parts = [];
+	if (owner.command) parts.push(String(owner.command));
+	if (owner.pid) parts.push(`pid ${owner.pid}`);
+	if (owner.createdAt) parts.push(`since ${owner.createdAt}`);
+	return parts.length > 0 ? parts.join(", ") : "another team.mjs command";
+}
+
+export async function withTeamLock(dir, command, fn, options = {}) {
+	const timeoutMs = positiveIntegerOrFallback(options.timeoutMs ?? LOCK_TIMEOUT_MS, 10000);
+	const retryMs = positiveIntegerOrFallback(options.retryMs ?? LOCK_RETRY_MS, 25);
+	const lockDir = join(dir, ".team.lock");
+	const deadline = Date.now() + timeoutMs;
+	let acquired = false;
+	for (;;) {
+		try {
+			await mkdir(lockDir, { mode: 0o700 });
+			acquired = true;
+			await writeFile(
+				join(lockDir, "owner.json"),
+				`${JSON.stringify({ pid: process.pid, command, createdAt: new Date().toISOString() }, null, 2)}\n`,
+				{ encoding: "utf8", flag: "wx" },
+			);
+			break;
+		} catch (error) {
+			if (acquired) {
+				await rm(lockDir, { recursive: true, force: true });
+				throw error;
+			}
+			if (!error || error.code !== "EEXIST") throw error;
+			const st = await lstatOrNull(lockDir);
+			if (st?.isSymbolicLink()) throw new Error(`refused: team lock path is a symlink: ${lockDir}`);
+			if (st && !st.isDirectory()) throw new Error(`refused: team lock path is not a directory: ${lockDir}`);
+			if (Date.now() >= deadline) {
+				const owner = await describeLockOwner(lockDir);
+				throw new Error(`team state is locked by ${owner}; retry after that command completes`);
+			}
+			await delay(Math.min(retryMs, Math.max(1, deadline - Date.now())));
+		}
+	}
+	try {
+		return await fn();
+	} finally {
+		await rm(lockDir, { recursive: true, force: true });
+	}
+}
+
 // Create a directory chain refusing any symlinked component, so team state can never be
 // written through a symlink that escapes the workspace.
 async function mkdirNoSymlink(dir, stopAt) {

package/packages/omo-codex/plugin/skills/teammode/scripts/team.mjs

@@ -35,6 +35,7 @@ import {
 	setMemberStatus,
 	setMemberWorktree,
 	teamExists,
+	withTeamLock,
 	writeGuideAtomic,
 	writeTeamAtomic,
 } from "./team-state.mjs";
@@ -82,57 +83,71 @@ async function persist(team, dir) {
 	await writeGuideAtomic(team, buildGuide(team), dir);
 }
 
+async function mutateTeam(cwd, sessionId, command, fn) {
+	const dir = await assertSafeTeamDir(cwd, sessionId);
+	return withTeamLock(dir, command, async () => {
+		const team = await readTeam(dir);
+		return fn(team, dir);
+	});
+}
+
 const handlers = {
 	async init(cwd, flags) {
 		const teamName = requireFlag(flags, "name");
 		const sessionName = requireFlag(flags, "session-name");
 		const sessionId = typeof flags.session === "string" ? flags.session : `team-${randomUUID().slice(0, 8)}`;
 		const dir = await ensureTeamDir(cwd, sessionId);
-		if (await teamExists(dir)) {
-			process.stdout.write(`exists: ${dir} (left untouched; re-init is a safe no-op)\n`);
-			return;
-		}
-		const team = buildTeam({
-			teamName,
-			sessionName,
-			sessionId,
-			dir,
-			worktreeEnabled: flags.worktree === true,
-			baseBranch: typeof flags["base-branch"] === "string" ? flags["base-branch"] : "dev",
+		await withTeamLock(dir, "init", async () => {
+			if (await teamExists(dir)) {
+				process.stdout.write(`exists: ${dir} (left untouched; re-init is a safe no-op)\n`);
+				return;
+			}
+			const team = buildTeam({
+				teamName,
+				sessionName,
+				sessionId,
+				dir,
+				worktreeEnabled: flags.worktree === true,
+				baseBranch: typeof flags["base-branch"] === "string" ? flags["base-branch"] : "dev",
+			});
+			await persist(team, dir);
+			process.stdout.write(`created: ${dir}\n`);
+			process.stdout.write(`team.json + guide.md written; artifacts/ ready. session id: ${sessionId}\n`);
+			process.stdout.write(`next: add-member --team ${sessionId} --id A --name "<short role>" --focus "<part/ownership/perspective>" --lens area|ownership|perspective --deliverable "<...>"\n`);
 		});
-		await persist(team, dir);
-		process.stdout.write(`created: ${dir}\n`);
-		process.stdout.write(`team.json + guide.md written; artifacts/ ready. session id: ${sessionId}\n`);
-		process.stdout.write(`next: add-member --team ${sessionId} --id A --name "<short role>" --focus "<part/ownership/perspective>" --lens area|ownership|perspective --deliverable "<...>"\n`);
 	},
 
 	async "add-member"(cwd, flags) {
 		const sessionId = requireFlag(flags, "team");
-		const { dir, team } = await loadTeam(cwd, sessionId);
 		const memberId = requireFlag(flags, "id").trim();
-		addMember(team, {
+		const memberInput = {
 			id: memberId,
 			name: typeof flags.name === "string" ? flags.name : null,
 			focus: requireFlag(flags, "focus"),
 			lens: requireFlag(flags, "lens"),
 			deliverable: typeof flags.deliverable === "string" ? flags.deliverable : "",
 			branch: typeof flags.branch === "string" ? flags.branch : null,
+		};
+		const { team, member } = await mutateTeam(cwd, sessionId, "add-member", async (team, dir) => {
+			addMember(team, memberInput);
+			await persist(team, dir);
+			return { team, member: team.members.find((m) => m.id === memberId) };
 		});
-		await persist(team, dir);
-		const member = team.members.find((m) => m.id === memberId);
 		process.stdout.write(`added member ${memberId} to team ${sessionId}.\n\nSend this as the new thread's first message (title the thread "${member.threadTitle}"):\n---\n${buildMemberPrompt(team, memberId)}\n---\n`);
 	},
 
 	async "bind-thread"(cwd, flags) {
 		const sessionId = requireFlag(flags, "team");
-		const { dir, team } = await loadTeam(cwd, sessionId);
-		bindThread(team, {
+		const input = {
 			id: requireFlag(flags, "id"),
 			threadId: requireFlag(flags, "thread"),
 			cwd: typeof flags.cwd === "string" ? flags.cwd : null,
 			worktreePath: typeof flags["worktree-path"] === "string" ? flags["worktree-path"] : null,
+		};
+		await mutateTeam(cwd, sessionId, "bind-thread", async (team, dir) => {
+			bindThread(team, input);
+			await persist(team, dir);
 		});
-		await persist(team, dir);
 		process.stdout.write(`bound member ${flags.id} to thread ${flags.thread}.\n`);
 	},
 
@@ -144,25 +159,29 @@ const handlers = {
 
 	async "set-status"(cwd, flags) {
 		const sessionId = requireFlag(flags, "team");
-		const { dir, team } = await loadTeam(cwd, sessionId);
-		setMemberStatus(team, {
+		const input = {
 			id: requireFlag(flags, "id"),
 			status: requireFlag(flags, "status"),
 			note: typeof flags.note === "string" ? flags.note : "",
+		};
+		await mutateTeam(cwd, sessionId, "set-status", async (team, dir) => {
+			setMemberStatus(team, input);
+			await persist(team, dir);
 		});
-		await persist(team, dir);
 		process.stdout.write(`member ${flags.id} -> ${flags.status}\n`);
 	},
 
 	async "worktree-add"(cwd, flags) {
 		const sessionId = requireFlag(flags, "team");
-		const { dir, team } = await loadTeam(cwd, sessionId);
-		const member = memberOrThrow(team, requireFlag(flags, "id"));
-		const result = addMemberWorktree(cwd, team, member, {
-			baseBranch: typeof flags["base-branch"] === "string" ? flags["base-branch"] : null,
+		const memberId = requireFlag(flags, "id");
+		const baseBranch = typeof flags["base-branch"] === "string" ? flags["base-branch"] : null;
+		const { member, result } = await mutateTeam(cwd, sessionId, "worktree-add", async (team, dir) => {
+			const member = memberOrThrow(team, memberId);
+			const result = addMemberWorktree(cwd, team, member, { baseBranch });
+			setMemberWorktree(team, { id: member.id, path: result.path, branch: result.branch });
+			await persist(team, dir);
+			return { member, result };
 		});
-		setMemberWorktree(team, { id: member.id, path: result.path, branch: result.branch });
-		await persist(team, dir);
 		const note = result.created ? "" : " (already exists)";
 		const thread = member.threadId
 			? `\nMember thread: ${codexThreadLink(member.threadId)}\nTell that member to: cd "${result.path}"`
@@ -174,11 +193,15 @@ const handlers = {
 
 	async "worktree-remove"(cwd, flags) {
 		const sessionId = requireFlag(flags, "team");
-		const { dir, team } = await loadTeam(cwd, sessionId);
-		const member = memberOrThrow(team, requireFlag(flags, "id"));
-		removeMemberWorktree(cwd, team, member, { force: flags.force === true });
-		clearMemberWorktree(team, { id: member.id });
-		await persist(team, dir);
+		const memberId = requireFlag(flags, "id");
+		const force = flags.force === true;
+		const member = await mutateTeam(cwd, sessionId, "worktree-remove", async (team, dir) => {
+			const member = memberOrThrow(team, memberId);
+			removeMemberWorktree(cwd, team, member, { force });
+			clearMemberWorktree(team, { id: member.id });
+			await persist(team, dir);
+			return member;
+		});
 		process.stdout.write(`removed worktree for member ${member.id}\n`);
 	},
 
@@ -208,25 +231,30 @@ const handlers = {
 
 	async archive(cwd, flags) {
 		const sessionId = requireFlag(flags, "team");
-		const { dir, team } = await loadTeam(cwd, sessionId);
-		archive(team, {
+		const input = {
 			id: typeof flags.id === "string" ? flags.id : null,
 			note: typeof flags.note === "string" ? flags.note : "",
+		};
+		await mutateTeam(cwd, sessionId, "archive", async (team, dir) => {
+			archive(team, input);
+			await persist(team, dir);
 		});
-		await persist(team, dir);
 		process.stdout.write(flags.id ? `archived member ${flags.id}\n` : `archived team ${sessionId} and closed all members\n`);
 	},
 
 	async delete(cwd, flags) {
 		const sessionId = requireFlag(flags, "team");
-		const { dir, team } = await loadTeam(cwd, sessionId);
-		const active = team.members.filter((m) => m.status !== "archived");
-		if (flags.force !== true && (team.status !== "archived" || active.length > 0)) {
-			throw new Error(
-				`refused: team "${sessionId}" is not archived or still has ${active.length} active member(s). Archive first, or pass --force to delete anyway.`,
-			);
-		}
-		await rm(dir, { recursive: true, force: true });
+		const dir = await assertSafeTeamDir(cwd, sessionId);
+		await withTeamLock(dir, "delete", async () => {
+			const team = await readTeam(dir);
+			const active = team.members.filter((m) => m.status !== "archived");
+			if (flags.force !== true && (team.status !== "archived" || active.length > 0)) {
+				throw new Error(
+					`refused: team "${sessionId}" is not archived or still has ${active.length} active member(s). Archive first, or pass --force to delete anyway.`,
+				);
+			}
+			await rm(dir, { recursive: true, force: true });
+		});
 		process.stdout.write(`deleted team state: ${dir}\n`);
 	},
 
@@ -247,9 +275,11 @@ const handlers = {
 
 	async guide(cwd, flags) {
 		const sessionId = requireFlag(flags, "team");
-		const { dir, team } = await loadTeam(cwd, sessionId);
-		await writeGuideAtomic(team, buildGuide(team), dir);
-		process.stdout.write(`${team.paths.guide}\n`);
+		const guidePath = await mutateTeam(cwd, sessionId, "guide", async (team, dir) => {
+			await writeGuideAtomic(team, buildGuide(team), dir);
+			return team.paths.guide;
+		});
+		process.stdout.write(`${guidePath}\n`);
 	},
 };
 

package/packages/omo-codex/plugin/skills/ulw-loop/SKILL.md

@@ -20,7 +20,7 @@ This skill is intentionally compact. The full workflow lives in `references/full
 ## Non-Negotiables
 
 - Use the ulw-loop CLI state under `.omo/ulw-loop`; do not hand-edit goal state.
-- After any compaction or context loss, re-read brief + goals + ledger FIRST (`omo sparkshell cat .omo/ulw-loop/ledger.jsonl` or read directly) plus `omo ulw-loop status --json`, then resume; never re-plan from scratch.
+- After any compaction or context loss, re-read brief + goals + ledger FIRST plus `omo ulw-loop status --json`, then resume; never re-plan from scratch.
 - If `omo ulw-loop create-goals` says the existing aggregate is already complete, start unrelated new work with a fresh `--session-id <new-id>` instead of steering or forcing the completed default state. Use `--force` only to intentionally overwrite completed evidence.
 - Every success criterion needs observable evidence from a real surface: a channel (tmux, HTTP, browser, computer-use) or, for CLI- or data-shaped criteria, an auxiliary surface (CLI stdout, DB diff, parsed config dump).
 - Record evidence through the CLI only after cleanup receipts are available.

package/packages/omo-codex/plugin/skills/ulw-loop/references/full-workflow.md

@@ -65,7 +65,7 @@ Codex subagent reliability:
 - `.omo/ulw-loop/goals.json`: goals with embedded `successCriteria` per goal.
 - `.omo/ulw-loop/ledger.jsonl`: append-only audit trail.
 - Read artifacts before resuming, steering, or checkpointing.
-- After compaction or context loss, re-read brief + goals + ledger FIRST via `omo sparkshell cat .omo/ulw-loop/ledger.jsonl` (or direct paths), then `omo ulw-loop status --json`. Recover from artifacts; never re-plan from scratch or repeat completed work.
+- After compaction or context loss, re-read brief + goals + ledger FIRST, then `omo ulw-loop status --json`. Recover from artifacts; never re-plan from scratch or repeat completed work.
 - Never invent state outside `.omo/ulw-loop` artifacts or `omo ulw-loop status --json`.
 
 ## Bootstrap
@@ -194,9 +194,9 @@ omo ulw-loop checkpoint --goal-id <id> --status complete --evidence "<e2e eviden
 `--quality-gate-json` shape:
 ```json
 {
-  "codeReview":{"by":"lazycodex-code-reviewer","recommendation":"APPROVE","codeQualityStatus":"CLEAR","reportPath":"packages/omo-codex/plugin/components/ulw-loop/test/fixtures/artifacts/code-review.md","evidence":"Diff review passed.","blockers":[]},
-  "manualQa":{"by":"lazycodex-qa-executor","status":"passed","evidence":"CLI and data surfaces passed.","surfaceEvidence":[{"id":"surface-cli-pass","criterionRef":"C1","surface":"cli","invocation":"omo ulw-loop checkpoint --quality-gate-json sample-quality-gate.json --json","verdict":"passed","artifactRefs":["artifact-cli-pass"]},{"id":"surface-data-pass","criterionRef":"C2","surface":"data","invocation":"diff -u before-ledger.json after-ledger.json","verdict":"passed","artifactRefs":["artifact-data-diff"]}],"adversarialCases":[{"id":"adv-malformed-input","criterionRef":"C3","scenario":"malformed gate input omits manual QA evidence","expectedBehavior":"validator rejects ULW_LOOP_QUALITY_GATE_INVALID","verdict":"passed","artifactRefs":["artifact-cli-reject"]}],"artifactRefs":[{"id":"artifact-cli-pass","kind":"cli-transcript","description":"CLI pass artifact.","path":"packages/omo-codex/plugin/components/ulw-loop/test/fixtures/artifacts/cli-pass.txt"},{"id":"artifact-cli-reject","kind":"log","description":"Reject log artifact.","path":"packages/omo-codex/plugin/components/ulw-loop/test/fixtures/artifacts/rejection.txt"},{"id":"artifact-data-diff","kind":"data-diff","description":"Data diff artifact.","path":"packages/omo-codex/plugin/components/ulw-loop/test/fixtures/artifacts/data-diff.txt"}]},
-  "gateReview":{"by":"lazycodex-gate-reviewer","recommendation":"APPROVE","reportPath":"packages/omo-codex/plugin/components/ulw-loop/test/fixtures/artifacts/gate-review.md","evidence":"Gate review passed.","blockers":[]},
+  "codeReview":{"by":"lazycodex-code-reviewer","recommendation":"APPROVE","codeQualityStatus":"CLEAR","reportPath":"test/fixtures/artifacts/code-review.md","evidence":"Diff review passed.","blockers":[]},
+  "manualQa":{"by":"lazycodex-qa-executor","status":"passed","evidence":"CLI and data surfaces passed.","surfaceEvidence":[{"id":"surface-cli-pass","criterionRef":"C1","surface":"cli","invocation":"omo ulw-loop checkpoint --quality-gate-json sample-quality-gate.json --json","verdict":"passed","artifactRefs":["artifact-cli-pass"]},{"id":"surface-data-pass","criterionRef":"C2","surface":"data","invocation":"diff -u before-ledger.json after-ledger.json","verdict":"passed","artifactRefs":["artifact-data-diff"]}],"adversarialCases":[{"id":"adv-malformed-input","criterionRef":"C3","scenario":"malformed gate input omits manual QA evidence","expectedBehavior":"validator rejects ULW_LOOP_QUALITY_GATE_INVALID","verdict":"passed","artifactRefs":["artifact-cli-reject"]}],"artifactRefs":[{"id":"artifact-cli-pass","kind":"cli-transcript","description":"CLI pass artifact.","path":"test/fixtures/artifacts/cli-pass.txt"},{"id":"artifact-cli-reject","kind":"log","description":"Reject log artifact.","path":"test/fixtures/artifacts/rejection.txt"},{"id":"artifact-data-diff","kind":"data-diff","description":"Data diff artifact.","path":"test/fixtures/artifacts/data-diff.txt"}]},
+  "gateReview":{"by":"lazycodex-gate-reviewer","recommendation":"APPROVE","reportPath":"test/fixtures/artifacts/gate-review.md","evidence":"Gate review passed.","blockers":[]},
   "iteration":{"fullRerun":true,"status":"passed","rerunCommands":["bunx vitest run packages/omo-codex/plugin/components/ulw-loop/test/quality-gate-doc.test.ts"],"evidence":"Focused rerun passed."},
   "criteriaCoverage":{"totalCriteria":3,"passCount":3,"originalIntent":"User wanted artifact-backed completion.","desiredOutcome":"Behavior ships with review and QA evidence.","userOutcomeReview":"Result matches brief and goals.","adversarialClassesCovered":["malformed_input","stale_state"]}
 }

package/packages/omo-codex/plugin/skills/visual-qa/SKILL.md

@@ -35,7 +35,7 @@ Verify a rendered UI against intent using objective script evidence plus two par
 - Use when output must match a mock, a baseline, or a stated design intent; when you suspect a regression; when CJK (Korean/Japanese/Chinese) text may clip, misalign, or wrap awkwardly; when a claimed design system might actually be a flat image; when a terminal layout may overflow or its borders may break.
 - Skip when there is no rendered surface (pure backend or library logic with no visual or terminal output). For broad post-implementation review use review-work; this skill is the visual specialist.
 
-In the commands below, `$SKILL_DIR` is this skill's own directory (the folder containing this SKILL.md). The bundled script lives at `scripts/cli.ts` inside it.
+In the commands below, `$SKILL_DIR` is this skill's own directory (the folder containing this SKILL.md). The bundled Node evidence CLI lives at `scripts/visual-qa.mjs` inside it; the TypeScript source in `scripts/cli.ts` is for development.
 
 ## Step 1 - Detect the surface
 
@@ -66,11 +66,11 @@ Every gate runs on captures produced AFTER the last edit to the rendered source.
 ### Web
 
 1. Capture a REFERENCE image: the user's mock/target, generated page snapshot, Figma export, source-site capture, or known-good baseline. Save as PNG. If the user provided overview text or annotations, save them next to the image and treat them as part of the reference packet.
-2. Capture the ACTUAL rendered screenshot at the same viewport size. In Codex, when `browser:control-in-app-browser` is available and the page does not need an authenticated user browser session, use that Browser plugin first for navigation, page state inspection, and screenshots. If it is unavailable or lacks the needed capture action, use the project's configured browser tooling (the playwright, agent-browser, or dev-browser skill). Save as PNG. If none is configured or available, install [agent-browser](https://github.com/vercel-labs/agent-browser) (`bun add -g agent-browser && agent-browser install`) and capture with it — see `$SKILL_DIR/references/agent-browser-setup.md` for the full setup, including how to shoot a fixed-viewport screenshot.
+2. Capture the ACTUAL rendered screenshot at the same viewport size. In Codex, when `browser:control-in-app-browser` is available and the page does not need an authenticated user browser session, use that Browser plugin first for navigation, page state inspection, and screenshots. If it is unavailable or lacks the needed capture action, use the project's configured browser tooling (the playwright, agent-browser, or dev-browser skill). Save as PNG. If none is configured or available, install [agent-browser](https://github.com/vercel-labs/agent-browser) (`npm install -g agent-browser && agent-browser install`) and capture with it — see `$SKILL_DIR/references/agent-browser-setup.md` for the full setup, including how to shoot a fixed-viewport screenshot.
 3. Run the diff and keep the JSON:
 
 ```
-bun "$SKILL_DIR/scripts/cli.ts" image-diff <reference.png> <actual.png>
+node "$SKILL_DIR/scripts/visual-qa.mjs" image-diff <reference.png> <actual.png>
 ```
 
 Key fields: `dimensionsMatch`, `diffRatio` (0..1), `similarityScore` (0..100), `alphaChannelIntact`, `hotspots[]` (grid regions ranked by `diffRatio`).
@@ -104,7 +104,7 @@ metadata with cleanup receipt.
 3. Run the check with the REAL terminal width and keep the JSON:
 
 ```
-bun "$SKILL_DIR/scripts/cli.ts" tui-check capture.txt --cols <N>
+node "$SKILL_DIR/scripts/visual-qa.mjs" tui-check capture.txt --cols <N>
 ```
 
 Key fields: `maxWidth`, `overflowLines[]`, `borderMisaligned`, `wideCharColumns[]`, `hasAnsi`.
@@ -267,7 +267,7 @@ Run this step IN ADDITION to Steps 1-4 when the original user task has a concret
 1. Pixel-perfect design-compare subagent (visual oracle). Dispatch a focused, read-only design-compare reviewer (recommend `gpt-5.5` with medium reasoning). It must crop/zoom BOTH the reference (target / Figma export / source-site screenshot / generated page snapshot) and the ACTUAL screenshot into matching regions and read them **pixel-by-pixel** - header, nav, each card, spacing, type ramp, color tokens - not at a glance. It must also compare the overview text or annotations against the rendered content and DOM text. Anchor every claim with the bundled tool:
 
 ```
-bun "$SKILL_DIR/scripts/cli.ts" image-diff <reference.png> <actual.png>
+node "$SKILL_DIR/scripts/visual-qa.mjs" image-diff <reference.png> <actual.png>
 ```
 
    It judges whether layout geometry, spacing, design tokens (color, type, radius, shadow), and the design itself are identical to the target, region by region. Anything off by more than rounding is a finding.

package/packages/omo-codex/plugin/skills/visual-qa/references/agent-browser-setup.md

@@ -11,11 +11,12 @@ Repo: https://github.com/vercel-labs/agent-browser
 ## Install
 
 ```
-bun add -g agent-browser && agent-browser install
+npm install -g agent-browser && agent-browser install
 ```
 
-`bun add -g agent-browser` installs the CLI globally; `agent-browser install` downloads the
-managed browser it drives. (Equivalent with npm: `npm install -g agent-browser && agent-browser install`.)
+`npm install -g agent-browser` installs the CLI globally; `agent-browser install` downloads the
+managed browser it drives. If Bun is already available, `bun add -g agent-browser && agent-browser install`
+is equivalent, but npm is the default because LazyCodex/Codex installations do not require Bun.
 
 Confirm it is ready and discover the current flags:
 
@@ -36,7 +37,7 @@ agent-browser screenshot actual.png      # add --full for full-page, --screensho
 Then feed the PNG into the diff exactly as in Step 2:
 
 ```
-bun "$SKILL_DIR/scripts/cli.ts" image-diff <reference.png> actual.png
+node "$SKILL_DIR/scripts/visual-qa.mjs" image-diff <reference.png> actual.png
 ```
 
 Match the viewport numbers to whatever the reference/mock was captured at; mismatched