@gajae-code/coding-agent 0.4.3 → 0.4.5

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

@@ -46,7 +46,7 @@ export interface ReceiptEnvelope<E = Record<string, unknown>> {
 export const RECEIPT_SCHEMA_VERSION = 1 as const;
 
 /** Deterministic stringify with sorted keys (stable hash basis). */
-function canonicalJson(value: unknown): string {
+export function canonicalJson(value: unknown): string {
 	if (value === null || typeof value !== "object") return JSON.stringify(value) ?? "null";
 	if (Array.isArray(value)) return `[${value.map(canonicalJson).join(",")}]`;
 	const obj = value as Record<string, unknown>;
@@ -96,9 +96,50 @@ export interface ValidationOutcome {
 	reasons: string[];
 }
 
+/** Reusable non-empty string guard for structural envelope checks. */
+function isNonEmptyString(value: unknown): value is string {
+	return typeof value === "string" && value.length > 0;
+}
+
+/**
+ * Validate the structural envelope fields independently of the hash. A receipt
+ * can be hash-self-consistent while carrying empty/missing identity fields (an
+ * attacker controls the bytes the hash is computed over), so these checks must
+ * run BEFORE any lifecycle transition is allowed. Fail-closed.
+ */
+function validateStructure(receipt: ReceiptEnvelope<unknown>): string[] {
+	const reasons: string[] = [];
+	if (!isNonEmptyString(receipt.receiptId)) reasons.push("envelope-missing-receiptId");
+	if (!isNonEmptyString(receipt.sessionId)) reasons.push("envelope-missing-sessionId");
+	if (!isNonEmptyString(receipt.source)) reasons.push("envelope-missing-source");
+	if (!isNonEmptyString(receipt.createdAt)) reasons.push("envelope-missing-createdAt");
+	// Family vocabulary itself is enforced by `validateFamily`; here we only
+	// require a non-empty family token so the envelope is well-formed.
+	if (!isNonEmptyString(receipt.family)) reasons.push("envelope-missing-family");
+	if (typeof receipt.valid !== "boolean") reasons.push("envelope-bad-valid");
+	if (typeof receipt.sha256 !== "string") reasons.push("envelope-missing-sha256");
+	const subject = receipt.subject as ReceiptSubject | undefined;
+	if (!subject || typeof subject !== "object" || Array.isArray(subject) || !isNonEmptyString(subject.workspace)) {
+		reasons.push("envelope-bad-subject");
+	}
+	if (receipt.evidence === null || typeof receipt.evidence !== "object" || Array.isArray(receipt.evidence)) {
+		reasons.push("envelope-bad-evidence");
+	}
+	if (!receipt.artifactHashes || typeof receipt.artifactHashes !== "object" || Array.isArray(receipt.artifactHashes)) {
+		reasons.push("envelope-bad-artifactHashes");
+	}
+	return reasons;
+}
+
 /** Recompute the hash and run structural family checks. Fail-closed. */
 export function validateReceipt(receipt: ReceiptEnvelope<unknown>): ValidationOutcome {
+	// Fail closed on malformed/non-object envelopes (null, undefined, arrays,
+	// primitives) instead of throwing while destructuring below.
+	if (receipt === null || typeof receipt !== "object" || Array.isArray(receipt)) {
+		return { valid: false, reasons: ["malformed-envelope"] };
+	}
 	const reasons: string[] = [];
+	reasons.push(...validateStructure(receipt));
 	const { sha256, ...rest } = receipt;
 	if (sha256Hex(hashBasis(rest)) !== sha256) reasons.push("hash-mismatch");
 	if (receipt.schemaVersion !== RECEIPT_SCHEMA_VERSION) reasons.push("schema-version-mismatch");
@@ -156,6 +197,10 @@ export interface ReviewVerdictEvidence {
 	finalizedAt: string;
 	/** Bounded summary code/reference for the verdict; never raw assistant text. */
 	summaryRef: string | null;
+	/** Where the verdict came from: explicit operator input or extracted from final assistant text. */
+	verdictSource?: "input" | "assistant";
+	/** sha256 of the assistant text the verdict was extracted from, when sourced from the agent. */
+	assistantDigest?: string | null;
 }
 
 export interface ReviewFailureEvidence {
@@ -165,6 +210,10 @@ export interface ReviewFailureEvidence {
 	failedAt: string;
 	/** Routing hint for the operator/fallback path. */
 	fallback: string;
+	/** sha256 of the assistant text examined for a verdict, when one was available. */
+	assistantDigest?: string | null;
+	/** Bounded, whitespace-collapsed assistant summary (never an unbounded transcript dump). */
+	assistantSummary?: string | null;
 }
 
 function validateFamily(receipt: ReceiptEnvelope<unknown>): string[] {
@@ -181,11 +230,187 @@ function validateFamily(receipt: ReceiptEnvelope<unknown>): string[] {
 			return validateReviewVerdict(receipt.evidence as ReviewVerdictEvidence);
 		case "review-failure":
 			return validateReviewFailure(receipt.evidence as ReviewFailureEvidence);
+		case "phase-rollup":
+			return validatePhaseRollup(receipt.evidence as PhaseRollupEvidence);
 		default:
 			return [`unknown-family:${receipt.family}`];
 	}
 }
 
+// ---- Phase rollup (receipt-of-receipts) ----------------------------------------
+
+/** Pointer back to one superseded child task receipt. */
+export interface PhaseRollupChildPointer {
+	id: string;
+	status: "completed" | "failed" | "aborted" | "merge_failed" | "paused";
+	/** Artifact URI holding the child's full output, when available. */
+	outputUri: string | null;
+	/** Content hash of the child's output artifact, when available. */
+	outputSha256: string | null;
+	/** Hash of the child receipt itself (canonical JSON), for staleness checks. */
+	receiptSha256: string;
+	/**
+	 * Per-child ROI accounting carried into the rollup so the aggregate totals
+	 * below are recomputable/verifiable from child evidence (not self-reported).
+	 * `tokens` is the child's effective token count; cost/cloned are null when
+	 * the child reported no such accounting.
+	 */
+	tokens: number;
+	costTotal: number | null;
+	clonedTokens: number | null;
+	lowRoi: boolean;
+}
+
+export interface PhaseRollupEvidence {
+	/** Harness lifecycle boundary this rollup was emitted at. */
+	phase: string;
+	children: PhaseRollupChildPointer[];
+	aggregate: {
+		childCount: number;
+		completed: number;
+		failed: number;
+		totalTokens: number;
+		totalCostTotal: number | null;
+		totalClonedTokens: number | null;
+		lowRoiChildIds: string[];
+	};
+}
+
+const SHA256_HEX = /^[0-9a-f]{64}$/;
+
+const PHASE_ROLLUP_CHILD_STATUSES = new Set(["completed", "failed", "aborted", "merge_failed", "paused"]);
+
+/** Reconcile two recomputed-vs-reported numeric totals (null == "not reported"). */
+function numbersReconcile(actual: number | null, expected: number | null): boolean {
+	if (actual === null || expected === null) return actual === expected;
+	return Math.abs(actual - expected) <= 1e-9;
+}
+
+/** True when two id lists describe the same set (order-independent). */
+function sameIdSet(actual: readonly string[], expected: readonly string[]): boolean {
+	if (actual.length !== expected.length) return false;
+	const expectedSet = new Set(expected);
+	for (const id of actual) {
+		if (!expectedSet.has(id)) return false;
+	}
+	return new Set(actual).size === expectedSet.size;
+}
+
+export function validatePhaseRollup(e: PhaseRollupEvidence): string[] {
+	const reasons: string[] = [];
+	if (!e || typeof e.phase !== "string" || e.phase.length === 0) return ["phase-rollup-missing-phase"];
+	if (!Array.isArray(e.children) || e.children.length === 0) {
+		reasons.push("phase-rollup-empty-children");
+		return reasons;
+	}
+	const seenIds = new Set<string>();
+	let completedFromChildren = 0;
+	let failedFromChildren = 0;
+	let tokensFromChildren = 0;
+	let costFromChildren = 0;
+	let clonedFromChildren = 0;
+	let anyCost = false;
+	let anyCloned = false;
+	const lowRoiFromChildren: string[] = [];
+	for (const child of e.children) {
+		if (!child || typeof child.id !== "string" || child.id.length === 0) {
+			reasons.push("phase-rollup-child-missing-id");
+			continue;
+		}
+		if (seenIds.has(child.id)) reasons.push(`phase-rollup-duplicate-child-id:${child.id}`);
+		seenIds.add(child.id);
+		if (!PHASE_ROLLUP_CHILD_STATUSES.has(child.status)) {
+			reasons.push(`phase-rollup-child-bad-status:${child.id}`);
+		}
+		if (child.status === "completed") completedFromChildren++;
+		if (child.status === "failed" || child.status === "merge_failed") failedFromChildren++;
+		if (typeof child.receiptSha256 !== "string" || !SHA256_HEX.test(child.receiptSha256)) {
+			reasons.push(`phase-rollup-child-bad-receipt-hash:${child.id}`);
+		}
+		if (child.outputUri !== null && (typeof child.outputUri !== "string" || child.outputUri.length === 0)) {
+			reasons.push(`phase-rollup-child-bad-output-uri:${child.id}`);
+		}
+		if (child.outputSha256 !== null && !SHA256_HEX.test(child.outputSha256)) {
+			reasons.push(`phase-rollup-child-bad-output-hash:${child.id}`);
+		}
+		// Receipt-of-receipts integrity requires BOTH an output URI and its
+		// content hash. Reject either one-sided pairing fail-closed: a hash
+		// without a URI is unanchored, and a URI without a hash is unverifiable.
+		if (child.outputSha256 !== null && child.outputUri === null) {
+			reasons.push(`phase-rollup-child-orphan-output-hash:${child.id}`);
+		}
+		if (child.outputUri !== null && child.outputSha256 === null) {
+			reasons.push(`phase-rollup-child-orphan-output-uri:${child.id}`);
+		}
+		// Per-child ROI accounting must be well-formed before it can be summed
+		// for the recomputed aggregate reconciliation below.
+		if (typeof child.tokens !== "number" || !Number.isFinite(child.tokens) || child.tokens < 0) {
+			reasons.push(`phase-rollup-child-bad-tokens:${child.id}`);
+		} else {
+			tokensFromChildren += child.tokens;
+		}
+		if (child.costTotal !== null) {
+			if (typeof child.costTotal !== "number" || !Number.isFinite(child.costTotal) || child.costTotal < 0) {
+				reasons.push(`phase-rollup-child-bad-cost:${child.id}`);
+			} else {
+				anyCost = true;
+				costFromChildren += child.costTotal;
+			}
+		}
+		if (child.clonedTokens !== null) {
+			if (typeof child.clonedTokens !== "number" || !Number.isFinite(child.clonedTokens) || child.clonedTokens < 0) {
+				reasons.push(`phase-rollup-child-bad-cloned-tokens:${child.id}`);
+			} else {
+				anyCloned = true;
+				clonedFromChildren += child.clonedTokens;
+			}
+		}
+		if (typeof child.lowRoi !== "boolean") {
+			reasons.push(`phase-rollup-child-bad-low-roi:${child.id}`);
+		} else if (child.lowRoi) {
+			lowRoiFromChildren.push(child.id);
+		}
+	}
+	const aggregate = e.aggregate;
+	if (!aggregate || typeof aggregate.childCount !== "number") {
+		reasons.push("phase-rollup-missing-aggregate");
+		return reasons;
+	}
+	if (aggregate.childCount !== e.children.length) reasons.push("phase-rollup-child-count-mismatch");
+	if (aggregate.completed !== completedFromChildren) reasons.push("phase-rollup-aggregate-completed-mismatch");
+	if (aggregate.failed !== failedFromChildren) reasons.push("phase-rollup-aggregate-failed-mismatch");
+	for (const field of ["totalTokens", "completed", "failed"] as const) {
+		const value = aggregate[field];
+		if (typeof value !== "number" || !Number.isFinite(value) || value < 0) {
+			reasons.push(`phase-rollup-aggregate-bad-${field}`);
+		}
+	}
+	for (const field of ["totalCostTotal", "totalClonedTokens"] as const) {
+		const value = aggregate[field];
+		if (value !== null && (typeof value !== "number" || !Number.isFinite(value) || value < 0)) {
+			reasons.push(`phase-rollup-aggregate-bad-${field}`);
+		}
+	}
+	// Recompute the ROI aggregates from child evidence and fail closed on any
+	// self-reported total that does not reconcile. `null` is the canonical
+	// "no child reported this metric" value, mirroring the builder.
+	if (aggregate.totalTokens !== tokensFromChildren) {
+		reasons.push("phase-rollup-aggregate-tokens-mismatch");
+	}
+	if (!numbersReconcile(aggregate.totalCostTotal, anyCost ? costFromChildren : null)) {
+		reasons.push("phase-rollup-aggregate-cost-mismatch");
+	}
+	if (!numbersReconcile(aggregate.totalClonedTokens, anyCloned ? clonedFromChildren : null)) {
+		reasons.push("phase-rollup-aggregate-cloned-tokens-mismatch");
+	}
+	if (!Array.isArray(aggregate.lowRoiChildIds)) {
+		reasons.push("phase-rollup-aggregate-bad-lowRoiChildIds");
+	} else if (!sameIdSet(aggregate.lowRoiChildIds, lowRoiFromChildren)) {
+		reasons.push("phase-rollup-aggregate-low-roi-mismatch");
+	}
+	return reasons;
+}
+
 function validateVanish(e: VanishEvidence): string[] {
 	const reasons: string[] = [];
 	if (!e || typeof e.gitDelta !== "string") return ["vanish-missing-evidence"];
@@ -230,6 +455,9 @@ function validateCompletion(e: CompletionEvidence): string[] {
 		reasons.push("completion-missing-validation-receipts");
 	}
 	if (Array.isArray(e.blockers) && e.blockers.length > 0) reasons.push("completion-has-blockers");
+	// NOTE: evidence.finalLifecycle vs the lifecycle target is reconciled
+	// fail-closed at the ingest layer (`evidenceContradiction` ->
+	// `evidence-lifecycle-mismatch`), where the actual transition is gated.
 	return reasons;
 }
 

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

@@ -36,6 +36,8 @@ export interface HarnessRpc {
 	isLive?(): boolean;
 	/** ISO timestamp of the last observed event frame, or null. */
 	lastFrameAt?(): string | null;
+	/** Final assistant text from the live session (for review-verdict extraction); null when unavailable. */
+	getLastAssistantText?(): Promise<string | null>;
 }
 
 export interface AcceptanceResult {
@@ -240,6 +242,12 @@ export class GajaeCodeRpc implements HarnessRpc {
 		};
 	}
 
+	async getLastAssistantText(): Promise<string | null> {
+		const res = await this.#send({ type: "get_last_assistant_text" });
+		const data = (res.data ?? {}) as Record<string, unknown>;
+		return typeof data.text === "string" ? data.text : null;
+	}
+
 	async sendPrompt(prompt: string): Promise<{ commandId: string; ack: boolean }> {
 		const id = randomUUID();
 		const ackPromise = new Promise<Record<string, unknown>>((resolve, reject) => {

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

@@ -29,6 +29,33 @@ export function isReviewVerdict(value: unknown): value is ReviewVerdict {
 	return typeof value === "string" && (REVIEW_VERDICTS as readonly string[]).includes(value);
 }
 
+/**
+ * Alias verdict tokens accepted from free-form assistant text, mapped to their canonical verdict.
+ * `MERGE_READY` is treated as `APPROVE_MERGE_READY`.
+ */
+const VERDICT_ALIASES: Readonly<Record<string, ReviewVerdict>> = {
+	MERGE_READY: "APPROVE_MERGE_READY",
+};
+
+/**
+ * Extract a single closed-vocabulary review verdict from free-form assistant text.
+ *
+ * Scans for canonical verdict tokens (and accepted aliases) as whole words and returns the
+ * LAST occurrence — the agent's final stated decision wins over any earlier mention. Returns
+ * null when no allowed token is present, so the finalizer fails closed on a missing verdict.
+ */
+export function extractReviewVerdict(text: string | null | undefined): ReviewVerdict | null {
+	if (typeof text !== "string" || text.length === 0) return null;
+	const tokens = [...REVIEW_VERDICTS, ...Object.keys(VERDICT_ALIASES)];
+	const pattern = new RegExp(`\\b(${tokens.join("|")})\\b`, "g");
+	let last: ReviewVerdict | null = null;
+	for (const match of text.matchAll(pattern)) {
+		const token = match[1];
+		last = VERDICT_ALIASES[token] ?? (token as ReviewVerdict);
+	}
+	return last;
+}
+
 /** Lifecycle states of an operated session. */
 export type HarnessLifecycle =
 	| "new"
@@ -68,7 +95,8 @@ export type ReceiptFamily =
 	| "validation"
 	| "completion"
 	| "review-verdict"
-	| "review-failure";
+	| "review-failure"
+	| "phase-rollup";
 
 /** The CLI verbs / primitives exposed by `gjc harness <verb>`. */
 export type HarnessVerb =