oh-my-opencode 4.16.3 → 4.17.0

package/packages/omo-codex/plugin/components/ulw-loop/src/stop-resume-hook.ts

@@ -0,0 +1,208 @@
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { isAbsolute, join } from "node:path";
+
+import { normalizeUlwLoopSessionId, ulwLoopDir } from "./paths.js";
+import type { UlwLoopItem, UlwLoopPlan } from "./types.js";
+
+// Turn-death recovery only: Codex emits Stop when a turn ends, so a run that
+// dies mid-turn (crash, kill, context blowup before any Stop) never reaches
+// this handler. Mid-turn stalls are out of scope by design.
+
+const RESUME_CAP = 2;
+
+// Mirrors start-work-continuation's context-pressure bail-out: injecting a
+// resume directive into an already-overflowing context makes things worse.
+const CONTEXT_PRESSURE_MARKERS = [
+	"context compacted",
+	"context_length_exceeded",
+	"skill descriptions were shortened",
+	"context_too_large",
+	"codex ran out of room in the model's context window",
+	"your input exceeds the context window",
+	"long threads and multiple compactions",
+] as const;
+
+interface StopPayload {
+	readonly session_id: string;
+	readonly cwd: string;
+	readonly transcript_path: string;
+	readonly stop_hook_active: boolean;
+}
+
+export function runStopResumeHook(input: unknown): string {
+	const payload = parseStopPayload(input);
+	if (payload === null || payload.stop_hook_active) return "";
+	if (transcriptShowsContextPressure(payload.transcript_path)) return "";
+	if (boulderContinuationWillFire(payload.cwd, payload.session_id)) return "";
+	const stateDir = ulwLoopDir(payload.cwd, { sessionId: payload.session_id });
+	const plan = readPlan(join(stateDir, "goals.json"));
+	if (plan === null || plan.aggregateCompletion?.status === "complete") return "";
+	const goal = resumableGoal(plan);
+	if (goal === undefined) return "";
+	if (!consumeResumeBudget(stateDir, goal.id)) return "";
+	const output: { decision: "block"; reason: string } = {
+		decision: "block",
+		reason: renderResumeDirective(plan, goal, payload.session_id),
+	};
+	return JSON.stringify(output);
+}
+
+export async function runStopResumeHookCli(stdin: NodeJS.ReadableStream, stdout: NodeJS.WritableStream): Promise<void> {
+	try {
+		const chunks: Buffer[] = [];
+		for await (const chunk of stdin) chunks.push(Buffer.from(chunk));
+		const output = runStopResumeHook(JSON.parse(Buffer.concat(chunks).toString("utf8")));
+		if (output.length > 0) stdout.write(output);
+	} catch (error) {
+		if (error instanceof Error) return;
+	}
+}
+
+function resumableGoal(plan: UlwLoopPlan): UlwLoopItem | undefined {
+	const active = plan.goals.find((goal) => goal.id === plan.activeGoalId);
+	if (active !== undefined && isResumableStatus(active.status)) return active;
+	return plan.goals.find((goal) => isResumableStatus(goal.status));
+}
+
+function isResumableStatus(status: UlwLoopItem["status"]): boolean {
+	return status === "pending" || status === "in_progress";
+}
+
+// Two-strike cap keyed on ledger movement: an unchanged ledger.jsonl line
+// count across resumes means the loop is not progressing. The stuck marker is
+// a separate file — a ledger append would change the count and self-reset.
+function consumeResumeBudget(stateDir: string, goalId: string): boolean {
+	const ledgerLineCount = countLedgerLines(join(stateDir, "ledger.jsonl"));
+	const counterPath = join(stateDir, `auto-resume-${goalId}.json`);
+	const previous = readCounter(counterPath);
+	const count = previous !== null && previous.ledgerLineCount === ledgerLineCount ? previous.count : 0;
+	if (count >= RESUME_CAP) {
+		writeFileSync(join(stateDir, `auto-resume-${goalId}.stuck`), `no ledger progress after ${count} resumes\n`);
+		return false;
+	}
+	writeFileSync(counterPath, JSON.stringify({ count: count + 1, ledgerLineCount }));
+	return true;
+}
+
+function renderResumeDirective(plan: UlwLoopPlan, goal: UlwLoopItem, sessionId: string): string {
+	const normalized = normalizeUlwLoopSessionId(sessionId);
+	const option =
+		normalized !== null && plan.goalsPath.includes(`/${normalized}/`) ? ` --session-id ${normalized}` : "";
+	return [
+		`The ulw-loop run in this session still has unfinished goals (next: ${goal.id} — ${goal.title}).`,
+		"The turn ended before the loop completed. Resume it now:",
+		`1. Run \`omo ulw-loop status${option} --json\` to reload the plan, the active goal, and currentAttemptDir.`,
+		"2. Continue the active goal's remaining success criteria, recording evidence with record-evidence.",
+		`3. Checkpoint through \`omo ulw-loop checkpoint${option}\` when the goal's criteria are proven.`,
+		"If the loop is genuinely blocked on the user, checkpoint the goal as blocked with the reason instead.",
+	].join("\n");
+}
+
+function readPlan(goalsPath: string): UlwLoopPlan | null {
+	try {
+		return JSON.parse(readFileSync(goalsPath, "utf8")) as UlwLoopPlan;
+	} catch (error) {
+		if (error instanceof Error) return null;
+		throw error;
+	}
+}
+
+function countLedgerLines(ledgerPath: string): number {
+	try {
+		return readFileSync(ledgerPath, "utf8").split("\n").filter(Boolean).length;
+	} catch (error) {
+		if (error instanceof Error) return 0;
+		throw error;
+	}
+}
+
+function readCounter(counterPath: string): { count: number; ledgerLineCount: number } | null {
+	try {
+		if (!existsSync(counterPath)) return null;
+		const parsed = JSON.parse(readFileSync(counterPath, "utf8")) as Record<string, unknown>;
+		if (typeof parsed["count"] !== "number" || typeof parsed["ledgerLineCount"] !== "number") return null;
+		return { count: parsed["count"], ledgerLineCount: parsed["ledgerLineCount"] };
+	} catch (error) {
+		if (error instanceof Error) return null;
+		throw error;
+	}
+}
+
+// Local ~10-LOC approximation of start-work-continuation's boulder check (no
+// cross-component import allowed): any continuable work for this session means
+// that hook owns the Stop event, so this one stays silent.
+function boulderContinuationWillFire(cwd: string, sessionId: string): boolean {
+	try {
+		const raw = JSON.parse(readFileSync(join(cwd, ".omo", "boulder.json"), "utf8")) as Record<string, unknown>;
+		const works = raw["works"];
+		// The flat legacy shape has no works map: the top level is the single work.
+		const entries = typeof works === "object" && works !== null ? Object.values(works) : [raw];
+		return entries.some((work) => {
+			if (typeof work !== "object" || work === null) return false;
+			const entry = work as Record<string, unknown>;
+			const sessionIds = Array.isArray(entry["session_ids"]) ? entry["session_ids"] : [];
+			const continuable = entry["status"] === "active" || entry["status"] === "paused";
+			return continuable && sessionIds.includes(`codex:${sessionId}`) && boulderPlanHasRemainingTask(cwd, entry);
+		});
+	} catch (error) {
+		if (error instanceof Error) return false;
+		throw error;
+	}
+}
+
+function transcriptShowsContextPressure(transcriptPath: string): boolean {
+	try {
+		const transcript = readFileSync(transcriptPath, "utf8").toLowerCase();
+		return CONTEXT_PRESSURE_MARKERS.some((marker) => transcript.includes(marker));
+	} catch (error) {
+		if (error instanceof Error) return false;
+		throw error;
+	}
+}
+
+// start-work-continuation only fires while its plan checklist has remaining
+// items; a boulder work whose plan is exhausted (or unreadable) leaves the
+// Stop event to this hook.
+function boulderPlanHasRemainingTask(cwd: string, entry: Record<string, unknown>): boolean {
+	const activePlan = entry["active_plan"];
+	if (typeof activePlan !== "string" || activePlan.trim().length === 0) return false;
+	const planPath = isAbsolute(activePlan) ? activePlan : join(cwd, activePlan);
+	const worktree = entry["worktree_path"];
+	const candidates =
+		typeof worktree === "string" && worktree.trim().length > 0 && !isAbsolute(activePlan)
+			? [join(isAbsolute(worktree) ? worktree : join(cwd, worktree), activePlan), planPath]
+			: [planPath];
+	for (const candidate of candidates) {
+		try {
+			return readFileSync(candidate, "utf8")
+				.split(/\r?\n/)
+				.some((line) => line.startsWith("- [ ] "));
+		} catch (error) {
+			if (!(error instanceof Error)) throw error;
+		}
+	}
+	return false;
+}
+
+function parseStopPayload(value: unknown): StopPayload | null {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) return null;
+	const record = value as Record<string, unknown>;
+	const optionalMessage = record["last_assistant_message"];
+	const valid =
+		record["hook_event_name"] === "Stop" &&
+		typeof record["session_id"] === "string" &&
+		typeof record["turn_id"] === "string" &&
+		typeof record["transcript_path"] === "string" &&
+		typeof record["cwd"] === "string" &&
+		typeof record["model"] === "string" &&
+		typeof record["permission_mode"] === "string" &&
+		typeof record["stop_hook_active"] === "boolean" &&
+		(optionalMessage === undefined || typeof optionalMessage === "string");
+	if (!valid) return null;
+	return {
+		session_id: record["session_id"] as string,
+		cwd: record["cwd"] as string,
+		transcript_path: record["transcript_path"] as string,
+		stop_hook_active: record["stop_hook_active"] as boolean,
+	};
+}

