oh-my-opencode 5.0.0-beta.56 → 5.0.0-beta.60

package/packages/omo-codex/plugin/components/ulw-loop/src/sdk/factory.ts

@@ -0,0 +1,159 @@
+import { checkpointUlwLoop } from "../checkpoint.js";
+import { checkpointTemplate } from "../checkpoint-template.js";
+import { recordEvidence } from "../evidence.js";
+import { type UlwLoopScope, ulwLoopAttemptEvidenceDir } from "../paths.js";
+import { addUlwLoopGoal, createUlwLoopPlan, startNextUlwLoop, summarizeUlwLoopPlan } from "../plan-crud.js";
+import { readUlwLoopPlan } from "../plan-io.js";
+import { recordFinalReviewBlockers } from "../review-blockers.js";
+import { UlwLoopError } from "../runtime.js";
+import { statusNextActions } from "../status-next-actions.js";
+import { steerUlwLoop } from "../steering.js";
+import type { UlwLoopOperation } from "./manifest.js";
+import { ULW_LOOP_MANIFEST } from "./manifest.js";
+import type {
+	AgentToolkit,
+	AgentToolkitDependencies,
+	CheckpointArgs,
+	ToolkitContext,
+	ToolkitDispatchRequest,
+	ToolkitDispatchResponse,
+	ToolkitError,
+	ToolkitFailure,
+	ToolkitResponseFor,
+	ToolkitResultFor,
+	ToolkitUnknownRequest,
+} from "./types.js";
+
+function validateContext(context: ToolkitContext): void {
+	if (!context.cwd.trim()) throw new UlwLoopError("cwd is required.", "ULW_LOOP_CWD_REQUIRED");
+	if (!context.sessionId.trim())
+		throw new UlwLoopError("ULW_LOOP_SESSION_ID_REQUIRED: sessionId is required.", "ULW_LOOP_SESSION_ID_REQUIRED");
+	if (context.surface !== "omo-senpi" && context.surface !== "lazycodex")
+		throw new UlwLoopError("surface must be omo-senpi or lazycodex.", "ULW_LOOP_SURFACE_INVALID");
+}
+
+function errorDetails(error: UlwLoopError): ToolkitError {
+	const details =
+		error.details === undefined
+			? undefined
+			: Object.fromEntries(Object.entries(error.details).map(([key, value]) => [key, String(value)]));
+	return details === undefined
+		? { code: error.code, message: error.message }
+		: { code: error.code, message: error.message, details };
+}
+
+function failure<Operation extends string>(operation: Operation, error: UlwLoopError): ToolkitFailure<Operation> {
+	return { ok: false, operation, error: errorDetails(error) };
+}
+
+function caught<Operation extends string>(operation: Operation, error: Error): ToolkitFailure<Operation> {
+	return failure(operation, error instanceof UlwLoopError ? error : new UlwLoopError(error.message, "ULW_LOOP_ERROR"));
+}
+
+function isKnownRequest(request: ToolkitDispatchRequest | ToolkitUnknownRequest): request is ToolkitDispatchRequest {
+	return ULW_LOOP_MANIFEST.operations.some((operation) => operation.name === request.operation);
+}
+
+function unreachable(value: never): never {
+	throw new UlwLoopError(`Unhandled operation: ${String(value)}`, "ULW_LOOP_OPERATION_UNHANDLED");
+}
+
+function nextActionsFrom(result: object): readonly string[] {
+	if (!("nextActions" in result) || !Array.isArray(result.nextActions)) return [];
+	return result.nextActions.filter((action): action is string => typeof action === "string").slice(0, 8);
+}
+
+export function createAgentToolkit(context: ToolkitContext, deps: AgentToolkitDependencies = {}): AgentToolkit {
+	validateContext(context);
+	const scope: UlwLoopScope = { sessionId: context.sessionId };
+	const notify = async <Operation extends UlwLoopOperation>(
+		operation: Operation,
+		response: ToolkitResponseFor<Operation>,
+	): Promise<ToolkitResponseFor<Operation>> => {
+		if (deps.hooks?.onOperation !== undefined) await deps.hooks.onOperation({ operation, context, response });
+		return response;
+	};
+	const invoke = async <Operation extends UlwLoopOperation>(
+		operation: Operation,
+		fn: () => Promise<ToolkitResultFor<Operation>>,
+	): Promise<ToolkitResponseFor<Operation>> => {
+		try {
+			const result = await fn();
+			const nextActions = typeof result === "object" && result !== null ? nextActionsFrom(result) : [];
+			return await notify(operation, { ok: true, operation, result, nextActions });
+		} catch (error) {
+			const response = caught(operation, error instanceof Error ? error : new Error("ULW_LOOP_ERROR"));
+			return notify(operation, response);
+		}
+	};
+	const toolkit: AgentToolkit = {
+		dispatch: async (request): Promise<ToolkitDispatchResponse> => {
+			if (!isKnownRequest(request))
+				return failure(
+					request.operation,
+					new UlwLoopError(`Unknown operation: ${request.operation}`, "ULW_LOOP_OPERATION_UNKNOWN"),
+				);
+			switch (request.operation) {
+				case "help":
+					return toolkit.help();
+				case "create-goals":
+					return toolkit.createGoals(request.args);
+				case "status":
+					return toolkit.status();
+				case "complete-goals":
+					return toolkit.completeGoals(request.args);
+				case "checkpoint":
+					return toolkit.checkpoint(request.args);
+				case "steer":
+					return toolkit.steer(request.args);
+				case "add-goal":
+					return toolkit.addGoal(request.args);
+				case "criteria":
+					return toolkit.criteria(request.args);
+				case "record-evidence":
+					return toolkit.recordEvidence(request.args);
+				case "record-review-blockers":
+					return toolkit.recordReviewBlockers(request.args);
+				default:
+					return unreachable(request);
+			}
+		},
+		help: () => invoke("help", async () => ULW_LOOP_MANIFEST),
+		createGoals: (args) => invoke("create-goals", () => createUlwLoopPlan(context.cwd, args, scope)),
+		status: () =>
+			invoke("status", async () => {
+				const plan = await readUlwLoopPlan(context.cwd, scope);
+				const active = plan.goals.find((goal) => goal.id === plan.activeGoalId);
+				return {
+					plan,
+					summary: summarizeUlwLoopPlan(plan),
+					nextActions: statusNextActions(plan),
+					// Attempt directories are an evidence-layout v2 concept; a v1 plan must not advertise one.
+					...(active === undefined || plan.evidenceLayoutVersion !== 2
+						? {}
+						: { currentAttemptDir: ulwLoopAttemptEvidenceDir(active.id, active.attempt, scope) }),
+				};
+			}),
+		completeGoals: (args = {}) => invoke("complete-goals", () => startNextUlwLoop(context.cwd, args, scope)),
+		checkpoint: (args: CheckpointArgs) =>
+			invoke("checkpoint", () =>
+				args.printTemplate === true
+					? checkpointTemplate(context.cwd, scope, args.goalId, { surface: context.surface })
+					: checkpointUlwLoop(context.cwd, args, scope, { surface: context.surface }),
+			),
+		steer: (args) => invoke("steer", () => steerUlwLoop(context.cwd, args, scope)),
+		addGoal: (args) => invoke("add-goal", () => addUlwLoopGoal(context.cwd, args, scope)),
+		criteria: (args) =>
+			invoke("criteria", async () => {
+				const plan = await readUlwLoopPlan(context.cwd, scope);
+				const goal = plan.goals.find((candidate) => candidate.id === args.goalId);
+				if (goal === undefined)
+					throw new UlwLoopError(`Unknown ulw-loop id: ${args.goalId}.`, "ULW_LOOP_GOAL_NOT_FOUND");
+				return { goalId: goal.id, criteria: goal.successCriteria };
+			}),
+		recordEvidence: (args) => invoke("record-evidence", () => recordEvidence(context.cwd, args, scope)),
+		recordReviewBlockers: (args) =>
+			invoke("record-review-blockers", () => recordFinalReviewBlockers(context.cwd, args, scope)),
+	};
+	return toolkit;
+}

