oh-my-opencode 5.1.29 → 5.1.30

package/packages/omo-codex/plugin/test/materialize-shared-upstreams.test.mjs

@@ -0,0 +1,179 @@
+import assert from "node:assert/strict";
+import { spawnSync } from "node:child_process";
+import { copyFileSync, mkdirSync, mkdtempSync, readFileSync, realpathSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import test from "node:test";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+const scripts = join(dirname(fileURLToPath(import.meta.url)), "..", "scripts");
+
+// Drive the shipped CLI in a disposable layout. Only external Git results and
+// backoff time are controlled; no test-only export or option is added to it.
+function runCli(t, { failures = 0, strict = true, strictEnv = false, skip = false, pins = "valid" } = {}) {
+	const root = realpathSync(mkdtempSync(join(tmpdir(), "omo-materialize-retry-")));
+	t.after(() => rmSync(root, { recursive: true, force: true }));
+	const entry = join(root, "packages", "omo-codex", "plugin", "scripts");
+	const shared = join(root, "packages", "shared-skills");
+	mkdirSync(entry, { recursive: true });
+	mkdirSync(join(shared, "scripts"), { recursive: true });
+	for (const name of ["materialize-shared-upstreams.mjs", "entry-guard.mjs"]) {
+		copyFileSync(join(scripts, name), join(entry, name));
+	}
+	writeFileSync(join(shared, "scripts", "materialize-frontend-refs.mjs"),
+		'export async function materializeFrontendRefs({ strict }) { globalThis.record({ op: "materialize", strict }); return { skipped: false }; }\n');
+	writeFileSync(join(shared, "stage-omowright-runtime.mjs"),
+		'export async function stageOmowrightRuntime() { globalThis.record({ op: "stage" }); return { version: "fixture" }; }\n');
+	const trace = join(root, "trace.json");
+	writeFileSync(trace, "[]");
+	const preload = join(root, "git-fixture.mjs");
+	writeFileSync(preload, `
+import childProcess from "node:child_process";
+import timers from "node:timers/promises";
+import { syncBuiltinESMExports } from "node:module";
+import { writeFileSync } from "node:fs";
+const events = [];
+const realSleep = timers.setTimeout;
+let attempts = 0;
+let paths = [];
+globalThis.record = (event) => {
+  events.push(event);
+  writeFileSync(${JSON.stringify(trace)}, JSON.stringify(events));
+};
+childProcess.execFileSync = (command, args, options) => {
+  if (command !== "git") throw new Error("unexpected command: " + command);
+  record({ op: args[0], args, cwd: options.cwd, windowsHide: options.windowsHide });
+  if (args[0] === "submodule") {
+    paths = args.slice(4);
+    if (++attempts <= ${failures}) throw new Error("fixture fetch unavailable");
+    return Buffer.alloc(0);
+  }
+  if (args[0] !== "ls-files") throw new Error("unexpected Git operation");
+  if (${JSON.stringify(pins)} === "error") throw new Error("fixture index unavailable");
+  return paths.map((path, i) => {
+    const mode = ${JSON.stringify(pins)} === "invalid" ? "100644" : "160000";
+    const stage = ${JSON.stringify(pins)} === "unmerged" ? "2" : "0";
+    const sha = String(i + 1).repeat(${JSON.stringify(pins)} === "sha256" ? 64 : 40);
+    return mode + " " + sha + " " + stage + "\\t" + path + "\\0";
+  }).join("");
+};
+timers.setTimeout = async (ms) => {
+  record({ op: "sleep", ms });
+  await realSleep(15);
+  record({ op: "wake", ms });
+};
+syncBuiltinESMExports();
+`);
+	const env = { ...process.env };
+	delete env.NODE_OPTIONS;
+	delete env.OMO_SKIP_MATERIALIZE;
+	delete env.OMO_MATERIALIZE_STRICT;
+	if (strictEnv) env.OMO_MATERIALIZE_STRICT = "1";
+	if (skip) env.OMO_SKIP_MATERIALIZE = "1";
+	const result = spawnSync(process.execPath, ["--import", pathToFileURL(preload).href, join(entry, "materialize-shared-upstreams.mjs"), ...(strict ? ["--strict"] : [])], {
+		cwd: root, env, encoding: "utf8", windowsHide: true, timeout: 10000,
+	});
+	assert.ifError(result.error);
+	assert.equal(result.signal, null, result.stderr);
+	return { ...result, events: JSON.parse(readFileSync(trace, "utf8")), root };
+}
+
+const operations = (result) => result.events.map(({ op }) => op);
+const attempts = (result) => result.events.filter(({ op }) => op === "submodule");
+const delays = (result) => result.events.filter(({ op }) => op === "sleep").map(({ ms }) => ms);
+
+function assertFetchContract(result, count) {
+	assert.equal(attempts(result).length, count);
+	for (const call of attempts(result)) {
+		assert.deepEqual(call.args.slice(0, 4), ["submodule", "update", "--init", "--recursive"]);
+		assert.equal(call.args.includes("--remote"), false);
+		assert.equal(call.cwd, result.root);
+		assert.equal(call.windowsHide, true);
+	}
+}
+
+test("#given reachable pins #when strict materialization runs #then fetch once without backoff", (t) => {
+	const r = runCli(t);
+	assert.equal(r.status, 0, r.stderr);
+	assertFetchContract(r, 1);
+	assert.deepEqual(operations(r), ["submodule", "materialize", "stage"]);
+});
+
+test("#given one failed fetch #when strict materialization retries #then await recovery before staging", (t) => {
+	const r = runCli(t, { failures: 1 });
+	assert.equal(r.status, 0, r.stderr);
+	assertFetchContract(r, 2);
+	assert.deepEqual(delays(r), [1000]);
+	assert.deepEqual(operations(r), ["submodule", "sleep", "wake", "submodule", "materialize", "stage"]);
+});
+
+test("#given two failed fetches #when the final attempt recovers #then stop retrying with bounded backoff", (t) => {
+	const r = runCli(t, { failures: 2 });
+	assert.equal(r.status, 0, r.stderr);
+	assertFetchContract(r, 3);
+	assert.deepEqual(delays(r), [1000, 2000]);
+	assert.equal(r.events.filter(({ op }) => op === "materialize").length, 1);
+	assert.equal(r.events.some(({ op }) => op === "ls-files"), false);
+});
+
+test("#given persistent fetch failure #when strict attempts exhaust #then fail with every path and pinned SHA", (t) => {
+	const r = runCli(t, { failures: 9 });
+	assert.equal(r.status, 1, r.stderr);
+	assertFetchContract(r, 3);
+	assert.deepEqual(delays(r), [1000, 2000]);
+	assert.equal(r.events.some(({ op }) => op === "materialize" || op === "stage"), false);
+	assert.match(r.stderr, /failed after 3 attempts/);
+	assert.match(r.stderr, /fixture fetch unavailable/);
+	const paths = attempts(r)[0].args.slice(4);
+	paths.forEach((path, i) => assert.ok(r.stderr.includes(`${path}@${String(i + 1).repeat(40)}`), r.stderr));
+	const lookup = r.events.find(({ op }) => op === "ls-files");
+	assert.deepEqual(lookup.args, ["ls-files", "--stage", "-z", "--", ...paths]);
+	assert.equal(lookup.cwd, r.root);
+	assert.equal(lookup.windowsHide, true);
+});
+
+test("#given persistent fetch failure #when best-effort attempts exhaust #then warn and materialize once", (t) => {
+	const r = runCli(t, { failures: 9, strict: false });
+	assert.equal(r.status, 0, r.stderr);
+	assertFetchContract(r, 3);
+	assert.deepEqual(delays(r), [1000, 2000]);
+	assert.deepEqual(operations(r).slice(-3), ["ls-files", "materialize", "stage"]);
+	assert.match(r.stderr, /continuing without submodule refresh/);
+	assert.equal(r.events.find(({ op }) => op === "materialize").strict, false);
+});
+
+test("#given an unreadable index #when retries exhaust #then preserve the original fetch failure and name paths", (t) => {
+	const r = runCli(t, { failures: 9, pins: "error" });
+	assert.equal(r.status, 1, r.stderr);
+	assertFetchContract(r, 3);
+	assert.match(r.stderr, /fixture fetch unavailable/);
+	for (const path of attempts(r)[0].args.slice(4)) assert.ok(r.stderr.includes(`${path}@unknown`), r.stderr);
+	assert.match(r.stderr, /pinned SHA unavailable/);
+});
+
+for (const pins of ["invalid", "unmerged"]) {
+	test(`#given ${pins} index entries #when reporting failure #then do not invent resolved gitlink pins`, (t) => {
+		const r = runCli(t, { failures: 9, pins });
+		assert.equal(r.status, 1, r.stderr);
+		for (const path of attempts(r)[0].args.slice(4)) assert.ok(r.stderr.includes(`${path}@unknown`), r.stderr);
+	});
+}
+
+test("#given SHA-256 gitlinks #when retries exhaust #then retain complete pinned object IDs", (t) => {
+	const r = runCli(t, { failures: 9, pins: "sha256" });
+	assert.equal(r.status, 1, r.stderr);
+	attempts(r)[0].args.slice(4).forEach((path, i) => assert.ok(r.stderr.includes(`${path}@${String(i + 1).repeat(64)}`), r.stderr));
+});
+
+test("#given strict mode from the environment #when retries exhaust #then fail before downstream materialization", (t) => {
+	const r = runCli(t, { failures: 9, strict: false, strictEnv: true });
+	assert.equal(r.status, 1, r.stderr);
+	assertFetchContract(r, 3);
+	assert.equal(r.events.some(({ op }) => op === "materialize"), false);
+});
+
+test("#given materialization was already performed #when skip is set #then perform no Git or materializer calls", (t) => {
+	const r = runCli(t, { failures: 9, skip: true });
+	assert.equal(r.status, 0, r.stderr);
+	assert.deepEqual(r.events, []);
+});

package/packages/omo-codex/plugin/test/windows-console-hide.test.mjs

@@ -0,0 +1,150 @@
+import assert from "node:assert/strict";
+import { readdirSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import test from "node:test";
+import { fileURLToPath } from "node:url";
+
+// Platform contract (#9838, same class as #7144 and #8501): plugin scripts run from Codex hooks, which
+// have no console of their own. On Windows a console-subsystem child spawned there without windowsHide
+// gets a FRESH console window; the detached `cmd.exe /c npm.cmd` auto-update got one on every update.
+// This gate walks every plugin script and resolves the node:child_process entry points each file
+// imports, so a new call site, or an exec*/fork call a spawn-only regex would miss, cannot ship
+// unflagged. The flag is inert on posix, so the call text is the only place this is provable off Windows.
+const ENTRY_POINTS = ["spawnSync", "spawn", "execFileSync", "execFile", "execSync", "exec", "fork"];
+
+// Intentionally visible processes, or calls whose text cannot carry the literal flag, go here with a
+// reason. None today.
+const ALLOWLIST = [];
+
+const scriptsDir = join(dirname(fileURLToPath(import.meta.url)), "..", "scripts");
+
+// readdirSync returns backslash-separated entries on win32; matching on raw entries would silently
+// find nothing there while the gate still looked green.
+function toPosix(entry) {
+	return entry.replaceAll("\\", "/");
+}
+
+function scriptSources() {
+	return readdirSync(scriptsDir, { recursive: true, encoding: "utf8" })
+		.map(toPosix)
+		.filter((entry) => /\.(mjs|mts|js|cjs|ts)$/.test(entry))
+		.sort();
+}
+
+function importedEntryPoints(source) {
+	const locals = new Set();
+	for (const [, clause] of source.matchAll(/import\s*\{([^}]*)\}\s*from\s*["'](?:node:)?child_process["']/g)) {
+		for (const specifier of (clause ?? "").split(",")) {
+			const [importedPart, aliasPart] = specifier.split(/\s+as\s+/);
+			const imported = (importedPart ?? "").trim().replace(/^type\s+/, "");
+			if (!ENTRY_POINTS.includes(imported)) continue;
+			locals.add((aliasPart ?? imported).trim());
+		}
+	}
+	return [...locals];
+}
+
+// A namespace, default or require import would hide calls from the named-import resolution above, so
+// the gate refuses those forms instead of silently auditing nothing.
+function unsupportedImportForms(source) {
+	return [
+		/import\s+\*\s+as\s+\w+\s+from\s*["'](?:node:)?child_process["']/,
+		/import\s+\w+\s*(?:,\s*\{[^}]*\})?\s*from\s*["'](?:node:)?child_process["']/,
+		/require\(\s*["'](?:node:)?child_process["']\s*\)/,
+	].filter((pattern) => pattern.test(source)).length;
+}
+
+function callText(source, openingParen) {
+	let depth = 0;
+	for (let index = openingParen; index < source.length; index += 1) {
+		if (source[index] === "(") depth += 1;
+		else if (source[index] === ")") {
+			depth -= 1;
+			if (depth === 0) return source.slice(openingParen, index + 1);
+		}
+	}
+	return source.slice(openingParen);
+}
+
+// Comment prose names these functions too, so only the code spelling (identifier then `(`) on a
+// non-comment line counts as a call.
+function isCommentLine(source, offset) {
+	const lineStart = source.lastIndexOf("\n", offset - 1) + 1;
+	const lead = source.slice(lineStart, offset).trimStart();
+	return lead.startsWith("//") || lead.startsWith("*") || lead.startsWith("/*");
+}
+
+function collectCalls(file, source) {
+	const calls = [];
+	for (const local of importedEntryPoints(source)) {
+		for (const match of source.matchAll(new RegExp(String.raw`(?<![\w$.])${local}\(`, "g"))) {
+			if (isCommentLine(source, match.index)) continue;
+			calls.push({
+				file,
+				line: source.slice(0, match.index).split("\n").length,
+				callee: local,
+				text: `${local}${callText(source, match.index + match[0].length - 1)}`,
+			});
+		}
+	}
+	return calls;
+}
+
+function auditedCalls() {
+	return scriptSources().flatMap((file) => collectCalls(file, readFileSync(join(scriptsDir, file), "utf8")));
+}
+
+function isAllowlisted(call) {
+	return ALLOWLIST.some((entry) => entry.file === call.file && entry.callee === call.callee);
+}
+
+test("#given every plugin script child_process call #when inspected #then each passes windowsHide: true or is allowlisted with a reason", () => {
+	const offenders = auditedCalls()
+		.filter((call) => !/windowsHide:\s*true/.test(call.text) && !isAllowlisted(call))
+		.map((call) => `${call.file}:${call.line} ${call.callee}`);
+
+	assert.deepEqual(offenders, []);
+});
+
+test("#given every plugin script #when its child_process import is read #then it uses a form the gate can audit", () => {
+	const unauditable = scriptSources().filter((file) => unsupportedImportForms(readFileSync(join(scriptsDir, file), "utf8")) > 0);
+
+	assert.deepEqual(unauditable, []);
+});
+
+test("#given the audit #when it runs #then it still reaches the detached auto-update spawn it exists for", () => {
+	const autoUpdate = auditedCalls().filter((call) => call.file === "auto-update.mjs" && call.callee === "spawn");
+
+	assert.ok(autoUpdate.length > 0, "the gate no longer sees auto-update.mjs spawn calls");
+});
+
+test("#given the allowlist #when checked #then every entry has a reason and still matches a real call", () => {
+	const calls = auditedCalls();
+	const stale = ALLOWLIST.filter(
+		(entry) => !entry.reason || !calls.some((call) => call.file === entry.file && call.callee === entry.callee),
+	);
+
+	assert.deepEqual(stale, []);
+});
+
+test("#given an aliased execFile import without the flag #when audited #then the call is reported, not skipped", () => {
+	const source = ['import { execFile as run } from "node:child_process";', 'run("powershell.exe", args, { encoding: "utf8" }, callback);'].join("\n");
+
+	const calls = collectCalls("fixture.mjs", source);
+
+	assert.deepEqual(
+		calls.map((call) => call.callee),
+		["run"],
+	);
+	assert.equal(/windowsHide:\s*true/.test(calls[0].text), false);
+});
+
+test("#given a namespace child_process import #when checked #then it is refused as unauditable", () => {
+	assert.equal(unsupportedImportForms('import * as cp from "node:child_process";'), 1);
+	assert.equal(unsupportedImportForms('const cp = require("child_process");'), 1);
+	assert.equal(unsupportedImportForms('import { spawn } from "node:child_process";'), 0);
+});
+
+test("#given a win32 directory entry #when normalized #then it matches under POSIX separators", () => {
+	assert.equal(toPosix("lib\\auto-update.mjs"), "lib/auto-update.mjs");
+});

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

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-// omo-codex-install:83c45a1c78073f1bfdb31c0a25d9fea733aa0d90e789d9e378db864df0e4a431:fcd96f611f49548cfb4f350c4f2a6db29a6e296c08b6a888e8f835ae206e9833
+// omo-codex-install:c0434c323119abd4c8f9dbe2770f25c161f77afbc2510028fd56c1cf8686c9f0:e05728c791992ba8b6cd306a4648b585ac26e82c604e589ee39a47768c95fb09
 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.1.29",
+    version: "5.1.30",
     type: "module",
     private: true,
     description: "Codex harness adapter for oh-my-openagent. Vendored Codex plugin namespace (omo) + TypeScript installer + telemetry.",
@@ -10239,6 +10239,9 @@ function resolveStdio(options) {
   }
   return [options.stdin ?? "ignore", options.stdout ?? "pipe", options.stderr ?? "inherit"];
 }
+function createBunSpawnOptions(options) {
+  return { ...options, windowsHide: true };
+}
 function createNodeSpawnOptions(options, platform = process.platform) {
   const nodeOptions = {
     stdio: resolveStdio(options),
@@ -10327,7 +10330,7 @@ function spawn(cmdOrOpts, opts) {
   const { cmd, opts: options } = resolveCommand(cmdOrOpts, opts);
   const bun = getBunRuntime();
   if (bun)
-    return wrapBunProcess(bun.spawn(cmd, options));
+    return wrapBunProcess(bun.spawn(cmd, createBunSpawnOptions(options)));
   const [bin, ...args] = cmd;
   if (!bin)
     throw new Error("spawn requires a command");
@@ -10409,7 +10412,7 @@ function isKnownNonGitBashLauncher(path) {
 }
 function whereCommand(command) {
   try {
-    return execFileSync("where", [command], { encoding: "utf8" }).split(/\r?\n/).map((line) => line.trim()).filter((line) => line.length > 0);
+    return execFileSync("where", [command], { encoding: "utf8", windowsHide: true }).split(/\r?\n/).map((line) => line.trim()).filter((line) => line.length > 0);
   } catch (error) {
     if (error instanceof Error)
       return [];

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

@@ -11,7 +11,7 @@ One library, two engines. omowright ships inside this skill; choose the engine b
 |---|---|---|
 | A site the user is signed into, their open tabs, a form, a click-through, a screenshot, web QA, an extension popup | **attached** — the user's own browser through BrowserSkill | `connectBrowserSkill()` |
 | A throwaway profile, bot-scoring evasion, a CAPTCHA, network interception, a QA flight trace, coordinate control, headless runs | **owned** — a browser your code launches | `connectPipe()` / `connectCloakProfile()` — [references/owned-engine/README.md](references/owned-engine/README.md) |
-| Text out of a URL, a 403 bypass, a platform that blocks fetchers | neither | the `ultimate-browsing` skill |
+| A 403/WAF host the attached engine cannot open, a platform with a native reader, an archive snapshot | neither | the `ultimate-browsing` skill |
 
 **Attached is the default,** because it is the only engine carrying the user's logins and the only
 one where a human is a single call away. Never substitute one engine for the other silently: if

package/packages/shared-skills/skills/browser/runtime/omowright/manifest.json

@@ -5,5 +5,5 @@
     "index.js": "b6b064fab277031c6c51f5a58b84b31040f9960bf767bf646adc0540c1d25c1b",
     "page-bundle.js": "bfd51e8383cf47200d57387bbbed258bce5a3a3d00c38fc108034d2888e23f0c"
   },
-  "stagedAtUtc": "2026-10-09T17:46:21.855Z"
+  "stagedAtUtc": "2026-10-11T14:43:14.044Z"
 }

package/packages/shared-skills/skills/ultimate-browsing/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: ultimate-browsing
-description: "Renders, drives, and screenshots web pages: JS-rendered sources, clicks and forms, persistent logins, WAF-blocked hosts (platform-native readers, stealth Chrome), and the browsing lane of a research run, with screenshots as provenance. Not for plain search or unblocked static fetch."
+description: "Reaches web pages the user's browser cannot open: WAF-blocked and bot-scored hosts, platform-native readers (Chinese and social platforms), archive snapshots with provenance, and a browser you own for stealth or throwaway profiles. Not for plain search, an unblocked static fetch, or a page the user's browser can open."
 ---
 
 # Ultimate Browsing
 
-Web access for everything a plain fetch cannot finish: a page that renders in JS, a click or a form, a screenshot, a login that must persist across pages, or a host that blocks generic fetchers (WAF / 403 / Cloudflare). Start at the cheapest tier that can do the job and climb only when it cannot:
+Web access for the hosts the user's browser cannot open (WAF / 403 / Cloudflare / bot-scored pages) and for platforms with a native reader. Reading and interaction on a page the user's browser can open belong to the `browser` skill's attached engine, not here. Start at the cheapest tier that can reach the blocked host and climb only when it cannot:
 
 **Tier 1 — insane-search** (headless extraction + WAF bypass) -> **Tier 1.5 — agent-reach** (platform-native APIs, esp. Chinese platforms) -> **Tier 2 — a real browser** through omowright from js eval: 2a the owned engine (a browser your code launches, CloakBrowser for stealth), 2b the attached engine (the user's own signed-in browser).
 
@@ -14,29 +14,27 @@ Web access for everything a plain fetch cannot finish: a page that renders in JS
 ```
 User request
   |
-  +- extract text/data from a URL --------------------- TIER 1  insane-search
+  +- a page the user's browser can open (read, click, screenshot, QA, login)  NOT this skill (browser skill, attached engine)
+  +- simple search query ------------------------------ NOT this skill (use web-search)
+  |
   +- URL blocked / 403 / Cloudflare / WAF ------------- TIER 1  insane-search
   +- YouTube/Vimeo/TikTok subtitles or metadata ------- TIER 1  insane-search (yt-dlp)
-  +- read an article / blog / Reddit / HN / arXiv ----- TIER 1  insane-search
+  +- archive snapshot of a dead or changed page ------- TIER 1  insane-search (surrogates, provenance-tagged)
   |
   +- Chinese platform (xhs/douyin/weibo/bilibili/v2ex/wechat)  TIER 1.5 agent-reach
   +- podcast transcript / stock forum ----------------- TIER 1.5 agent-reach
   +- Twitter feed / LinkedIn profile / GitHub via CLI - TIER 1.5 agent-reach
   |
-  +- Tier 1/1.5 returned empty or partial ------------- TIER 2  2a owned engine -> 2b attached engine
-  +- click / fill form / scroll / interact ------------ TIER 2  2a owned engine -> 2b attached engine
-  +- screenshot / render / play video ----------------- TIER 2  2a owned engine -> 2b attached engine
-  +- login session across pages / the user's account --- TIER 2  2b attached engine (their browser)
-  +- test web app / QA / dogfood ---------------------- TIER 2  2a owned engine -> 2b attached engine
-  |
-  +- simple search query ------------------------------ NOT this skill (use web-search)
+  +- Tier 1/1.5 returned empty or partial ------------- TIER 2  2a owned engine (stealth)
+  +- a blocked host that also needs a click, a scroll or a screenshot  TIER 2  2a owned engine
+  +- the user's account on a host the owned engine cannot pass  TIER 2  2b attached engine (their browser)
 ```
 
 Read the matching reference before acting: [`references/insane-search/README.md`](references/insane-search/README.md), [`references/agent-reach/README.md`](references/agent-reach/README.md), or [`references/chrome-stealth.md`](references/chrome-stealth.md).
 
 ## Tier 1 — insane-search (headless extraction)
 
-**When**: content extraction, blocked-URL bypass, media metadata — no browser UI needed.
+**When**: blocked-URL bypass, media metadata, archive surrogates — no browser UI needed.
 **Why first**: ~10x faster than a browser, no process spin-up; handles most "fetch this blocked page" requests via curl_cffi TLS impersonation, yt-dlp (1858 sites), official public APIs, mobile URL transforms, **Phase-2.5 surrogate archives** (Wayback / archive.today snapshots, provenance-tagged — see [`references/insane-search/cache-archive.md`](references/insane-search/cache-archive.md)), a key-gated Jina Reader (`JINA_API_KEY`), and a Playwright real-Chrome fallback. The engine lives **inside this skill** at `engine/` and is invoked as a module. Surrogate results are dated COPIES: a result whose `provenance` is `snapshot` must be reported with its `snapshot_timestamp`, never presented as the live page.
 
 ```bash
@@ -56,7 +54,7 @@ The full engine harness (rules R1-R7, the Phase 0 official-API index, the no-sit
 
 ### Escalate to Tier 1.5 or Tier 2 when
 - The target is a Chinese / social platform with a native reader -> Tier 1.5.
-- insane-search returns empty/partial, or the page needs JS interaction, a screenshot, a persistent login, or media playback -> Tier 2.
+- insane-search returns empty/partial, or the blocked page needs JS interaction, a screenshot, or media playback -> Tier 2.
 
 ## Tier 1.5 — agent-reach (platform-native readers)
 
@@ -82,7 +80,7 @@ Routing table, per-platform auth (set `TWITTER_*` env vars, `gh auth login`, a t
 
 ## Tier 2 — a real browser (real interaction)
 
-**When**: real interaction is needed (clicks, forms, screenshots, video, persistent login), or Tier 1/1.5 failed.
+**When**: Tier 1/1.5 failed on a blocked host, or that host needs interaction (clicks, scroll, screenshots, video). A page the user's browser can open is the `browser` skill's job, attached engine first.
 
 Both tiers are omowright, staged inside the `browser` skill and loaded from js eval:
 
@@ -110,9 +108,9 @@ try {
 
 The rest of the surface (CUA coordinates, captcha solving, routes, traces, frames, human handoff) is in the `browser` skill's `references/owned-engine/`. A stealth binary is not proof of access: inspect the rendered result and report challenges that remain.
 
-### Tier 2b — attached engine (logged-in pages)
+### Tier 2b — attached engine (the user's account on a blocked host)
 
-When the page needs the user's account, drive the browser they are already signed into instead of cloning their profile: `connectBrowserSkill()` → `session.navigate` → `bskSnapshot(session)` / `session.observe()` → `session.click` → `session.stop()`. NEVER launch against or clear cookies/cache/site data from the user's live profile, and never fall back to the owned engine for an authenticated criterion: if no extension is connected, run the `browser` skill's onboarding script and relay its one human step. The full loop is the `browser` skill.
+When the blocked flow needs the user's account, drive the browser they are already signed into instead of cloning their profile: `connectBrowserSkill()` → `session.navigate` → `bskSnapshot(session)` / `session.observe()` → `session.click` → `session.stop()`. NEVER launch against or clear cookies/cache/site data from the user's live profile, and never fall back to the owned engine for an authenticated criterion: if no extension is connected, run the `browser` skill's onboarding script and relay its one human step. The full loop is the `browser` skill.
 
 ### Cookie login (cross-platform)
 

package/packages/shared-skills/skills/ulw-research/SKILL.md

@@ -86,7 +86,7 @@ Saturation research defaults to teammode, not isolated fire-and-forget workers:
 
 ## Worker ground rules
 
-Research workers (explore, librarian, browsing) differ by harness, but assume:
+Research workers (explore, web, repo-dive) differ by harness, but assume:
 
 - **Read-only.** Most research workers cannot write files. Never ask a worker to write the journal or any session file — every journal write is yours.
 - **No recursion — workers AND members.** Workers cannot spawn their own subagents, and team members must not re-orchestrate: a member researches its axis and reports; it never stands up its own team, loads this skill, or fans out a research swarm of its own. Depth comes from YOUR expansion waves. Say so in every spawn message — a member that starts its own research protocol burns the run's budget on duplicated orchestration and returns nothing you can cite.
@@ -119,11 +119,13 @@ Before spawning anything, decompose the query. Start from "what must be true if
 <analysis>
 Core question: <the actual information need>
 Axes (3+ orthogonal): <axis — what to search, where, why> ...
-Codebase relevant: <yes/no> · External: <yes/no> · Browsing: <yes/no> · Verification likely: <yes/no>
+Codebase relevant: <yes/no> · External: <yes/no> · Collection: <search-only | browser> · Verification likely: <yes/no>
 Scale: <axis count, source territories, target document length> · Precision demand: <what a wrong claim costs here> → lifecycle: <single team | research team then refinement team>
 </analysis>
 ```
 
+`Collection` is `search-only` only when a result snippet settles every axis (a date, a version, a spec value); anything that needs reading a source is `browser`.
+
 Then create the session directory:
 
 ```bash
@@ -169,26 +171,23 @@ Otherwise launch the entire first wave in one turn — every axis at once, as te
 
 Scaling floor — more angles always justify more workers:
 
-| Query scope | explore | librarian | browsing | repo-dive | floor |
-|---|---|---|---|---|---|
-| Single topic, codebase only | 3 | 0 | 0 | 0 | 3 |
-| Single topic, web only | 0 | 4 | 1 | 1 | 6 |
-| Single topic, both | 2 | 3 | 1 | 1 | 7 |
-| Multi-faceted | 4 | 6 | 2 | 2 | 14 |
-| Full due diligence | 4 | 6 | 3 | 2 | 15 |
-
-The browsing column is BINDING, not advisory: when the brief says `Browsing: yes`, the roster names a browsing-worker angle, armed with the `ultimate-browsing` skill, before the first wave launches, and that worker is spawned in the same turn as the rest of the wave. A run that reaches wave 2 with zero browsing workers on a `Browsing: yes` brief has silently downgraded every source to what plain fetch happened to return.
+| Query scope | explore | web | repo-dive | floor |
+|---|---|---|---|---|
+| Single topic, codebase only | 3 | 0 | 0 | 3 |
+| Single topic, web only | 0 | 5 | 1 | 6 |
+| Single topic, both | 2 | 4 | 1 | 7 |
+| Multi-faceted | 4 | 8 | 2 | 14 |
+| Full due diligence | 4 | 9 | 2 | 15 |
 
 **Disambiguate before you expand.** When the topic names something that could resolve several ways — a product, a person, a codename, a version — the first wave settles WHICH entity before any worker researches its history, benchmarks, or controversies: canonical name, first-party URL or account, whether it exists in the claimed category, and a confidence line. An unresolved entity never becomes a premise in a later wave's spawn message; that is exactly how a run starts inventing facts about something that does not exist.
 
 Role protocols — embed the relevant one in each spawn message; every worker gets a unique angle:
 
 - **Codebase (explore), 2-4 workers.** Grep with 3+ keyword variations; structural/AST search; LSP definitions and references; file-name globs; `git log --all -S '<keyword>'` and `--grep` for history including deleted code. Cross-validate hits across tools. Report absolute file paths, patterns with `file:line`, and how findings connect.
-- **Web (librarian), 3-6 workers.** At least 10 distinct websearch queries per worker, each with a different operator or angle (see Search craft); fetch the full page for every result that matters — snippets lie. Context7 with 3+ queries per known library. grep.app and `gh search code|repos|issues` for real-world usage. Official docs via sitemap discovery (`<base>/sitemap.xml`), then targeted pages.
-- **Browsing, 1-3 workers on a `Browsing: yes` brief (0 otherwise), every one loaded with the `ultimate-browsing` skill.** The skill owns the routing — the harness's own browser first, then its extraction engine with archive surrogates, platform-native readers, and Chrome stealth as each source demands; the worker owns the deliverable. This worker RENDERS pages, it does not re-fetch them: its standing deliverable is a full-page screenshot of every top source plus the rendered text plain fetch could not reach; a worker that returns only fetched text has not done its job. JS-rendered, login-gated, WAF-blocked, and screenshot-bearing sources all belong here rather than in the web lane. **Provenance is part of the claim**: when a source came back with `provenance` of `snapshot` (an archive copy), cite it with its `snapshot_timestamp` and never state it as the current live page; content from a `proxy` route is `untrusted` and needs a second independent route before any claim rests on it. When one blocked territory hides many leads, fan out more browsing subagents in parallel for breadth instead of serializing one worker through them.
+- **Web, 3-9 workers, every one loaded with the `browser` skill.** Search with 10+ websearch queries per worker, each with a different operator or angle (see Search craft); a result is a candidate, not a source. Read every candidate in the user's browser through the `browser` skill's attached engine: one named session per worker, one tab per source, several tabs open side by side while sources are compared — `session.tabCreate` / `tabSelect` / `tabClose` where the harness has a JS eval kernel, `bsk tab create --url <url>` / `tab select <id>` / `tab close <id>` / `tab list` on the CLI — the page scrolled to its end, a full-page screenshot of each top source saved as provenance, the tab closed once reported. A browser on another machine is reached through the `browser` skill's remote reference or a user-level skill that bridges to it, never replaced by a local headless one. `webfetch` is for raw files only: PDF, JSON, feeds, sitemaps. A host the browser cannot open (WAF, bot score, 403) goes to `ultimate-browsing`, whose provenance travels with the claim: a `snapshot` result cites its `snapshot_timestamp` and is never stated as the live page; a `proxy` result is `untrusted` until a second independent route agrees. Context7 with 3+ queries per known library; grep.app and `gh search code|repos|issues` for real-world usage; official docs via sitemap discovery (`<base>/sitemap.xml`), then targeted pages. A worker whose sources are all fetched text has searched, not read.
 - **Repo deep-dive (librarian), 0-2 workers.** Shallow-clone the most relevant repos to `${TMPDIR:-/tmp}`, pin the HEAD SHA, read core modules, follow call chains, return SHA-pinned permalinks.
 
-Example spawn (codebase axis; librarian, browsing, and repo-dive follow the same contract with their own protocol):
+Example spawn (codebase axis; web and repo-dive follow the same contract with their own protocol):
 
 ```
 task(subagent_type="explore", run_in_background=true, prompt="TASK: act as a codebase researcher. AXIS: <specific angle>.
@@ -207,9 +206,9 @@ This loop is what makes the mode research rather than search. Collect returns as
 3. Spawn an expansion worker immediately for each new unchecked lead:
 
 ```
-task(subagent_type="librarian", run_in_background=true, prompt="TASK: expansion wave <N> — investigate: <lead>.
+task(category="deep-low", load_skills=["browser"], run_in_background=true, prompt="TASK: expansion wave <N> — investigate: <lead>.
 PARENT: <which return surfaced it>. This is an explicit exhaustive-research assignment; budgets do not apply.
-<role protocol for the lead's territory — librarian protocol for external leads, explore protocol for codebase leads>
+<role protocol for the lead's territory — web protocol for external leads, explore protocol for codebase leads>
 End your reply with the ## EXPAND tail.")
 ```
 
@@ -331,7 +330,7 @@ Asset workers (background, parallel, each fed `design-spec.md`) — visuals are
 - **Charts for every quantitative finding, computed from real data.** Pull the numbers into an actual table first (CSV/JSON under `$SESSION_DIR`), then plot from that table, never from prose. Follow the data-scientist tool doctrine — numpy always, Polars for filtering/sorting/transforms, DuckDB for joins/aggregations/window functions, never pandas — and load the `data-scientist` skill when this session has it: `uv run --with numpy --with polars --with duckdb --with pyarrow --with matplotlib python`. Keep `pyarrow` in that set — the DuckDB-to-Polars handoff (`.pl()`) fails without it, and `.df()` fails without pandas, so hand data across through `.pl()`, never `.df()`. Save to `$SESSION_DIR/assets/`.
 - **Mermaid graphs** for process, architecture, argument, timeline, and evidence-flow structure, themed to the spec's fonts and palette. Render each to SVG and confirm the file exists before the document references it.
 - **Generated visuals through the imagegen skill whenever the session has it:** a cover plus a concept illustration per major theme, prompted from the spec's style, palette, and mood — document-styled illustration, never generic stock art dropped into a designed page.
-- **Full-page screenshots** of the top 5-10 sources (browsing worker) as provenance you can show.
+- **Full-page screenshots** of the top 5-10 sources, saved by the web workers while reading, as provenance you can show.
 
 **Verify the asset manifest before rendering.** List every asset the document references, assert each file exists and is non-empty on disk, and re-render whatever is missing. A document that renders with three broken diagrams is a document you will publish twice.
 
@@ -390,7 +389,7 @@ High-yield combinations: official docs (`site:<docs domain>`), GitHub implementa
 | Obeying a surrounding "stop exploring" rule mid-research | Authority section — those rules do not bind this mode |
 | Asking a worker to write journal or session files | Workers are read-only; you journal every return |
 | Two workers given the same angle | One unique angle per worker, always |
-| A `Browsing: yes` run whose roster carries no browsing worker, or a browsing worker spawned without `ultimate-browsing` | The browsing column is binding — name the angle in the brief and spawn it, armed with the skill, in the first wave before any lead is chased |
+| A web worker that returned only fetched text, or a `Collection: browser` run whose workers never opened a tab | Sources are read in the user's browser through the `browser` skill; `webfetch` is for raw files; every web worker carries the skill from the first wave |
 | Contested claim settled by judgment | Phase 3 — run code, capture output, verdict |
 | Deliverable claims without citations | Every claim cites a source or a verification artifact |
 | Guessing the deliverable format | Derive it from the request and destination; ask the empty-info interview only for what is still missing, and record `answered_by` for every field |

package/packages/shared-skills/skills/ulw-research/scripts/cli-support.test.ts

@@ -1,5 +1,5 @@
-import { describe, expect, test } from "bun:test"
-import { mkdtempSync, readdirSync, readFileSync, writeFileSync } from "node:fs"
+import { describe, expect, onTestFinished, test } from "bun:test"
+import { mkdtempSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs"
 import { tmpdir } from "node:os"
 import { join } from "node:path"
 import { pathToFileURL } from "node:url"
@@ -8,7 +8,9 @@ import { CliError, exitCodeFor, parseArgs, readJsonFile, writeJsonAtomic } from
 import { isCliEntry } from "./entry-guard.mjs"
 
 function tempDir() {
-	return mkdtempSync(join(tmpdir(), "report-tools-"))
+	const dir = mkdtempSync(join(tmpdir(), "report-tools-"))
+	onTestFinished(() => rmSync(dir, { recursive: true, force: true }))
+	return dir
 }
 
 describe("parseArgs", () => {

package/packages/shared-skills/skills/ulw-research/scripts/outcome.test.ts

@@ -1,5 +1,5 @@
-import { describe, expect, test } from "bun:test"
-import { existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, writeFileSync } from "node:fs"
+import { describe, expect, onTestFinished, test } from "bun:test"
+import { existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs"
 import { tmpdir } from "node:os"
 import { join } from "node:path"
 
@@ -22,8 +22,14 @@ import {
 const STAMP = "20260101-120000"
 const START_LOCAL = new Date(2026, 0, 1, 12, 0, 0)
 
+function tempRoot(): string {
+	const root = mkdtempSync(join(tmpdir(), "ulw-outcome-"))
+	onTestFinished(() => rmSync(root, { recursive: true, force: true }))
+	return root
+}
+
 function sessionDir(): string {
-	const dir = join(mkdtempSync(join(tmpdir(), "ulw-outcome-")), STAMP)
+	const dir = join(tempRoot(), STAMP)
 	mkdirSync(dir)
 	return dir
 }
@@ -57,7 +63,7 @@ describe("initManifest", () => {
 
 	test("#given a session dir without a YYYYMMDD-HHMMSS basename #when initialised #then it throws a typed error", () => {
 		// given
-		const dir = mkdtempSync(join(tmpdir(), "ulw-outcome-"))
+		const dir = tempRoot()
 		// when / then
 		expect(() => initManifest({ sessionDir: dir, promised: ["pdf"], lane: null })).toThrow(OutcomeError)
 	})