@gajae-code/coding-agent 0.4.1 → 0.4.3

package/src/gjc-runtime/ultragoal-runtime.ts

@@ -228,18 +228,35 @@ function planSnapshotForReceipt(input: {
 	goal: UltragoalGoal;
 	beforeStatus: UltragoalGoalStatus;
 	targetGoalUpdatedAt: string;
+	receiptKind: UltragoalReceiptKind;
 }): unknown {
+	const targetGoalSnapshot = {
+		...input.goal,
+		status: input.beforeStatus,
+		updatedAt: input.targetGoalUpdatedAt,
+		evidence: undefined,
+		completedAt: undefined,
+		completionVerification: undefined,
+	};
+	const goals =
+		input.receiptKind === "final-aggregate"
+			? input.plan.goals.map(goal => ({
+					...goal,
+					status: goal.id === input.goal.id ? input.beforeStatus : goal.status,
+					updatedAt: goal.id === input.goal.id ? input.targetGoalUpdatedAt : goal.updatedAt,
+					evidence: goal.id === input.goal.id ? undefined : goal.evidence,
+					completedAt: goal.id === input.goal.id ? undefined : goal.completedAt,
+					completionVerification: undefined,
+				}))
+			: [targetGoalSnapshot];
 	return {
-		...input.plan,
-		updatedAt: undefined,
-		goals: input.plan.goals.map(goal => ({
-			...goal,
-			status: goal.id === input.goal.id ? input.beforeStatus : goal.status,
-			updatedAt: goal.id === input.goal.id ? input.targetGoalUpdatedAt : goal.updatedAt,
-			evidence: goal.id === input.goal.id ? undefined : goal.evidence,
-			completedAt: goal.id === input.goal.id ? undefined : goal.completedAt,
-			completionVerification: undefined,
-		})),
+		version: input.plan.version,
+		brief: input.plan.brief,
+		gjcGoalMode: input.plan.gjcGoalMode,
+		gjcObjective: input.plan.gjcObjective,
+		gjcObjectiveAliases: input.plan.gjcObjectiveAliases,
+		createdAt: input.plan.createdAt,
+		goals,
 	};
 }
 
@@ -264,6 +281,7 @@ export function computeUltragoalPlanGeneration(input: {
 			goal: input.goal,
 			beforeStatus: input.beforeStatus,
 			targetGoalUpdatedAt,
+			receiptKind: input.receiptKind,
 		}),
 	);
 	const requiredGoalSetHashBeforeCheckpoint = hashStructuredValue(
@@ -569,6 +587,31 @@ function chooseNextGoal(plan: UltragoalPlan, retryFailed: boolean): UltragoalGoa
 		(retryFailed ? plan.goals.find(goal => goal.status === "failed") : undefined)
 	);
 }