package/packages/omo-codex/plugin/components/ulw-loop/src/sdk/manifest.ts

@@ -0,0 +1,42 @@
+export const ULW_LOOP_OPERATIONS = [
+	"help",
+	"create-goals",
+	"status",
+	"complete-goals",
+	"checkpoint",
+	"steer",
+	"add-goal",
+	"criteria",
+	"record-evidence",
+	"record-review-blockers",
+] as const;
+
+export type UlwLoopOperation = (typeof ULW_LOOP_OPERATIONS)[number];
+
+export interface ToolkitOperationManifest {
+	readonly name: UlwLoopOperation;
+	readonly mutating: boolean;
+}
+
+export interface ToolkitManifest {
+	readonly version: 1;
+	readonly name: "ulw-loop";
+	readonly operations: readonly ToolkitOperationManifest[];
+}
+
+export const ULW_LOOP_MANIFEST = {
+	version: 1,
+	name: "ulw-loop",
+	operations: [
+		{ name: "help", mutating: false },
+		{ name: "create-goals", mutating: true },
+		{ name: "status", mutating: false },
+		{ name: "complete-goals", mutating: true },
+		{ name: "checkpoint", mutating: true },
+		{ name: "steer", mutating: true },
+		{ name: "add-goal", mutating: true },
+		{ name: "criteria", mutating: false },
+		{ name: "record-evidence", mutating: true },
+		{ name: "record-review-blockers", mutating: true },
+	] satisfies readonly ToolkitOperationManifest[],
+} satisfies ToolkitManifest;

