lazycodex-ai 5.0.0-beta.89 → 5.0.0-beta.90

package/packages/omo-codex/plugin/skills/ulw-research/scripts/repair-tracker.mjs

@@ -0,0 +1,171 @@
+// repair-tracker.mjs - the bounded repair loop as a pure state machine.
+//
+// Every decide() call is one check of the current artifact: the first call is attempt 0 (the
+// initial check), each later call follows one repair already taken. The loop stops on max
+// attempts, a measure plateau, a repeated defect signature (oscillation), or the wall clock.
+// On a stop the artifact is delivered with its residual defects unless a content-integrity
+// code remains, which blocks delivery. Time is always injected; this module never reads a
+// clock. Severities come from contracts.mjs only, so no caller can demote a defect.
+
+import { DEFECT_CODES, INTEGRITY_CODES, REPAIR_DEFAULTS, SCHEMA_VERSION, validateRepairState } from "./contracts.mjs"
+
+/**
+ * @typedef {{ code: string, message?: string }} Defect
+ * @typedef {{ at: string, measure: number[], signature: string, action: string }} Attempt
+ * @typedef {{ schemaVersion: number, startedAt: string, budget: { maxAttempts: number, plateauLimit: number, wallClockMs: number }, integrityCodes: string[], attempts: Attempt[], consecutiveNonProgress: number, seenSignatures: string[] }} RepairState
+ * @typedef {{ action: "repair"|"deliver"|"block", reason: string|null, residual: Defect[], blocking: Defect[] }} Decision
+ */
+
+const SEVERITY_INDEX = Object.freeze({ blocker: 0, major: 1, minor: 2 })
+const MIN_ARTIFACT_BYTES = 512
+const MIN_RENDERS = 1
+
+export class RepairTrackerError extends Error {
+	/** @param {string} code @param {string} message */
+	constructor(code, message) {
+		super(message)
+		this.name = "RepairTrackerError"
+		this.code = code
+	}
+}
+
+function toIso(value, label) {
+	const date = value instanceof Date ? value : typeof value === "string" || typeof value === "number" ? new Date(value) : null
+	if (date === null || !Number.isFinite(date.getTime())) {
+		throw new RepairTrackerError("invalid_time", `${label} must be a Date, an ISO timestamp, or epoch milliseconds`)
+	}
+	return date.toISOString()
+}
+
+function assertKnownCode(code, label) {
+	if (typeof code !== "string" || !Object.hasOwn(DEFECT_CODES, code)) {
+		throw new RepairTrackerError("unknown_defect_code", `${label} ${JSON.stringify(code)} is not a known defect code`)
+	}
+}
+
+/** Callers may add integrity codes; the contract set is always included, so none can be removed. */
+function integritySet(extra) {
+	return new Set([...INTEGRITY_CODES, ...(extra ?? [])])
+}
+
+/**
+ * @param {{ maxAttempts?: number, plateauLimit?: number, wallClockMs?: number, integrityCodes?: Iterable<string>, startedAt: Date|string|number }} options
+ * @returns {RepairState}
+ */
+export function createTracker({ maxAttempts, plateauLimit, wallClockMs, integrityCodes, startedAt }) {
+	if (startedAt === undefined) throw new RepairTrackerError("invalid_time", "startedAt is required (the tracker never reads the clock)")
+	const codes = [...integritySet(integrityCodes)].sort()
+	for (const code of codes) assertKnownCode(code, "integrity code")
+	const state = {
+		schemaVersion: SCHEMA_VERSION,
+		startedAt: toIso(startedAt, "startedAt"),
+		budget: {
+			maxAttempts: maxAttempts ?? REPAIR_DEFAULTS.maxAttempts,
+			plateauLimit: plateauLimit ?? REPAIR_DEFAULTS.plateauLimit,
+			wallClockMs: wallClockMs ?? REPAIR_DEFAULTS.wallClockMs,
+		},
+		integrityCodes: codes,
+		attempts: [],
+		consecutiveNonProgress: 0,
+		seenSignatures: [],
+	}
+	assertValid(state)
+	return state
+}
+
+/** The artifact is worth delivering with residual defects only when it exists and was rendered. */
+export function isArtifactOk({ bytes, renders }) {
+	return Number.isFinite(bytes) && bytes >= MIN_ARTIFACT_BYTES && Number.isFinite(renders) && renders >= MIN_RENDERS
+}
+
+export function measureOf(defects) {
+	const measure = [0, 0, 0]
+	for (const defect of defects) measure[SEVERITY_INDEX[DEFECT_CODES[defect.code].severity]] += 1
+	return measure
+}
+
+export function signatureOf(defects) {
+	return [...new Set(defects.map((defect) => defect.code))].sort().join("|")
+}
+
+function lessThan(a, b) {
+	for (let i = 0; i < a.length; i += 1) {
+		if (a[i] !== b[i]) return a[i] < b[i]
+	}
+	return false
+}
+
+function stopReason(state, { signature, consecutiveNonProgress, repairsTaken, elapsedMs }) {
+	const { maxAttempts, plateauLimit, wallClockMs } = state.budget
+	if (state.seenSignatures.includes(signature)) return "oscillation"
+	if (consecutiveNonProgress >= plateauLimit) return "plateau"
+	if (repairsTaken >= maxAttempts) return "max_attempts"
+	if (elapsedMs >= wallClockMs) return "wall_clock"
+	return null
+}
+
+/**
+ * @param {RepairState} state a tracker state (createTracker or deserializeState)
+ * @param {Defect[]} defects the current check's defects
+ * @param {Date|string|number} now injected time of this check
+ * @param {{ artifactOk?: boolean }} [artifact] caller-supplied; see isArtifactOk
+ * @returns {{ state: RepairState, decision: Decision }}
+ */
+export function decide(state, defects, now, { artifactOk = false } = {}) {
+	if (!Array.isArray(defects)) throw new RepairTrackerError("invalid_defects", "defects must be an array")
+	defects.forEach((defect, index) => assertKnownCode(defect?.code, `defects[${index}].code`))
+	const at = toIso(now, "now")
+	const measure = measureOf(defects)
+	const signature = signatureOf(defects)
+	const previous = state.attempts.at(-1)
+	const consecutiveNonProgress = previous && !lessThan(measure, previous.measure) ? state.consecutiveNonProgress + 1 : 0
+	const repairsTaken = state.attempts.filter((attempt) => attempt.action === "repair").length
+	const integrity = integritySet(state.integrityCodes)
+	const blocking = defects.filter((defect) => integrity.has(defect.code))
+
+	/** @type {Decision} */
+	let decision
+	if (defects.length === 0) decision = { action: "deliver", reason: "clean", residual: [], blocking: [] }
+	else {
+		const elapsedMs = Date.parse(at) - Date.parse(state.startedAt)
+		const reason = stopReason(state, { signature, consecutiveNonProgress, repairsTaken, elapsedMs })
+		if (reason === null) decision = { action: "repair", reason: null, residual: [...defects], blocking }
+		else if (blocking.length > 0) decision = { action: "block", reason: "blocking", residual: [...defects], blocking }
+		else decision = { action: artifactOk ? "deliver" : "block", reason, residual: [...defects], blocking }
+	}
+
+	const next = {
+		...state,
+		budget: { ...state.budget },
+		integrityCodes: [...state.integrityCodes],
+		attempts: [...state.attempts, { at, measure, signature, action: decision.action }],
+		consecutiveNonProgress,
+		seenSignatures: state.seenSignatures.includes(signature) ? [...state.seenSignatures] : [...state.seenSignatures, signature],
+	}
+	return { state: next, decision }
+}
+
+function assertValid(state) {
+	const { ok, errors } = validateRepairState(state)
+	if (!ok) throw new RepairTrackerError("invalid_repair_state", `invalid repair state: ${errors.join("; ")}`)
+	if (!Array.isArray(state.integrityCodes)) throw new RepairTrackerError("invalid_repair_state", "integrityCodes must be an array")
+	for (const code of state.integrityCodes) assertKnownCode(code, "integrity code")
+}
+
+/** @returns {string} the repair-state.json text */
+export function serializeState(state) {
+	assertValid(state)
+	return `${JSON.stringify(state, null, 2)}\n`
+}
+
+/** @param {string} text repair-state.json contents @returns {RepairState} */
+export function deserializeState(text) {
+	let state
+	try {
+		state = JSON.parse(text)
+	} catch (error) {
+		throw new RepairTrackerError("invalid_repair_state", `repair state is not JSON: ${error.message}`)
+	}
+	assertValid(state)
+	return state
+}

