@sayknow-cli/coding-agent 0.3.16 → 0.4.1

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

@@ -3,7 +3,7 @@
  *
  * Responsibilities:
  *  - hold the {@link SessionLease} (single writer),
- *  - own the {@link HarnessRpc} subprocess (injected; real `SayknowCliRpc` in prod, fake in tests),
+ *  - own an injected SDK session transport,
  *  - serve owner-routed primitives over the {@link ControlServer} endpoint,
  *  - be the SOLE writer of the severity event stream,
  *  - heartbeat the lease.
@@ -15,9 +15,9 @@ import { execFileSync } from "node:child_process";
 import { randomBytes, randomUUID } from "node:crypto";
 import { existsSync } from "node:fs";
 import type { AgentWireOwnerObservation } from "../modes/shared/agent-wire/event-contract";
-import { observeRpcOutboundFrame } from "../modes/shared/agent-wire/event-observation";
+import { observeAgentWireFrame } from "../modes/shared/agent-wire/event-observation";
 import { classifyRecovery } from "./classifier";
-import { ControlServer, type EndpointRequest } from "./control-endpoint";
+import { ControlServer, type EndpointHandler, type EndpointRequest } from "./control-endpoint";
 import { defaultFinalizeChecks, type FinalizeChecks, runFinalize, type ValidationCommandSpec } from "./finalize";
 import { type OperateResult, operate } from "./operate";
 import { preserveDirtyWorktree } from "./preserve";
@@ -30,16 +30,22 @@ import {
 	type VanishEvidence,
 	validateReceipt,
 } from "./receipts";
-import { type HarnessRpc, type RpcStateSnapshot, singleFlightAccept } from "./rpc-adapter";
 import {
 	acquireLease,
 	canWriteEvents,
 	classifyLeaseStatus,
 	heartbeat,
+	LeaseError,
 	readLease,
 	releaseLease,
 	type SessionLease,
 } from "./session-lease";
+import {
+	type HarnessSessionTransport,
+	type HarnessSessionTransportCloseContext,
+	type SessionStateSnapshot,
+	singleFlightAccept,
+} from "./session-transport";
 import { buildStateView, nextAllowedActions, submitUnavailableReason } from "./state-machine";
 import {
 	appendEvent,
@@ -78,10 +84,26 @@ function reconcileLiveOwnerState(state: SessionState): { state: SessionState; re
 	};
 }
 
