@sayknow-cli/coding-agent 0.2.2

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/preserve.ts

@@ -0,0 +1,102 @@
+/**
+ * Real dirty-worktree preservation (architect blocker B2).
+ *
+ * Before any destructive recovery on a dirty/unknown worktree, capture REAL evidence and a
+ * recoverable snapshot WITHOUT mutating the working tree:
+ *   - the tracked diff (`git diff HEAD`) + its sha256,
+ *   - an untracked-file manifest (path/size/sha256),
+ *   - a `git stash create` commit object stored in the stash list (`git stash store`),
+ *     which snapshots tracked+staged changes without touching the worktree.
+ *
+ * This is what backs a valid `vanish` receipt so the data-loss invariant is enforced in
+ * practice, not just structurally.
+ */
+import { execFileSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+import * as path from "node:path";
+import type { GitDelta } from "./types";
+
+export interface UntrackedEntry {
+	path: string;
+	size: number;
+	sha256: string;
+}
+
+export interface PreserveResult {
+	gitDelta: GitDelta;
+	trackedDiff: string;
+	trackedDiffSha256: string;
+	untrackedManifest: UntrackedEntry[];
+	stashRef: string | null;
+	snapshotComplete: boolean;
+}
+
+function git(workspace: string, args: string[]): string {
+	return execFileSync("git", args, { cwd: workspace, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] });
+}
+
+function sha256(input: string | Buffer): string {
+	return createHash("sha256").update(input).digest("hex");
+}
+
+/**
+ * Capture + snapshot a (possibly dirty) worktree without mutating it. Safe to call on a clean
+ * tree (returns empty evidence). Never deletes, resets, or cleans.
+ */
+export function preserveDirtyWorktree(workspace: string): PreserveResult {
+	let trackedDiff = "";
+	try {
+		trackedDiff = git(workspace, ["diff", "HEAD"]);
+	} catch {
+		trackedDiff = "";
+	}
+
+	let untracked: string[] = [];
+	try {
+		untracked = git(workspace, ["ls-files", "--others", "--exclude-standard"])
+			.split("\n")
+			.map(s => s.trim())
+			.filter(Boolean);
+	} catch {
+		untracked = [];
+	}
+
+	const untrackedManifest: UntrackedEntry[] = [];
+	for (const rel of untracked) {
+		try {
+			const buf = readFileSync(path.join(workspace, rel));
+			untrackedManifest.push({ path: rel, size: buf.length, sha256: sha256(buf) });
+		} catch {
+			// unreadable entry — record path with a marker rather than dropping it
+			untrackedManifest.push({ path: rel, size: -1, sha256: "unreadable" });
+		}
+	}
+
+	// `git stash create` builds a stash commit WITHOUT modifying the working tree; store it so
+	// it survives in the stash list as a recoverable ref. No-op (empty oid) on a clean tree.
+	let stashRef: string | null = null;
+	try {
+		const oid = git(workspace, ["stash", "create", "harness-vanish-snapshot"]).trim();
+		if (oid) {
+			git(workspace, ["stash", "store", "-m", "harness-vanish-snapshot", oid]);
+			stashRef = oid;
+		}
+	} catch {
+		stashRef = null;
+	}
+
+	const dirty = trackedDiff.trim().length > 0 || untrackedManifest.length > 0;
+	// snapshotComplete iff every dirty component is actually captured: tracked changes need a
+	// stash ref, untracked entries need readable hashes.
+	const trackedCaptured = trackedDiff.trim().length === 0 || stashRef !== null;
+	const untrackedCaptured = untrackedManifest.every(e => e.sha256 !== "unreadable");
+	return {
+		gitDelta: dirty ? "dirty" : "clean",
+		trackedDiff,
+		trackedDiffSha256: sha256(trackedDiff),
+		untrackedManifest,
+		stashRef,
+		snapshotComplete: trackedCaptured && untrackedCaptured,
+	};
+}

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);
+}

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