package/packages/omo-codex/plugin/skills/ulw-research/scripts/report-tools-commands.mjs

@@ -0,0 +1,214 @@
+// report-tools-commands.mjs - one function per report-tools subcommand. Each returns
+// { json | text, summary?, exitCode } and never exits the process; report-tools.mjs dispatches.
+
+import { existsSync, readFileSync, statSync, writeFileSync } from "node:fs"
+import { dirname, join, resolve } from "node:path"
+
+import { CliError, parseArgs, readJsonFile, writeJsonAtomic } from "./cli-support.mjs"
+import { REPAIR_DEFAULTS } from "./contracts.mjs"
+import { parseLineageMode, parsePalette, renderDesignSpec } from "./design-spec.mjs"
+import { extractFromHtml, extractFromPath, fetchHtml } from "./format-extract.mjs"
+import { checkLayout } from "./gates-layout.mjs"
+import { checkStatic } from "./gates-static.mjs"
+import { parseHtml } from "./html-lite.mjs"
+import { buildProbeSource } from "./layout-probe.mjs"
+import * as outcome from "./outcome.mjs"
+import { createTracker, decide, deserializeState, isArtifactOk, serializeState } from "./repair-tracker.mjs"
+
+const SEVERITY_ORDER = { blocker: 0, major: 1, minor: 2 }
+
+function readText(path) {
+	try {
+		return readFileSync(path, "utf8")
+	} catch (error) {
+		throw new CliError(`cannot read ${path}: ${error.code ?? error.message}`)
+	}
+}
+
+function nowFrom(flags) {
+	if (flags.now === undefined) return new Date()
+	const date = new Date(flags.now)
+	if (Number.isNaN(date.getTime())) throw new CliError("--now requires an ISO timestamp")
+	return date
+}
+
+function sessionDirFrom(flags) {
+	const dir = flags["session-dir"] ?? process.env.SESSION_DIR
+	if (!dir) throw new CliError("--session-dir is required (or set SESSION_DIR)")
+	return resolve(dir)
+}
+
+export function runCheck(argv) {
+	const args = parseArgs(argv, { repeatable: ["require-section"] })
+	const reportPath = args.positionals[0]
+	if (!reportPath) throw new CliError("usage: check <report.html> --design-spec <design-spec.md> [--layout <boxes.json>] [--require-section <regex>]... [--max-defects N]")
+	const specText = readText(args.required("design-spec"))
+	const doc = parseHtml(readText(reportPath))
+	const requireSections = (args.flags["require-section"] ?? []).map((source) => new RegExp(source, "i"))
+	const result = checkStatic(doc, {
+		palette: parsePalette(specText),
+		lineageMode: parseLineageMode(specText),
+		requireSections,
+		baseDir: dirname(resolve(reportPath)),
+	})
+	const defects = [...result.defects]
+	const gatesRun = [...result.gatesRun]
+	let layout = "not_run"
+	if (args.flags.layout !== undefined) {
+		const layoutResult = checkLayout(readJsonFile(args.flags.layout))
+		defects.push(...layoutResult.defects)
+		gatesRun.push("layout")
+		layout = layoutResult.defects.some((d) => d.severity === "blocker") ? "fail" : "pass"
+	}
+	defects.sort((a, b) => SEVERITY_ORDER[a.severity] - SEVERITY_ORDER[b.severity] || (a.line ?? 0) - (b.line ?? 0) || a.code.localeCompare(b.code))
+	const counts = { blocker: 0, major: 0, minor: 0, total: defects.length }
+	for (const defect of defects) counts[defect.severity] += 1
+	const max = args.int("max-defects", 200)
+	const status = counts.blocker > 0 ? "fail" : "pass"
+	const exitCode = status === "fail" ? 1 : 0
+	return {
+		json: { command: "check", status, exitCode, layout, defects: defects.slice(0, max), counts, gatesRun, gatesSkipped: result.gatesSkipped },
+		summary: `check: ${status.toUpperCase()} - ${counts.blocker} blocker, ${counts.major} major, ${counts.minor} minor; layout ${layout}`,
+		exitCode,
+	}
+}
+
+export function runLayoutProbe(argv) {
+	const args = parseArgs(argv, { booleans: ["json"] })
+	const source = buildProbeSource({ cap: args.int("cap", 400), root: args.flags.root ?? "main, article" })
+	return args.flags.json ? { json: { command: "layout-probe", source }, exitCode: 0 } : { text: source, exitCode: 0 }
+}
+
+export function runRepairDecide(argv) {
+	const args = parseArgs(argv)
+	const statePath = args.required("state")
+	const now = nowFrom(args.flags)
+	const defectsInput = readJsonFile(args.required("defects"))
+	const defects = Array.isArray(defectsInput) ? defectsInput : defectsInput.defects
+	if (!Array.isArray(defects)) throw new CliError("--defects must be a JSON array or a check result with a defects array")
+	const state = existsSync(statePath)
+		? deserializeState(readText(statePath))
+		: createTracker({
+				maxAttempts: args.int("max-attempts", REPAIR_DEFAULTS.maxAttempts),
+				plateauLimit: args.int("plateau-limit", REPAIR_DEFAULTS.plateauLimit),
+				wallClockMs: args.int("wall-clock-ms", REPAIR_DEFAULTS.wallClockMs),
+				startedAt: now,
+			})
+	// Fail closed: deliver-on-exhaustion needs proof of a usable artifact (bytes and renders).
+	const artifactOk =
+		args.flags["artifact-bytes"] !== undefined && args.flags.renders !== undefined
+			? isArtifactOk({ bytes: Number(args.flags["artifact-bytes"]), renders: Number(args.flags.renders) })
+			: false
+	const { state: next, decision } = decide(state, defects, now, { artifactOk })
+	writeFileSync(statePath, serializeState(next))
+	recordRepair(args.flags, next, decision)
+	const exitCode = decision.action === "block" ? 1 : 0
+	return { json: { command: "repair decide", decision }, summary: `repair: ${decision.action}${decision.reason ? ` (${decision.reason})` : ""}`, exitCode }
+}
+
+/** With a session dir that holds outcome.json, the repair summary and residual list land in the manifest. */
+function recordRepair(flags, state, decision) {
+	const dir = flags["session-dir"] ?? process.env.SESSION_DIR
+	if (!dir) return
+	const file = join(resolve(dir), outcome.MANIFEST_FILENAME)
+	if (!existsSync(file)) return
+	const manifest = outcome.readManifest(file)
+	manifest.repair = { attempts: state.attempts.length, action: decision.action, reason: decision.reason }
+	if (decision.action !== "repair") manifest.residualDefects = decision.residual.map((defect) => ({ ...defect, message: defect.message ?? defect.code }))
+	outcome.writeManifest(file, manifest)
+}
+
+function manifestPath(flags) {
+	return join(sessionDirFrom(flags), outcome.MANIFEST_FILENAME)
+}
+
+export function runOutcome(argv) {
+	const [sub, ...rest] = argv
+	const args = parseArgs(rest, { booleans: ["json"] })
+	const file = sub === "state" ? null : manifestPath(args.flags)
+	switch (sub) {
+		case "init": {
+			const promised = args.required("promised").split(",").map((s) => s.trim()).filter(Boolean)
+			const manifest = outcome.initManifest({ sessionDir: sessionDirFrom(args.flags), promised, lane: args.flags.lane ?? null, now: nowFrom(args.flags) })
+			outcome.writeManifest(file, manifest)
+			return { json: { command: "outcome init", path: file, deliverables: manifest.deliverables }, exitCode: 0 }
+		}
+		case "set": {
+			const [format, status] = args.positionals
+			if (!format || !status) throw new CliError("usage: outcome set <format> <status> [--path p] [--reason r] [--pages n]")
+			const manifest = outcome.readManifest(file)
+			const detail = {}
+			if (args.flags.path !== undefined) {
+				detail.path = resolve(args.flags.path)
+				if (existsSync(detail.path)) detail.bytes = statSync(detail.path).size
+			}
+			if (args.flags.reason !== undefined) detail.reason = args.flags.reason
+			if (args.flags.pages !== undefined) detail.pages = args.int("pages")
+			outcome.writeManifest(file, outcome.setDeliverable(manifest, format, status, { ...detail, now: nowFrom(args.flags) }))
+			return { json: { command: "outcome set", format, status }, exitCode: 0 }
+		}
+		case "gate": {
+			const [gate, status] = args.positionals
+			if (!gate || !status) throw new CliError("usage: outcome gate <static|layout|visual|proofread> <pass|fail|not_run>")
+			outcome.writeManifest(file, outcome.setGate(outcome.readManifest(file), gate, status))
+			return { json: { command: "outcome gate", gate, status }, exitCode: 0 }
+		}
+		case "render": {
+			const [path] = args.positionals
+			if (!path) throw new CliError("usage: outcome render <path> --page N")
+			outcome.writeManifest(file, outcome.addRender(outcome.readManifest(file), resolve(path), args.int("page")))
+			return { json: { command: "outcome render", path: resolve(path) }, exitCode: 0 }
+		}
+		case "state": {
+			const deliverable = args.required("deliverable")
+			const sibling = join(dirname(resolve(deliverable)), outcome.MANIFEST_FILENAME)
+			const dir = args.flags["session-dir"] ?? process.env.SESSION_DIR
+			const candidate = dir ? join(resolve(dir), outcome.MANIFEST_FILENAME) : sibling
+			const manifest = existsSync(candidate) ? outcome.readManifest(candidate) : null
+			const state = outcome.deliverableState(resolve(deliverable), manifest)
+			return { json: { command: "outcome state", state }, summary: `state: ${state}`, exitCode: 0 }
+		}
+		case "verify": {
+			const result = outcome.verifyManifest(outcome.readManifest(file))
+			return { json: { command: "outcome verify", ...result }, summary: `verify: ${result.ok ? "OK" : `${result.problems.length} problem(s)`}`, exitCode: result.ok ? 0 : 1 }
+		}
+		case "finish": {
+			const manifest = outcome.readManifest(file)
+			const ledgerPath = args.flags.ledger ?? join(sessionDirFrom(args.flags), "sources-ledger.md")
+			const now = nowFrom(args.flags)
+			const facts = outcome.briefingFacts(manifest, existsSync(ledgerPath) ? readText(ledgerPath) : "", now)
+			manifest.finishedAt = now.toISOString()
+			manifest.elapsedMinutes = facts.minutes
+			manifest.sources = { total: facts.sources, domains: facts.domains }
+			outcome.writeManifest(file, manifest)
+			return { json: { command: "outcome finish", finishedAt: manifest.finishedAt, elapsedMinutes: facts.minutes, sources: manifest.sources }, exitCode: 0 }
+		}
+		case "briefing": {
+			const manifest = outcome.readManifest(file)
+			const ledgerPath = args.flags.ledger ?? join(sessionDirFrom(args.flags), "sources-ledger.md")
+			const ledger = existsSync(ledgerPath) ? readText(ledgerPath) : ""
+			const now = nowFrom(args.flags)
+			if (args.flags.json) return { json: { command: "outcome briefing", ...outcome.briefingFacts(manifest, ledger, now) }, exitCode: 0 }
+			return { text: outcome.buildBriefing(manifest, ledger, now), exitCode: 0 }
+		}
+		default:
+			throw new CliError("usage: outcome <init|set|gate|render|state|verify|finish|briefing> ...")
+	}
+}
+
+export async function runFormatExtract(argv) {
+	const args = parseArgs(argv, { booleans: ["from-url"] })
+	const [reference] = args.positionals
+	if (!reference) throw new CliError("usage: format-extract <reference> --out <design-spec.md> [--from-url]")
+	const out = args.required("out")
+	let extract
+	try {
+		extract = args.flags["from-url"] ? extractFromHtml(await fetchHtml(reference), { origin: reference }) : extractFromPath(reference)
+	} catch (error) {
+		// An unsupported, unreadable, or unreachable reference is an input problem (exit 2), not a gate result.
+		throw new CliError(`format-extract ${reference}: ${error.message}`)
+	}
+	writeJsonAtomic(`${out}.extract.json`, { ...extract, tokens: { light: Object.fromEntries(extract.tokens?.light ?? []), dark: Object.fromEntries(extract.tokens?.dark ?? []) } })
+	writeFileSync(out, renderDesignSpec(extract))
+	return { json: { command: "format-extract", out: resolve(out), origin: extract.origin, lineageMode: extract.lineageMode, notes: extract.notes ?? [] }, summary: `format-extract: wrote ${out}`, exitCode: 0 }
+}