package/packages/omo-codex/plugin/components/ulw-loop/src/sdk/types.ts

@@ -0,0 +1,140 @@
+import type { CheckpointUlwLoopArgs, CheckpointUlwLoopResult } from "../checkpoint.js";
+import type { CheckpointTemplate } from "../checkpoint-template.js";
+import type { recordEvidence } from "../evidence.js";
+import type { addUlwLoopGoal, createUlwLoopPlan, startNextUlwLoop, summarizeUlwLoopPlan } from "../plan-crud.js";
+import type { recordFinalReviewBlockers } from "../review-blockers.js";
+import type { steerUlwLoop } from "../steering.js";
+import type { UlwLoopSteeringProposal } from "../steering-types.js";
+import type { UlwLoopToolkitSurface } from "../surface.js";
+import type { UlwLoopPlan } from "../types.js";
+import type { ULW_LOOP_MANIFEST, UlwLoopOperation } from "./manifest.js";
+
+export type ToolkitSurface = UlwLoopToolkitSurface;
+
+export interface ToolkitContext {
+	readonly cwd: string;
+	readonly sessionId: string;
+	readonly surface: ToolkitSurface;
+}
+
+export type CreateGoalsArgs = Parameters<typeof createUlwLoopPlan>[1];
+export type CompleteGoalsArgs = NonNullable<Parameters<typeof startNextUlwLoop>[1]>;
+export type SteerArgs = UlwLoopSteeringProposal;
+export type AddGoalArgs = Parameters<typeof addUlwLoopGoal>[1];
+export type RecordEvidenceArgs = Parameters<typeof recordEvidence>[1];
+export type CriteriaArgs = { readonly goalId: string };
+export type CheckpointMutationArgs = CheckpointUlwLoopArgs & { readonly printTemplate?: false };
+export type CheckpointTemplateArgs = { readonly printTemplate: true; readonly goalId?: string };
+export type CheckpointArgs = CheckpointMutationArgs | CheckpointTemplateArgs;
+export type RecordReviewBlockersArgs = Parameters<typeof recordFinalReviewBlockers>[1];
+
+export type ToolkitDispatchRequest =
+	| { readonly operation: "help"; readonly args?: Record<never, never> }
+	| { readonly operation: "create-goals"; readonly args: CreateGoalsArgs }
+	| { readonly operation: "status"; readonly args?: Record<never, never> }
+	| { readonly operation: "complete-goals"; readonly args?: CompleteGoalsArgs }
+	| { readonly operation: "checkpoint"; readonly args: CheckpointArgs }
+	| { readonly operation: "steer"; readonly args: SteerArgs }
+	| { readonly operation: "add-goal"; readonly args: AddGoalArgs }
+	| { readonly operation: "criteria"; readonly args: CriteriaArgs }
+	| { readonly operation: "record-evidence"; readonly args: RecordEvidenceArgs }
+	| { readonly operation: "record-review-blockers"; readonly args: RecordReviewBlockersArgs };
+
+export interface ToolkitUnknownRequest {
+	readonly operation: string;
+	readonly args?: Record<never, never>;
+}
+
+export interface ToolkitError {
+	readonly code: string;
+	readonly message: string;
+	readonly details?: Readonly<Record<string, string>>;
+}
+
+export interface ToolkitSuccess<Operation extends UlwLoopOperation, Result> {
+	readonly ok: true;
+	readonly operation: Operation;
+	readonly result: Result;
+	readonly nextActions: readonly string[];
+	readonly warnings?: readonly string[];
+}
+
+export interface ToolkitFailure<Operation extends string = string> {
+	readonly ok: false;
+	readonly operation: Operation;
+	readonly error: ToolkitError;
+}
+
+type StatusResult = {
+	readonly plan: UlwLoopPlan;
+	readonly summary: ReturnType<typeof summarizeUlwLoopPlan>;
+	readonly nextActions: readonly string[];
+	readonly currentAttemptDir?: string;
+};
+
+type ResultFor<Operation extends UlwLoopOperation> = Operation extends "help"
+	? typeof ULW_LOOP_MANIFEST
+	: Operation extends "create-goals"
+		? Awaited<ReturnType<typeof createUlwLoopPlan>>
+		: Operation extends "status"
+			? StatusResult
+			: Operation extends "complete-goals"
+				? Awaited<ReturnType<typeof startNextUlwLoop>>
+				: Operation extends "checkpoint"
+					? CheckpointUlwLoopResult | CheckpointTemplate
+					: Operation extends "steer"
+						? Awaited<ReturnType<typeof steerUlwLoop>>
+						: Operation extends "add-goal"
+							? Awaited<ReturnType<typeof addUlwLoopGoal>>
+							: Operation extends "criteria"
+								? {
+										readonly goalId: string;
+										readonly criteria: UlwLoopPlan["goals"][number]["successCriteria"];
+									}
+								: Operation extends "record-evidence"
+									? Awaited<ReturnType<typeof recordEvidence>>
+									: Operation extends "record-review-blockers"
+										? Awaited<ReturnType<typeof recordFinalReviewBlockers>>
+										: never;
+
+export type ToolkitResultFor<Operation extends UlwLoopOperation> = ResultFor<Operation>;
+export type ToolkitResponseFor<Operation extends UlwLoopOperation> =
+	| ToolkitSuccess<Operation, ResultFor<Operation>>
+	| ToolkitFailure<Operation>;
+export type ToolkitOperationResponse = {
+	[Operation in UlwLoopOperation]: ToolkitResponseFor<Operation>;
+}[UlwLoopOperation];
+export type ToolkitDispatchResponse = ToolkitOperationResponse | ToolkitFailure<string>;
+export type ToolkitResponse<Result> = ToolkitSuccess<UlwLoopOperation, Result> | ToolkitFailure<string>;
+
+export interface ToolkitOperationHookEvent<Operation extends UlwLoopOperation = UlwLoopOperation> {
+	readonly operation: Operation;
+	readonly context: ToolkitContext;
+	readonly response: ToolkitResponseFor<Operation>;
+}
+
+export interface ToolkitHostHooks {
+	readonly onOperation?: <Operation extends UlwLoopOperation>(
+		event: ToolkitOperationHookEvent<Operation>,
+	) => void | Promise<void>;
+}
+
+export interface AgentToolkitDependencies {
+	readonly hooks?: ToolkitHostHooks;
+}
+
+export interface AgentToolkit {
+	readonly dispatch: (request: ToolkitDispatchRequest | ToolkitUnknownRequest) => Promise<ToolkitDispatchResponse>;
+	readonly help: () => Promise<ToolkitResponseFor<"help">>;
+	readonly createGoals: (args: CreateGoalsArgs) => Promise<ToolkitResponseFor<"create-goals">>;
+	readonly status: () => Promise<ToolkitResponseFor<"status">>;
+	readonly completeGoals: (args?: CompleteGoalsArgs) => Promise<ToolkitResponseFor<"complete-goals">>;
+	readonly checkpoint: (args: CheckpointArgs) => Promise<ToolkitResponseFor<"checkpoint">>;
+	readonly steer: (args: SteerArgs) => Promise<ToolkitResponseFor<"steer">>;
+	readonly addGoal: (args: AddGoalArgs) => Promise<ToolkitResponseFor<"add-goal">>;
+	readonly criteria: (args: CriteriaArgs) => Promise<ToolkitResponseFor<"criteria">>;
+	readonly recordEvidence: (args: RecordEvidenceArgs) => Promise<ToolkitResponseFor<"record-evidence">>;
+	readonly recordReviewBlockers: (
+		args: RecordReviewBlockersArgs,
+	) => Promise<ToolkitResponseFor<"record-review-blockers">>;
+}