+function flattenAggregateCauses(errors: readonly unknown[]): unknown[] {
+	const causes: unknown[] = [];
+	for (const error of errors) {
+		if (error instanceof AggregateError) causes.push(...flattenAggregateCauses(error.errors));
+		else causes.push(error);
+	}
+	return causes;
+}
+
+/**
+ * Nominal sentinel: raised only after #stopOnce has verified teardown so the
+ * retry loop can rethrow it immediately. A private class prevents a lookalike
+ * cleanup AggregateError (message collision) from bypassing verification retries.
+ */
+class FramePumpAfterVerifiedCleanupError extends AggregateError {}
+
 export interface OwnerOptions {
 	root: string;
 	sessionId: string;
-	rpc: HarnessRpc;
+	transport: HarnessSessionTransport;
 	ownerId?: string;
 	ttlMs?: number;
 	heartbeatMs?: number;
@@ -89,6 +111,20 @@ export interface OwnerOptions {
 	clock?: () => number;
 	finalizeChecks?: FinalizeChecks;
 	validationCommands?: ValidationCommandSpec[];
+	/** Test seam for deterministic control-endpoint teardown failures. */
+	controlServerFactory?: (socketPath: string, handler: EndpointHandler) => ControlServer;
+	/** Test seam for deterministic lease-release teardown failures. */
+	leaseRelease?: typeof releaseLease;
+	/** Test seam for deterministic lease-heartbeat behavior (e.g. renewal barriers). */
+	leaseHeartbeat?: typeof heartbeat;
+	/** Test seams for frame persistence failures. */
+	framePersistence?: {
+		appendEvent?: typeof appendEvent;
+		writeSessionState?: typeof writeSessionState;
+	};
+	/** Test seams; production retries verified shutdown without a finite limit. */
+	cleanupRetryMs?: number;
+	cleanupRetryLimit?: number;
 }
 
 export interface OwnerStartInfo {
@@ -100,20 +136,40 @@ export interface OwnerStartInfo {
 const DEFAULT_TTL_MS = 30_000;
 const DEFAULT_HEARTBEAT_MS = 10_000;
 const DEFAULT_ACCEPT_TIMEOUT_MS = 60_000;
+const DEFAULT_CLEANUP_RETRY_MS = 500;
+const MAX_RETAINED_CLEANUP_FAILURES = 32;
 
 export class RuntimeOwner {
 	readonly ownerId: string;
-	#opts: Required<Omit<OwnerOptions, "clock" | "finalizeChecks" | "validationCommands">> & { clock?: () => number };
+	#opts: Required<
+		Omit<
+			OwnerOptions,
+			"clock" | "finalizeChecks" | "validationCommands" | "controlServerFactory" | "framePersistence"
+		>
+	> & { clock?: () => number };
 	#server: ControlServer;
 	#cursor = 0;
 	#leaseEpoch = 0;
+	#leaseHeld = false;
 	#heartbeatTimer: NodeJS.Timeout | null = null;
+	#heartbeatFenced = false;
+	// Every renewal the heartbeat interval starts is tracked here until it settles.
+	// Teardown drains the whole set so no already-started renewal can still be
+	// polling the lease mutation lock when releaseLease runs.
+	#heartbeatInFlight = new Set<Promise<unknown>>();
 	#socketPath: string;
 	#finalizeChecks?: FinalizeChecks;
 	#validationCommands?: ValidationCommandSpec[];
 	#unsubscribeFrames: (() => void) | null = null;
 	#framePump: Promise<void> = Promise.resolve();
+	#framePumpFailure: unknown = null;
 	#coalesced = new Map<string, true>();
+	#stopPromise: Promise<void> | null = null;
+	#lastStopFailures: unknown[] = [];
+	#reportedStopFailures = new Set<string>();
+	#transportClosed = false;
+	#serverClosed = false;
+	#framePersistence: Required<NonNullable<OwnerOptions["framePersistence"]>>;
 
 	constructor(opts: OwnerOptions) {
 		this.ownerId = opts.ownerId ?? `owner-${randomUUID()}`;
@@ -121,19 +177,52 @@ export class RuntimeOwner {
 		this.#opts = {
 			root: opts.root,
 			sessionId: opts.sessionId,
-			rpc: opts.rpc,
+			transport: opts.transport,
 			ownerId: this.ownerId,
 			ttlMs: opts.ttlMs ?? DEFAULT_TTL_MS,
 			heartbeatMs: opts.heartbeatMs ?? DEFAULT_HEARTBEAT_MS,
 			acceptanceTimeoutMs: opts.acceptanceTimeoutMs ?? DEFAULT_ACCEPT_TIMEOUT_MS,
 			clock: opts.clock,
+			cleanupRetryMs: opts.cleanupRetryMs ?? DEFAULT_CLEANUP_RETRY_MS,
+			cleanupRetryLimit: opts.cleanupRetryLimit ?? Number.POSITIVE_INFINITY,
+			leaseRelease: opts.leaseRelease ?? releaseLease,
+			leaseHeartbeat: opts.leaseHeartbeat ?? heartbeat,
 		};
 		this.#finalizeChecks = opts.finalizeChecks;
 		this.#validationCommands = opts.validationCommands;
-		this.#server = new ControlServer(this.#socketPath, req => this.#handle(req));
+		this.#framePersistence = {
+			appendEvent: opts.framePersistence?.appendEvent ?? appendEvent,
+			writeSessionState: opts.framePersistence?.writeSessionState ?? writeSessionState,
+		};
+		this.#server = (opts.controlServerFactory ?? ((socketPath, handler) => new ControlServer(socketPath, handler)))(
+			this.#socketPath,
+			req => this.#handle(req),
+		);
 	}
 
 	async start(): Promise<OwnerStartInfo> {
+		try {
+			return await this.#startOnce();
+		} catch (startError) {
+			try {
+				await this.stop();
+			} catch (cleanupError) {
+				const cleanupCauses = flattenAggregateCauses([cleanupError]);
+				throw new AggregateError(
+					[startError, ...cleanupCauses],
+					"Runtime owner startup and exact-child rollback failed.",
+				);
+			}
+			if (this.#lastStopFailures.length > 0)
+				throw new AggregateError(
+					[startError, ...flattenAggregateCauses(this.#lastStopFailures)],
+					"Runtime owner startup failed after retrying exact-child rollback.",
+				);
+			throw startError;
+		}
+	}
+
+	async #startOnce(): Promise<OwnerStartInfo> {
 		const { root, sessionId } = this.#opts;
 		const eventsPath = sessionPaths(root, sessionId).events;
 		const existing = await readEvents(root, sessionId, 0);
@@ -146,19 +235,34 @@ export class RuntimeOwner {
 			ttlMs: this.#opts.ttlMs,
 			clock: this.#opts.clock,
 		});
+		this.#leaseHeld = true;
 		this.#leaseEpoch = lease.leaseEpoch;
-		await this.#server.listen();
-		await this.#emit("info", "owner_started", { ownerId: this.ownerId, leaseEpoch: this.#leaseEpoch });
-		if (this.#opts.rpc.onEventFrame) {
-			this.#unsubscribeFrames = this.#opts.rpc.onEventFrame(frame => this.#handleFrame(frame));
-		}
 		this.#heartbeatTimer = setInterval(() => {
-			void heartbeat(root, sessionId, this.ownerId, this.#opts.ttlMs, this.#opts.clock).catch(err => {
-				// Self-stop if a legitimate dead-owner takeover revoked our lease.
-				if (err instanceof Error && err.message.includes("not_lease_holder")) void this.stop();
+			// Once teardown fences the heartbeat we must never start a renewal again:
+			// a renewal here would contend the lease mutation lock with the release
+			// path and can starve it (lease_lock_timeout).
+			if (this.#heartbeatFenced) return;
+			const renewal = this.#opts
+				.leaseHeartbeat(root, sessionId, this.ownerId, this.#opts.ttlMs, this.#opts.clock)
+				.catch(err => {
+					// Self-stop if a legitimate dead-owner takeover revoked our lease.
+					if (err instanceof Error && err.message.includes("not_lease_holder")) void this.stop().catch(() => {});
+				});
+			// Track every in-flight renewal so teardown can drain them ALL before
+			// releasing the lease. setInterval can start a new renewal before the
+			// previous one settles, and lock acquisition is non-FIFO, so awaiting only
+			// the latest would leave an older renewal able to contend releaseLease.
+			this.#heartbeatInFlight.add(renewal);
+			void renewal.finally(() => {
+				this.#heartbeatInFlight.delete(renewal);
 			});
 		}, this.#opts.heartbeatMs);
 		this.#heartbeatTimer.unref?.();
+		await this.#server.listen();
+		await this.#emit("info", "owner_started", { ownerId: this.ownerId, leaseEpoch: this.#leaseEpoch });
+		if (this.#opts.transport.onEventFrame) {
+			this.#unsubscribeFrames = this.#opts.transport.onEventFrame(frame => this.#handleFrame(frame));
+		}
 		return { ownerId: this.ownerId, socketPath: this.#socketPath, leaseEpoch: this.#leaseEpoch };
 	}
 
@@ -175,13 +279,18 @@ 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 = observeRpcOutboundFrame(frame);
+		const mapped = observeAgentWireFrame(frame);
 		if (!mapped) return;
 		if (mapped.semantic || (mapped.signal && !mapped.coalesceKey)) {
 			this.#framePump = this.#framePump
-				.then(() => this.#flushCoalesced())
-				.then(() => this.#emitMapped(mapped))
-				.catch(() => {});
+				.then(async () => {
+					if (this.#framePumpFailure !== null) return;
+					await this.#flushCoalesced();
+					await this.#emitMapped(mapped);
+				})
+				.catch(error => {
+					if (this.#framePumpFailure === null) this.#framePumpFailure = error;
+				});
 		} else if (mapped.coalesceKey) {
 			// Coalesce progress-noise by key; never enqueues a per-frame emit, so a message_update
 			// storm cannot starve semantic frames. Bound memory.
@@ -197,7 +306,7 @@ export class RuntimeOwner {
 		if (this.#coalesced.size === 0) return;
 		const coalescedFrames = this.#coalesced.size;
 		this.#coalesced.clear();
-		await this.#emit("info", "rpc_activity", { coalescedFrames });
+		await this.#emit("info", "rpc_activity", { coalescedFrames }, true);
 	}
 
 	async #emitMapped(mapped: AgentWireOwnerObservation): Promise<void> {
@@ -211,13 +320,14 @@ export class RuntimeOwner {
 			) {
 				state.lifecycle = "finalizing";
 				state.updatedAt = new Date(this.#opts.clock ? this.#opts.clock() : Date.now()).toISOString();
-				await writeSessionState(this.#opts.root, state);
+				await this.#framePersistence.writeSessionState(this.#opts.root, state);
 			}
 		}
 		await this.#emit(
 			mapped.severity,
 			mapped.kind,
 			mapped.signal ? { ...mapped.evidence, signal: mapped.signal } : mapped.evidence,
+			true,
 		);
 	}
 
@@ -248,7 +358,12 @@ export class RuntimeOwner {
 		return rpcActive ? "rpc-not-idle" : null;
 	}
 
-	async #emit(severity: Severity, kind: string, evidence: Record<string, unknown>): Promise<void> {
+	async #emit(
+		severity: Severity,
+		kind: string,
+		evidence: Record<string, unknown>,
+		framePersistence = false,
+	): Promise<void> {
 		const lease = await readLease(this.#opts.root, this.#opts.sessionId);
 		// Single-writer guard: only emit while we still hold a live lease.
 		if (!lease || !canWriteEvents(lease, this.ownerId, this.#opts.clock)) return;
@@ -274,7 +389,11 @@ export class RuntimeOwner {
 			nextAllowedActions: nextAllowedActions(view.lifecycle, true, { submitUnavailableReason: submitGateReason }),
 			writer: { ownerId: this.ownerId, leaseEpoch: this.#leaseEpoch },
 		};
-		await appendEvent(this.#opts.root, this.#opts.sessionId, envelope);
+		await (framePersistence ? this.#framePersistence.appendEvent : appendEvent)(
+			this.#opts.root,
+			this.#opts.sessionId,
+			envelope,
+		);
 	}
 
 	#response(
@@ -291,7 +410,7 @@ export class RuntimeOwner {
 		};
 	}
 
-	#submitGateReason(state: SessionState, rpcState: RpcStateSnapshot | null): string | null {
+	#submitGateReason(state: SessionState, rpcState: SessionStateSnapshot | null): string | null {
 		const rpcReason = rpcState
 			? rpcState.isStreaming || rpcState.steeringQueueDepth > 0 || rpcState.followupQueueDepth > 0
 				? "rpc-not-idle"
@@ -333,9 +452,9 @@ export class RuntimeOwner {
 		const state = await this.#loadState();
 		const workspace = state.handle.workspace;
 		let streaming = false;
-		let rpcState: RpcStateSnapshot | null = null;
+		let rpcState: SessionStateSnapshot | null = null;
 		try {
-			rpcState = await this.#opts.rpc.getState();
+			rpcState = await this.#opts.transport.getState();
 			streaming = rpcState.isStreaming;
 		} catch {
 			streaming = false;
@@ -366,8 +485,8 @@ export class RuntimeOwner {
 				gitDelta = "unknown";
 			}
 		}
-		const rpcLive = this.#opts.rpc.isLive ? this.#opts.rpc.isLive() : rpcState !== null;
-		const rpcLastFrameAt = this.#opts.rpc.lastFrameAt ? this.#opts.rpc.lastFrameAt() : null;
+		const rpcLive = this.#opts.transport.isLive ? this.#opts.transport.isLive() : rpcState !== null;
+		const rpcLastFrameAt = this.#opts.transport.lastFrameAt ? this.#opts.transport.lastFrameAt() : null;
 		// Sticky semantic signals come from the persisted owner event log -> survive polling gaps.
 		const recent = (await readEvents(this.#opts.root, this.#opts.sessionId, 0)).slice(-200);
 		const observedSignals = this.#aggregateSignals(recent).slice(0, 7);
@@ -519,7 +638,7 @@ export class RuntimeOwner {
 			sessionId: this.#opts.sessionId,
 			workspace: state.handle.workspace,
 			branch: state.handle.branch ?? "",
-			rpc: this.#opts.rpc,
+			transport: this.#opts.transport,
 			observe: () => this.#observeGit(),
 			finalizeChecks: this.#finalizeChecks ?? defaultFinalizeChecks(state.handle.workspace),
 			validationCommands: this.#validationCommands,
@@ -544,8 +663,8 @@ export class RuntimeOwner {
 		// 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);
+		if (reviewOnly && inputVerdict == null && this.#opts.transport.getLastAssistantText) {
+			assistantText = await this.#opts.transport.getLastAssistantText().catch(() => null);
 		}
 		const fin = await runFinalize({
 			root: this.#opts.root,
@@ -595,7 +714,7 @@ export class RuntimeOwner {
 				lifecycleGate,
 			);
 		}
-		const result = await singleFlightAccept(this.#opts.rpc, prompt, this.#opts.acceptanceTimeoutMs);
+		const result = await singleFlightAccept(this.#opts.transport, prompt, this.#opts.acceptanceTimeoutMs);
 		if (result.accepted) {
 			state.lifecycle = "observing";
 			state.updatedAt = new Date(this.#opts.clock ? this.#opts.clock() : Date.now()).toISOString();
@@ -625,7 +744,31 @@ export class RuntimeOwner {
 	}
 
 	async #observe(): Promise<PrimitiveResponse> {
+		// Observation is a read barrier over every frame accepted before this request.
+		// Without it, a fast poll can read state/event storage while the serial frame
+		// pump is still persisting a terminal event, losing sticky completion evidence.
+		await this.#framePump;
 		const state = await this.#loadState();
+		if (this.#framePumpFailure !== null) {
+			const failedState: SessionState = {
+				...state,
+				lifecycle: "blocked",
+				blockers: [...new Set([...state.blockers, "frame-persistence-failed"])],
+			};
+			return this.#response(
+				failedState,
+				{
+					observation: {
+						lifecycle: "blocked",
+						observedSignals: ["frame-persistence-failed"],
+						rpcLive: this.#opts.transport.isLive?.() ?? true,
+					},
+					framePumpFailure: { severity: "critical", error: String(this.#framePumpFailure) },
+					ownerRouted: true,
+				},
+				false,
+			);
+		}
 		const observation = await this.#observeGit();
 		const submitGateReason =
 			typeof observation.submitUnavailableReason === "string" ? observation.submitUnavailableReason : null;
@@ -638,21 +781,178 @@ export class RuntimeOwner {
 		state.updatedAt = new Date(this.#opts.clock ? this.#opts.clock() : Date.now()).toISOString();
 		await writeSessionState(this.#opts.root, state);
 		await this.#emit("info", "owner_retired", {});
-		queueMicrotask(() => void this.stop());
+		queueMicrotask(() => void this.stop().catch(() => {}));
 		return this.#response(state, { retired: true });
 	}
 
-	async stop(): Promise<void> {
-		this.#unsubscribeFrames?.();
-		this.#unsubscribeFrames = null;
-		await this.#framePump.catch(() => {});
+	stop(): Promise<void> {
+		// Every public caller receives the one truthful shared teardown result. Only
+		// the object capability passed to the exact transport.close() invocation can
+		// break a direct cleanup cycle; ambient synchronous callers have no bypass.
+		if (this.#stopPromise) return this.#stopPromise;
+		const pending = Promise.withResolvers<void>();
+		this.#stopPromise = pending.promise;
+		void this.#stopUntilVerified().then(pending.resolve, pending.reject);
+		return pending.promise;
+	}
+
+	#closeTransport(): Promise<void> {
+		let available = true;
+		// `available` is the authority boundary; freezing the wrapper is only
+		// defense-in-depth against mutation by the receiving transport.
+		const context: HarnessSessionTransportCloseContext = Object.freeze({
+			acknowledgeDirectOwnerStopReentry(): Promise<void> {
+				if (!available) throw new Error("Runtime owner direct stop reentry capability is no longer available.");
+				available = false;
+				return Promise.resolve();
+			},
+		});
+		try {
+			return this.#opts.transport.close(context);
+		} finally {
+			// An async close implementation runs synchronously until it returns its
+			// promise. Expire the capability at that boundary so descendants cannot
+			// acquire completion authority after the direct invocation.
+			available = false;
+		}
+	}
+
+	async #stopUntilVerified(): Promise<void> {
+		this.#lastStopFailures = [];
+		this.#reportedStopFailures.clear();
+		for (let attempt = 1; ; attempt++) {
+			try {
+				await this.#stopOnce();
+				if (this.#framePumpFailure !== null) {
+					throw new FramePumpAfterVerifiedCleanupError(
+						[this.#framePumpFailure, ...flattenAggregateCauses(this.#lastStopFailures)],
+						`Runtime owner frame pump failed after verified cleanup: ${String(this.#framePumpFailure)}`,
+					);
+				}
+				return;
+			} catch (error) {
+				if (error instanceof FramePumpAfterVerifiedCleanupError) throw error;
+				if (this.#lastStopFailures.length === MAX_RETAINED_CLEANUP_FAILURES) this.#lastStopFailures.shift();
+				this.#lastStopFailures.push(error);
+				if (attempt >= this.#opts.cleanupRetryLimit)
+					throw new AggregateError(
+						[
+							...(this.#framePumpFailure === null ? [] : [this.#framePumpFailure]),
+							...flattenAggregateCauses(this.#lastStopFailures),
+						],
+						"Runtime owner cleanup could not be verified.",
+					);
+				await Bun.sleep(this.#opts.cleanupRetryMs);
+			}
+		}
+	}
+
+	async #reportStopFailure(kind: string, error: unknown): Promise<unknown | null> {
+		if (this.#reportedStopFailures.has(kind)) return null;
+		this.#reportedStopFailures.add(kind);
+		try {
+			await this.#emit("critical", kind, { error: String(error) });
+			return null;
+		} catch (reportError) {
+			return reportError;
+		}
+	}
+
+	async #stopOnce(): Promise<void> {
+		const failures: unknown[] = [];
+		const recordFailure = async (kind: string, error: unknown): Promise<void> => {
+			failures.push(error);
+			const reportFailure = await this.#reportStopFailure(kind, error);
+			if (reportFailure !== null) failures.push(reportFailure);
+		};
+		const unsubscribe = this.#unsubscribeFrames;
+		if (unsubscribe) {
+			try {
+				unsubscribe();
+				this.#unsubscribeFrames = null;
+			} catch (error) {
+				await recordFailure("owner_unsubscribe_failed", error);
+			}
+		}
+		await this.#framePump;
+
+		// The transport owns the exact spawned child. Do not surrender the lease while
+		// it is unverified; once each stage succeeds, retain that proof across retries.
+		if (!this.#transportClosed) {
+			try {
+				await this.#closeTransport();
+				this.#transportClosed = true;
+			} catch (error) {
+				await recordFailure("owner_transport_stop_failed", error);
+			}
+		}
+		if (!this.#transportClosed) throw new AggregateError(failures, "Runtime owner transport cleanup failed.");
+
+		if (!this.#serverClosed) {
+			try {
+				await this.#server.close();
+				this.#serverClosed = true;
+			} catch (error) {
+				await recordFailure("owner_server_stop_failed", error);
+			}
+		}
+		if (!this.#serverClosed) throw new AggregateError(failures, "Runtime owner endpoint cleanup failed.");
+
+		// Transport and endpoint are verified closed, so we are committed to
+		// surrendering the lease. Stop, fence, and join the heartbeat first: an
+		// in-flight or scheduled renewal would otherwise contend the lease mutation
+		// lock with releaseLease and can starve it (lease_lock_timeout). Fencing
+		// before release preserves exact-owner fencing — a fenced owner never renews,
+		// so it can neither revive its own lease nor touch a successor's.
+		await this.#fenceHeartbeat();
+
+		if (this.#leaseHeld) {
+			try {
+				await this.#opts.leaseRelease(this.#opts.root, this.#opts.sessionId, this.ownerId);
+				this.#leaseHeld = false;
+			} catch (error) {
+				if (error instanceof LeaseError && error.code === "not_lease_holder") {
+					// A successor already owns the lease. Our transport and endpoint are
+					// verified closed, so there is no old authority left to release.
+					this.#leaseHeld = false;
+				} else {
+					await recordFailure("owner_lease_release_failed", error);
+				}
+			}
+		}
+		if (this.#leaseHeld) throw new AggregateError(failures, "Runtime owner lease cleanup failed.");
+
+		// Heartbeat was already fenced before the lease release above; this is a
+		// defensive no-op that also covers any path that skipped the release stage.
+		if (this.#heartbeatTimer) {
+			clearInterval(this.#heartbeatTimer);
+			this.#heartbeatTimer = null;
+		}
+		if (failures.length > 0) throw new AggregateError(failures, "Runtime owner cleanup failed.");
+	}
+
+	/**
+	 * Permanently stop the lease heartbeat and drain every in-flight renewal.
+	 *
+	 * Fencing is terminal: `#heartbeatFenced` stays set so no scheduled interval
+	 * callback can start a new renewal after teardown begins. The interval is
+	 * cleared, then EVERY renewal already started (there may be more than one, since
+	 * `setInterval` does not wait for the async `heartbeat()` of a prior tick) is
+	 * awaited so each releases the lease mutation lock before the release path
+	 * acquires it. This eliminates heartbeat/release self-contention on the
+	 * non-FIFO lock (lease_lock_timeout) without weakening exact-owner fencing.
+	 */
+	async #fenceHeartbeat(): Promise<void> {
+		this.#heartbeatFenced = true;
 		if (this.#heartbeatTimer) {
 			clearInterval(this.#heartbeatTimer);
 			this.#heartbeatTimer = null;
 		}
-		await this.#server.close().catch(() => {});
-		await this.#opts.rpc.close().catch(() => {});
-		await releaseLease(this.#opts.root, this.#opts.sessionId, this.ownerId).catch(() => {});
+		// Snapshot then drain: no new renewal can be added once fenced, so this
+		// settles every renewal that could still hold or be waiting on the lock.
+		const inFlight = [...this.#heartbeatInFlight];
+		this.#heartbeatInFlight.clear();
+		if (inFlight.length > 0) await Promise.allSettled(inFlight);
 	}
 }
 

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

@@ -1,12 +1,9 @@
 /**
- * Phase-boundary receipt rollup builder (receipt-of-receipts).
+ * EXPERIMENTAL: 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.
+ * This builder is not wired into finalize or retire yet; child receipts remain
+ * authoritative until a lifecycle integration preserves their supersession
+ * semantics. It is retained for controlled integration experiments only.
  */
 import type { TaskResultReceipt } from "../task/receipt";
 import {

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

@@ -1,3 +1,8 @@
+/**
+ * EXPERIMENTAL: Receipt ingestion is a pure evaluator and is not yet wired to
+ * finalize or retire lifecycle mutation. Callers must not treat its result as
+ * authoritative lifecycle persistence.
+ */
 import type { CompletionEvidence, ReceiptEnvelope, ReviewVerdictEvidence } from "./receipts";
 import { validateReceipt } from "./receipts";
 import { canTransition } from "./state-machine";