package/packages/omo-codex/plugin/skills/ulw-research/scripts/report-tools.mjs

@@ -0,0 +1,61 @@
+#!/usr/bin/env node
+// report-tools.mjs - the ulw-research deliverable CLI. Invoked as
+//   node "$SKILL_DIR/scripts/report-tools.mjs" <command> ...
+// Exit codes: 0 pass, 1 semantic failure (blockers, a failed verify, a blocked repair), 2 usage or IO.
+
+import { CliError, emit, exitCodeFor } from "./cli-support.mjs"
+import { isCliEntry } from "./entry-guard.mjs"
+import { runCheck, runFormatExtract, runLayoutProbe, runOutcome, runRepairDecide } from "./report-tools-commands.mjs"
+
+export const COMMANDS = Object.freeze([
+	"check",
+	"layout-probe",
+	"repair decide",
+	"outcome init",
+	"outcome set",
+	"outcome gate",
+	"outcome render",
+	"outcome state",
+	"outcome verify",
+	"outcome finish",
+	"outcome briefing",
+	"format-extract",
+])
+
+export async function run(argv) {
+	const [command, ...rest] = argv
+	switch (command) {
+		case "check":
+			return runCheck(rest)
+		case "layout-probe":
+			return runLayoutProbe(rest)
+		case "repair":
+			if (rest[0] !== "decide") throw new CliError("usage: repair decide --state <file> --defects <json>")
+			return runRepairDecide(rest.slice(1))
+		case "outcome":
+			return runOutcome(rest)
+		case "format-extract":
+			return runFormatExtract(rest)
+		case "--help":
+		case "help":
+			if (rest.includes("--json")) return { json: { commands: COMMANDS }, exitCode: 0 }
+			return { text: `report-tools <command>\n${COMMANDS.map((name) => `  ${name}`).join("\n")}`, exitCode: 0 }
+		default:
+			throw new CliError(`usage: report-tools <${COMMANDS.join(" | ")}> (run --help)`)
+	}
+}
+
+export async function main(argv = process.argv.slice(2)) {
+	try {
+		const result = await run(argv)
+		emit(result)
+		return exitCodeFor(result)
+	} catch (error) {
+		process.stderr.write(`report-tools: ${error.message}\n`)
+		return exitCodeFor(error)
+	}
+}
+
+if (isCliEntry(import.meta.url)) {
+	process.exitCode = await main()
+}

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

