oh-my-opencode 4.9.2 → 4.10.0

package/packages/omo-codex/plugin/test/bootstrap-hooks.test.mjs

@@ -0,0 +1,166 @@
+import assert from "node:assert/strict";
+import { readdir, readFile, stat } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import test from "node:test";
+
+import { collectCommandHooks, readComponentHookManifests, readJson, root } from "./aggregate-plugin-fixture.mjs";
+
+const PLUGIN_ROOT_TARGET_PATTERN = /\$\{PLUGIN_ROOT\}([^"']+)/g;
+const SKIPPED_DIRECTORY_NAMES = new Set([".git", "node_modules"]);
+const EXPECTED_BOOTSTRAP_COMMAND = 'node "${PLUGIN_ROOT}/components/bootstrap/dist/cli.js" hook session-start';
+const EXPECTED_BOOTSTRAP_COMMAND_WINDOWS =
+	'powershell -NoProfile -ExecutionPolicy Bypass -File "${PLUGIN_ROOT}\\components\\bootstrap\\scripts\\bootstrap.ps1"';
+
+async function pathExists(absolutePath) {
+	try {
+		await stat(absolutePath);
+		return true;
+	} catch (error) {
+		if (error instanceof Error && "code" in error && error.code === "ENOENT") return false;
+		throw error;
+	}
+}
+
+async function findHooksManifestPaths(directory, results = []) {
+	const entries = await readdir(directory, { withFileTypes: true });
+	for (const entry of entries) {
+		if (SKIPPED_DIRECTORY_NAMES.has(entry.name)) continue;
+		const path = join(directory, entry.name);
+		if (entry.isDirectory()) {
+			await findHooksManifestPaths(path, results);
+			continue;
+		}
+		if (entry.name === "hooks.json") results.push(path);
+	}
+	return results;
+}
+
+function collectAsyncOptIns(value, manifestPath, offenders) {
+	if (Array.isArray(value)) {
+		for (const entry of value) collectAsyncOptIns(entry, manifestPath, offenders);
+		return offenders;
+	}
+	if (typeof value !== "object" || value === null) return offenders;
+	if (value.async === true) offenders.push(manifestPath);
+	for (const entry of Object.values(value)) collectAsyncOptIns(entry, manifestPath, offenders);
+	return offenders;
+}
+
+function collectPluginRootTargets(handler) {
+	const targets = [];
+	for (const commandText of [handler.command, handler.commandWindows]) {
+		if (typeof commandText !== "string") continue;
+		for (const match of commandText.matchAll(PLUGIN_ROOT_TARGET_PATTERN)) {
+			targets.push(match[1].split(/[\\/]/).filter((part) => part.length > 0));
+		}
+	}
+	return targets;
+}
+
+async function readHookManifestsWithRoots() {
+	const aggregate = { source: "hooks/hooks.json", hooks: await readJson("hooks/hooks.json"), roots: [root] };
+	const components = (await readComponentHookManifests()).map(({ source, hooks }) => ({
+		source,
+		hooks,
+		roots: [dirname(dirname(join(root, source))), root],
+	}));
+	return [aggregate, ...components];
+}
+
+function findBootstrapSessionStartHandlers(hooks) {
+	const groups = Array.isArray(hooks.hooks?.SessionStart) ? hooks.hooks.SessionStart : [];
+	const located = [];
+	for (const group of groups) {
+		for (const handler of group.hooks ?? []) {
+			if (typeof handler.command !== "string") continue;
+			if (!handler.command.includes("components/bootstrap/dist/cli.js")) continue;
+			located.push({ group, handler });
+		}
+	}
+	return located;
+}
+
+test("#given every hooks.json under the plugin #when handlers are inspected #then no entry opts into unsupported async execution", async () => {
+	// given
+	const manifestPaths = await findHooksManifestPaths(root);
+
+	// when
+	const offenders = [];
+	for (const manifestPath of manifestPaths) {
+		collectAsyncOptIns(JSON.parse(await readFile(manifestPath, "utf8")), manifestPath, offenders);
+	}
+
+	// then
+	assert(manifestPaths.length >= 2, "expected the aggregate and component hooks manifests to be discovered");
+	assert.deepEqual(offenders, [], `Codex skips async hooks silently; remove "async": true from: ${offenders.join(", ")}`);
+});
+
+test("#given aggregate and component hook manifests #when command targets are resolved #then every command and commandWindows target exists", async () => {
+	// given
+	const manifests = await readHookManifestsWithRoots();
+
+	// when
+	const missing = [];
+	for (const manifest of manifests) {
+		for (const { handler } of collectCommandHooks(manifest.hooks, manifest.source)) {
+			for (const targetParts of collectPluginRootTargets(handler)) {
+				const candidates = manifest.roots.map((rootPath) => join(rootPath, ...targetParts));
+				let found = false;
+				for (const candidate of candidates) {
+					if (await pathExists(candidate)) {
+						found = true;
+						break;
+					}
+				}
+				if (!found) missing.push(`${manifest.source}: ${targetParts.join("/")}`);
+			}
+		}
+	}
+
+	// then
+	assert.deepEqual(missing, []);
+});
+
+test("#given the bootstrap component #when its SessionStart registration is inspected #then aggregate and component entries declare both platform commands", async () => {
+	// given
+	const aggregateHooks = await readJson("hooks/hooks.json");
+	const componentHooks = await readJson("components/bootstrap/hooks/hooks.json");
+
+	// when
+	const aggregateEntries = findBootstrapSessionStartHandlers(aggregateHooks);
+	const componentEntries = findBootstrapSessionStartHandlers(componentHooks);
+
+	// then
+	for (const [label, entries] of [
+		["aggregate", aggregateEntries],
+		["component", componentEntries],
+	]) {
+		assert.equal(entries.length, 1, `${label} hooks.json must register exactly one bootstrap SessionStart handler`);
+		const { group, handler } = entries[0];
+		assert.equal(group.matcher, undefined, `${label} bootstrap SessionStart entry must be matcher-less`);
+		assert.equal(handler.type, "command");
+		assert.equal(handler.command, EXPECTED_BOOTSTRAP_COMMAND);
+		assert.equal(handler.commandWindows, EXPECTED_BOOTSTRAP_COMMAND_WINDOWS);
+		assert.equal(typeof handler.timeout, "number");
+		assert(handler.timeout <= 60, `${label} bootstrap timeout must stay <= 60 seconds`);
+		assert.equal(typeof handler.statusMessage, "string");
+		assert.match(handler.statusMessage, /^LazyCodex\([^)]+\): .+$/);
+	}
+});
+
+test("#given the built bootstrap bundle #when its module references are inspected #then it depends on Node built-ins only", async () => {
+	// given
+	const bundlePath = join(root, "components", "bootstrap", "dist", "cli.js");
+	assert.equal(await pathExists(bundlePath), true, "components/bootstrap/dist/cli.js must exist after the plugin build");
+	const bundle = await readFile(bundlePath, "utf8");
+
+	// when
+	const externalSpecifiers = [
+		...[...bundle.matchAll(/\brequire\(["']([^"']+)["']\)/g)].map((match) => match[1]),
+		...[...bundle.matchAll(/\bfrom\s*["']([^"']+)["']/g)].map((match) => match[1]),
+	].filter((specifier) => !specifier.startsWith("node:"));
+
+	// then
+	assert(bundle.length > 0, "bootstrap bundle must not be empty");
+	assert.deepEqual(externalSpecifiers, [], "bootstrap dist must bundle everything except node: built-ins");
+});

package/packages/omo-codex/plugin/test/bootstrap-orchestration.test.mjs

@@ -0,0 +1,371 @@
+import assert from "node:assert/strict";
+import { mkdir, mkdtemp, readFile, rm, stat, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import test from "node:test";
+import { fileURLToPath } from "node:url";
+
+const CLI_URL = new URL("../components/bootstrap/dist/cli.js", import.meta.url);
+const CLI_PATH = fileURLToPath(CLI_URL);
+const {
+	BOOTSTRAP_RESTART_NOTICE,
+	bootstrapLocks,
+	executeSessionStartHook,
+	parseWorkerFlags,
+	runBootstrapWorker,
+	runSessionStartHook,
+} = await import(CLI_URL.href);
+
+const PLUGIN_VERSION = "9.9.9";
+
+async function withFixture(run, options = {}) {
+	const root = await mkdtemp(join(tmpdir(), "omo-bootstrap-orch-"));
+	try {
+		const pluginRoot = join(root, "plugin");
+		const pluginData = join(root, "plugin-data");
+		await mkdir(join(pluginRoot, ".codex-plugin"), { recursive: true });
+		await mkdir(pluginData, { recursive: true });
+		await writeFile(
+			join(pluginRoot, ".codex-plugin", "plugin.json"),
+			`${JSON.stringify({ name: "omo", version: options.version ?? PLUGIN_VERSION })}\n`,
+		);
+		await run({
+			env: { PLUGIN_DATA: pluginData, PLUGIN_ROOT: pluginRoot },
+			pluginData,
+			pluginRoot,
+			root,
+		});
+	} finally {
+		await rm(root, { force: true, recursive: true });
+	}
+}
+
+function hookRecorder() {
+	const notices = [];
+	const spawned = [];
+	return {
+		notices,
+		spawned,
+		spawnWorker: (invocation) => {
+			spawned.push(invocation);
+		},
+		writeNotice: (line) => {
+			notices.push(line);
+		},
+	};
+}
+
+async function readStateFile(pluginData) {
+	return JSON.parse(await readFile(join(pluginData, "bootstrap", "state.json"), "utf8"));
+}
+
+async function writeStateFile(pluginData, state) {
+	await mkdir(join(pluginData, "bootstrap"), { recursive: true });
+	await writeFile(join(pluginData, "bootstrap", "state.json"), `${JSON.stringify(state)}\n`);
+}
+
+test("#given a fresh PLUGIN_DATA #when the session-start hook runs #then it spawns the detached worker and emits the restart notice", async () => {
+	await withFixture(async (fixture) => {
+		const recorder = hookRecorder();
+
+		const result = await executeSessionStartHook({ env: fixture.env, ...recorder });
+
+		assert.equal(result.exitCode, 0);
+		assert.equal(result.action, "spawned");
+		assert.equal(recorder.spawned.length, 1);
+		assert.equal(recorder.spawned[0].command, process.execPath);
+		assert.deepEqual(recorder.spawned[0].args, [CLI_PATH, "worker"]);
+		assert.equal(recorder.spawned[0].env.PLUGIN_DATA, fixture.pluginData);
+		assert.equal(recorder.notices.length, 1);
+		assert.deepEqual(JSON.parse(recorder.notices[0]), {
+			hookSpecificOutput: {
+				hookEventName: "SessionStart",
+				additionalContext: BOOTSTRAP_RESTART_NOTICE,
+			},
+		});
+	});
+});
+
+test("#given a completed marker for the current version #when the hook runs #then it exits 0 silently without spawning", async () => {
+	await withFixture(async (fixture) => {
+		await writeStateFile(fixture.pluginData, { completedForVersion: PLUGIN_VERSION, lastAttemptAt: 1, lastStatus: "success" });
+		const recorder = hookRecorder();
+
+		const result = await executeSessionStartHook({ env: fixture.env, ...recorder });
+
+		assert.equal(result.exitCode, 0);
+		assert.equal(result.action, "skip-completed");
+		assert.deepEqual(recorder.spawned, []);
+		assert.deepEqual(recorder.notices, []);
+	});
+});
+
+test("#given a marker stamped for an older plugin version #when the hook runs #then the version bump re-spawns the worker", async () => {
+	await withFixture(async (fixture) => {
+		await writeStateFile(fixture.pluginData, { completedForVersion: "0.0.1", lastAttemptAt: 1, lastStatus: "success" });
+		const recorder = hookRecorder();
+
+		const result = await executeSessionStartHook({ env: fixture.env, ...recorder });
+
+		assert.equal(result.action, "spawned");
+		assert.equal(recorder.spawned.length, 1);
+	});
+});
+
+test("#given a fresh bootstrap lock held by another process #when the hook runs #then it exits 0 without spawning", async () => {
+	await withFixture(async (fixture) => {
+		await mkdir(join(fixture.pluginData, "bootstrap"), { recursive: true });
+		await writeFile(join(fixture.pluginData, "bootstrap", "state.json.lock"), `${Date.now()}\n`);
+		const recorder = hookRecorder();
+
+		const result = await executeSessionStartHook({ env: fixture.env, ...recorder });
+
+		assert.equal(result.exitCode, 0);
+		assert.equal(result.action, "skip-locked");
+		assert.deepEqual(recorder.spawned, []);
+		assert.deepEqual(recorder.notices, []);
+	});
+});
+
+test("#given a stale bootstrap lock #when the hook runs #then it spawns anyway", async () => {
+	await withFixture(async (fixture) => {
+		await mkdir(join(fixture.pluginData, "bootstrap"), { recursive: true });
+		await writeFile(join(fixture.pluginData, "bootstrap", "state.json.lock"), "1\n");
+		const staleNow = Date.now() + 11 * 60 * 1_000;
+		const recorder = hookRecorder();
+
+		const result = await executeSessionStartHook({ env: fixture.env, now: staleNow, ...recorder });
+
+		assert.equal(result.action, "spawned");
+	});
+});
+
+test("#given PLUGIN_DATA or PLUGIN_ROOT missing #when the hook runs #then it exits 0 silently", async () => {
+	await withFixture(async (fixture) => {
+		const recorder = hookRecorder();
+
+		const noData = await executeSessionStartHook({ env: { PLUGIN_ROOT: fixture.pluginRoot }, ...recorder });
+		const noRoot = await executeSessionStartHook({ env: { PLUGIN_DATA: fixture.pluginData }, ...recorder });
+
+		assert.equal(noData.exitCode, 0);
+		assert.equal(noData.action, "skip-missing-env");
+		assert.equal(noRoot.action, "skip-missing-env");
+		assert.deepEqual(recorder.spawned, []);
+	});
+});
+
+test("#given an unreadable plugin version manifest #when the hook runs #then it exits 0 without spawning", async () => {
+	await withFixture(async (fixture) => {
+		await rm(join(fixture.pluginRoot, ".codex-plugin", "plugin.json"));
+		const recorder = hookRecorder();
+
+		const result = await executeSessionStartHook({ env: fixture.env, ...recorder });
+
+		assert.equal(result.exitCode, 0);
+		assert.equal(result.action, "skip-version-unresolved");
+		assert.deepEqual(recorder.spawned, []);
+	});
+});
+
+test("#given the public hook runner #when every branch resolves #then it always returns exit code 0", async () => {
+	await withFixture(async (fixture) => {
+		const recorder = hookRecorder();
+
+		assert.equal(await runSessionStartHook({ env: fixture.env, ...recorder }), 0);
+		assert.equal(await runSessionStartHook({ env: {}, ...recorder }), 0);
+	});
+});
+
+test("#given a fresh state #when the worker runs #then steps execute and the versioned success marker is persisted", async () => {
+	await withFixture(async (fixture) => {
+		const contexts = [];
+		const now = 42_000;
+
+		const result = await runBootstrapWorker({
+			argv: ["--codex-home", join(fixture.root, "codex-home")],
+			env: fixture.env,
+			now,
+			steps: [
+				{
+					name: "setup",
+					run: async (context) => {
+						contexts.push(context);
+						return { degraded: [] };
+					},
+				},
+			],
+		});
+
+		assert.equal(result.ran, true);
+		assert.equal(result.status, "success");
+		assert.equal(contexts.length, 1);
+		assert.equal(contexts[0].codexHome, join(fixture.root, "codex-home"));
+		assert.equal(contexts[0].pluginRoot, fixture.pluginRoot);
+		assert.equal(contexts[0].pluginData, fixture.pluginData);
+		assert.equal(contexts[0].pluginVersion, PLUGIN_VERSION);
+		assert.deepEqual(await readStateFile(fixture.pluginData), {
+			completedForVersion: PLUGIN_VERSION,
+			degraded: [],
+			lastAttemptAt: now,
+			lastStatus: "success",
+		});
+	});
+});
+
+test("#given a marker written between hook and worker start #when the worker re-checks under lock #then it honors the marker (TOCTOU)", async () => {
+	await withFixture(async (fixture) => {
+		await writeStateFile(fixture.pluginData, { completedForVersion: PLUGIN_VERSION, lastAttemptAt: 7, lastStatus: "success" });
+		let stepRuns = 0;
+
+		const result = await runBootstrapWorker({
+			env: fixture.env,
+			steps: [
+				{
+					name: "setup",
+					run: async () => {
+						stepRuns += 1;
+						return { degraded: [] };
+					},
+				},
+			],
+		});
+
+		assert.deepEqual(result, { ran: false, reason: "already-completed" });
+		assert.equal(stepRuns, 0);
+		assert.deepEqual(await readStateFile(fixture.pluginData), {
+			completedForVersion: PLUGIN_VERSION,
+			lastAttemptAt: 7,
+			lastStatus: "success",
+		});
+	});
+});
+
+test("#given both locks already held #when the worker starts #then it is refused without writing state", async () => {
+	await withFixture(async (fixture) => {
+		const locks = await bootstrapLocks({ env: fixture.env, pluginData: fixture.pluginData });
+		assert.notEqual(locks, null);
+
+		const result = await runBootstrapWorker({ env: fixture.env, steps: [] });
+
+		assert.deepEqual(result, { ran: false, reason: "locked" });
+		await assert.rejects(() => stat(join(fixture.pluginData, "bootstrap", "state.json")));
+		await locks.release();
+		await assert.rejects(() => stat(locks.bootstrapLockPath));
+	});
+});
+
+test("#given throwing and degraded steps #when the worker runs #then degraded reasons are persisted and the worker still exits cleanly", async () => {
+	await withFixture(async (fixture) => {
+		const now = 84_000;
+
+		const result = await runBootstrapWorker({
+			env: fixture.env,
+			now,
+			steps: [
+				{
+					name: "setup",
+					run: async () => {
+						throw new Error("config.toml unwritable");
+					},
+				},
+				{
+					name: "sg",
+					run: async () => ({
+						degraded: [{ component: "ast_grep", hint: "npx lazycodex-ai doctor", reason: "checksum mismatch for darwin-arm64" }],
+					}),
+				},
+			],
+		});
+
+		assert.equal(result.ran, true);
+		assert.equal(result.status, "degraded");
+		const state = await readStateFile(fixture.pluginData);
+		assert.equal(state.completedForVersion, PLUGIN_VERSION);
+		assert.equal(state.lastAttemptAt, now);
+		assert.equal(state.lastStatus, "degraded");
+		assert.equal(state.degraded.length, 2);
+		assert.deepEqual(state.degraded[0], {
+			component: "setup",
+			hint: "npx lazycodex-ai doctor",
+			reason: "config.toml unwritable",
+		});
+		assert.deepEqual(state.degraded[1], {
+			component: "ast_grep",
+			hint: "npx lazycodex-ai doctor",
+			reason: "checksum mismatch for darwin-arm64",
+		});
+	});
+});
+
+test("#given a completed marker #when the worker runs with --once #then the marker is bypassed and steps run again", async () => {
+	await withFixture(async (fixture) => {
+		await writeStateFile(fixture.pluginData, { completedForVersion: PLUGIN_VERSION, lastAttemptAt: 7, lastStatus: "success" });
+		let stepRuns = 0;
+
+		const result = await runBootstrapWorker({
+			argv: ["--once"],
+			env: fixture.env,
+			steps: [
+				{
+					name: "setup",
+					run: async () => {
+						stepRuns += 1;
+						return { degraded: [] };
+					},
+				},
+			],
+		});
+
+		assert.equal(result.ran, true);
+		assert.equal(stepRuns, 1);
+	});
+});
+
+test("#given --only sg #when the worker runs #then only the matching step executes", async () => {
+	await withFixture(async (fixture) => {
+		const ran = [];
+		const step = (name) => ({
+			name,
+			run: async () => {
+				ran.push(name);
+				return { degraded: [] };
+			},
+		});
+
+		const result = await runBootstrapWorker({
+			argv: ["--only", "sg"],
+			env: fixture.env,
+			steps: [step("setup"), step("sg")],
+		});
+
+		assert.equal(result.ran, true);
+		assert.deepEqual(ran, ["sg"]);
+	});
+});
+
+test("#given worker CLI flags #when parsed #then --codex-home/--once/--only/--manifest-dir are recognized and unknown flags throw", () => {
+	assert.deepEqual(parseWorkerFlags(["--codex-home", "/x", "--once", "--only", "sg", "--manifest-dir", "/m"]), {
+		codexHome: "/x",
+		manifestDir: "/m",
+		once: true,
+		only: "sg",
+	});
+	assert.deepEqual(parseWorkerFlags([]), { once: false });
+	assert.throws(() => parseWorkerFlags(["--bogus"]), /--bogus/);
+	assert.throws(() => parseWorkerFlags(["--codex-home"]), /--codex-home/);
+});
+
+test("#given a missing plugin version in the worker #when it runs #then it records a degraded state instead of crashing", async () => {
+	await withFixture(async (fixture) => {
+		await rm(join(fixture.pluginRoot, ".codex-plugin", "plugin.json"));
+
+		const result = await runBootstrapWorker({ env: fixture.env, now: 5_000, steps: [] });
+
+		assert.equal(result.ran, true);
+		assert.equal(result.status, "degraded");
+		const state = await readStateFile(fixture.pluginData);
+		assert.equal(state.completedForVersion, undefined);
+		assert.equal(state.lastStatus, "degraded");
+		assert.match(state.degraded[0].reason, /plugin version/i);
+	});
+});

package/packages/omo-codex/plugin/test/bootstrap-ps-guard.test.mjs

@@ -0,0 +1,134 @@
+import assert from "node:assert/strict";
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import test from "node:test";
+
+import { collectCommandHooks, readJson, root } from "./aggregate-plugin-fixture.mjs";
+
+const BOOTSTRAP_SCRIPT_RELATIVE_PATH = join("components", "bootstrap", "scripts", "bootstrap.ps1");
+const HOOK_MANIFEST_SOURCES = ["hooks/hooks.json", "components/bootstrap/hooks/hooks.json"];
+const BOOTSTRAP_PS1_COMMAND_WINDOWS_TARGET = "\\components\\bootstrap\\scripts\\bootstrap.ps1";
+const TLS12_LINE_PATTERN =
+	/\[Net\.ServicePointManager\]::SecurityProtocol\s*=\s*\[Net\.ServicePointManager\]::SecurityProtocol\s+-bor\s+\[Net\.SecurityProtocolType\]::Tls12/;
+const PWSH7_ONLY_TOKENS = [
+	{ token: "??", pattern: /\?\?/, reason: "null-coalescing operator requires pwsh 7" },
+	{ token: "?.", pattern: /\?\./, reason: "null-conditional member access requires pwsh 7" },
+	{ token: "-Parallel", pattern: /-Parallel\b/i, reason: "ForEach-Object -Parallel requires pwsh 7" },
+];
+
+async function readBootstrapScript() {
+	return readFile(join(root, BOOTSTRAP_SCRIPT_RELATIVE_PATH), "utf8");
+}
+
+function numberedLines(content) {
+	return content.split(/\r?\n/).map((text, index) => ({ line: index + 1, text }));
+}
+
+test("#given bootstrap.ps1 #when the download preamble is inspected #then it forces TLS 1.2 on ServicePointManager", async () => {
+	// given
+	const content = await readBootstrapScript();
+
+	// then
+	assert.match(
+		content,
+		TLS12_LINE_PATTERN,
+		"bootstrap.ps1 must OR Tls12 into [Net.ServicePointManager]::SecurityProtocol before any Invoke-WebRequest",
+	);
+});
+
+test("#given bootstrap.ps1 #when scanned for pwsh-7-only syntax #then Windows PowerShell 5.1 can parse every line", async () => {
+	// given
+	const content = await readBootstrapScript();
+
+	// when
+	const offenders = [];
+	for (const { token, pattern, reason } of PWSH7_ONLY_TOKENS) {
+		for (const { line, text } of numberedLines(content)) {
+			if (pattern.test(text)) {
+				offenders.push(`pwsh-7-only token \`${token}\` (${reason}) at bootstrap.ps1:${line}: ${text.trim()}`);
+			}
+		}
+	}
+
+	// then
+	assert.deepEqual(offenders, [], "bootstrap.ps1 runs under Windows PowerShell 5.1 (System32); pwsh-7-only syntax breaks it");
+});
+
+test("#given bootstrap.ps1 #when environment writes are scanned #then no Machine-scope target appears", async () => {
+	// given
+	const content = await readBootstrapScript();
+
+	// when
+	const offenders = numberedLines(content)
+		.filter(({ text }) => /\bmachine\b/i.test(text))
+		.map(({ line, text }) => `Machine-scope token at bootstrap.ps1:${line}: ${text.trim()}`);
+
+	// then
+	assert.deepEqual(offenders, [], "bootstrap.ps1 must only touch User-scope environment values (Machine scope needs elevation)");
+});
+
+test("#given bootstrap.ps1 #when execution policy mutations are scanned #then Set-ExecutionPolicy is never invoked", async () => {
+	// given
+	const content = await readBootstrapScript();
+
+	// when
+	const offenders = numberedLines(content)
+		.filter(({ text }) => /set-executionpolicy/i.test(text))
+		.map(({ line, text }) => `Set-ExecutionPolicy at bootstrap.ps1:${line}: ${text.trim()}`);
+
+	// then
+	assert.deepEqual(offenders, [], "the hook line already passes -ExecutionPolicy Bypass; the script must not change policy");
+});
+
+test("#given bootstrap.ps1 #when the final executable statement is located #then it is `exit 0` so sessions are never blocked", async () => {
+	// given
+	const content = await readBootstrapScript();
+
+	// when
+	const statements = content
+		.split(/\r?\n/)
+		.map((line) => line.trim())
+		.filter((line) => line.length > 0 && !line.startsWith("#"));
+
+	// then
+	assert.equal(statements.at(-1), "exit 0", "the terminal statement of bootstrap.ps1 must be `exit 0`");
+});
+
+test("#given bootstrap.ps1 #when every character is inspected #then the script is ASCII-only for cp949-safe consoles", async () => {
+	// given
+	const content = await readBootstrapScript();
+
+	// when
+	const offenders = [];
+	for (const { line, text } of numberedLines(content)) {
+		for (const character of text) {
+			const codePoint = character.codePointAt(0);
+			if (codePoint > 0x7f) {
+				offenders.push(`non-ASCII U+${codePoint.toString(16).toUpperCase().padStart(4, "0")} at bootstrap.ps1:${line}: ${text.trim()}`);
+			}
+		}
+	}
+
+	// then
+	assert.deepEqual(offenders, [], "bootstrap.ps1 output and source must be ASCII-only (cp949 consoles mangle anything else)");
+});
+
+test("#given the aggregate and bootstrap component hook manifests #when commandWindows entries are read #then the bootstrap SessionStart hook launches bootstrap.ps1", async () => {
+	for (const source of HOOK_MANIFEST_SOURCES) {
+		// given
+		const hooks = await readJson(source);
+
+		// when
+		const launchers = collectCommandHooks(hooks, source)
+			.map(({ handler }) => handler.commandWindows)
+			.filter((command) => typeof command === "string" && command.includes(BOOTSTRAP_PS1_COMMAND_WINDOWS_TARGET));
+
+		// then
+		assert.equal(launchers.length, 1, `${source} must register exactly one commandWindows pointing at bootstrap.ps1`);
+		assert.match(
+			launchers[0],
+			/^powershell -NoProfile -ExecutionPolicy Bypass -File /,
+			`${source} must launch bootstrap.ps1 with -NoProfile and -File`,
+		);
+	}
+});