+export interface UltragoalRunCompletionState {
+	requiredGoals: UltragoalGoal[];
+	incompleteGoals: UltragoalGoal[];
+	nextGoal?: UltragoalGoal;
+	allComplete: boolean;
+	hasBlockers: boolean;
+	needsFinalAggregateReceipt: boolean;
+}
+
+export function getUltragoalRunCompletionState(
+	plan: UltragoalPlan,
+	options: { retryFailed?: boolean } = {},
+): UltragoalRunCompletionState {
+	const requiredGoals = requiredUltragoalGoals(plan);
+	const incompleteGoals = requiredGoals.filter(goal => !TERMINAL_OR_SKIPPED_STATUSES.has(goal.status));
+	const nextGoal = chooseNextGoal(plan, options.retryFailed === true);
+	return {
+		requiredGoals,
+		incompleteGoals,
+		nextGoal,
+		allComplete: requiredGoals.length > 0 && incompleteGoals.length === 0,
+		hasBlockers: incompleteGoals.some(goal => goal.status === "blocked" || goal.status === "review_blocked"),
+		needsFinalAggregateReceipt: plan.gjcGoalMode === "aggregate" && incompleteGoals.length === 0,
+	};
+}
 
 export async function startNextUltragoalGoal(input: { cwd: string; retryFailed?: boolean }): Promise<{
 	plan: UltragoalPlan;
@@ -578,7 +621,7 @@ export async function startNextUltragoalGoal(input: { cwd: string; retryFailed?:
 	const plan = await readUltragoalPlan(input.cwd);
 	if (!plan) throw new Error("No ultragoal plan found. Run `gjc ultragoal create-goals --brief ...` first.");
 	const goal = chooseNextGoal(plan, input.retryFailed === true);
-	if (!goal) return { plan, allComplete: plan.goals.every(item => TERMINAL_OR_SKIPPED_STATUSES.has(item.status)) };
+	if (!goal) return { plan, allComplete: getUltragoalRunCompletionState(plan).allComplete };
 	if (goal.status !== "active") {
 		const now = new Date().toISOString();
 		goal.status = "active";
@@ -639,7 +682,11 @@ function requireObjectArray(value: unknown, fieldName: string): JsonObject[] {
 function requiredStringField(row: JsonObject, key: string, fieldName: string): string {
 	const value = row[key];
 	if (typeof value !== "string" || value.trim().length === 0) {
-		throw new Error(`qualityGate ${fieldName}.${key} must be a non-empty string`);
+		const hint =
+			key === "obligation" && typeof row.description === "string" && row.description.trim().length > 0
+				? "; found description, but complete-checkpoint contractCoverage rows require obligation"
+				: "";
+		throw new Error(`qualityGate ${fieldName}.${key} must be a non-empty string${hint}`);
 	}
 	return value.trim();
 }
@@ -1015,6 +1062,17 @@ async function readRequiredCompletionQualityGate(cwd: string, value: string | un
 	return gate;
 }
 
+function snapshotUpdatedAtMilliseconds(value: unknown): number | null {
+	if (typeof value === "number" && Number.isFinite(value)) return value;
+	if (typeof value !== "string" || value.trim().length === 0) return null;
+	const trimmed = value.trim();
+	if (/^\d+$/.test(trimmed)) {
+		const parsed = Number.parseInt(trimmed, 10);
+		return Number.isFinite(parsed) ? parsed : null;
+	}
+	const parsed = Date.parse(trimmed);
+	return Number.isFinite(parsed) ? parsed : null;
+}
 async function readGjcGoalSnapshot(input: {
 	cwd: string;
 	value: string | undefined;
@@ -1026,16 +1084,23 @@ async function readGjcGoalSnapshot(input: {
 }): Promise<unknown> {
 	if (!input.value?.trim()) {
 		if (!input.required) return undefined;
-		throw new Error(`${input.errorPrefix} require --gjc-goal-json from a fresh active goal({"op":"get"}) snapshot`);
+		throw new Error(
+			`${input.errorPrefix} require --gjc-goal-json from a fresh active goal({"op":"get"}) snapshot; this is the GJC goal-mode receipt, not the .gjc/ultragoal/goals.json goal record`,
+		);
 	}
 	const snapshot = await readStructuredValue(input.cwd, input.value);
 	const snapshotObject = qualityGateObject(snapshot);
 	const detailsObject = qualityGateObject(snapshotObject?.details);
 	const goalObject = qualityGateObject(snapshotObject?.goal) ?? qualityGateObject(detailsObject?.goal);
-	if (!goalObject) throw new Error(`${input.errorPrefix} require --gjc-goal-json with a goal object`);
-	const updatedAt = typeof goalObject.updatedAt === "number" ? goalObject.updatedAt : null;
+	if (!goalObject)
+		throw new Error(
+			`${input.errorPrefix} require --gjc-goal-json with a goal object from goal({"op":"get"}); pass the active GJC goal-mode snapshot, not the .gjc/ultragoal/goals.json goal record`,
+		);
+	const updatedAt = snapshotUpdatedAtMilliseconds(goalObject.updatedAt);
 	if (!updatedAt)
-		throw new Error(`${input.errorPrefix} require --gjc-goal-json goal.updatedAt from goal({"op":"get"})`);
+		throw new Error(
+			`${input.errorPrefix} require --gjc-goal-json goal.updatedAt as epoch milliseconds or an ISO timestamp from goal({"op":"get"}); pass the active GJC goal-mode snapshot, not the .gjc/ultragoal/goals.json goal record`,
+		);
 	const nowMilliseconds = Date.now();
 	if (updatedAt < nowMilliseconds - GJC_GOAL_SNAPSHOT_MAX_AGE_MILLISECONDS) {
 		throw new Error(`${input.errorPrefix} require a fresh --gjc-goal-json snapshot`);
@@ -1052,7 +1117,9 @@ async function readGjcGoalSnapshot(input: {
 		return snapshot;
 	}
 	if (!expectedObjectives.has(objective)) {
-		throw new Error(`${input.errorPrefix} require --gjc-goal-json objective to match the active Ultragoal objective`);
+		throw new Error(
+			`${input.errorPrefix} require --gjc-goal-json objective to match the active GJC goal-mode objective from goal({"op":"get"}), not the .gjc/ultragoal/goals.json goal ${input.goal?.id ?? "record"}`,
+		);
 	}
 	if (goalObject.status !== "active") {
 		throw new Error(`${input.errorPrefix} require --gjc-goal-json goal.status to be active`);
@@ -1147,6 +1214,54 @@ export async function checkpointUltragoalGoal(input: {
 	});
 	return plan;
 }
+export interface UltragoalCheckpointContinuation {
+	plan: UltragoalPlan;
+	checkpointedGoal: UltragoalGoal;
+	nextGoal?: UltragoalGoal;
+	startedNext: boolean;
+	allComplete: boolean;
+	incompleteGoals: UltragoalGoal[];
+}
+
+export async function checkpointAndContinueUltragoalGoal(input: {
+	cwd: string;
+	goalId: string;
+	status: UltragoalGoalStatus;
+	evidence: string;
+	gjcGoalJson?: string;
+	qualityGateJson?: string;
+	advanceNext?: boolean;
+	retryFailed?: boolean;
+}): Promise<UltragoalCheckpointContinuation> {
+	let plan = await checkpointUltragoalGoal(input);
+	const checkpointedGoal = plan.goals.find(goal => goal.id === input.goalId);
+	if (!checkpointedGoal) throw new Error(`No ultragoal goal found for ${input.goalId}.`);
+	if (input.status === "complete" && input.advanceNext === true) {
+		const beforeAdvance = getUltragoalRunCompletionState(plan, { retryFailed: input.retryFailed });
+		if (beforeAdvance.nextGoal && beforeAdvance.nextGoal.status !== "active") {
+			const started = await startNextUltragoalGoal({ cwd: input.cwd, retryFailed: input.retryFailed });
+			plan = started.plan;
+			const afterAdvance = getUltragoalRunCompletionState(plan, { retryFailed: input.retryFailed });
+			return {
+				plan,
+				checkpointedGoal,
+				nextGoal: started.goal,
+				startedNext: Boolean(started.goal),
+				allComplete: afterAdvance.allComplete,
+				incompleteGoals: afterAdvance.incompleteGoals,
+			};
+		}
+	}
+	const state = getUltragoalRunCompletionState(plan, { retryFailed: input.retryFailed });
+	return {
+		plan,
+		checkpointedGoal,
+		nextGoal: state.nextGoal,
+		startedNext: false,
+		allComplete: state.allComplete,
+		incompleteGoals: state.incompleteGoals,
+	};
+}
 
 export async function addUltragoalSubgoal(input: {
 	cwd: string;
@@ -1235,6 +1350,8 @@ function hasFlag(args: readonly string[], flag: string): boolean {
 	return args.includes(flag);
 }
 
+const HELP_FLAGS = new Set(["--help", "-h"]);
+
 const FLAGS_WITH_VALUES = new Set([
 	"--brief",
 	"--brief-file",
@@ -1250,6 +1367,10 @@ const FLAGS_WITH_VALUES = new Set([
 	"--rationale",
 ]);
 
+function isHelpArg(arg: string): boolean {
+	return HELP_FLAGS.has(arg);
+}
+
 function commandName(args: readonly string[]): string {
 	let skipNext = false;
 	for (const arg of args) {
@@ -1261,11 +1382,62 @@ function commandName(args: readonly string[]): string {
 			skipNext = true;
 			continue;
 		}
+		if (isHelpArg(arg)) continue;
 		if (!arg.startsWith("-")) return arg;
 	}
 	return "status";
 }
 
+function renderUltragoalHelp(args: readonly string[]): string | null {
+	if (!args.some(isHelpArg) && args[0] !== "help") return null;
+	const subject =
+		args[0] === "help" ? args.find((arg, index) => index > 0 && !arg.startsWith("-")) : commandName(args);
+	if (subject === "checkpoint") {
+		return [
+			"Run native GJC Ultragoal workflow commands",
+			"",
+			"USAGE",
+			"  $ gjc ultragoal checkpoint --goal-id <id> --status <status> --evidence <text> [FLAGS]",
+			"",
+			"FLAGS",
+			"      --goal-id=<value>            Durable .gjc/ultragoal goal id, e.g. G001",
+			"      --status=<value>             pending|active|complete|failed|blocked|review_blocked|superseded",
+			"      --evidence=<value>           Completion or checkpoint evidence text",
+			"      --quality-gate-json=<value>  JSON string or path for complete checkpoints",
+			'      --gjc-goal-json=<value>      JSON string or path containing the current goal({"op":"get"}) snapshot',
+			"      --json                       Output a machine-readable receipt",
+			"",
+			"COMPLETE CHECKPOINT RECEIPTS",
+			"  --quality-gate-json must be an object with architectReview, executorQa, and iteration.",
+			"  executorQa.contractCoverage[] rows require an obligation field; description is not a substitute.",
+			'  --gjc-goal-json must contain the active GJC goal-mode snapshot from goal({"op":"get"}), not the .gjc/ultragoal/goals.json goal record.',
+			"  goal.updatedAt may be epoch milliseconds or an ISO timestamp and must be fresh.",
+			"",
+			"EXAMPLES",
+			'  $ gjc ultragoal checkpoint --goal-id G001 --status blocked --evidence "waiting on review"',
+			'  $ gjc ultragoal checkpoint --goal-id G001 --status complete --evidence "tests passed" --gjc-goal-json ./goal.json --quality-gate-json ./quality-gate.json --json',
+			"",
+		].join("\n");
+	}
+	return [
+		"Run native GJC Ultragoal workflow commands",
+		"",
+		"USAGE",
+		"  $ gjc ultragoal <command> [FLAGS]",
+		"",
+		"COMMANDS",
+		"  status",
+		"  create-goals",
+		"  complete-goals",
+		"  checkpoint",
+		"  steer",
+		"  record-review-blockers",
+		"",
+		"Run `gjc ultragoal checkpoint --help` for complete checkpoint receipt requirements.",
+		"",
+	].join("\n");
+}
+
 async function readBrief(cwd: string, args: readonly string[]): Promise<string> {
 	const inline = flagValue(args, "--brief");
 	if (inline !== undefined) return inline;
@@ -1306,8 +1478,54 @@ function renderCompleteHandoff(
 		"",
 	].join("\n");
 }
+function renderCheckpointContinuation(
+	result: UltragoalCheckpointContinuation,
+	status: UltragoalGoalStatus,
+	json: boolean,
+	cwd: string,
+): string {
+	if (json)
+		return renderCliWriteReceipt({
+			ok: true,
+			goal_id: result.checkpointedGoal.id,
+			status,
+			goals_path: getUltragoalPaths(cwd).goalsPath,
+			completion_receipt_kind: result.checkpointedGoal.completionVerification?.receiptKind,
+			quality_gate_hash: result.checkpointedGoal.completionVerification?.qualityGateHash,
+			all_complete: result.allComplete,
+			next_goal_id: result.nextGoal?.id,
+			next_goal_status: result.nextGoal?.status,
+			started_next: result.startedNext,
+			incomplete_goal_ids: result.incompleteGoals.map(goal => goal.id),
+		});
+	const lines = [`Checkpointed ${result.checkpointedGoal.id} as ${status}.`];
+	if (status === "complete") {
+		if (result.allComplete) {
+			lines.push("All ultragoal goals are complete.");
+		} else if (result.nextGoal) {
+			lines.push(`Next ultragoal goal: ${result.nextGoal.id} — ${result.nextGoal.title}`);
+			lines.push(`Objective: ${result.nextGoal.objective}`);
+			lines.push(`GJC objective: ${result.plan.gjcObjective}`);
+			lines.push(
+				result.startedNext
+					? "The next ultragoal goal is active; continue the current aggregate GJC goal and checkpoint this story when verified."
+					: "Run `gjc ultragoal complete-goals` to activate the next ultragoal story.",
+			);
+		}
+	} else if (status === "failed") {
+		lines.push("Resume failed goals with `gjc ultragoal complete-goals --retry-failed` after the blocker is fixed.");
+	} else if (status === "blocked" || status === "review_blocked") {
+		lines.push(
+			"Blocked ultragoal work must be resolved with explicit blocker work or steering before final completion.",
+		);
+	}
+	lines.push("");
+	return lines.join("\n");
+}
 
 async function dispatchUltragoalCommand(args: string[], cwd: string): Promise<UltragoalCommandResult> {
+	const help = renderUltragoalHelp(args);
+	if (help) return { status: 0, stdout: help };
 	try {
 		const command = commandName(args);
 		const json = hasFlag(args, "--json");
@@ -1344,27 +1562,18 @@ async function dispatchUltragoalCommand(args: string[], cwd: string): Promise<Ul
 				const goalId = flagValue(args, "--goal-id") ?? "";
 				const status = parseGoalStatus(flagValue(args, "--status"));
 				const evidence = flagValue(args, "--evidence") ?? "";
-				const plan = await checkpointUltragoalGoal({
+				const result = await checkpointAndContinueUltragoalGoal({
 					cwd,
 					goalId,
 					status,
 					evidence,
 					gjcGoalJson: flagValue(args, "--gjc-goal-json"),
 					qualityGateJson: flagValue(args, "--quality-gate-json"),
+					advanceNext: status === "complete",
 				});
-				const goal = plan.goals.find(item => item.id === goalId);
 				return {
 					status: 0,
-					stdout: json
-						? renderCliWriteReceipt({
-								ok: true,
-								goal_id: goalId,
-								status,
-								goals_path: getUltragoalPaths(cwd).goalsPath,
-								completion_receipt_kind: goal?.completionVerification?.receiptKind,
-								quality_gate_hash: goal?.completionVerification?.qualityGateHash,
-							})
-						: `ultragoal checkpoint goal-id=${goalId} status=${status}\n`,
+					stdout: renderCheckpointContinuation(result, status, json, cwd),
 				};
 			}
 			case "steer": {
@@ -1469,7 +1678,8 @@ async function reconcileUltragoalState(cwd: string): Promise<void> {
 export async function runNativeUltragoalCommand(args: string[], cwd = process.cwd()): Promise<UltragoalCommandResult> {
 	const command = commandName(args);
 	const result = await dispatchUltragoalCommand(args, cwd);
-	if (result.status === 0 && RECONCILE_COMMANDS.has(command)) {
+	const isHelp = args.some(isHelpArg) || args[0] === "help";
+	if (!isHelp && result.status === 0 && RECONCILE_COMMANDS.has(command)) {
 		await reconcileUltragoalState(cwd);
 	}
 	return result;

package/src/harness-control-plane/finalize.ts

@@ -17,10 +17,13 @@ import {
 	type CompletionEvidence,
 	type ReceiptEnvelope,
 	type ReceiptSubject,
+	type ReviewFailureEvidence,
+	type ReviewVerdictEvidence,
 	type ValidationEvidence,
 	validateReceipt,
 } from "./receipts";
 import { readReceiptIndex, writeReceiptImmutable } from "./storage";
+import { isReviewVerdict, type ReviewVerdict } from "./types";
 
 export interface ValidationCommandSpec {
 	name: string;
@@ -49,6 +52,12 @@ export interface FinalizeOptions {
 	requireTests?: boolean;
 	requireCommit?: boolean;
 	requirePr?: boolean;
+	/** Review-only sessions produce a terminal verdict instead of implementation validation. */
+	reviewOnly?: boolean;
+	/** Operator/loop-supplied terminal review verdict (closed vocabulary). */
+	verdict?: string | null;
+	/** Bounded PR/issue reference for the review target (e.g. "PR-414"). Never resolved from the live repo. */
+	prTarget?: string | null;
 	validationCommands?: ValidationCommandSpec[];
 	checks: FinalizeChecks;
 	clock?: () => number;
@@ -60,6 +69,7 @@ export interface FinalizeResult {
 	validation: { name: string; valid: boolean; exitStatus: number }[];
 	commitHash: string | null;
 	prUrl: string | null;
+	verdict?: ReviewVerdict | null;
 	issueArtifact: string | null;
 	blockers: string[];
 }
@@ -69,6 +79,8 @@ function receiptId(prefix: string): string {
 }
 
 export async function runFinalize(opts: FinalizeOptions): Promise<FinalizeResult> {
+	if (opts.reviewOnly) return runReviewFinalize(opts);
+
 	const now = () => new Date(opts.clock ? opts.clock() : Date.now()).toISOString();
 	const blockers: string[] = [];
 	const validation: FinalizeResult["validation"] = [];
@@ -178,6 +190,78 @@ export async function runFinalize(opts: FinalizeOptions): Promise<FinalizeResult
 	};
 }
 
+/**
+ * Review-only finalizer: produces a terminal verdict receipt (no implementation validation,
+ * no commit/PR resolution) when a valid, autonomous verdict is supplied; otherwise writes a
+ * durable, bounded `review-failure` receipt suitable for fallback routing.
+ *
+ * It never *resolves* PR/commit metadata from the live repo; the only PR reference attached is
+ * the session's own declared review target (`prTarget`), so a review session cannot report an
+ * unrelated PR resolved from the current checkout.
+ *
+ * `OWNER_CONFIRMATION_REQUIRED` is a valid verdict but is NOT an autonomous success: it is
+ * recorded durably yet returns `completed: false` with an `owner-confirmation-required` blocker
+ * so downstream routing escalates to a human instead of treating it as merge-ready.
+ */
+async function runReviewFinalize(opts: FinalizeOptions): Promise<FinalizeResult> {
+	const now = () => new Date(opts.clock ? opts.clock() : Date.now()).toISOString();
+	const prTarget = opts.prTarget ?? null;
+	const subject: ReceiptSubject = { workspace: opts.workspace, branch: opts.branch, head: null, commit: null };
+	const baseResult: Omit<FinalizeResult, "completed" | "receiptPath" | "verdict" | "blockers"> = {
+		validation: [],
+		commitHash: null,
+		prUrl: null,
+		issueArtifact: null,
+	};
+
+	if (!isReviewVerdict(opts.verdict)) {
+		const reason = opts.verdict == null ? "review-verdict-missing" : "review-verdict-invalid";
+		const failure: ReviewFailureEvidence = { reason, prTarget, failedAt: now(), fallback: "operator-or-omx-review" };
+		const receipt = buildReceipt<ReviewFailureEvidence>({
+			receiptId: receiptId("revfail"),
+			sessionId: opts.sessionId,
+			family: "review-failure",
+			source: "finalizer",
+			subject,
+			evidence: failure,
+			createdAt: now(),
+		});
+		const outcome = validateReceipt(receipt);
+		const entry = await writeReceiptImmutable(
+			opts.root,
+			opts.sessionId,
+			"review-failure",
+			receipt.receiptId,
+			receipt,
+		);
+		const blockers = outcome.valid ? [reason] : [reason, ...outcome.reasons];
+		return { ...baseResult, completed: false, receiptPath: entry.path, verdict: null, blockers };
+	}
+
+	const verdict = opts.verdict as ReviewVerdict;
+	const evidence: ReviewVerdictEvidence = {
+		verdict,
+		prTarget,
+		finalizedAt: now(),
+		summaryRef: typeof opts.prTarget === "string" ? `verdict:${verdict}@${opts.prTarget}` : `verdict:${verdict}`,
+	};
+	const receipt = buildReceipt<ReviewVerdictEvidence>({
+		receiptId: receiptId("verdict"),
+		sessionId: opts.sessionId,
+		family: "review-verdict",
+		source: "finalizer",
+		subject,
+		evidence,
+		createdAt: now(),
+	});
+	const outcome = validateReceipt(receipt);
+	const entry = await writeReceiptImmutable(opts.root, opts.sessionId, "review-verdict", receipt.receiptId, receipt);
+	// A confirmation-required verdict is recorded but never an autonomous success.
+	const humanActionRequired = verdict === "OWNER_CONFIRMATION_REQUIRED";
+	const completed = outcome.valid && !humanActionRequired;
+	const blockers = !outcome.valid ? outcome.reasons : humanActionRequired ? ["owner-confirmation-required"] : [];
+	return { ...baseResult, completed, receiptPath: entry.path, verdict, blockers };
+}
 function git(workspace: string, args: string[]): string | null {
 	try {
 		return execFileSync("git", args, {

package/src/harness-control-plane/owner.ts

@@ -14,10 +14,10 @@
 import { execFileSync } from "node:child_process";
 import { randomBytes, randomUUID } from "node:crypto";
 import { existsSync } from "node:fs";
+import { observeRpcOutboundFrame } from "../modes/shared/agent-wire/event-observation";
 import { classifyRecovery } from "./classifier";
 import { ControlServer, type EndpointRequest } from "./control-endpoint";
 import { defaultFinalizeChecks, type FinalizeChecks, runFinalize, type ValidationCommandSpec } from "./finalize";
-import { mapRpcFrame } from "./frame-mapper";
 import { type OperateResult, operate } from "./operate";
 import { preserveDirtyWorktree } from "./preserve";
 import {
@@ -174,7 +174,7 @@ export class RuntimeOwner {
 
 	/** Map an RPC frame and route it: semantic/signal-bearing -> serial emit; high-frequency progress -> coalesce. */
 	#handleFrame(frame: Record<string, unknown>): void {
-		const mapped = mapRpcFrame(frame);
+		const mapped = observeRpcOutboundFrame(frame);
 		if (!mapped) return;
 		if (mapped.semantic || (mapped.signal && !mapped.coalesceKey)) {
 			this.#framePump = this.#framePump
@@ -199,7 +199,7 @@ export class RuntimeOwner {
 		await this.#emit("info", "rpc_activity", { coalescedFrames });
 	}
 
-	async #emitMapped(mapped: NonNullable<ReturnType<typeof mapRpcFrame>>): Promise<void> {
+	async #emitMapped(mapped: NonNullable<ReturnType<typeof observeRpcOutboundFrame>>): Promise<void> {
 		await this.#emit(
 			mapped.severity,
 			mapped.kind,
@@ -359,6 +359,14 @@ export class RuntimeOwner {
 
 	async #validate(): Promise<PrimitiveResponse> {
 		const state = await this.#loadState();
+		if (state.handle.mode === "review") {
+			// Review-only sessions do not run implementation validation and never attach PR metadata.
+			state.lifecycle = "validating";
+			state.updatedAt = new Date(this.#opts.clock ? this.#opts.clock() : Date.now()).toISOString();
+			await writeSessionState(this.#opts.root, state);
+			await this.#emit("info", "validated", { count: 0, reviewOnly: true });
+			return this.#response(state, { validation: [], reviewOnly: true });
+		}
 		const checks = this.#finalizeChecks ?? defaultFinalizeChecks(state.handle.workspace);
 		const commit = await checks.resolveCommit();
 		const subject: ReceiptSubject = {
@@ -495,11 +503,15 @@ export class RuntimeOwner {
 		const state = await this.#loadState();
 		const workspace = state.handle.workspace;
 		const checks = this.#finalizeChecks ?? defaultFinalizeChecks(workspace);
+		const reviewOnly = state.handle.mode === "review";
 		const fin = await runFinalize({
 			root: this.#opts.root,
 			sessionId: this.#opts.sessionId,
 			workspace,
 			branch: state.handle.branch ?? "",
+			reviewOnly,
+			verdict: reviewOnly ? (typeof input.verdict === "string" ? input.verdict : null) : undefined,
+			prTarget: reviewOnly ? state.handle.issueOrPr : undefined,
 			requireTests: input.requireTests !== false,
 			requireCommit: input.requireCommit !== false,
 			requirePr: input.requirePr !== false,
@@ -514,6 +526,7 @@ export class RuntimeOwner {
 		await this.#emit(fin.completed ? "info" : "critical", "finalized", {
 			completed: fin.completed,
 			blockers: fin.blockers,
+			...(reviewOnly ? { verdict: fin.verdict ?? null, reviewOnly: true } : {}),
 		});
 		return this.#response(state, { finalize: fin }, fin.completed);
 	}

package/src/harness-control-plane/receipts.ts

@@ -13,7 +13,13 @@
  *   - completion        the finalize gate: receipt-valid + commit + PR/issue + validations
  */
 import { createHash } from "node:crypto";
-import type { GitDelta, ReceiptFamily, RecoveryClassification } from "./types";
+import {
+	type GitDelta,
+	isReviewVerdict,
+	type ReceiptFamily,
+	type RecoveryClassification,
+	type ReviewVerdict,
+} from "./types";
 
 export interface ReceiptSubject {
 	workspace: string;
@@ -144,6 +150,23 @@ export interface CompletionEvidence {
 	blockers: string[];
 }
 
+export interface ReviewVerdictEvidence {
+	verdict: ReviewVerdict;
+	prTarget: string | null;
+	finalizedAt: string;
+	/** Bounded summary code/reference for the verdict; never raw assistant text. */
+	summaryRef: string | null;
+}
+
+export interface ReviewFailureEvidence {
+	/** Machine-actionable reason the review produced no terminal verdict. */
+	reason: string;
+	prTarget: string | null;
+	failedAt: string;
+	/** Routing hint for the operator/fallback path. */
+	fallback: string;
+}
+
 function validateFamily(receipt: ReceiptEnvelope<unknown>): string[] {
 	switch (receipt.family) {
 		case "vanish":
@@ -154,6 +177,10 @@ function validateFamily(receipt: ReceiptEnvelope<unknown>): string[] {
 			return validateValidation(receipt.evidence as ValidationEvidence);
 		case "completion":
 			return validateCompletion(receipt.evidence as CompletionEvidence);
+		case "review-verdict":
+			return validateReviewVerdict(receipt.evidence as ReviewVerdictEvidence);
+		case "review-failure":
+			return validateReviewFailure(receipt.evidence as ReviewFailureEvidence);
 		default:
 			return [`unknown-family:${receipt.family}`];
 	}
@@ -206,6 +233,17 @@ function validateCompletion(e: CompletionEvidence): string[] {
 	return reasons;
 }
 
+function validateReviewVerdict(e: ReviewVerdictEvidence): string[] {
+	if (!e) return ["review-verdict-missing-evidence"];
+	if (!isReviewVerdict(e.verdict)) return ["review-verdict-not-in-vocabulary"];
+	return [];
+}
+
+function validateReviewFailure(e: ReviewFailureEvidence): string[] {
+	if (!e || typeof e.reason !== "string" || e.reason.length === 0) return ["review-failure-missing-reason"];
+	return [];
+}
+
 /** Classifications that MUST have a valid `vanish` receipt before the action proceeds. */
 export function requiresVanishBeforeAction(classification: RecoveryClassification): boolean {
 	return (

package/src/harness-control-plane/rpc-adapter.ts

@@ -174,7 +174,13 @@ export class GajaeCodeRpc implements HarnessRpc {
 		// Any other frame is a session/agent event: advance the cursor.
 		this.#cursor += 1;
 		this.#lastFrameAt = new Date().toISOString();
-		if (type === "agent_start") {
+		// Session events arrive as canonical `event` frames: the agent event type
+		// lives in `payload.event_type`. Non-event frames keep their flat `type`.
+		const effectiveType =
+			type === "event" && frame.payload && typeof frame.payload === "object"
+				? (frame.payload as { event_type?: unknown }).event_type
+				: type;
+		if (effectiveType === "agent_start") {
 			const cursor = this.#cursor;
 			this.#agentStartCursors.push(cursor);
 			this.#waiters = this.#waiters.filter(w => {