@@ -58,7 +58,9 @@ try {
 
 NEVER launch anything against, or clear cookies/cache/site data from, the user's live profile;
 the attached engine is the only sanctioned way to a signed-in page. If no extension is connected,
-run the `browser` skill's `scripts/browser-install.mjs`, relay its one human step, and wait — do
+run the `browser` skill's `scripts/browser-install.mjs` for the browser the user actually uses
+(from memory, or its detection; on `needsChoice` ask them and pass `--browser=<id>`), relay its
+one human step, and wait — do
 not fall back to the owned engine for an authenticated criterion.
 
 ## Capture a screenshot at a fixed viewport

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

@@ -166,3 +166,14 @@ test("#given the flattened plugin cache the Codex installer produces #when sync-
 		await rm(codexHome, { recursive: true, force: true });
 	}
 });
+
+test("#given the shared ulw-research skill #when the Codex overlay runs #then the overlay applies", async () => {
+	// given
+	const shared = await readFile(join(sharedSkillsRoot, "ulw-research", "SKILL.md"), "utf8");
+
+	// when
+	const actual = applyCodexSkillOverlays("ulw-research", shared);
+
+	// then
+	assert.notEqual(actual, shared, "the ulw-research overlay anchor no longer matches the shared SKILL.md");
+});

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

