@gajae-code/coding-agent 0.4.3 → 0.4.5

package/src/cursor.ts

@@ -161,7 +161,20 @@ function formatMcpToolErrorMessage(toolName: string, availableTools: string[]):
 }
 
 export class CursorExecHandlers implements ICursorExecHandlers {
-	constructor(private options: CursorExecBridgeOptions) {}
+	constructor(private options: CursorExecBridgeOptions) {
+		// Bind every native handler so methods stay instance-safe when invoked
+		// detached/unbound by the Cursor provider (e.g. `const read = handlers.read`).
+		// Without this, `this.#optionsForCall()` throws "undefined is not an object".
+		this.read = this.read.bind(this);
+		this.ls = this.ls.bind(this);
+		this.grep = this.grep.bind(this);
+		this.write = this.write.bind(this);
+		this.delete = this.delete.bind(this);
+		this.shell = this.shell.bind(this);
+		this.shellStream = this.shellStream.bind(this);
+		this.diagnostics = this.diagnostics.bind(this);
+		this.mcp = this.mcp.bind(this);
+	}
 
 	#optionsForCall(): CursorExecBridgeOptions {
 		return {
@@ -185,9 +198,24 @@ export class CursorExecHandlers implements ICursorExecHandlers {
 
 	async grep(args: Parameters<NonNullable<ICursorExecHandlers["grep"]>>[0]) {
 		const toolCallId = decodeToolCallId(args.toolCallId);
+		// Cursor's native Glob tool arrives as a grep exec with a glob but no content
+		// pattern. The search tool requires a non-empty pattern, so an empty pattern
+		// means "list files matching this glob" — route that to find instead of
+		// throwing "Pattern must not be empty".
+		const pattern = typeof args.pattern === "string" ? args.pattern : "";
+		if (pattern.trim().length === 0) {
+			if (args.glob) {
+				const globPath = `${args.path || "."}/${args.glob}`;
+				return executeTool(this.#optionsForCall(), "find", toolCallId, { paths: [globPath] });
+			}
+			const result = buildToolErrorResult(
+				"Cursor grep request rejected: pattern must not be empty. Provide a non-empty search pattern.",
+			);
+			return createToolResultMessage(toolCallId, "search", result, true);
+		}
 		const searchPath = args.glob ? `${args.path || "."}/${args.glob}` : args.path || ".";
 		const toolResultMessage = await executeTool(this.#optionsForCall(), "search", toolCallId, {
-			pattern: args.pattern,
+			pattern,
 			paths: [searchPath],
 			i: args.caseInsensitive || undefined,
 		});

package/src/extensibility/extensions/types.ts

@@ -122,6 +122,19 @@ export interface ExtensionUIDialogOptions {
 	 * select-only rendering hint; non-TUI bridges drop it and do not serialize it.
 	 */
 	scrollTitleRows?: number;
+	/**
+	 * For interactive TUI select dialogs, handle the option with `optionLabel`
+	 * inline: selecting it keeps the title and option list on screen and opens
+	 * a free-text input below the list. Submitting calls `onSubmit` with the
+	 * typed text and resolves the select with `optionLabel`; Escape returns to
+	 * option selection. Non-TUI bridges (RPC, ACP) drop it; callers must keep
+	 * a fallback path for selects that resolve `optionLabel` without invoking
+	 * `onSubmit`.
+	 */
+	customInput?: {
+		optionLabel: string;
+		onSubmit: (text: string) => void;
+	};
 }
 
 /** Raw terminal input listener for extensions. */

package/src/gjc-runtime/launch-worktree.ts

@@ -140,6 +140,17 @@ function readWorktreeEntryFromPath(repoRoot: string, worktreePath: string): GitW
 	return { path: path.resolve(worktreePath), head, branchRef, detached: !branchRef };
 }
 
+function resolveCanonicalRepoRoot(cwd: string): string {
+	const repoRoot = runGit(cwd, ["rev-parse", "--show-toplevel"]);
+	const commonDir = tryRunGit(repoRoot, ["rev-parse", "--git-common-dir"]);
+	if (!commonDir) return repoRoot;
+	const resolvedCommonDir = path.resolve(repoRoot, commonDir);
+	if (path.basename(resolvedCommonDir) !== ".git") return repoRoot;
+	const ownerRoot = path.dirname(resolvedCommonDir);
+	if (tryRunGit(ownerRoot, ["rev-parse", "--is-inside-work-tree"]) !== "true") return repoRoot;
+	return ownerRoot;
+}
+
 function isWorktreeDirty(worktreePath: string): boolean {
 	return runGit(worktreePath, ["status", "--porcelain"]).length > 0;
 }
@@ -187,7 +198,7 @@ export function planLaunchWorktree(
 	mode: GjcLaunchWorktreeMode,
 ): GjcLaunchWorktreePlan | { enabled: false } {
 	if (!mode.enabled) return { enabled: false };
-	const repoRoot = runGit(cwd, ["rev-parse", "--show-toplevel"]);
+	const repoRoot = resolveCanonicalRepoRoot(cwd);
 	const baseRef = runGit(repoRoot, ["rev-parse", "HEAD"]);
 	const branchName = mode.detached ? null : mode.name;
 	if (branchName) validateBranchName(repoRoot, branchName);

package/src/gjc-runtime/session-state-sidecar.ts

@@ -0,0 +1,117 @@
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import type { AssistantMessage } from "@gajae-code/ai";
+import { logger } from "@gajae-code/utils";
+
+export const GJC_COORDINATOR_SESSION_STATE_FILE_ENV = "GJC_COORDINATOR_SESSION_STATE_FILE";
+export const GJC_COORDINATOR_SESSION_ID_ENV = "GJC_COORDINATOR_SESSION_ID";
+
+type RuntimeState = "ready_for_input" | "running" | "needs_user_input" | "completed" | "errored";
+
+interface RuntimeStateEvent {
+	type: string;
+	messages?: unknown[];
+}
+
+interface RuntimeStateContext {
+	sessionId: string;
+	cwd: string;
+	sessionFile?: string | null;
+}
+
+function lastAssistant(messages: unknown[] | undefined): AssistantMessage | undefined {
+	if (!messages) return undefined;
+	for (let index = messages.length - 1; index >= 0; index--) {
+		const message = messages[index];
+		if (message && typeof message === "object" && (message as { role?: unknown }).role === "assistant") {
+			return message as AssistantMessage;
+		}
+	}
+	return undefined;
+}
+
+function assistantText(assistant: AssistantMessage | undefined): string | null {
+	if (!assistant) return null;
+	const text = assistant.content
+		.filter(part => part.type === "text")
+		.map(part => part.text)
+		.join("\n")
+		.trim();
+	return text.length > 0 ? text : null;
+}
+
+function finalResponseForEvent(event: RuntimeStateEvent): {
+	text: string | null;
+	format: "markdown";
+	source: "agent_end";
+	artifact_path: null;
+	truncated: false;
+} | null {
+	if (event.type !== "agent_end") return null;
+	return {
+		text: assistantText(lastAssistant(event.messages)),
+		format: "markdown",
+		source: "agent_end",
+		artifact_path: null,
+		truncated: false,
+	};
+}
+
+function stateForEvent(event: RuntimeStateEvent): RuntimeState | null {
+	if (event.type === "agent_start" || event.type === "turn_start") return "running";
+	if (event.type === "agent_end") {
+		const assistant = lastAssistant(event.messages);
+		return assistant?.stopReason === "error" ? "errored" : "completed";
+	}
+	if (event.type === "notice") return null;
+	return null;
+}
+
+export async function persistCoordinatorRuntimeStateFromEvent(
+	event: RuntimeStateEvent,
+	context: RuntimeStateContext,
+): Promise<void> {
+	const stateFile = process.env[GJC_COORDINATOR_SESSION_STATE_FILE_ENV]?.trim();
+	if (!stateFile) return;
+	const state = stateForEvent(event);
+	if (!state) return;
+	const now = new Date().toISOString();
+	let previous: Record<string, unknown> = {};
+	try {
+		previous = JSON.parse(await Bun.file(stateFile).text()) as Record<string, unknown>;
+	} catch {
+		previous = {};
+	}
+	const finalResponse = finalResponseForEvent(event);
+	const payload = {
+		schema_version: 1,
+		session_id: process.env[GJC_COORDINATOR_SESSION_ID_ENV]?.trim() || context.sessionId,
+		state,
+		ready_for_input: state === "completed" || state === "ready_for_input",
+		updated_at: now,
+		current_turn_id: typeof previous.current_turn_id === "string" ? previous.current_turn_id : null,
+		last_turn_id: typeof previous.last_turn_id === "string" ? previous.last_turn_id : null,
+		live: typeof previous.live === "boolean" ? previous.live : null,
+		reason: null,
+		source: "agent_session_event",
+		event: event.type,
+		cwd: context.cwd,
+		session_file: context.sessionFile ?? null,
+		...(finalResponse ? { final_response: finalResponse } : {}),
+		...(state === "errored"
+			? {
+					error: {
+						code: "agent_error",
+						message: lastAssistant(event.messages)?.errorMessage ?? "agent_error",
+						recoverable: true,
+					},
+				}
+			: {}),
+	};
+	try {
+		await fs.mkdir(path.dirname(stateFile), { recursive: true });
+		await Bun.write(stateFile, `${JSON.stringify(payload, null, 2)}\n`);
+	} catch (error) {
+		logger.warn("Failed to persist coordinator runtime state", { error: String(error), stateFile });
+	}
+}

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

@@ -19,11 +19,12 @@ import {
 	type ReceiptSubject,
 	type ReviewFailureEvidence,
 	type ReviewVerdictEvidence,
+	sha256Hex,
 	type ValidationEvidence,
 	validateReceipt,
 } from "./receipts";
 import { readReceiptIndex, writeReceiptImmutable } from "./storage";
-import { isReviewVerdict, type ReviewVerdict } from "./types";
+import { extractReviewVerdict, isReviewVerdict, type ReviewVerdict } from "./types";
 
 export interface ValidationCommandSpec {
 	name: string;
@@ -56,6 +57,11 @@ export interface FinalizeOptions {
 	reviewOnly?: boolean;
 	/** Operator/loop-supplied terminal review verdict (closed vocabulary). */
 	verdict?: string | null;
+	/**
+	 * Final assistant text from the live RPC owner, used to extract a closed-vocabulary verdict
+	 * for review-only sessions when no explicit {@link verdict} is supplied. Never persisted raw.
+	 */
+	assistantText?: 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[];
@@ -78,6 +84,14 @@ function receiptId(prefix: string): string {
 	return `${prefix}-${Date.now()}-${randomBytes(4).toString("hex")}`;
 }
 
+/** Bound + whitespace-collapse assistant text into a redaction-safe digest summary (never a raw dump). */
+function boundedAssistantSummary(text: string | null): string | null {
+	if (!text) return null;
+	const collapsed = text.replace(/\s+/g, " ").trim();
+	if (collapsed.length === 0) return null;
+	return collapsed.length > 280 ? `${collapsed.slice(0, 280)}…` : collapsed;
+}
+
 export async function runFinalize(opts: FinalizeOptions): Promise<FinalizeResult> {
 	if (opts.reviewOnly) return runReviewFinalize(opts);
 
@@ -214,9 +228,27 @@ async function runReviewFinalize(opts: FinalizeOptions): Promise<FinalizeResult>
 		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" };
+	// Explicit operator/loop verdict always wins. Only when none is supplied do we fall back to
+	// extracting a closed-vocabulary verdict from the live RPC owner's final assistant text.
+	const explicitProvided = opts.verdict != null;
+	const explicitValid = isReviewVerdict(opts.verdict);
+	const assistantText = typeof opts.assistantText === "string" ? opts.assistantText : null;
+	const extracted = explicitProvided ? null : extractReviewVerdict(assistantText);
+	const verdict: ReviewVerdict | null = explicitValid ? (opts.verdict as ReviewVerdict) : extracted;
+	const verdictSource: "input" | "assistant" = explicitValid ? "input" : "assistant";
+
+	if (!verdict) {
+		const reason = explicitProvided ? "review-verdict-invalid" : "review-verdict-missing";
+		const assistantDigest = assistantText ? sha256Hex(assistantText) : null;
+		const assistantSummary = boundedAssistantSummary(assistantText);
+		const failure: ReviewFailureEvidence = {
+			reason,
+			prTarget,
+			failedAt: now(),
+			fallback: "operator-or-omx-review",
+			...(assistantDigest ? { assistantDigest } : {}),
+			...(assistantSummary ? { assistantSummary } : {}),
+		};
 		const receipt = buildReceipt<ReviewFailureEvidence>({
 			receiptId: receiptId("revfail"),
 			sessionId: opts.sessionId,
@@ -238,12 +270,14 @@ async function runReviewFinalize(opts: FinalizeOptions): Promise<FinalizeResult>
 		return { ...baseResult, completed: false, receiptPath: entry.path, verdict: null, blockers };
 	}
 
-	const verdict = opts.verdict as ReviewVerdict;
+	const assistantDigest = verdictSource === "assistant" && assistantText ? sha256Hex(assistantText) : null;
 	const evidence: ReviewVerdictEvidence = {
 		verdict,
 		prTarget,
 		finalizedAt: now(),
 		summaryRef: typeof opts.prTarget === "string" ? `verdict:${verdict}@${opts.prTarget}` : `verdict:${verdict}`,
+		verdictSource,
+		...(assistantDigest ? { assistantDigest } : {}),
 	};
 	const receipt = buildReceipt<ReviewVerdictEvidence>({
 		receiptId: receiptId("verdict"),

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

@@ -504,13 +504,21 @@ export class RuntimeOwner {
 		const workspace = state.handle.workspace;
 		const checks = this.#finalizeChecks ?? defaultFinalizeChecks(workspace);
 		const reviewOnly = state.handle.mode === "review";
+		const inputVerdict = reviewOnly ? (typeof input.verdict === "string" ? input.verdict : null) : undefined;
+		// Review-only finalize with no explicit verdict pulls the final assistant text from the live
+		// RPC owner so the verdict can be extracted deterministically instead of demanded from the operator.
+		let assistantText: string | null = null;
+		if (reviewOnly && inputVerdict == null && this.#opts.rpc.getLastAssistantText) {
+			assistantText = await this.#opts.rpc.getLastAssistantText().catch(() => null);
+		}
 		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,
+			verdict: inputVerdict,
+			assistantText: reviewOnly ? assistantText : undefined,
 			prTarget: reviewOnly ? state.handle.issueOrPr : undefined,
 			requireTests: input.requireTests !== false,
 			requireCommit: input.requireCommit !== false,

package/src/harness-control-plane/phase-rollup.ts

@@ -0,0 +1,96 @@
+/**
+ * Phase-boundary receipt rollup builder (receipt-of-receipts).
+ *
+ * At a harness lifecycle boundary, N child task receipts can be superseded by a
+ * single `phase-rollup` receipt that preserves per-child pointers (id, status,
+ * outputRef, sha256) plus aggregate ROI totals. The rollup is hash-sealed via
+ * the standard receipt envelope and validated fail-closed like every other
+ * family (see `validatePhaseRollup` in receipts.ts). Pure builder — no runtime
+ * injection behavior is changed here.
+ */
+import type { TaskResultReceipt } from "../task/receipt";
+import {
+	type BuildReceiptInput,
+	buildReceipt,
+	canonicalJson,
+	type PhaseRollupChildPointer,
+	type PhaseRollupEvidence,
+	type ReceiptEnvelope,
+	sha256Hex,
+} from "./receipts";
+
+function childPointer(receipt: TaskResultReceipt): PhaseRollupChildPointer {
+	const ref = receipt.outputRef;
+	// Receipt-of-receipts integrity requires BOTH a pointer URI and its content
+	// hash. A URI without a verifiable hash cannot be integrity-checked, so we
+	// drop the (one-sided) pointer entirely rather than emit an unverifiable ref
+	// that the fail-closed validator would reject.
+	const hasVerifiableRef = Boolean(ref?.uri) && Boolean(ref?.sha256);
+	return {
+		id: receipt.id,
+		status: receipt.status,
+		outputUri: hasVerifiableRef ? (ref?.uri ?? null) : null,
+		outputSha256: hasVerifiableRef ? (ref?.sha256 ?? null) : null,
+		// Normalize through JSON first: in-memory task receipts carry optional
+		// fields with value `undefined`, which canonicalJson would hash as
+		// `null` while persisted/parsed receipts omit those keys entirely.
+		// JSON round-tripping drops undefined-valued keys so the hash is
+		// identical for in-memory and rehydrated copies of the same receipt.
+		receiptSha256: sha256Hex(canonicalJson(JSON.parse(JSON.stringify(receipt)))),
+		// Per-child ROI accounting so the rollup aggregate is recomputable from
+		// child evidence (see validatePhaseRollup). `tokens` falls back to the
+		// receipt's raw token count when no ROI proxy is present.
+		tokens: receipt.roi?.tokens ?? receipt.tokens,
+		costTotal: receipt.roi?.costTotal ?? null,
+		clonedTokens: receipt.roi?.clonedTokens ?? null,
+		lowRoi: receipt.roi?.lowRoi ?? false,
+	};
+}
+
+export interface BuildPhaseRollupInput {
+	receiptId: string;
+	sessionId: string;
+	source: string;
+	subject: BuildReceiptInput<PhaseRollupEvidence>["subject"];
+	phase: string;
+	children: readonly TaskResultReceipt[];
+	/** Supply for deterministic output; defaults to now. */
+	createdAt?: string;
+}
+
+export function buildPhaseRollupReceipt(input: BuildPhaseRollupInput): ReceiptEnvelope<PhaseRollupEvidence> {
+	// `null` means "no child reported this metric" — the canonical value the
+	// fail-closed validator reconciles against. Decide presence from whether a
+	// child carried the field at all (not from a >0 sum), so a legitimate
+	// all-zero total reconciles instead of collapsing to null and mismatching.
+	const anyCost = input.children.some(child => (child.roi?.costTotal ?? null) !== null);
+	const anyCloned = input.children.some(child => (child.roi?.clonedTokens ?? null) !== null);
+	const totalCostTotal = anyCost
+		? input.children.reduce((total, child) => total + (child.roi?.costTotal ?? 0), 0)
+		: null;
+	const totalClonedTokens = anyCloned
+		? input.children.reduce((total, child) => total + (child.roi?.clonedTokens ?? 0), 0)
+		: null;
+	const evidence: PhaseRollupEvidence = {
+		phase: input.phase,
+		children: input.children.map(childPointer),
+		aggregate: {
+			childCount: input.children.length,
+			completed: input.children.filter(child => child.status === "completed").length,
+			failed: input.children.filter(child => child.status === "failed" || child.status === "merge_failed").length,
+			totalTokens: input.children.reduce((total, child) => total + (child.roi?.tokens ?? child.tokens), 0),
+			totalCostTotal,
+			totalClonedTokens,
+			lowRoiChildIds: input.children.filter(child => child.roi?.lowRoi).map(child => child.id),
+		},
+	};
+	return buildReceipt({
+		receiptId: input.receiptId,
+		sessionId: input.sessionId,
+		family: "phase-rollup",
+		source: input.source,
+		subject: input.subject,
+		evidence,
+		createdAt: input.createdAt,
+	});
+}

package/src/harness-control-plane/receipt-ingest.ts

@@ -0,0 +1,127 @@
+import type { CompletionEvidence, ReceiptEnvelope, ReviewVerdictEvidence } from "./receipts";
+import { validateReceipt } from "./receipts";
+import { canTransition } from "./state-machine";
+import type { HarnessLifecycle, ReceiptFamily, SessionState } from "./types";
+
+export const RECEIPT_DIGEST_MAX_CHARS = 280;
+
+export const RECEIPT_FAMILY_LIFECYCLE_TARGETS: Partial<Record<ReceiptFamily, HarnessLifecycle>> = {
+	completion: "completed",
+	// Review-only sessions terminate on a valid review verdict rather than a
+	// completion receipt; the finalizer treats valid verdicts as terminal.
+	"review-verdict": "completed",
+};
+
+/**
+ * Family-specific evidence consistency: the lifecycle target must agree with
+ * what the evidence itself claims. Hash validity alone is not enough — a
+ * semantically contradictory receipt must not drive the lifecycle.
+ */
+function evidenceContradiction(receipt: ReceiptEnvelope<unknown>, target: HarnessLifecycle): string | undefined {
+	if (receipt.family === "completion") {
+		const evidence = receipt.evidence as CompletionEvidence;
+		if (evidence.finalLifecycle !== target) {
+			return `evidence-lifecycle-mismatch:${evidence.finalLifecycle}`;
+		}
+	}
+	if (receipt.family === "review-verdict") {
+		const evidence = receipt.evidence as ReviewVerdictEvidence;
+		// Owner confirmation is not a terminal success verdict.
+		if (evidence.verdict === "OWNER_CONFIRMATION_REQUIRED") {
+			return "review-verdict-not-terminal";
+		}
+	}
+	return undefined;
+}
+
+export interface ReceiptIngestResult {
+	accepted: ReceiptEnvelope<unknown>[];
+	rejected: { receipt: ReceiptEnvelope<unknown>; reasons: string[] }[];
+	transitions: { from: HarnessLifecycle; to: HarnessLifecycle; receiptId: string }[];
+	finalLifecycle: HarnessLifecycle;
+	digest: string;
+}
+
+export function ingestReceipts(
+	state: SessionState,
+	receipts: readonly ReceiptEnvelope<unknown>[],
+): ReceiptIngestResult {
+	let lifecycle = state.lifecycle;
+	const accepted: ReceiptEnvelope<unknown>[] = [];
+	const rejected: { receipt: ReceiptEnvelope<unknown>; reasons: string[] }[] = [];
+	const transitions: { from: HarnessLifecycle; to: HarnessLifecycle; receiptId: string }[] = [];
+
+	for (const receipt of receipts) {
+		const validation = validateReceipt(receipt);
+		if (!validation.valid) {
+			rejected.push({ receipt, reasons: validation.reasons });
+			continue;
+		}
+
+		// Fail closed on receipts the envelope itself marks invalid: the hash
+		// can be self-consistent while the issuer recorded the receipt as not
+		// proving its claim.
+		if (receipt.valid !== true) {
+			rejected.push({ receipt, reasons: ["receipt-marked-invalid"] });
+			continue;
+		}
+
+		// Fail closed on cross-session receipts: a self-consistent receipt from
+		// another session must never drive this session's lifecycle.
+		if (receipt.sessionId !== state.sessionId) {
+			rejected.push({ receipt, reasons: [`session-mismatch:${receipt.sessionId}`] });
+			continue;
+		}
+
+		const target = RECEIPT_FAMILY_LIFECYCLE_TARGETS[receipt.family];
+		if (target) {
+			// Non-terminal review verdicts (OWNER_CONFIRMATION_REQUIRED) are
+			// valid receipts but do not complete the session: accept, no move.
+			if (receipt.family === "review-verdict" && evidenceContradiction(receipt, target) !== undefined) {
+				accepted.push(receipt);
+				continue;
+			}
+			// Other contradictions (e.g. completion evidence whose
+			// finalLifecycle disagrees with the target) reject fail-closed.
+			const contradiction = evidenceContradiction(receipt, target);
+			if (contradiction !== undefined) {
+				rejected.push({ receipt, reasons: [contradiction] });
+				continue;
+			}
+			if (!canTransition(lifecycle, target)) {
+				rejected.push({ receipt, reasons: [`illegal-transition:${lifecycle}->${target}`] });
+				continue;
+			}
+
+			transitions.push({ from: lifecycle, to: target, receiptId: receipt.receiptId });
+			lifecycle = target;
+		}
+
+		accepted.push(receipt);
+	}
+
+	return {
+		accepted,
+		rejected,
+		transitions,
+		finalLifecycle: lifecycle,
+		digest: buildReceiptIngestDigest(receipts.length, accepted.length, rejected, state.lifecycle, lifecycle),
+	};
+}
+
+function buildReceiptIngestDigest(
+	total: number,
+	acceptedCount: number,
+	rejected: readonly { receipt: ReceiptEnvelope<unknown>; reasons: readonly string[] }[],
+	initialLifecycle: HarnessLifecycle,
+	finalLifecycle: HarnessLifecycle,
+): string {
+	let digest = `ingested ${total} receipts: ${acceptedCount} accepted, ${rejected.length} rejected; lifecycle ${initialLifecycle}->${finalLifecycle}`;
+	if (rejected.length > 0) {
+		const rejectedSummary = rejected
+			.map(item => `${item.receipt?.receiptId ?? "<malformed>"}(${item.reasons.join("|")})`)
+			.join(",");
+		digest += `; rejected: ${rejectedSummary}`;
+	}
+	return digest.slice(0, RECEIPT_DIGEST_MAX_CHARS);
+}