package/packages/omo-codex/plugin/components/ulw-loop/src/sdk.ts

@@ -0,0 +1,3 @@
+export { createAgentToolkit } from "./sdk/factory.js";
+export * from "./sdk/manifest.js";
+export * from "./sdk/types.js";

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

@@ -0,0 +1,137 @@
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+import { seedDefaultSuccessCriteria } from "../src/plan-crud.js";
+import { readUlwLoopPlan } from "../src/plan-io.js";
+import {
+	createAgentToolkit,
+	type ToolkitContext,
+	type ToolkitDispatchRequest,
+	ULW_LOOP_MANIFEST,
+	ULW_LOOP_OPERATIONS,
+} from "../src/sdk.js";
+
+describe("agent toolkit SDK contract", () => {
+	it("exposes exactly the ten existing operations in its manifest", () => {
+		expect(ULW_LOOP_OPERATIONS).toEqual([
+			"help",
+			"create-goals",
+			"status",
+			"complete-goals",
+			"checkpoint",
+			"steer",
+			"add-goal",
+			"criteria",
+			"record-evidence",
+			"record-review-blockers",
+		]);
+		expect(ULW_LOOP_MANIFEST.operations.map((operation) => operation.name)).toEqual(ULW_LOOP_OPERATIONS);
+	});
+
+	it("fails closed for an absent session identity", () => {
+		expect(() => createAgentToolkit({ cwd: ".", sessionId: "", surface: "lazycodex" })).toThrow(
+			"ULW_LOOP_SESSION_ID_REQUIRED",
+		);
+	});
+
+	it("uses explicit surface roles for SDK checkpoint templates", async () => {
+		for (const surface of ["omo-senpi", "lazycodex"] as const) {
+			const cwd = await mkdtemp(join(tmpdir(), `ulw-sdk-template-${surface}-`));
+			try {
+				const toolkit = createAgentToolkit({ cwd, sessionId: `template-${surface}`, surface });
+				const created = await toolkit.createGoals({ brief: "Template fixture" });
+				expect(created.ok).toBe(true);
+				const template = await toolkit.checkpoint({ printTemplate: true });
+				expect(template.ok).toBe(true);
+				if (!template.ok) return;
+				expect(template.operation).toBe("checkpoint");
+				expect("qualityGateTemplate" in template.result).toBe(true);
+				if (!("qualityGateTemplate" in template.result)) return;
+				expect(template.result.qualityGateTemplate["manualQa"]).toMatchObject({ by: "main-session" });
+				expect(template.result.qualityGateTemplate["gateReview"]).toMatchObject({
+					by: surface === "omo-senpi" ? "category:deep" : "main-session",
+				});
+			} finally {
+				await rm(cwd, { recursive: true, force: true });
+			}
+		}
+	});
+
+	it("returns the stable unknown-operation error at the public dispatch boundary", async () => {
+		const toolkit = createAgentToolkit({ cwd: ".", sessionId: "sdk-contract", surface: "lazycodex" });
+		const result = await toolkit.dispatch({ operation: "does-not-exist" });
+		expect(result.ok).toBe(false);
+		if (!result.ok) expect(result.error.code).toBe("ULW_LOOP_OPERATION_UNKNOWN");
+	});
+
+	it("calls every operation through typed structured envelopes on a session-scoped fixture", async () => {
+		const cwd = await mkdtemp(join(tmpdir(), "ulw-sdk-contract-"));
+		try {
+			const context: ToolkitContext = { cwd, sessionId: "sdk-contract", surface: "lazycodex" };
+			const hookOperations: string[] = [];
+			const toolkit = createAgentToolkit(context, {
+				hooks: {
+					onOperation: ({ operation }) => {
+						hookOperations.push(operation);
+					},
+				},
+			});
+			const request = async (value: ToolkitDispatchRequest) => {
+				const response = await toolkit.dispatch(value);
+				expect(response.ok).toBe(true);
+				return response;
+			};
+
+			await request({ operation: "help", args: {} });
+			await request({ operation: "create-goals", args: { brief: "Build the SDK fixture" } });
+			await request({ operation: "status", args: {} });
+			const started = await request({ operation: "complete-goals", args: {} });
+			if (!started.ok || started.operation !== "complete-goals" || "done" in started.result)
+				throw new Error("fixture did not start a goal");
+			const goalId = started.result.goal.id;
+			const criterionId = seedDefaultSuccessCriteria(0, "Build the SDK fixture")[0]?.id;
+			if (criterionId === undefined) throw new Error("fixture has no criterion");
+			await request({ operation: "criteria", args: { goalId } });
+			await request({
+				operation: "record-evidence",
+				args: { goalId, criterionId, status: "pass", evidence: "fixture proof" },
+			});
+			await request({
+				operation: "steer",
+				args: {
+					kind: "annotate_ledger",
+					source: "cli",
+					evidence: "fixture observation",
+					rationale: "fixture rationale",
+				},
+			});
+			const plan = await readUlwLoopPlan(cwd, { sessionId: context.sessionId });
+			const review = await request({
+				operation: "record-review-blockers",
+				args: {
+					goalId,
+					title: "Review follow-up",
+					objective: "Exercise review blockers",
+					evidence: "fixture review evidence",
+					codexGoalJson: JSON.stringify({ goal: { objective: plan.codexObjective, status: "active" } }),
+				},
+			});
+			if (!review.ok || review.operation !== "record-review-blockers")
+				throw new Error("fixture did not record review blockers");
+			await request({
+				operation: "checkpoint",
+				args: { goalId: review.result.newGoal.id, status: "failed", evidence: "fixture failure" },
+			});
+			await request({
+				operation: "add-goal",
+				args: { title: "Extra fixture goal", objective: "Exercise add-goal" },
+			});
+			const operationCount = hookOperations.length;
+			expect(operationCount).toBe(10);
+			expect(new Set(hookOperations)).toEqual(new Set(ULW_LOOP_OPERATIONS));
+		} finally {
+			await rm(cwd, { recursive: true, force: true });
+		}
+	});
+});

