oh-my-opencode 4.12.1 → 4.14.0

package/packages/omo-codex/plugin/components/codegraph/test/session-start-worker-availability.test.ts

@@ -0,0 +1,106 @@
+import { describe, expect, it } from "bun:test";
+import { existsSync, mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { runCodegraphSessionStartWorker } from "../src/hook.ts";
+
+describe("CodeGraph SessionStart worker availability", () => {
+	it("#given CodeGraph cannot be resolved or provisioned #when worker runs #then it logs a graceful skip", async () => {
+		// given
+		const workspace = mkdtempSync(join(tmpdir(), "omo-codegraph-worker-"));
+		const homeDir = mkdtempSync(join(tmpdir(), "omo-codegraph-worker-home-"));
+		const outcomes: unknown[] = [];
+		const calls: string[] = [];
+
+		try {
+			// when
+			const result = await runCodegraphSessionStartWorker({
+				cwd: workspace,
+				env: { HOME: homeDir },
+				nodeVersion: "22.14.0",
+				logOutcome: (outcome) => outcomes.push(outcome),
+				deps: {
+					ensureGitignored: () => {
+						calls.push("ensureGitignored");
+						return true;
+					},
+					ensureProvisioned: () => Promise.resolve({ error: "offline", provisioned: false }),
+					prepareWorkspace: () => {
+						calls.push("prepareWorkspace");
+						return {
+							dataDir: join(homeDir, ".omo/codegraph/projects/test"),
+							dataRoot: join(homeDir, ".omo/codegraph"),
+							linked: true,
+							mode: "global-linked",
+							projectLink: join(workspace, ".codegraph"),
+						};
+					},
+					resolveCommand: () => ({ argsPrefix: [], command: "codegraph", exists: false, source: "path" }),
+					runCommand: () => {
+						calls.push("runCommand");
+						return Promise.resolve({ exitCode: 0, stdout: "", timedOut: false });
+					},
+				},
+			});
+
+			// then
+			expect(result).toEqual({ action: "skipped-unavailable" });
+			expect(calls).toEqual([]);
+			expect(outcomes).toEqual([
+				{
+					action: "skipped-unavailable",
+					error: "offline",
+					projectRoot: workspace,
+					source: "path",
+				},
+			]);
+		} finally {
+			rmSync(workspace, { recursive: true, force: true });
+			rmSync(homeDir, { recursive: true, force: true });
+		}
+	});
+
+	it("#given CodeGraph is unavailable and auto provisioning is disabled #when worker runs #then it leaves the project untouched", async () => {
+		// given
+		const workspace = mkdtempSync(join(tmpdir(), "omo-codegraph-worker-unavailable-"));
+		const homeDir = mkdtempSync(join(tmpdir(), "omo-codegraph-worker-unavailable-home-"));
+		const outcomes: unknown[] = [];
+
+		try {
+			// when
+			const result = await runCodegraphSessionStartWorker({
+				config: { codegraph: { auto_provision: false, enabled: true }, sources: [], warnings: [] },
+				nodeVersion: "22.14.0",
+				cwd: workspace,
+				env: { HOME: homeDir },
+				logOutcome: (outcome) => outcomes.push(outcome),
+				deps: {
+					ensureProvisioned: () => {
+						throw new Error("auto provision should not run");
+					},
+					resolveCommand: () => ({ argsPrefix: [], command: "missing-codegraph", exists: false, source: "path" }),
+					runCommand: () => {
+						throw new Error("codegraph command should not run");
+					},
+				},
+			});
+
+			// then
+			expect(result).toEqual({ action: "skipped-unavailable" });
+			expect(existsSync(join(workspace, ".codegraph"))).toBe(false);
+			expect(existsSync(join(workspace, ".git", "info", "exclude"))).toBe(false);
+			expect(outcomes).toEqual([
+				{
+					action: "skipped-unavailable",
+					error: "codegraph binary unavailable and auto_provision is disabled",
+					projectRoot: workspace,
+					source: "path",
+				},
+			]);
+		} finally {
+			rmSync(workspace, { recursive: true, force: true });
+			rmSync(homeDir, { recursive: true, force: true });
+		}
+	});
+});

package/packages/omo-codex/plugin/components/codegraph/test/session-start-worker-flow.test.ts

@@ -0,0 +1,220 @@
+import { describe, expect, it } from "bun:test";
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { resolveCodegraphCommandInvocation, runCodegraphSessionStartWorker } from "../src/hook.ts";
+
+describe("CodeGraph SessionStart worker flow", () => {
+	it("#given Windows install_dir has codegraph.cmd #when worker resolves provisioned CodeGraph #then it uses the cmd shim", async () => {
+		await withProcessPlatform("win32", async () => {
+			// given
+			const workspace = mkdtempSync(join(tmpdir(), "omo-codegraph-worker-win32-"));
+			const homeDir = mkdtempSync(join(tmpdir(), "omo-codegraph-worker-win32-home-"));
+			const installDir = mkdtempSync(join(tmpdir(), "omo-codegraph-worker-win32-install-"));
+			const binPath = join(installDir, "bin", "codegraph.cmd");
+			const calls: { readonly args: readonly string[]; readonly command: string; readonly env: Record<string, string> }[] = [];
+			const outcomes: unknown[] = [];
+			try {
+				mkdirSync(join(installDir, "bin"), { recursive: true });
+				writeFileSync(binPath, "");
+
+				// when
+				const result = await runCodegraphSessionStartWorker({
+					config: { codegraph: { enabled: true, install_dir: installDir }, sources: [], trustedCodegraphInstallDir: installDir, warnings: [] },
+					nodeVersion: "22.14.0",
+					cwd: workspace,
+					env: { HOME: homeDir },
+					logOutcome: (outcome) => outcomes.push(outcome),
+					deps: {
+						ensureGitignored: () => true,
+						ensureProvisioned: () => {
+							throw new Error("provisioning should not run when install_dir binary exists");
+						},
+						prepareWorkspace: () => ({
+							dataDir: join(homeDir, ".omo/codegraph/projects/test"),
+							dataRoot: join(homeDir, ".omo/codegraph"),
+							linked: true,
+							mode: "global-linked",
+							projectLink: join(workspace, ".codegraph"),
+						}),
+						resolveCommand: (options) => {
+							const provisioned = options?.provisioned?.() ?? null;
+							return { argsPrefix: [], command: provisioned ?? "missing-codegraph", exists: provisioned !== null, source: provisioned === null ? "path" : "provisioned" };
+						},
+						runCommand: (_projectRoot, command, args, options) => {
+							calls.push({ args, command, env: options.env });
+							return Promise.resolve({ exitCode: 0, stdout: calls.length === 1 ? '{"initialized":false}' : "", timedOut: false });
+						},
+					},
+				});
+
+				// then
+				expect(result).toEqual({ action: "initialized" });
+				expect(calls.map((call) => ({ args: [...call.args], command: call.command }))).toEqual([
+					{ args: ["status", "--json"], command: binPath },
+					{ args: ["init"], command: binPath },
+				]);
+				expect(calls[0]?.env["CODEGRAPH_INSTALL_DIR"]).toBe(installDir);
+				expect(outcomes).toEqual([{ action: "initialized", exitCode: 0, projectRoot: workspace, source: "provisioned", timedOut: false }]);
+			} finally {
+				rmSync(workspace, { recursive: true, force: true });
+				rmSync(homeDir, { recursive: true, force: true });
+				rmSync(installDir, { recursive: true, force: true });
+			}
+		});
+	});
+
+	it("#given Windows codegraph.cmd #when default worker runner builds invocation #then it runs through cmd.exe", () => {
+		// given
+		const command = "C:\\Users\\test\\.omo\\codegraph\\bin\\codegraph.cmd";
+
+		// when
+		const invocation = resolveCodegraphCommandInvocation(command, ["status", "--json"], "win32");
+
+		// then
+		expect(invocation).toEqual({
+			args: ["/d", "/s", "/c", command, "status", "--json"],
+			command: "cmd.exe",
+		});
+	});
+
+	it("#given Windows CodeGraph resolves to a Node script #when default worker runner builds invocation #then Node executes it", () => {
+		// given
+		const command = "C:\\Users\\test\\.omo\\codegraph\\bin\\codegraph.cjs";
+
+		// when
+		const invocation = resolveCodegraphCommandInvocation(command, ["status", "--json"], "win32");
+
+		// then
+		expect(invocation).toEqual({
+			args: [command, "status", "--json"],
+			command: process.execPath,
+		});
+	});
+
+	it("#given non-Windows codegraph command #when default worker runner builds invocation #then it executes directly", () => {
+		// given
+		const command = "/home/test/.omo/codegraph/bin/codegraph";
+
+		// when
+		const invocation = resolveCodegraphCommandInvocation(command, ["sync"], "linux");
+
+		// then
+		expect(invocation).toEqual({ args: ["sync"], command });
+	});
+
+	it("#given resolved CodeGraph status #when worker runs #then it runs status before init or sync", async () => {
+		for (const scenario of [
+			{ action: "initialized", args: [["status", "--json"], ["init"]], stdout: '{"initialized":false}' },
+			{ action: "synced", args: [["status", "--json"], ["sync"]], stdout: '{"initialized":true}' },
+		] as const) {
+			// given
+			const workspace = mkdtempSync(join(tmpdir(), "omo-codegraph-status-"));
+			const homeDir = mkdtempSync(join(tmpdir(), "omo-codegraph-status-home-"));
+			const calls: { readonly args: readonly string[]; readonly command: string; readonly env: Record<string, string> }[] = [];
+			const outcomes: unknown[] = [];
+			try {
+				// when
+				const result = await runCodegraphSessionStartWorker({
+					config: { codegraph: { enabled: true, install_dir: "/tmp/codegraph-install" }, sources: [], trustedCodegraphInstallDir: "/tmp/codegraph-install", warnings: [] },
+					nodeVersion: "22.14.0",
+					cwd: workspace,
+					env: { HOME: homeDir },
+					logOutcome: (outcome) => outcomes.push(outcome),
+					deps: {
+						ensureGitignored: () => true,
+						ensureProvisioned: () => Promise.resolve({ binPath: "/tmp/codegraph", provisioned: true }),
+						prepareWorkspace: () => ({
+							dataDir: join(homeDir, ".omo/codegraph/projects/test"),
+							dataRoot: join(homeDir, ".omo/codegraph"),
+							linked: true,
+							mode: "global-linked",
+							projectLink: join(workspace, ".codegraph"),
+						}),
+						resolveCommand: () => ({ argsPrefix: [], command: "/tmp/codegraph", exists: true, source: "path" }),
+						runCommand: (_projectRoot, command, args, options) => {
+							calls.push({ args, command, env: options.env });
+							return Promise.resolve({ exitCode: 0, stdout: calls.length === 1 ? scenario.stdout : "", timedOut: false });
+						},
+					},
+				});
+
+				// then
+				expect(result).toEqual({ action: scenario.action });
+				expect(calls.map((call) => [...call.args])).toEqual(scenario.args.map((args) => [...args]));
+				expect(calls[0]?.env["CODEGRAPH_INSTALL_DIR"]).toBe("/tmp/codegraph-install");
+				expect(outcomes).toEqual([{ action: scenario.action, exitCode: 0, projectRoot: workspace, source: "path", timedOut: false }]);
+			} finally {
+				rmSync(workspace, { recursive: true, force: true });
+				rmSync(homeDir, { recursive: true, force: true });
+			}
+		}
+	});
+
+	it("#given ambient provider tokens #when default worker runner spawns CodeGraph #then child env only gets safe and controlled variables", async () => {
+		// given
+		const workspace = mkdtempSync(join(tmpdir(), "omo-codegraph-worker-env-"));
+		const homeDir = mkdtempSync(join(tmpdir(), "omo-codegraph-worker-env-home-"));
+		const logPath = join(homeDir, "child-env.jsonl");
+		const originalOpenAiKey = process.env["OPENAI_API_KEY"];
+		process.env["OPENAI_API_KEY"] = "sk-test-secret";
+
+		try {
+			const fakeCodegraphScript = [
+				"const fs = require('node:fs');",
+				`fs.appendFileSync(${JSON.stringify(logPath)}, JSON.stringify({install:process.env.CODEGRAPH_INSTALL_DIR,openai:process.env.OPENAI_API_KEY}) + '\\n');`,
+				"process.stdout.write('{\"initialized\":true}');",
+			].join("");
+
+			// when
+			const result = await runCodegraphSessionStartWorker({
+				config: { codegraph: { enabled: true }, sources: [], warnings: [] },
+				cwd: workspace,
+				env: { HOME: homeDir },
+				logOutcome: () => undefined,
+				nodeVersion: "22.14.0",
+				deps: {
+					ensureGitignored: () => true,
+					ensureProvisioned: () => {
+						throw new Error("provisioning should not run when command is resolved");
+					},
+					prepareWorkspace: () => ({
+						dataDir: join(homeDir, ".omo/codegraph/projects/test"),
+						dataRoot: join(homeDir, ".omo/codegraph"),
+						linked: true,
+						mode: "global-linked",
+						projectLink: join(workspace, ".codegraph"),
+					}),
+					resolveCommand: () => ({ argsPrefix: ["-e", fakeCodegraphScript], command: process.execPath, exists: true, source: "bundled" }),
+				},
+			});
+
+			// then
+			expect(result).toEqual({ action: "synced" });
+			const captured = readFileSync(logPath, "utf8")
+				.trim()
+				.split("\n")
+				.map((line) => JSON.parse(line));
+			expect(captured).toEqual([
+				{ install: join(homeDir, ".omo", "codegraph") },
+				{ install: join(homeDir, ".omo", "codegraph") },
+			]);
+		} finally {
+			if (originalOpenAiKey === undefined) delete process.env["OPENAI_API_KEY"];
+			else process.env["OPENAI_API_KEY"] = originalOpenAiKey;
+			rmSync(workspace, { recursive: true, force: true });
+			rmSync(homeDir, { recursive: true, force: true });
+		}
+	});
+});
+
+async function withProcessPlatform(platform: NodeJS.Platform, run: () => Promise<void>): Promise<void> {
+	const descriptor = Object.getOwnPropertyDescriptor(process, "platform");
+	Object.defineProperty(process, "platform", { configurable: true, enumerable: true, value: platform });
+	try {
+		await run();
+	} finally {
+		if (descriptor !== undefined) Object.defineProperty(process, "platform", descriptor);
+	}
+}

package/packages/omo-codex/plugin/components/comment-checker/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@code-yeongyu/codex-comment-checker",
-	"version": "4.12.1",
+	"version": "4.14.0",
 	"description": "Codex plugin that runs comment-checker after edit-like PostToolUse hooks.",
 	"type": "module",
 	"packageManager": "npm@11.12.1",

package/packages/omo-codex/plugin/components/git-bash/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@sisyphuslabs/codex-git-bash-hook",
-	"version": "4.12.1",
+	"version": "4.14.0",
 	"description": "Codex hook component that reminds Windows sessions to prefer the OMO git_bash MCP.",
 	"type": "module",
 	"private": true,

package/packages/omo-codex/plugin/components/lazycodex-executor-verify/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@code-yeongyu/codex-lazycodex-executor-verify",
-	"version": "4.12.1",
+	"version": "4.14.0",
 	"description": "Codex SubagentStop evidence verifier for LazyCodex executor completions.",
 	"type": "module",
 	"packageManager": "npm@11.12.1",

package/packages/omo-codex/plugin/components/lsp/dist/cli.js

@@ -446,7 +446,10 @@ function wrap(proc) {
 }
 function killProcessTree(proc, signal) {
   if (process.platform === "win32" && proc.pid) {
-    const result = spawnSync("taskkill", ["/pid", String(proc.pid), "/f", "/t"], { stdio: "ignore" });
+    const result = spawnSync("taskkill", ["/pid", String(proc.pid), "/f", "/t"], {
+      stdio: "ignore",
+      windowsHide: true
+    });
     if (!result.error && result.status === 0)
       return;
     if (result.error)

package/packages/omo-codex/plugin/components/lsp/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@code-yeongyu/codex-lsp",
-	"version": "4.12.1",
+	"version": "4.14.0",
 	"description": "Codex plugin that exposes Language Server Protocol tools and post-edit diagnostics.",
 	"type": "module",
 	"packageManager": "npm@11.12.1",

package/packages/omo-codex/plugin/components/rules/dist/cli.js

@@ -4032,9 +4032,9 @@ function getSparkShellRuntimeAwareness(env = process.env, deps = {}) {
   return [
     SPARKSHELL_AWARENESS_MARKER,
     "",
-    `- Prefer \`${command} sparkshell <command>\` for repo inspection, CLI smoke tests, git/history checks, and bounded verification before falling back to raw shell commands.`,
-    `- Use \`${command} sparkshell --shell '<command>'\` only when shell metacharacters are required.`,
-    `- Use \`${command} sparkshell --tmux-pane <pane-id> --tail-lines 400\` to inspect an existing tmux pane. Tail lines must stay between 100 and 1000.`,
+    `- Use \`${command} sparkshell <command> [args...]\` first for repo inspection, CLI smoke tests, git/history checks, and bounded command output. Pass ordinary commands as executable and arguments in separate argv tokens, for example \`${command} sparkshell rg --files\`; not \`${command} sparkshell 'rg --files'\`, because the quoted string is treated as one executable name. Raw \`rg\`/\`grep\`/\`cat\`/\`git\` are fallbacks when Sparkshell is unavailable or too narrow for the task.`,
+    `- Use \`${command} sparkshell --shell '<command>'\` only for shell syntax such as metacharacters, pipelines, redirects, command substitution, or variable expansion.`,
+    `- Use \`${command} sparkshell --tmux-pane <pane-id> --tail-lines 400\` only to inspect an existing pane, never to launch ordinary commands. Tail lines must stay between 100 and 1000.`,
     "- When no native sidecar or appserver is available, Sparkshell silently falls back to raw command execution. `OMO_SPARKSHELL_BIN` selects a native sidecar path.",
     "- When `CODEX_THREAD_ID` identifies a Codex session, Sparkshell feeds recent session context (first/latest user request + last 5 conversation messages) into oversized-output condensation for relevance ranking, but never appends that context to command output. `OMO_SPARKSHELL_SESSION_CONTEXT=0` disables the lookup.",
     `- Route potentially huge output (full log files, big diffs, \`cat\`/\`grep\` over large artifacts) through \`${command} sparkshell\` instead of reading it raw: oversized output is condensed to a budget while preserving error signatures, repeated patterns, session-goal-relevant lines, and head/tail. Tune with \`--budget <chars>\`; disable with \`OMO_SPARKSHELL_CONDENSE=0\`.`,

package/packages/omo-codex/plugin/components/rules/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@code-yeongyu/codex-rules",
-	"version": "4.12.1",
+	"version": "4.14.0",
 	"description": "Codex plugin that injects project rule files into model context through lifecycle hooks.",
 	"type": "module",
 	"packageManager": "npm@11.12.1",

package/packages/omo-codex/plugin/components/rules/src/sparkshell-awareness.ts

@@ -81,9 +81,9 @@ export function getSparkShellRuntimeAwareness(env: RuntimeEnv = process.env, dep
 	return [
 		SPARKSHELL_AWARENESS_MARKER,
 		"",
-		`- Prefer \`${command} sparkshell <command>\` for repo inspection, CLI smoke tests, git/history checks, and bounded verification before falling back to raw shell commands.`,
-		`- Use \`${command} sparkshell --shell '<command>'\` only when shell metacharacters are required.`,
-		`- Use \`${command} sparkshell --tmux-pane <pane-id> --tail-lines 400\` to inspect an existing tmux pane. Tail lines must stay between 100 and 1000.`,
+		`- Use \`${command} sparkshell <command> [args...]\` first for repo inspection, CLI smoke tests, git/history checks, and bounded command output. Pass ordinary commands as executable and arguments in separate argv tokens, for example \`${command} sparkshell rg --files\`; not \`${command} sparkshell 'rg --files'\`, because the quoted string is treated as one executable name. Raw \`rg\`/\`grep\`/\`cat\`/\`git\` are fallbacks when Sparkshell is unavailable or too narrow for the task.`,
+		`- Use \`${command} sparkshell --shell '<command>'\` only for shell syntax such as metacharacters, pipelines, redirects, command substitution, or variable expansion.`,
+		`- Use \`${command} sparkshell --tmux-pane <pane-id> --tail-lines 400\` only to inspect an existing pane, never to launch ordinary commands. Tail lines must stay between 100 and 1000.`,
 		"- When no native sidecar or appserver is available, Sparkshell silently falls back to raw command execution. `OMO_SPARKSHELL_BIN` selects a native sidecar path.",
 		"- When `CODEX_THREAD_ID` identifies a Codex session, Sparkshell feeds recent session context (first/latest user request + last 5 conversation messages) into oversized-output condensation for relevance ranking, but never appends that context to command output. `OMO_SPARKSHELL_SESSION_CONTEXT=0` disables the lookup.",
 		`- Route potentially huge output (full log files, big diffs, \`cat\`/\`grep\` over large artifacts) through \`${command} sparkshell\` instead of reading it raw: oversized output is condensed to a budget while preserving error signatures, repeated patterns, session-goal-relevant lines, and head/tail. Tune with \`--budget <chars>\`; disable with \`OMO_SPARKSHELL_CONDENSE=0\`.`,

package/packages/omo-codex/plugin/components/rules/test/sparkshell-awareness.test.ts

@@ -1,3 +1,5 @@
+// allow: SIZE_OK - rules sparkshell-awareness coverage validates one injected guidance contract; this release adds narrow prompt cases and future growth should split by guidance surface.
+
 import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
@@ -19,6 +21,36 @@ function parseAdditionalContext(output: string): string {
 	return parsed.hookSpecificOutput?.additionalContext ?? "";
 }
 
+function normalizeGuidance(value: string): string {
+	return value.toLowerCase().replace(/\s+/g, " ").trim();
+}
+
+function expectSparkshellFirstContract(value: string): void {
+	const guidance = normalizeGuidance(value);
+
+	expect(value).toContain("`omo sparkshell <command> [args...]`");
+	expect(guidance).toMatch(/`omo sparkshell <command> \[args\.\.\.\]`[^.]*\bfirst\b/);
+	expect(guidance).toMatch(/\brepo inspection\b/);
+	expect(guidance).toMatch(/\bcli smoke tests\b/);
+	expect(guidance).toMatch(/\bgit\/history checks\b/);
+	expect(guidance).toMatch(/\bbounded command output\b/);
+	expect(guidance).toMatch(/\braw\b[^.]*`rg`\/`grep`\/`cat`\/`git`[^.]*\bfallbacks?\b/);
+	expect(guidance).toMatch(/\bsparkshell is unavailable\b/);
+	expect(guidance).toMatch(/\btoo narrow\b/);
+	expect(value).toContain("`omo sparkshell rg --files`");
+	expect(guidance).toMatch(/\bseparate argv tokens\b/);
+	expect(value).toContain("not `omo sparkshell 'rg --files'`");
+	expect(guidance).toMatch(/\bone executable name\b/);
+	expect(guidance).toMatch(/`omo sparkshell --shell '<command>'`[^.]*\bmetacharacters\b[^.]*\bpipelines\b/);
+	expect(guidance).toMatch(
+		/`omo sparkshell --tmux-pane <pane-id> --tail-lines 400`[^.]*\bonly\b[^.]*\binspect\b[^.]*\bexisting pane\b/,
+	);
+	expect(guidance).toMatch(
+		/`omo sparkshell --tmux-pane <pane-id> --tail-lines 400`[^.]*\bnever\b[^.]*\blaunch ordinary commands\b/,
+	);
+	expect(guidance).not.toMatch(/\bprefer\b[^.]*\bbefore raw shell commands\b/);
+}
+
 function parseHookOutput(value: unknown): HookOutput {
 	if (typeof value !== "object" || value === null) {
 		return {};
@@ -85,15 +117,16 @@ describe("Codex Sparkshell awareness", () => {
 		);
 
 		// then
-		expect(parseAdditionalContext(output)).toContain("omo sparkshell <command>");
-		expect(parseAdditionalContext(output)).toContain("OMO_SPARKSHELL_SESSION_CONTEXT");
-		expect(parseAdditionalContext(output)).toContain("OMO_SPARKSHELL_CONDENSE");
-		expect(parseAdditionalContext(output)).toContain("OMO_SPARKSHELL_SPARK");
-		expect(parseAdditionalContext(output)).toContain("[sparkshell caption]");
-		expect(parseAdditionalContext(output)).toContain("never appends that context to command output");
-		expect(parseAdditionalContext(output)).toContain("what the full output contained");
-		expect(parseAdditionalContext(output)).not.toContain("[REDACTED]");
-		expect(parseAdditionalContext(output)).not.toContain("appends recent session context");
+		const context = parseAdditionalContext(output);
+		expectSparkshellFirstContract(context);
+		expect(context).toContain("OMO_SPARKSHELL_SESSION_CONTEXT");
+		expect(context).toContain("OMO_SPARKSHELL_CONDENSE");
+		expect(context).toContain("OMO_SPARKSHELL_SPARK");
+		expect(context).toContain("[sparkshell caption]");
+		expect(context).toContain("never appends that context to command output");
+		expect(context).toContain("what the full output contained");
+		expect(context).not.toContain("[REDACTED]");
+		expect(context).not.toContain("appends recent session context");
 	});
 
 	it("#given inactive env #when SessionStart runs #then emits no Sparkshell guidance", async () => {

package/packages/omo-codex/plugin/components/start-work-continuation/directive.md

@@ -20,7 +20,7 @@ You are mid-flight on a Prometheus work plan; this turn is an automatic continua
 3. Follow the `start-work` skill in full. The skill is already loaded from your earlier turn — re-read its file at `packages/omo-codex/plugin/skills/start-work/SKILL.md` if you have lost context.
 4. Apply the checkbox's tier from its ledger entry, or classify it now per the start-work skill: LIGHT (default — a narrow change inside existing layers) needs one real-surface proof of the deliverable, with auxiliary surfaces first-class for CLI- or data-shaped work, and only trigger-mapped adversarial classes; HEAVY (new module/abstraction, auth/security, external integration, schema/migration, concurrency, cross-domain refactor, care signals) takes the full per-criterion regime. When unsure, take HEAVY; never downgrade.
 5. Decompose the checkbox into atomic sub-tasks. Dispatch them in PARALLEL via `multi_agent_v1.spawn_agent` calls in this same response unless a sub-task has a NAMED blocking dependency (input from another sub-task or shared file). Use `fork_context: false` unless full history is truly required. Put role and specialty instructions inside `message`.
-6. Every sub-task message MUST be self-contained, an executable assignment rather than a context handoff: start with `TASK: <imperative assignment>`, then name `DELIVERABLE`, `SCOPE`, and `VERIFY`. It must include all 7 sections and name one Manual-QA channel with its exact tool and exact invocation (the literal `curl` / `send-keys` / `page.click` with concrete inputs and the binary PASS/FAIL observable), plus the applicable ultraqa adversarial classes, a captured artifact, and a cleanup receipt. Channels: HTTP call (`curl -i`); tmux (`send-keys` + `capture-pane`); browser use — use Chrome to drive the page, else download and use agent-browser (https://github.com/vercel-labs/agent-browser); computer use — OS-level GUI automation for a desktop app.
+6. Every sub-task message MUST be self-contained, executable, not a context handoff: start with `TASK: <imperative assignment>`, then name `DELIVERABLE`, `SCOPE`, and `VERIFY`. It must include all 7 sections and a Manual-QA channel with exact invocation (`curl`, `send-keys`, `browser:control-in-app-browser` action, `page.click`) and PASS/FAIL observable, plus ultraqa classes, artifact, and cleanup receipt. Channels: HTTP (`curl -i`); tmux (`send-keys` + `capture-pane`); browser (Codex: `browser:control-in-app-browser` first unless auth/persistent profile needed; else Chrome/agent-browser); computer use.
 7. Treat every worker DoneClaim as untrusted input. Run independent AdversarialVerify before any checkbox can become FullyDone; `confirmed` is the only pass verdict, while `false-positive`, `needs-fix`, and `needs-human-review` loop back to the executor with exact feedback.
 8. Use `multi_agent_v1.wait_agent` for mailbox signals, not proof of completion — a timeout only means no new mailbox update arrived; a running child is alive. For sub-tasks likely to exceed one wait cycle, require `WORKING: <task> - <current phase>` before long passes and `BLOCKED: <reason>` only when progress stops. Send `TASK STILL ACTIVE: return <deliverable> or BLOCKED: <reason>` only when the child is completed without the deliverable, ack-only, or no longer running. If that followup is still silent or ack-only, record inconclusive, do not count it as pass/review approval, close if safe, and respawn a smaller `fork_context: false` task with the missing deliverable.
 9. After verification of ALL sub-tasks under this checkbox: `apply_patch` the plan to change `- [ ]` → `- [x]`, re-read the plan to confirm the count decreased, append a `task-completed` line to the ledger, then continue.
@@ -30,17 +30,17 @@ You are mid-flight on a Prometheus work plan; this turn is an automatic continua
 
 - No production code before a failing-first proof exists: a unit test at a seam, otherwise the sub-task's Manual-QA scenario captured failing. A test that mirrors its implementation (mock-call assertions, pinned constants) is not evidence. When the change touches existing behavior, PIN it first: a baseline characterization test that passes on the unchanged code, with exact inputs, exact observable, and exact assertion. PIN → RED → GREEN → SURFACE.
 - No `--dry-run` as evidence. No "should work". No "tests pass" as completion proof.
+- TUI visual evidence MUST use the web terminal pattern when a task drives an OpenCode/Codex/terminal UI: capture the pane or run `node script/qa/web-terminal-visual-qa.mjs --title "<surface>" --from-file <capture.txt> --evidence-dir <dir>` (or `--command` when tmux is available), then cite `terminal.png`, `terminal.txt`, and `metadata.json`.
 - No `as any` / `@ts-ignore` / `@ts-expect-error`. No deleting failing tests.
 - Probe every ultraqa adversarial class whose trigger fact holds (malformed input, prompt injection, cancel/resume, stale state, dirty worktree, hung or long commands, flaky tests, misleading success output, repeated interruptions — trigger map in the start-work skill) and capture the observable for each. A clean happy-path artifact alone is NOT a PASS when an applicable class went unprobed; record skipped classes with a one-line not-applicable reason.
-- Cleanup receipt is mandatory. Register each QA resource teardown (scripts, tmux sessions, browser contexts, PIDs, ports, containers, temp dirs) as its own todo the moment it spawns, then execute it. Leftover QA state = BLOCKED, not PASS.
+- Cleanup receipt is mandatory. Register each QA teardown (scripts, tmux, browser contexts, PIDs, ports, containers, temp dirs) as a todo when it spawns, then execute it. Leftover QA state = BLOCKED, not PASS.
 - The worktree path (if set in boulder.json) governs every file edit and command. Do not stray into the main repo.
+- PR or branch implementation/review/merge work requires a task-owned git worktree. Treat the main worktree as read-only context.
 - session_ids you write to boulder.json MUST be prefixed `codex:`. Bare ids on read are legacy `opencode:`.
 
-# Global Review and Debugging Gate
+# Final gate
 
-Before completion, run `review-work` and a `debugging` runtime audit. Treat timeout, missing deliverable, ack-only, `BLOCKED:`, and inconclusive review lanes as failures, not progress. Record at least three debugging hypotheses and the runtime evidence that confirms or refutes each one.
-
-Do not print `ORCHESTRATION COMPLETE`. Do not create a PR, PR handoff, or branch handoff. Do not write a final completion answer until this gate passes. Always redact secrets, tokens, credentials, auth headers, cookies, env dumps, private logs, and PII from ledgers, PR bodies, and handoffs.
+Before completion, run `review-work` and a `debugging` runtime audit; inconclusive lanes fail. Do not create a PR, PR handoff, branch handoff, merge, or final completion answer until this gate passes. For PR/branch work, stay in the task-owned worktree: create/update the PR, wait for CI/review/Cubic gates, merge by default unless explicitly opted out, then clean up. Redact secrets, tokens, credentials, auth headers, cookies, env dumps, logs, and PII.
 
 # Stop conditions for THIS turn
 

package/packages/omo-codex/plugin/components/start-work-continuation/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@code-yeongyu/codex-start-work-continuation",
-	"version": "4.12.1",
+	"version": "4.14.0",
 	"description": "Codex Stop hook continuation injector for omo-codex start-work plans.",
 	"type": "module",
 	"packageManager": "npm@11.12.1",

package/packages/omo-codex/plugin/components/start-work-continuation/test/codex-hook.test.ts

@@ -138,6 +138,29 @@ describe("start-work Stop hook", () => {
 		expect(parsed.reason.split(/\s+/).filter(Boolean).length).toBeLessThanOrEqual(1100);
 	});
 
+	it("#given active codex work #when continuation directive is emitted #then PR lifecycle stays worktree-bound", () => {
+		// given
+		const workspace = createWorkspace({
+			boulderJson: createBoulderJson({
+				sessionIds: ["codex:sess_abc"],
+				status: "active",
+				worktreePath: "/tmp/worktree",
+			}),
+			planMarkdown: ["# Plan", "", "## TODOs", "- [ ] First"].join("\n"),
+		});
+		const fs = createMemoryFs();
+
+		// when
+		const output = runStopHook(createStopInput(workspace), fs);
+
+		// then
+		const parsed = parseBlockOutput(output);
+		expect(parsed.reason).toContain("PR or branch implementation/review/merge work requires a task-owned git worktree");
+		expect(parsed.reason).toContain("Treat the main worktree as read-only context");
+		expect(parsed.reason).toContain("create/update the PR, wait for CI/review/Cubic gates, merge by default");
+		expect(parsed.reason).toContain("Do not create a PR, PR handoff, branch handoff, merge");
+	});
+
 	it("#given stop hook source #when inspected #then it remains Boulder-only without planning bootstrap logic", () => {
 		// given
 		const hook = readFileSync(new URL("../src/codex-hook.ts", import.meta.url), "utf8");

package/packages/omo-codex/plugin/components/teammode/dist/cli.js

@@ -41,25 +41,43 @@ async function runTeammodeHookCli(stdin, stdout) {
 }
 function threadTitleReminder(threadReference) {
   const id = formatIdentifier(threadReference.id);
-  return threadReference.kind === "thread" ? `THREAD ID ${id}: CALL codex_app.set_thread_title NOW. USE THE REAL TASK/ROLE.` : `PENDING WORKTREE ID ${id}: CALL codex_app.set_thread_title AS SOON AS THREAD ID EXISTS. USE THE REAL TASK/ROLE.`;
+  return threadReference.kind === "thread" ? `THREAD ID ${id}: CALL codex_app.set_thread_title NOW. USE THE REAL TASK/ROLE.` : `PENDING WORKTREE ID ${id}: WORKTREE THREAD IS NOT READY YET. DO NOT bind-thread OR SEND THE MEMBER BOOTSTRAP UNTIL A REAL THREAD ID EXISTS. THEN CALL codex_app.set_thread_title USING THE REAL TASK/ROLE.`;
 }
 function formatIdentifier(value) {
   const normalized = value.replace(/\s+/g, " ").trim();
   return normalized.length <= 200 ? normalized : `${normalized.slice(0, 197)}...`;
 }
 function extractThreadCreationReference(toolResponse) {
-  if (!isRecord(toolResponse))
+  const response = parseToolResponseRecord(toolResponse);
+  if (response === null)
     return null;
-  const threadId = toolResponse["threadId"];
+  const threadId = response["threadId"];
   if (typeof threadId === "string" && threadId.trim().length > 0) {
     return { kind: "thread", id: threadId };
   }
-  const pendingWorktreeId = toolResponse["pendingWorktreeId"];
+  const pendingWorktreeId = response["pendingWorktreeId"];
   if (typeof pendingWorktreeId === "string" && pendingWorktreeId.trim().length > 0) {
     return { kind: "pendingWorktree", id: pendingWorktreeId };
   }
   return null;
 }
+function parseToolResponseRecord(toolResponse) {
+  if (isRecord(toolResponse))
+    return toolResponse;
+  if (typeof toolResponse !== "string")
+    return null;
+  const trimmed = toolResponse.trim();
+  if (trimmed.length === 0)
+    return null;
+  try {
+    const parsed = JSON.parse(trimmed);
+    return isRecord(parsed) ? parsed : null;
+  } catch (error) {
+    if (error instanceof SyntaxError)
+      return null;
+    return null;
+  }
+}
 function isPostToolUsePayload(value) {
   if (!isRecord(value))
     return false;

package/packages/omo-codex/plugin/components/teammode/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@sisyphuslabs/codex-teammode",
-	"version": "4.12.1",
+	"version": "4.14.0",
 	"description": "Codex team-mode hook component that keeps background thread titles descriptive after create_thread.",
 	"type": "module",
 	"private": true,