@@ -0,0 +1,128 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { withFileLock } from "../config/file-lock";
+import type { ReceiptEnvelope } from "./receipts";
+
+export const RECEIPT_SPOOL_DIR_ENV = "SKC_RECEIPT_SPOOL_DIR";
+export const RECEIPT_SPOOL_FILENAME = "spool.jsonl";
+export const RECEIPT_SPOOL_CURSOR_WIDTH = 12;
+
+export interface ReceiptSpoolRecord {
+	cursor: string;
+	envelope: ReceiptEnvelope<unknown>;
+}
+
+export interface ReceiptSpoolAppendResult {
+	cursor: string;
+	path: string;
+}
+
+const receiptSpoolDirStorage = new AsyncLocalStorage<string | undefined>();
+const spoolQueues = new Map<string, Promise<void>>();
+const noop = (): void => undefined;
+export async function withReceiptSpoolDir<T>(spoolDir: string, fn: () => Promise<T>): Promise<T> {
+	const trimmed = spoolDir.trim();
+	if (!trimmed) throw new Error("receipt_spool_dir_empty");
+	const resolved = path.resolve(trimmed);
+	return receiptSpoolDirStorage.run(resolved, fn);
+}
+
+export function resolveReceiptSpoolDir(env: NodeJS.ProcessEnv = process.env): string | undefined {
+	const active = receiptSpoolDirStorage.getStore();
+	if (active !== undefined) return active;
+	const raw = env[RECEIPT_SPOOL_DIR_ENV]?.trim();
+	return raw ? path.resolve(raw) : undefined;
+}
+
+export function receiptSpoolPath(spoolDir: string): string {
+	return path.join(path.resolve(spoolDir), RECEIPT_SPOOL_FILENAME);
+}
+
+function parseCursor(value: unknown): bigint | undefined {
+	if (typeof value !== "string" || !/^\d+$/.test(value)) return undefined;
+	try {
+		return BigInt(value);
+	} catch {
+		return undefined;
+	}
+}
+
+export function formatReceiptSpoolCursor(cursor: bigint): string {
+	const raw = cursor.toString();
+	return raw.length >= RECEIPT_SPOOL_CURSOR_WIDTH ? raw : raw.padStart(RECEIPT_SPOOL_CURSOR_WIDTH, "0");
+}
+
+export async function readHighestReceiptSpoolCursor(spoolDir: string): Promise<bigint> {
+	const spoolFile = receiptSpoolPath(spoolDir);
+	let raw: string;
+	try {
+		raw = await fs.readFile(spoolFile, "utf8");
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "ENOENT") return 0n;
+		throw error;
+	}
+
+	let highest = 0n;
+	for (const line of raw.split("\n")) {
+		const trimmed = line.trim();
+		if (!trimmed) continue;
+		try {
+			const parsed = JSON.parse(trimmed) as { cursor?: unknown };
+			const cursor = parseCursor(parsed.cursor);
+			if (cursor !== undefined && cursor > highest) highest = cursor;
+		} catch {
+			// A crash may leave a torn tail; consumers skip malformed lines and so do we.
+		}
+	}
+	return highest;
+}
+
+async function enqueueSpoolAppend<T>(spoolFile: string, task: () => Promise<T>): Promise<T> {
+	const previous = spoolQueues.get(spoolFile) ?? Promise.resolve();
+	const running = previous.catch(noop).then(task);
+	const normalized = running.then(noop, noop);
+	spoolQueues.set(spoolFile, normalized);
+	normalized
+		.finally(() => {
+			if (spoolQueues.get(spoolFile) === normalized) spoolQueues.delete(spoolFile);
+		})
+		.catch(noop);
+	return running;
+}
+
+export async function appendReceiptToSpool(
+	spoolDir: string,
+	envelope: ReceiptEnvelope<unknown>,
+): Promise<ReceiptSpoolAppendResult> {
+	const resolvedDir = path.resolve(spoolDir);
+	const spoolFile = receiptSpoolPath(resolvedDir);
+	return enqueueSpoolAppend(spoolFile, async () => {
+		await fs.mkdir(resolvedDir, { recursive: true, mode: 0o700 });
+		return withFileLock(
+			spoolFile,
+			async () => {
+				const cursor = formatReceiptSpoolCursor((await readHighestReceiptSpoolCursor(resolvedDir)) + 1n);
+				const record: ReceiptSpoolRecord = { cursor, envelope };
+				const handle = await fs.open(spoolFile, "a", 0o600);
+				try {
+					await handle.writeFile(`${JSON.stringify(record)}\n`, "utf8");
+					await handle.sync();
+				} finally {
+					await handle.close();
+				}
+				return { cursor, path: spoolFile };
+			},
+			{ staleMs: 30_000, retries: 100, retryDelayMs: 25 },
+		);
+	});
+}
+
+export async function appendReceiptToConfiguredSpool(
+	envelope: ReceiptEnvelope<unknown>,
+	env: NodeJS.ProcessEnv = process.env,
+): Promise<ReceiptSpoolAppendResult | undefined> {
+	const spoolDir = resolveReceiptSpoolDir(env);
+	if (!spoolDir) return undefined;
+	return appendReceiptToSpool(spoolDir, envelope);
+}