package/packages/omo-codex/plugin/components/ulw-loop/test/sdk-session-context.test.ts

@@ -0,0 +1,148 @@
+import { type ChildProcess, spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import { mkdtemp, readFile, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+
+import { ulwLoopLedgerPath, ulwLoopStateLockPath } from "../src/paths.js";
+import { createAgentToolkit } from "../src/sdk.js";
+
+const children: ChildProcess[] = [];
+const workDirs: string[] = [];
+
+afterEach(async () => {
+	for (const child of children.splice(0)) {
+		if (child.exitCode === null) child.kill("SIGKILL");
+	}
+	for (const dir of workDirs.splice(0)) await rm(dir, { recursive: true, force: true });
+});
+
+const HOLDER_SCRIPT = `
+const fs = require("node:fs");
+const path = require("node:path");
+const [lockPath, holdMs] = process.argv.slice(1);
+fs.mkdirSync(path.dirname(lockPath), { recursive: true });
+const fd = fs.openSync(lockPath, "wx");
+fs.writeSync(fd, JSON.stringify({ pid: process.pid, createdAt: new Date().toISOString(), token: "holder-" + process.pid }));
+fs.closeSync(fd);
+process.stdout.write("HELD\\n");
+setTimeout(() => {
+	fs.writeFileSync(lockPath + ".released", "");
+	fs.unlinkSync(lockPath);
+}, Number(holdMs));
+`;
+
+async function makeWorkdir(): Promise<string> {
+	const dir = await mkdtemp(join(tmpdir(), "ulw-sdk-session-"));
+	workDirs.push(dir);
+	return dir;
+}
+
+function holdStateLock(lockPath: string, holdMs: number): Promise<{ readonly releasedMarker: string }> {
+	return new Promise((resolve, reject) => {
+		const child = spawn(process.execPath, ["-e", HOLDER_SCRIPT, lockPath, String(holdMs)], {
+			stdio: ["ignore", "pipe", "inherit"],
+		});
+		children.push(child);
+		let output = "";
+		child.stdout.setEncoding("utf8");
+		child.stdout.on("data", (chunk: string) => {
+			output += chunk;
+			if (output.includes("HELD")) resolve({ releasedMarker: `${lockPath}.released` });
+		});
+		child.once("error", reject);
+	});
+}
+
+async function seedSession(
+	cwd: string,
+	sessionId: string,
+): Promise<{ readonly goalId: string; readonly criteria: readonly string[] }> {
+	const toolkit = createAgentToolkit({ cwd, sessionId, surface: "lazycodex" });
+	const created = await toolkit.createGoals({ brief: "Session context fixture" });
+	if (!created.ok) throw new Error("fixture could not create goals");
+	const started = await toolkit.completeGoals({});
+	if (!started.ok || started.operation !== "complete-goals" || "done" in started.result)
+		throw new Error("fixture could not start a goal");
+	const goalId = started.result.goal.id;
+	const criteria = await toolkit.criteria({ goalId });
+	if (!criteria.ok || criteria.operation !== "criteria") throw new Error("fixture has no criteria");
+	return { goalId, criteria: criteria.result.criteria.map((criterion) => criterion.id) };
+}
+
+describe("agent toolkit session context", () => {
+	describe("#given a plan written under session A", () => {
+		it("#when session B reads through its own context #then the read fails closed instead of borrowing A", async () => {
+			const cwd = await makeWorkdir();
+			await seedSession(cwd, "session-a");
+
+			const foreign = createAgentToolkit({ cwd, sessionId: "session-b", surface: "lazycodex" });
+			const status = await foreign.status();
+
+			expect(status.ok).toBe(false);
+		});
+	});
+
+	describe("#given the session state lock held by another process", () => {
+		it("#when an SDK mutation runs #then it waits for that release before writing", async () => {
+			const cwd = await makeWorkdir();
+			const sessionId = "session-lock";
+			const seeded = await seedSession(cwd, sessionId);
+			const criterionId = seeded.criteria[0];
+			if (criterionId === undefined) throw new Error("fixture has no criterion");
+			const holder = await holdStateLock(ulwLoopStateLockPath(cwd, { sessionId }), 300);
+
+			const toolkit = createAgentToolkit({ cwd, sessionId, surface: "lazycodex" });
+			const recorded = await toolkit.recordEvidence({
+				goalId: seeded.goalId,
+				criterionId,
+				status: "pass",
+				evidence: "waited for the held lock",
+			});
+
+			expect(recorded.ok).toBe(true);
+			expect(existsSync(holder.releasedMarker)).toBe(true);
+		});
+	});
+
+	describe("#given two SDK instances bound to one session directory", () => {
+		it("#when both record evidence concurrently #then the ledger keeps both entries", async () => {
+			const cwd = await makeWorkdir();
+			const sessionId = "session-concurrent";
+			const seeded = await seedSession(cwd, sessionId);
+			const first = seeded.criteria[0];
+			const second = seeded.criteria[1];
+			if (first === undefined || second === undefined) throw new Error("fixture needs two criteria");
+
+			const results = await Promise.all([
+				createAgentToolkit({ cwd, sessionId, surface: "lazycodex" }).recordEvidence({
+					goalId: seeded.goalId,
+					criterionId: first,
+					status: "pass",
+					evidence: "first instance",
+				}),
+				createAgentToolkit({ cwd, sessionId, surface: "lazycodex" }).recordEvidence({
+					goalId: seeded.goalId,
+					criterionId: second,
+					status: "pass",
+					evidence: "second instance",
+				}),
+			]);
+
+			expect(results.every((result) => result.ok)).toBe(true);
+			const ledger = await readFile(ulwLoopLedgerPath(cwd, { sessionId }), "utf8");
+			const recorded = ledger
+				.split("\n")
+				.filter((line) => line.trim().length > 0)
+				.map((line): unknown => JSON.parse(line))
+				.filter((entry): entry is { readonly criterionId: string } => {
+					if (typeof entry !== "object" || entry === null || !("criterionId" in entry)) return false;
+					return typeof entry.criterionId === "string";
+				})
+				.map((entry) => entry.criterionId);
+			expect(recorded).toContain(first);
+			expect(recorded).toContain(second);
+		});
+	});
+});

package/packages/omo-codex/plugin/hooks/post-compact-resetting-git-bash-mcp-reminder.json

@@ -7,7 +7,7 @@
 						"type": "command",
 						"command": "node \"${PLUGIN_ROOT}/components/git-bash/dist/cli.js\" hook post-compact",
 						"timeout": 5,
-						"statusMessage": "(OmO 5.0.0-beta.56) Resetting Git Bash MCP Reminder",
+						"statusMessage": "(OmO 5.0.0-beta.60) Resetting Git Bash MCP Reminder",
 						"commandWindows": "powershell -NoProfile -ExecutionPolicy Bypass -File \"${PLUGIN_ROOT}\\components\\bootstrap\\scripts\\node-dispatch.ps1\" \"${PLUGIN_ROOT}\\components\\git-bash\\dist\\cli.js\" hook post-compact"
 					}
 				],