package/packages/omo-codex/plugin/components/ulw-loop/test/cli-create-goals.test.ts

@@ -103,6 +103,8 @@ describe("ulwLoopCommand create-goals", () => {
 
 	it("#given completed default aggregate #when creating another default plan #then guides to a fresh session", async () => {
 		await createPlan("- Finished");
+		expect(await ulwLoopCommand(["complete-goals"])).toBe(0);
+		resetOutput();
 		for (const criterionId of ["C001", "C002", "C003"]) await passCriterion("G001-finished", criterionId);
 		expect(
 			await ulwLoopCommand([
@@ -128,6 +130,16 @@ describe("ulwLoopCommand create-goals", () => {
 		expect(err.join("")).toContain("--force only");
 	});
 
+	it("#given an active goal on a v2 plan #when reading status --json #then exposes the current attempt dir", async () => {
+		await createPlan();
+		expect(await ulwLoopCommand(["complete-goals"])).toBe(0);
+		resetOutput();
+
+		expect(await ulwLoopCommand(["status", "--json"])).toBe(0);
+
+		expect(stdoutJson()).toMatchObject({ currentAttemptDir: ".omo/evidence/ulw/session/G001-goal-a/a1" });
+	});
+
 	it("#given two session ids #when creating goals #then writes isolated session-scoped plans", async () => {
 		expect(await ulwLoopCommand(["create-goals", "--session-id", "session-A", "--brief", "- Alpha", "--json"])).toBe(
 			0,

package/packages/omo-codex/plugin/components/ulw-loop/test/cli-entrypoint.test.ts

@@ -57,7 +57,10 @@ async function runCli(args: readonly string[], input = ""): Promise<CliResult> {
 }
 
 beforeAll(async () => {
-	const build = await runProcess("npm", ["run", "build"], componentRoot);
+	const build =
+		process.platform === "win32"
+			? await runProcess("cmd.exe", ["/c", "npm", "run", "build"], componentRoot)
+			: await runProcess("npm", ["run", "build"], componentRoot);
 	expect(build.code, `npm run build failed:\n${build.stderr}`).toBe(0);
 }, 120_000);
 

package/packages/omo-codex/plugin/components/ulw-loop/test/codex-goal-instruction.test.ts

@@ -58,53 +58,28 @@ describe("buildCodexGoalInstruction aggregate mode", () => {
 		expect(text).toContain(".omo/ulw-loop/goals.json");
 	});
 
-	it("given aggregate mode when rendering create_goal payload then omits numeric limits", () => {
-		const { json, text } = buildCodexGoalInstruction({
+	it("given aggregate mode when rendering create_goal payload then payload is the aggregate objective only", () => {
+		const { json } = buildCodexGoalInstruction({
 			plan: makePlan({ codexGoalMode: "aggregate" }),
 			goal: makeGoal(),
 		});
 		expect(json).toEqual({
 			objective: ULW_LOOP_AGGREGATE_CODEX_OBJECTIVE,
 		});
-		expect(text).toContain("objective only");
-		expect(text).not.toContain('"status"');
-		expect(text).toContain("Goals are unlimited");
-		expect(text).not.toMatch(/token[_-]?budget/i);
 	});
 
-	it("instructs not to call update_goal mid-aggregate when not final", () => {
-		const { text } = buildCodexGoalInstruction({
-			plan: makePlan({ codexGoalMode: "aggregate" }),
-			goal: makeGoal(),
-			isFinal: false,
-		});
-		expect(text).toContain("do not call update_goal mid-aggregate");
-		expect(text).toContain("checkpoint this OMO ledger story");
-		expect(text).toContain("update_goal is reserved for the final story after the mandatory quality gate passes");
-	});
-
-	it("#given a non-final aggregate story #when rendering instructions #then defers the current final quality gate", () => {
+	it("#given a non-final aggregate story #when rendering instructions #then omits the final quality gate tokens", () => {
 		const { text } = buildCodexGoalInstruction({
 			plan: makePlan({ codexGoalMode: "aggregate" }),
 			goal: makeGoal(),
 			isFinal: false,
 		});
 
-		expect(text).toMatch(/not the final .*do not run .*quality gate/i);
-		expect(text).toContain("checkpoint this OMO ledger story");
-		expect(text).toContain("continue the remaining stories");
-	});
-
-	it("includes quality gate instruction when isFinal", () => {
-		const { text } = buildCodexGoalInstruction({
-			plan: makePlan({ codexGoalMode: "aggregate" }),
-			goal: makeGoal(),
-			isFinal: true,
-		});
-		expect(text).toMatch(/quality gate/i);
+		for (const role of FINAL_REVIEW_ROLES) expect(text).not.toContain(role);
+		expect(text).not.toContain("record-review-blockers");
 	});
 
-	it("#given a final aggregate story #when rendering instructions #then requires the current LazyCodex quality gate", () => {
+	it("#given a final aggregate story #when rendering instructions #then includes the quality gate roles, fields, and commands", () => {
 		const { text } = buildCodexGoalInstruction({
 			plan: makePlan({ codexGoalMode: "aggregate" }),
 			goal: makeGoal(),
@@ -113,10 +88,8 @@ describe("buildCodexGoalInstruction aggregate mode", () => {
 
 		expectTextToContainAll(text, FINAL_REVIEW_ROLES);
 		expectTextToContainAll(text, QUALITY_GATE_SECTIONS);
-		expect(text).toMatch(/targeted verification/i);
-		expect(text).toMatch(/artifact path.*non-zero size/i);
-		expectTextToContainAll(text, ["original brief", "desired user-visible outcome", "userOutcomeReview"]);
-		expect(text).toMatch(/not clean.*do not call update_goal/i);
+		expectTextToContainAll(text, ["originalIntent", "desiredOutcome", "userOutcomeReview"]);
+		expect(text).toContain("update_goal");
 		expect(text).toContain("record-review-blockers");
 		expect(text).toContain("checkpoint");
 	});

package/packages/omo-codex/plugin/components/ulw-loop/test/fixtures/quality-gate-builder.ts

@@ -1,29 +1,40 @@
 import { mkdir, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 
-export const QA_DIR = ".omo/ulw-loop/qa";
+// v2 evidence layout: artifacts must live inside the goal's current attempt dir
+export function qaDirFor(goalId: string, attempt = 1, sessionId = "session"): string {
+	return `.omo/evidence/ulw/${sessionId}/${goalId}/a${attempt}`;
+}
+
+export const QA_DIR = qaDirFor("G001-finished");
 export const CODE_REVIEW_PATH = `${QA_DIR}/code-review.md`;
 export const GATE_REVIEW_PATH = `${QA_DIR}/gate-review.md`;
 export const CLI_PASS_PATH = `${QA_DIR}/cli-pass.txt`;
 export const REJECTION_LOG_PATH = `${QA_DIR}/rejection.txt`;
 export const MISSING_ARTIFACT_PATH = `${QA_DIR}/missing.txt`;
 
-export async function writeQualityGateArtifacts(repoRoot: string): Promise<void> {
-	await mkdir(join(repoRoot, QA_DIR), { recursive: true });
-	await writeFile(join(repoRoot, CODE_REVIEW_PATH), "code review approved\n", "utf8");
-	await writeFile(join(repoRoot, GATE_REVIEW_PATH), "gate review approved\n", "utf8");
-	await writeFile(join(repoRoot, CLI_PASS_PATH), "cli scenario passed\n", "utf8");
-	await writeFile(join(repoRoot, REJECTION_LOG_PATH), "invalid gate rejected\n", "utf8");
+export async function writeQualityGateArtifacts(repoRoot: string, qaDir = QA_DIR): Promise<void> {
+	await mkdir(join(repoRoot, qaDir), { recursive: true });
+	await writeFile(join(repoRoot, `${qaDir}/code-review.md`), "code review approved\n", "utf8");
+	await writeFile(join(repoRoot, `${qaDir}/gate-review.md`), "gate review approved\n", "utf8");
+	await writeFile(join(repoRoot, `${qaDir}/cli-pass.txt`), "cli scenario passed\n", "utf8");
+	await writeFile(join(repoRoot, `${qaDir}/rejection.txt`), "invalid gate rejected\n", "utf8");
 }
 
-export async function qualityGateJson(repoRoot: string, cliArtifactPath = CLI_PASS_PATH): Promise<string> {
-	await writeQualityGateArtifacts(repoRoot);
+export async function qualityGateJson(
+	repoRoot: string,
+	cliArtifactPath?: string,
+	goalId = "G001-finished",
+): Promise<string> {
+	const qaDir = qaDirFor(goalId);
+	await writeQualityGateArtifacts(repoRoot, qaDir);
+	const cliPath = cliArtifactPath ?? `${qaDir}/cli-pass.txt`;
 	return JSON.stringify({
 		codeReview: {
 			by: "lazycodex-code-reviewer",
 			recommendation: "APPROVE",
 			codeQualityStatus: "CLEAR",
-			reportPath: CODE_REVIEW_PATH,
+			reportPath: `${qaDir}/code-review.md`,
 			evidence: "Reviewed implementation and tests; no blockers remain.",
 			blockers: [],
 		},
@@ -56,20 +67,20 @@ export async function qualityGateJson(repoRoot: string, cliArtifactPath = CLI_PA
 					id: "artifact-cli-pass",
 					kind: "cli-transcript",
 					description: "CLI transcript for valid final checkpoint.",
-					path: cliArtifactPath,
+					path: cliPath,
 				},
 				{
 					id: "artifact-cli-reject",
 					kind: "log",
 					description: "Log proving invalid final checkpoint rejection.",
-					path: REJECTION_LOG_PATH,
+					path: `${qaDir}/rejection.txt`,
 				},
 			],
 		},
 		gateReview: {
 			by: "lazycodex-gate-reviewer",
 			recommendation: "APPROVE",
-			reportPath: GATE_REVIEW_PATH,
+			reportPath: `${qaDir}/gate-review.md`,
 			evidence: "Verified all criteria and artifact evidence.",
 			blockers: [],
 		},

package/packages/omo-codex/plugin/components/ulw-loop/test/package-smoke.test.ts

@@ -141,7 +141,9 @@ describe("skills/ulw-loop/SKILL.md", () => {
 		expect(text).toContain('- "ulw-loop"');
 	});
 
-	it("#given PATH omo lacks ulw-loop #when bootstrap runs #then falls back to cached ulw-loop CLI", async () => {
+	it.skipIf(process.platform === "win32")(
+		"#given PATH omo lacks ulw-loop #when bootstrap runs #then falls back to cached ulw-loop CLI",
+		async () => {
 		const text = await readText("skills/ulw-loop/references/full-workflow.md");
 		const bootstrap = bootstrapScriptFrom(text);
 		const root = await mkdtemp(join(tmpdir(), "omo-ulw-loop-bootstrap-"));
@@ -191,7 +193,8 @@ describe("source LOC budget", () => {
 	it("every source file stays at or under 250 pure LOC", async () => {
 		const files = [
 			"src/types.ts", "src/paths.ts", "src/plan-io.ts", "src/plan-crud.ts", "src/goal-status.ts",
-			"src/evidence.ts", "src/quality-gate.ts", "src/checkpoint.ts", "src/review-blockers.ts",
+			"src/evidence.ts", "src/quality-gate.ts", "src/quality-gate-verdicts.ts", "src/checkpoint.ts", "src/review-blockers.ts",
+			"src/stop-resume-hook.ts", "src/spawn-guard.ts",
 			"src/steering.ts", "src/codex-goal-instruction.ts", "src/codex-goal-snapshot.ts", "src/codex-hook.ts",
 			"src/cli.ts", "src/cli-arg-parser.ts", "src/cli-output.ts", "src/cli-steering.ts", "src/cli-commands.ts",
 		];

package/packages/omo-codex/plugin/components/ulw-loop/test/paths.test.ts

@@ -1,6 +1,9 @@
+import { join, posix, win32 } from "node:path";
+
 import { describe, expect, it } from "vitest";
 
 import {
+	isWithinAttemptDir,
 	normalizeUlwLoopSessionId,
 	repoRelative,
 	ulwLoopBriefPath,
@@ -12,28 +15,28 @@ import {
 describe("ulwLoopDir(repo)", () => {
 	it("returns repo + '/.omo/ulw-loop'", () => {
 		// when/then
-		expect(ulwLoopDir("/repo")).toBe("/repo/.omo/ulw-loop");
+		expect(ulwLoopDir("/repo")).toBe(join("/repo", ".omo", "ulw-loop"));
 	});
 
 	it("#given a session id #when resolving the loop dir #then scopes artifacts under that session", () => {
 		// when/then
-		expect(ulwLoopDir("/repo", { sessionId: "sess_abc" })).toBe("/repo/.omo/ulw-loop/sess_abc");
+		expect(ulwLoopDir("/repo", { sessionId: "sess_abc" })).toBe(join("/repo", ".omo", "ulw-loop", "sess_abc"));
 	});
 });
 
 describe("ulw-loop*Path helpers", () => {
 	it("compose artifact filenames under ulwLoopDir", () => {
 		// when/then
-		expect(ulwLoopBriefPath("/r")).toBe("/r/.omo/ulw-loop/brief.md");
-		expect(ulwLoopGoalsPath("/r")).toBe("/r/.omo/ulw-loop/goals.json");
-		expect(ulwLoopLedgerPath("/r")).toBe("/r/.omo/ulw-loop/ledger.jsonl");
+		expect(ulwLoopBriefPath("/r")).toBe(join("/r", ".omo", "ulw-loop", "brief.md"));
+		expect(ulwLoopGoalsPath("/r")).toBe(join("/r", ".omo", "ulw-loop", "goals.json"));
+		expect(ulwLoopLedgerPath("/r")).toBe(join("/r", ".omo", "ulw-loop", "ledger.jsonl"));
 	});
 
 	it("#given a session id #when composing artifact filenames #then returns session-scoped paths", () => {
 		// when/then
-		expect(ulwLoopBriefPath("/r", { sessionId: "session-A" })).toBe("/r/.omo/ulw-loop/session-A/brief.md");
-		expect(ulwLoopGoalsPath("/r", { sessionId: "session-A" })).toBe("/r/.omo/ulw-loop/session-A/goals.json");
-		expect(ulwLoopLedgerPath("/r", { sessionId: "session-A" })).toBe("/r/.omo/ulw-loop/session-A/ledger.jsonl");
+		expect(ulwLoopBriefPath("/r", { sessionId: "session-A" })).toBe(join("/r", ".omo", "ulw-loop", "session-A", "brief.md"));
+		expect(ulwLoopGoalsPath("/r", { sessionId: "session-A" })).toBe(join("/r", ".omo", "ulw-loop", "session-A", "goals.json"));
+		expect(ulwLoopLedgerPath("/r", { sessionId: "session-A" })).toBe(join("/r", ".omo", "ulw-loop", "session-A", "ledger.jsonl"));
 	});
 });
 
@@ -60,3 +63,35 @@ describe("repoRelative", () => {
 		expect(repoRelative("/elsewhere/file", "/repo")).toBe("/elsewhere/file");
 	});
 });
+
+describe("isWithinAttemptDir", () => {
+	const posixRoot = "/repo/.omo/evidence/ulw/s1/g1/a1";
+	const win32Root = "C:\\repo\\.omo\\evidence\\ulw\\s1\\g1\\a1";
+
+	it("#given a child artifact #when checked on posix #then it is contained", () => {
+		expect(isWithinAttemptDir(`${posixRoot}/cli-pass.txt`, posixRoot, posix)).toBe(true);
+	});
+
+	it("#given a child artifact #when checked with win32 separators #then it is contained", () => {
+		expect(isWithinAttemptDir(`${win32Root}\\cli-pass.txt`, win32Root, win32)).toBe(true);
+	});
+
+	it("#given the attempt root itself #when checked #then it is contained", () => {
+		expect(isWithinAttemptDir(posixRoot, posixRoot, posix)).toBe(true);
+		expect(isWithinAttemptDir(win32Root, win32Root, win32)).toBe(true);
+	});
+
+	it("#given a sibling dir sharing the prefix #when checked #then it is outside", () => {
+		expect(isWithinAttemptDir("/repo/.omo/evidence/ulw/s1/g1/a1x/f.txt", posixRoot, posix)).toBe(false);
+		expect(isWithinAttemptDir(`${win32Root}x\\f.txt`, win32Root, win32)).toBe(false);
+	});
+
+	it("#given a prior-attempt artifact #when checked #then it is outside", () => {
+		expect(isWithinAttemptDir("/repo/.omo/evidence/ulw/s1/g1/a0/f.txt", posixRoot, posix)).toBe(false);
+		expect(isWithinAttemptDir("C:\\repo\\.omo\\evidence\\ulw\\s1\\g1\\a0\\f.txt", win32Root, win32)).toBe(false);
+	});
+
+	it("#given a different-drive path #when checked on win32 #then it is outside", () => {
+		expect(isWithinAttemptDir("D:\\elsewhere\\f.txt", win32Root, win32)).toBe(false);
+	});
+});

package/packages/omo-codex/plugin/components/ulw-loop/test/quality-gate.test.ts

@@ -224,8 +224,8 @@ describe("validateQualityGate", () => {
 			}),
 		);
 
-		// then
-		expect(error.message).toContain("not_applicable");
+		// then — a reasonless not_applicable now fails on the missing reason field
+		expect(error.message).toContain("reason");
 	});
 
 	it("#given criteria coverage misses required criteria #when validated #then it is rejected", () => {
@@ -250,3 +250,56 @@ describe("validateQualityGate", () => {
 		expect(error.message).toContain("criteriaCoverage.userOutcomeReview");
 	});
 });
+
+describe("quality gate middle states (WATCH / reasoned not_applicable)", () => {
+	it("#given codeQualityStatus WATCH with APPROVE #when validating #then the gate accepts", () => {
+		const gate = structuredClone(VALID_GATE);
+		(gate.codeReview as { codeQualityStatus: string }).codeQualityStatus = "WATCH";
+		expect(() => validateQualityGate(gate)).not.toThrow();
+	});
+
+	it("#given codeQualityStatus BLOCK #when validating #then the gate rejects", () => {
+		const gate = structuredClone(VALID_GATE);
+		(gate.codeReview as { codeQualityStatus: string }).codeQualityStatus = "BLOCK";
+		expect(() => validateQualityGate(gate)).toThrow(/codeQualityStatus/);
+	});
+
+	it("#given a reasoned not_applicable adversarial case #when validating #then the gate accepts", () => {
+		const gate = structuredClone(VALID_GATE);
+		(gate.manualQa.adversarialCases[0] as { verdict: string; reason?: string }).verdict = "not_applicable";
+		(gate.manualQa.adversarialCases[0] as { verdict: string; reason?: string }).reason = "doc-only change";
+		expect(() => validateQualityGate(gate)).not.toThrow();
+	});
+
+	it("#given a reasonless not_applicable adversarial case #when validating #then the gate rejects", () => {
+		const gate = structuredClone(VALID_GATE);
+		(gate.manualQa.adversarialCases[0] as { verdict: string }).verdict = "not_applicable";
+		expect(() => validateQualityGate(gate)).toThrow(/reason/);
+	});
+
+	it("#given a not_applicable surface evidence verdict #when validating #then the gate still rejects", () => {
+		const gate = structuredClone(VALID_GATE);
+		(gate.manualQa.surfaceEvidence[0] as { verdict: string }).verdict = "not_applicable";
+		expect(() => validateQualityGate(gate)).toThrow(/not_applicable/);
+	});
+});
+
+describe("validateQualityGate attempt containment", () => {
+	const ATTEMPT_OPTS = { ...FS_OPTS, currentAttemptDir: "test/fixtures/artifacts" } as const;
+
+	it("#given artifacts inside the current attempt dir #when validating #then the gate accepts", () => {
+		expect(() => validateQualityGate(makeGate(), ATTEMPT_OPTS)).not.toThrow();
+	});
+
+	it("#given an artifact outside the current attempt dir #when validating #then the gate rejects naming the path", () => {
+		const opts = { ...FS_OPTS, currentAttemptDir: "test/fixtures/elsewhere" } as const;
+		expect(() => validateQualityGate(makeGate(), opts)).toThrow(
+			/\(test\/fixtures\/artifacts\/cli-pass\.txt\) must point to an artifact from the current attempt \(test\/fixtures\/elsewhere\)/,
+		);
+	});
+
+	it("#given a sibling dir sharing the attempt dir prefix #when validating #then the gate still rejects", () => {
+		const opts = { ...FS_OPTS, currentAttemptDir: "test/fixtures/artifact" } as const;
+		expect(() => validateQualityGate(makeGate(), opts)).toThrow(/current attempt/);
+	});
+});