@@ -158,8 +158,8 @@ prefixes when identity is needed.
 `;
 const reviewWorkCodexGatePattern = new RegExp(reviewWorkCodexGate.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"));
 
-const ulwResearchOriginalDeliveryGates = "### The delivery gates \u2014 every gate must PASS, in order\n\nNothing reaches the user until the gates pass:\n\n1. **Visual QA (always).** Render the produced artifact back to images \u2014 PDF pages to PNG, the HTML in a real browser \u2014 and look at them: missing or broken figures, images stretched or spilling their containers, diagram or chart text rendered off the spec's font or palette, clipped tables, overflowing CJK text, blank pages, unlabeled chart values, wrong page breaks. Fix and re-render until the pages are clean. Reading the source markup is not visual QA; inspect the pixels.\n2. **Proofread gate \u2014 `task(category=\"writing\", ...)`.** Hand the final text to a dedicated `writing` worker whose only job is language: grammar, spelling, punctuation, terminology consistency, and whether the prose reads NATIVELY in the report's own language. It returns a defect list; fix every item and re-run the gate on the delta. Deliver only on a clean pass \u2014 this gate runs BEFORE the first delivery, not after the user finds the typo.";
-const ulwResearchCodexDeliveryGate = "### The delivery gate \u2014 visual QA must PASS\n\nNothing reaches the user until the gate passes:\n\n**Visual QA (always).** Render the produced artifact back to images \u2014 PDF pages to PNG, the HTML in a real browser \u2014 and look at them: missing or broken figures, images stretched or spilling their containers, diagram or chart text rendered off the spec's font or palette, clipped tables, overflowing CJK text, blank pages, unlabeled chart values, wrong page breaks. Fix and re-render until the pages are clean. Reading the source markup is not visual QA; inspect the pixels.";
+const ulwResearchOriginalDeliveryGates = "Reading the source markup is not visual QA; inspect the pixels.\n4. **Proofread gate \u2014 `task(category=\"writing\", ...)`.** Hand the final text to a dedicated `writing` worker whose only job is language: grammar, spelling, punctuation, terminology consistency, and whether the prose reads NATIVELY in the report's own language. It proofreads only and never composes. It returns a defect list; fix every item and re-run the gate on the delta. Deliver only on a clean pass \u2014 this gate runs BEFORE the first delivery, not after the user finds the typo.";
+const ulwResearchCodexDeliveryGate = "Reading the source markup is not visual QA; inspect the pixels.";
 
 export function removeCodexSkillOverlays(skillName, content) {
 	if (skillName === "ulw-research") {

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

@@ -4,6 +4,7 @@ import { dirname, join } from "node:path";
 import test from "node:test";
 import { fileURLToPath } from "node:url";
 import { sharedSkillsRootPath } from "@oh-my-opencode/shared-skills";
+import { createSkillSourceCopyFilter } from "@oh-my-opencode/shared-skills/skill-source-filter";
 import {
 	canonicalUltraworkDirectiveRelativePath,
 	componentSkillSources,
@@ -260,3 +261,22 @@ test("#given packaged Codex ulw-plan surfaces #when inspected #then dangerous sa
 	assert.doesNotMatch(packagedWorkflow.content, dangerousBypassPattern, `${packagedWorkflow.path} ships unsafe Codex bypass guidance`);
 	assert.doesNotMatch(componentWorkflow.content, dangerousBypassPattern, `${componentWorkflow.path} ships unsafe Codex bypass guidance`);
 });
+
+test("#given the shared ulw-research runtime and references #when aggregate Codex skills are inspected #then every packaged file is byte-equal to its shared source", async () => {
+	// given
+	const sharedSkillRoot = join(sharedSkillsRootPath(), "ulw-research");
+	const packagedSkillRoot = join(root, "skills", "ulw-research");
+	const keep = createSkillSourceCopyFilter(sharedSkillRoot);
+	const inAssetDirs = (file) => /^(scripts|references)\//.test(file.replaceAll("\\", "/"));
+	const sharedFiles = (await listSkillFiles(sharedSkillRoot)).filter(inAssetDirs).filter((file) => keep(join(sharedSkillRoot, file))).sort();
+
+	// when
+	const packagedFiles = (await listSkillFiles(packagedSkillRoot)).filter(inAssetDirs).sort();
+
+	// then
+	assert.deepEqual(packagedFiles, sharedFiles);
+	for (const file of sharedFiles) {
+		const [packaged, shared] = await Promise.all([readFile(join(packagedSkillRoot, file)), readFile(join(sharedSkillRoot, file))]);
+		assert.ok(packaged.equals(shared), `ulw-research/${file} must ship the shared bytes`);
+	}
+});

package/packages/omo-codex/scripts/install-dist/install-local.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-// omo-codex-install:ed5913a0451b102580823bb453ab16a6b0fe5490e3c3cc96f21285ce1b271763:fef32404e9543827207e1db51df847e2c997e70ee31a7440d6a8cfb13c3450d0
+// omo-codex-install:cf5a89b3eed10326f90d8a72b6f8cbce5e75da7812a5d6483320ae4783e8b221:9ca19658ee60a48edee0d04d97631bfaacced4ecde342545a420a1f2639bc3de
 var __esm = (fn, res, err) => () => {
   if (fn)
     try {
@@ -9984,7 +9984,7 @@ var package_default;
 var init_package = __esm(() => {
   package_default = {
     name: "@oh-my-opencode/omo-codex",
-    version: "5.0.0-beta.89",
+    version: "5.0.0-beta.90",
     type: "module",
     private: true,
     description: "Codex harness adapter for oh-my-openagent. Vendored Codex plugin namespace (omo) + TypeScript installer + telemetry.",

package/packages/prompts-core/prompts/ultrawork/codex.md

@@ -6,7 +6,7 @@
 [CODE RED] Maximum precision. Outcome-first. Evidence-driven.
 
 # Role
-Expert coding agent. Ship verified work. No process narration.
+Expert coding agent. Ship verified work; report at handoffs, not between them.
 
 # Goal
 Deliver EXACTLY what the user asked, end-to-end working, proven by
@@ -438,8 +438,12 @@ commits this session — then stage + draft the message instead.
 # Output discipline
 - First line literally: `ULTRAWORK MODE ENABLED!`
 - After bootstrap: 1-2 paragraph plan summary + notepad path.
-- During execution: surface only state changes (existing tests read,
-  scenario PASS/FAIL with evidence paths, reviewer verdict).
+- During execution: at every handoff - todo phase change, blocker,
+  plan change, before a long pass - one handoff block composed after
+  weighing what the user asked and needs to know now:
+  `[Outcome so far] toward [ask + wanted]. You need: [ledger,
+  evidence paths, PASS/FAIL, reviewer verdict]. Now: [todo in
+  progress]. Next: [next open todo].`; nothing between handoffs.
 - Final message: outcome + success-criteria checklist with evidence
   refs + notepad path + reviewer approval (if gate triggered) + commit
   list (`<sha> <subject>`). No file-by-file changelog unless asked.

package/packages/shared-skills/skills/browser/SKILL.md

@@ -32,9 +32,16 @@ node "<skill-root>/scripts/browser-doctor.mjs" --json
 | State | Meaning | Next |
 |---|---|---|
 | `ready` | CLI, daemon and a connected browser | start a session |
-| `no-cli` / `no-daemon` / `no-extension` | something is missing | `node "<skill-root>/scripts/browser-install.mjs"` prepares everything it can, then prints the **single** step only the user can do (relaunch the browser and click **Enable**); relay it verbatim, wait, re-run the doctor |
+| `no-cli` / `no-daemon` / `no-extension` | something is missing | `node "<skill-root>/scripts/browser-install.mjs" [--browser=<id>]` prepares everything it can for **the browser the user uses**, then prints the **single** step only the user can do (relaunch that browser and click **Enable**); relay it verbatim, wait, re-run the doctor |
+| `choose-browser` | the signals do not single out one browser (Safari/Firefox default, an idle default while another browser runs, several in use) | nothing was installed; take the browser from memory or ask the user, then `browser-install.mjs --browser=<id>` |
 | `no-browser-support` | no Chromium-family profile on this machine | say so and stop |
 
+**Install into the browser the user actually uses, never into whatever happens to be on disk.** Before
+installing, check your memory for the user's browser; otherwise read the doctor's `browser` (picked
+from the OS default browser, running apps and recent use — `candidates` shows the evidence). If memory
+and the doctor disagree, or the doctor says `choose-browser`, ask the user. Pass the answer as
+`--browser=<id>` and record it in memory. A Chrome that is merely installed is not their browser.
+
 **Never launch a headless browser because the attached one is missing.** It has none of the
 user's sessions, so every login turns into a ladder you should not be climbing. Say which state
 you hit and ask.

package/packages/shared-skills/skills/browser/references/install.md

@@ -13,18 +13,46 @@ Three pieces. The onboarding script prepares all three; a human finishes exactly
 | | |
 |---|---|
 | Operating systems | macOS (Apple Silicon and Intel), Linux (x64, ARM64), Windows x64 |
-| Browsers | Chrome, Microsoft Edge, Brave, Chromium — any profile the doctor lists under `browsersDetected` |
+| Browsers | Chrome, Microsoft Edge, Brave, Chromium, Arc, Dia, Vivaldi, Opera, Comet, Naver Whale — whichever the doctor lists under `candidates` |
+
+## Which browser
+
+The extension goes into exactly one browser: the one the user works in. Installed is not the same as
+used — a Chrome launched once keeps its profile directory forever — so the scripts rank candidates by:
+
+| Signal | Where it comes from |
+|---|---|
+| Default browser | macOS LaunchServices `https` handler, Linux `xdg-settings`, Windows `UserChoice` ProgId |
+| Running now | the app in `/Applications` (macOS), the process table elsewhere |
+| Used in the last 7 days | the profile's `Local State` / `History` modification time |
+
+Order of authority:
+
+1. **Your memory.** If you recorded the user's browser before, pass it: `--browser=<id>`.
+2. **`--browser=<id>` / `OMOWRIGHT_BROWSER`** set by the user.
+3. **The default browser, when it is also in use** (or nothing else is).
+4. **The only browser in use** when no default can be read.
+
+Anything else is `choose-browser` (doctor) / `needsChoice: true` (install): nothing is registered and
+`candidates` lists every browser with its signals. Ask the user which one they use, run the install
+with `--browser=<id>`, and save the answer to memory so the next session does not ask again. When
+the default browser is Safari or Firefox, BrowserSkill cannot drive it — say so and ask which
+Chromium-family browser to use.
+
+The doctor also lists `registeredElsewhere`: browsers that still carry an entry from an older
+onboarding. They are not removed automatically (removing the entry uninstalls an extension the user
+may have enabled); remove one only when the user asks, with omowright's `unregisterExternalExtension`.
 
 ## One command
 
 ```bash
-node "<skill-root>/scripts/browser-install.mjs" [--json] [--wait-ms=180000]
+node "<skill-root>/scripts/browser-install.mjs" [--browser=<id>] [--json] [--wait-ms=180000]
 ```
 
 In order it: runs upstream's official `install.sh` / `install.ps1` into `~/.local/bin` (any PATH
 line the installer appends to a shell rc file is reverted — the library calls the binary by
-absolute path); starts the daemon with `bsk status`; and, for every Chromium-family profile it
-finds, registers the Web Store listing as an external extension:
+absolute path); starts the daemon with `bsk status`; and, for **the one browser the user actually
+uses**, registers the Web Store listing as an external extension:
 
 | Platform | Where the entry goes | The user's one step |
 |---|---|---|
@@ -32,6 +60,7 @@ finds, registers the Web Store listing as an external extension:
 | Windows | `HKCU\Software\<vendor>\<browser>\Extensions\<id>` (`reg add`, no admin) | click **Enable** on the toolbar badge; no restart |
 | Linux (Chromium) | `<user data dir>/External Extensions/<id>.json` | relaunch; installs without a prompt |
 | Linux (Chrome / Edge / Brave) | `/opt/google/chrome/extensions/<id>.json` and siblings — root only | otherwise open the store link it prints and click **Add** |
+| Opera, and Vivaldi / Whale off macOS | no external-extension path | open the store link it prints in that browser and click **Add** |
 
 The script prints that step as `humanStep`. **Relay it verbatim and wait**; with `--wait-ms` it
 keeps polling the daemon until the extension connects. An empty `browsersConnected` afterwards is
@@ -57,7 +86,7 @@ engine, one of them shadowing the one that knows about omowright and this packag
 ## Diagnosing
 
 ```bash
-node "<skill-root>/scripts/browser-doctor.mjs" --json   # this package's view: cli, daemon, profiles, registrations, connections
+node "<skill-root>/scripts/browser-doctor.mjs" --json   # this package's view: cli, daemon, the user's browser + candidates, registrations, connections
 bsk doctor                                              # upstream's own checks
 bsk logs                                                # daemon log
 ```