package/packages/omo-codex/plugin/hooks/post-compact-resetting-lsp-diagnostics-cache.json

@@ -7,7 +7,7 @@
 						"type": "command",
 						"command": "node \"${PLUGIN_ROOT}/components/lsp/dist/cli.js\" hook post-compact",
 						"timeout": 5,
-						"statusMessage": "(OmO 5.0.0-beta.56) Resetting LSP Diagnostics Cache",
+						"statusMessage": "(OmO 5.0.0-beta.60) Resetting LSP Diagnostics Cache",
 						"commandWindows": "powershell -NoProfile -ExecutionPolicy Bypass -File \"${PLUGIN_ROOT}\\components\\bootstrap\\scripts\\node-dispatch.ps1\" \"${PLUGIN_ROOT}\\components\\lsp\\dist\\cli.js\" hook post-compact"
 					}
 				],

package/packages/omo-codex/plugin/hooks/post-compact-resetting-project-rule-cache.json

@@ -7,7 +7,7 @@
 						"type": "command",
 						"command": "node \"${PLUGIN_ROOT}/components/rules/dist/cli.js\" hook post-compact",
 						"timeout": 10,
-						"statusMessage": "(OmO 5.0.0-beta.56) Resetting Project Rule Cache",
+						"statusMessage": "(OmO 5.0.0-beta.60) Resetting Project Rule Cache",
 						"commandWindows": "powershell -NoProfile -ExecutionPolicy Bypass -File \"${PLUGIN_ROOT}\\components\\bootstrap\\scripts\\node-dispatch.ps1\" \"${PLUGIN_ROOT}\\components\\rules\\dist\\cli.js\" hook post-compact"
 					}
 				],

package/packages/omo-codex/plugin/hooks/post-tool-use-checking-comments.json

@@ -7,7 +7,7 @@
 						"type": "command",
 						"command": "node \"${PLUGIN_ROOT}/components/comment-checker/dist/cli.js\" hook post-tool-use",
 						"timeout": 30,
-						"statusMessage": "(OmO 5.0.0-beta.56) Checking Comments",
+						"statusMessage": "(OmO 5.0.0-beta.60) Checking Comments",
 						"commandWindows": "powershell -NoProfile -ExecutionPolicy Bypass -File \"${PLUGIN_ROOT}\\components\\bootstrap\\scripts\\node-dispatch.ps1\" \"${PLUGIN_ROOT}\\components\\comment-checker\\dist\\cli.js\" hook post-tool-use"
 					}
 				],