@gajae-code/coding-agent 0.11.4 → 0.11.5

package/src/gjc-runtime/tmux-owner-isolation.ts

@@ -11,6 +11,7 @@ import * as fsSync from "node:fs";
 import * as fs from "node:fs/promises";
 
 import * as path from "node:path";
+import { openRecoveryFsRoot } from "@gajae-code/natives";
 import { isCompiledBinary } from "@gajae-code/utils/env";
 import { parseLinuxProcStartTime } from "./linux-proc";
 
@@ -1046,6 +1047,122 @@ function sameOwnerGenerationBaseline(left: OwnerGenerationBaseline, right: Owner
 	);
 }
 
+export interface ManagedOwnerPredecessorEvidence {
+	generation: string;
+	sessionId: string;
+	runId: string;
+	incarnation: string;
+	predecessorToken: string;
+}
+
+function exactManagedOwnerJson(authority: ReturnType<typeof openRecoveryFsRoot>, name: string): unknown {
+	const first = authority.read(name, 64 * 1024);
+	if (!first.ok || !first.data) throw new Error("managed_owner_replacement_evidence_unavailable");
+	const second = authority.read(name, 64 * 1024);
+	if (
+		!second.ok ||
+		!second.data ||
+		Buffer.compare(Buffer.from(first.data), Buffer.from(second.data)) !== 0 ||
+		JSON.stringify(first.identity) !== JSON.stringify(second.identity)
+	)
+		throw new Error("managed_owner_replacement_evidence_changed");
+	const content = Buffer.from(first.data).toString("utf8");
+	if (!content.endsWith("\n") || content.indexOf("\n") !== content.length - 1)
+		throw new Error("managed_owner_replacement_evidence_untrusted");
+	return JSON.parse(content);
+}
+
+/** Resolve one SIGABRT predecessor from the retained exact prior-generation root. */
+export function resolveManagedOwnerPredecessorSync(
+	stateDir: string,
+	sessionId: string,
+	baseline: OwnerGenerationBaseline,
+): ManagedOwnerPredecessorEvidence | undefined {
+	if (baseline.state === "absent") return undefined;
+	const root = lifecyclePaths(stateDir, sessionId, baseline.generation).root;
+	let entries: string[];
+	try {
+		entries = fsSync.readdirSync(root);
+	} catch {
+		throw new Error("managed_owner_replacement_evidence_unavailable");
+	}
+	const bindings = new Set<string>();
+	const receipts = new Set<string>();
+	for (const entry of entries) {
+		const binding = /^child-([^/]+)\.binding\.json$/.exec(entry);
+		const receipt = /^sigabrt-([^/]+)\.receipt\.json$/.exec(entry);
+		if (entry.startsWith("child-") && !binding) throw new Error("managed_owner_replacement_evidence_untrusted");
+		if (entry.startsWith("sigabrt-") && !receipt) throw new Error("managed_owner_replacement_evidence_untrusted");
+		if (binding) bindings.add(binding[1]!);
+		if (receipt) receipts.add(receipt[1]!);
+	}
+	if (bindings.size === 0 && receipts.size === 0) return undefined;
+	const tokens = [...bindings].filter(token => receipts.has(token));
+	if (tokens.length !== 1 || receipts.size !== 1) throw new Error("managed_owner_replacement_evidence_ambiguous");
+	const predecessorToken = tokens[0]!;
+	if (!/^[A-Za-z0-9._-]+$/.test(predecessorToken)) throw new Error("managed_owner_replacement_evidence_untrusted");
+	const authority = openRecoveryFsRoot(root);
+	try {
+		const binding = exactManagedOwnerJson(authority, `child-${predecessorToken}.binding.json`) as Record<
+			string,
+			unknown
+		>;
+		const receipt = exactManagedOwnerJson(authority, `sigabrt-${predecessorToken}.receipt.json`) as Record<
+			string,
+			unknown
+		>;
+		const command = binding.command;
+		const runId = binding.run_id;
+		const incarnation = binding.endpoint_incarnation;
+		const commandDigest =
+			Array.isArray(command) && command.length > 0 && command.every(value => typeof value === "string" && value)
+				? crypto.createHash("sha256").update(JSON.stringify(command)).digest("hex")
+				: "";
+		const valid =
+			binding.schema_version === 2 &&
+			binding.generation === baseline.generation &&
+			binding.session_id === sessionId &&
+			typeof runId === "string" &&
+			runId.length > 0 &&
+			typeof incarnation === "string" &&
+			incarnation.length > 0 &&
+			binding.child_token === predecessorToken &&
+			binding.command_sha256 === commandDigest &&
+			typeof binding.supervisor_pid === "number" &&
+			Number.isSafeInteger(binding.supervisor_pid) &&
+			binding.supervisor_pid > 0 &&
+			typeof binding.supervisor_start_time === "string" &&
+			typeof binding.created_at === "string" &&
+			receipt.schema_version === 2 &&
+			receipt.generation === binding.generation &&
+			receipt.session_id === binding.session_id &&
+			receipt.run_id === runId &&
+			receipt.endpoint_incarnation === incarnation &&
+			receipt.child_token === binding.child_token &&
+			receipt.command_sha256 === binding.command_sha256 &&
+			receipt.supervisor_pid === binding.supervisor_pid &&
+			receipt.supervisor_start_time === binding.supervisor_start_time &&
+			typeof receipt.child_pid === "number" &&
+			Number.isSafeInteger(receipt.child_pid) &&
+			receipt.child_pid > 0 &&
+			typeof receipt.child_start_time === "string" &&
+			typeof receipt.received_at === "string" &&
+			(receipt.exit_code === null || Number.isSafeInteger(receipt.exit_code)) &&
+			receipt.signal === "SIGABRT" &&
+			receipt.signal_number === 6;
+		if (!valid) throw new Error("managed_owner_replacement_evidence_untrusted");
+		return {
+			generation: baseline.generation,
+			sessionId,
+			runId,
+			incarnation,
+			predecessorToken,
+		};
+	} finally {
+		authority.close();
+	}
+}
+
 export async function captureOwnerGenerationBaseline(
 	stateDir: string,
 	sessionId: string,

package/src/gjc-runtime/ultragoal-owner-loss-recovery.ts

@@ -0,0 +1,328 @@
+import { createHash } from "node:crypto";
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { openRecoveryFsRoot } from "@gajae-code/natives";
+import type { ManagedOwnerSigabrtReceipt } from "./managed-owner-supervisor";
+import { sessionStateDir, sessionUltragoalDir } from "./session-layout";
+import { appendJsonlIdempotent, writeJsonAtomic } from "./state-writer";
+
+/** Immutable identity supplied by the owner-loss monitor and coordinator admission. */
+export interface UltragoalRecoveryBinding {
+	sessionId: string;
+	endpointIncarnation: string;
+	ownerGeneration: string;
+	cwd: string;
+}
+
+export interface UltragoalOwnerLossReceipt {
+	schema_version: 1;
+	session_id: string;
+	generation: string;
+	classification: "unexpected_owner_loss";
+	result: "signal" | "exit" | "unknown_terminal";
+	observed_at: string;
+}
+
+export type AuthoritativeOwnerLossReceipt = UltragoalOwnerLossReceipt | ManagedOwnerSigabrtReceipt;
+
+export interface UltragoalRecoverySnapshot {
+	/** B0 is captured once before recovery writes. P is protected and never rewritten. */
+	b0: { planSha256: string; ledgerSha256: string; capturedAt: string };
+	protectedPaths: string[];
+	/** Exact sanctioned deltas, never inferred from a worktree scan. */
+	sanctionedDeltas: string[];
+	/** Durable baseline-absent artifacts. */
+	absentArtifacts: string[];
+	/** Transient paths deliberately excluded from provenance. */
+	transientHistory: string[];
+}
+
+export type UltragoalRecoveryDisposition = "resume" | "handoff";
+export interface UltragoalRecoveryDecision {
+	disposition: UltragoalRecoveryDisposition;
+	reason: string;
+	snapshot?: UltragoalRecoverySnapshot;
+	terminal?: { yieldId: string; result: Record<string, unknown> };
+}
+
+interface TranscriptYield {
+	type: "yield";
+	id: string;
+	parentId: string | null;
+	result: Record<string, unknown>;
+}
+
+function nonEmpty(value: unknown): value is string {
+	return typeof value === "string" && value.trim().length > 0;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function exactChild(
+	entry: Record<string, unknown>,
+	parentId: string | null,
+): entry is Record<string, unknown> & { id: string } {
+	return entry.parentId === parentId && nonEmpty(entry.id);
+}
+
+function digest(bytes: Uint8Array): string {
+	return createHash("sha256").update(bytes).digest("hex");
+}
+
+function safeRelativePath(root: string, candidate: string): string | null {
+	const relative = path.relative(root, candidate);
+	if (!relative || relative === ".." || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) return null;
+	return relative;
+}
+
+async function bytesOrAbsent(filePath: string): Promise<Uint8Array | null> {
+	try {
+		return await fs.readFile(filePath);
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "ENOENT") return null;
+		throw error;
+	}
+}
+
+/**
+ * Parse the complete transcript; partial rows, alternate terminal spellings, and
+ * duplicate/conflicting yields are intentionally invalid authority.
+ */
+export function parseStrictTerminalTranscript(content: string): TranscriptYield | null {
+	if (!content?.endsWith("\n")) return null;
+	const entries: Array<Record<string, unknown> & { id: string }> = [];
+	let parentId: string | null = null;
+	for (const line of content.slice(0, -1).split("\n")) {
+		if (!line) return null;
+		let parsed: unknown;
+		try {
+			parsed = JSON.parse(line);
+		} catch {
+			return null;
+		}
+		if (!isRecord(parsed) || !nonEmpty(parsed.type) || !exactChild(parsed, parentId)) return null;
+		if (
+			parsed.type !== "yield" &&
+			parsed.type !== "toolResult" &&
+			parsed.type !== "tool_call" &&
+			parsed.type !== "message" &&
+			parsed.type !== "mode_change"
+		)
+			return null;
+		entries.push(parsed);
+		parentId = parsed.id;
+	}
+	if (entries.length < 2) return null;
+	if (entries.filter(entry => entry.type === "yield").length !== 1) return null;
+	const yieldEntry = entries[entries.length - 2]!;
+	const resultEntry = entries[entries.length - 1]!;
+	if (yieldEntry.type !== "yield" || !isRecord(yieldEntry.result) || resultEntry.type !== "toolResult") return null;
+	if (resultEntry.toolCallId !== yieldEntry.id || !Array.isArray(resultEntry.content)) return null;
+	return {
+		type: "yield",
+		id: yieldEntry.id,
+		parentId: yieldEntry.parentId as string | null,
+		result: yieldEntry.result,
+	};
+}
+
+/** Read through a retained root descriptor; pathname resolution never authorizes recovery input. */
+async function readRecoveryFile(root: string, candidate: string): Promise<string | null> {
+	if (process.platform !== "linux") return null;
+	const relative = safeRelativePath(path.resolve(root), path.resolve(candidate));
+	if (!relative) return null;
+	try {
+		const authority = openRecoveryFsRoot(root);
+		try {
+			const result = authority.read(relative, 4 * 1024 * 1024);
+			return result.ok && result.data ? new TextDecoder().decode(result.data) : null;
+		} finally {
+			authority.close();
+		}
+	} catch {
+		return null;
+	}
+}
+
+/** Validate a path through a retained native root descriptor; path strings alone are never authority. */
+export async function validateRecoveryPath(root: string, candidate: string): Promise<string | null> {
+	return (await readRecoveryFile(root, candidate)) === null ? null : candidate;
+}
+
+export function validateOwnerLossBinding(
+	binding: UltragoalRecoveryBinding,
+	receipt: unknown,
+): receipt is AuthoritativeOwnerLossReceipt {
+	if (!isRecord(receipt) || receipt.session_id !== binding.sessionId || receipt.generation !== binding.ownerGeneration)
+		return false;
+	if (receipt.schema_version === 2)
+		return (
+			receipt.signal === "SIGABRT" &&
+			receipt.signal_number === 6 &&
+			nonEmpty(receipt.run_id) &&
+			receipt.endpoint_incarnation === binding.endpointIncarnation &&
+			nonEmpty(receipt.child_token) &&
+			nonEmpty(receipt.command_sha256) &&
+			typeof receipt.supervisor_pid === "number" &&
+			Number.isSafeInteger(receipt.supervisor_pid) &&
+			receipt.supervisor_pid > 0 &&
+			typeof receipt.child_pid === "number" &&
+			Number.isSafeInteger(receipt.child_pid) &&
+			receipt.child_pid > 0 &&
+			nonEmpty(receipt.supervisor_start_time) &&
+			nonEmpty(receipt.child_start_time) &&
+			(receipt.exit_code === null || Number.isSafeInteger(receipt.exit_code)) &&
+			nonEmpty(receipt.received_at) &&
+			Number.isFinite(Date.parse(receipt.received_at))
+		);
+	return false;
+}
+
+/** Admission is valid only for this immutable coordinator endpoint incarnation. */
+export function validateRecoveryAdmission(binding: UltragoalRecoveryBinding, admission: unknown): boolean {
+	if (!isRecord(admission)) return false;
+	return (
+		admission.session_id === binding.sessionId &&
+		admission.endpoint_incarnation === binding.endpointIncarnation &&
+		admission.owner_generation === binding.ownerGeneration &&
+		admission.admitted === true
+	);
+}
+
+/** Raw plan and ledger evidence must be complete before their B0 hashes are trusted. */
+export function validateRawUltragoalEvidence(plan: Uint8Array, ledger: Uint8Array): boolean {
+	try {
+		const parsedPlan: unknown = JSON.parse(new TextDecoder().decode(plan));
+		if (!isRecord(parsedPlan) || !Array.isArray(parsedPlan.goals)) return false;
+		const content = new TextDecoder().decode(ledger);
+		if (!content.endsWith("\n")) return false;
+		for (const line of content.slice(0, -1).split("\n")) {
+			if (!line || !isRecord(JSON.parse(line))) return false;
+		}
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+/** Build a B0 snapshot without consulting unrelated paths or mutable sidecars. */
+export async function captureUltragoalRecoverySnapshot(input: {
+	cwd: string;
+	sessionId: string;
+	protectedPaths: readonly string[];
+	sanctionedDeltas: readonly string[];
+	absentArtifacts: readonly string[];
+	transientHistory: readonly string[];
+}): Promise<UltragoalRecoverySnapshot | null> {
+	const root = sessionUltragoalDir(input.cwd, input.sessionId);
+	const [plan, ledger] = await Promise.all([
+		bytesOrAbsent(path.join(root, "goals.json")),
+		bytesOrAbsent(path.join(root, "ledger.jsonl")),
+	]);
+	if (!plan || !ledger || !validateRawUltragoalEvidence(plan, ledger)) return null;
+	const allPaths = [
+		...input.protectedPaths,
+		...input.sanctionedDeltas,
+		...input.absentArtifacts,
+		...input.transientHistory,
+	];
+	if (allPaths.some(value => !nonEmpty(value) || path.isAbsolute(value) || value.split(/[\\/]/).includes("..")))
+		return null;
+	const sets = [input.protectedPaths, input.sanctionedDeltas, input.absentArtifacts, input.transientHistory].map(
+		values => new Set(values),
+	);
+	if (
+		sets.some((set, index) =>
+			sets.some((other, otherIndex) => otherIndex > index && [...set].some(value => other.has(value))),
+		)
+	)
+		return null;
+	return {
+		b0: { planSha256: digest(plan), ledgerSha256: digest(ledger), capturedAt: new Date().toISOString() },
+		protectedPaths: [...input.protectedPaths],
+		sanctionedDeltas: [...input.sanctionedDeltas],
+		absentArtifacts: [...input.absentArtifacts],
+		transientHistory: [...input.transientHistory],
+	};
+}
+
+/**
+ * Decide only from direct owner evidence plus a complete terminal transcript.
+ * All ambiguity maps to durable handoff; callers never guess a resume.
+ */
+export async function planUltragoalOwnerLossRecovery(input: {
+	binding: UltragoalRecoveryBinding;
+	receipt: unknown;
+	admission: unknown;
+
+	transcriptPath: string;
+	protectedPaths?: readonly string[];
+	sanctionedDeltas?: readonly string[];
+	absentArtifacts?: readonly string[];
+	transientHistory?: readonly string[];
+}): Promise<UltragoalRecoveryDecision> {
+	if (!validateOwnerLossBinding(input.binding, input.receipt))
+		return { disposition: "handoff", reason: "owner_receipt_untrusted" };
+	const content = await readRecoveryFile(input.binding.cwd, input.transcriptPath);
+	if (!validateRecoveryAdmission(input.binding, input.admission))
+		return { disposition: "handoff", reason: "coordinator_admission_untrusted" };
+	if (content === null) return { disposition: "handoff", reason: "transcript_path_untrusted" };
+	const terminal = parseStrictTerminalTranscript(content);
+	if (!terminal) return { disposition: "handoff", reason: "terminal_transcript_missing_or_invalid" };
+	if (terminal.result.status !== "success") return { disposition: "handoff", reason: "terminal_aborted_errored" };
+	const snapshot = await captureUltragoalRecoverySnapshot({
+		cwd: input.binding.cwd,
+		sessionId: input.binding.sessionId,
+		protectedPaths: input.protectedPaths ?? ["goals.json", "ledger.jsonl"],
+		sanctionedDeltas: input.sanctionedDeltas ?? [],
+		absentArtifacts: input.absentArtifacts ?? [],
+		transientHistory: input.transientHistory ?? [],
+	});
+	if (!snapshot) return { disposition: "handoff", reason: "baseline_or_path_invariant_failed" };
+	return {
+		disposition: "resume",
+		reason: "terminal_transcript_authoritative",
+		snapshot,
+		terminal: { yieldId: terminal.id, result: terminal.result },
+	};
+}
+
+/** Persist a monotonic replay journal and fail-closed handoff through sanctioned state writers. */
+export async function persistUltragoalRecoveryDecision(input: {
+	cwd: string;
+	sessionId: string;
+	binding: UltragoalRecoveryBinding;
+	decision: UltragoalRecoveryDecision;
+}): Promise<{ handoffPath: string; journalPath: string }> {
+	const stateDir = sessionStateDir(input.cwd, input.sessionId);
+	const handoffPath = path.join(stateDir, "ultragoal-owner-loss-recovery.json");
+	const journalPath = path.join(stateDir, "ultragoal-owner-loss-recovery.jsonl");
+	const record = {
+		schema_version: 1,
+		binding: input.binding,
+		disposition: input.decision.disposition,
+		reason: input.decision.reason,
+		snapshot: input.decision.snapshot ?? null,
+		terminal: input.decision.terminal ?? null,
+		created_at: new Date().toISOString(),
+	};
+	await writeJsonAtomic(handoffPath, record, {
+		cwd: input.cwd,
+		audit: { category: "state", verb: "write", owner: "gjc-runtime", sessionId: input.sessionId },
+	});
+	await appendJsonlIdempotent(
+		journalPath,
+		{ ...record, event: "owner_loss_recovery_decision" },
+		{
+			cwd: input.cwd,
+			audit: { category: "state", verb: "write", owner: "gjc-runtime", sessionId: input.sessionId },
+			key: entry => {
+				if (!isRecord(entry) || entry.event !== "owner_loss_recovery_decision") return undefined;
+				return `${entry.binding === undefined ? "" : JSON.stringify(entry.binding)}:${String(entry.disposition)}:${String(entry.reason)}`;
+			},
+		},
+	);
+	return { handoffPath, journalPath };
+}

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

@@ -33,6 +33,20 @@ import {
 	writeGuardedJsonAtomic,
 } from "./state-writer";
 
+export {
+	captureUltragoalRecoverySnapshot,
+	parseStrictTerminalTranscript,
+	persistUltragoalRecoveryDecision,
+	planUltragoalOwnerLossRecovery,
+	type UltragoalOwnerLossReceipt,
+	type UltragoalRecoveryBinding,
+	type UltragoalRecoveryDecision,
+	type UltragoalRecoverySnapshot,
+	validateOwnerLossBinding,
+	validateRawUltragoalEvidence,
+	validateRecoveryAdmission,
+	validateRecoveryPath,
+} from "./ultragoal-owner-loss-recovery";
 export type UltragoalGjcGoalMode = "aggregate" | "per-story";
 export type UltragoalGoalStatus =
 	| "pending"

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

@@ -115,6 +115,8 @@ export interface OwnerOptions {
 	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;
@@ -150,6 +152,11 @@ export class RuntimeOwner {
 	#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[];
@@ -179,6 +186,7 @@ export class RuntimeOwner {
 			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;
@@ -230,9 +238,23 @@ export class RuntimeOwner {
 		this.#leaseHeld = true;
 		this.#leaseEpoch = lease.leaseEpoch;
 		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().catch(() => {});
+			// 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?.();
@@ -876,6 +898,14 @@ export class RuntimeOwner {
 		}
 		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);
@@ -892,12 +922,38 @@ export class RuntimeOwner {
 		}
 		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;
+		}
+		// 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);
+	}
 }
 
 export interface ResolvedOwner {

package/src/hindsight/client.ts

@@ -12,6 +12,8 @@ import type { HindsightConfig } from "./config";
 
 const USER_AGENT = "oh-my-gajae-code";
 const DEFAULT_USER_AGENT = USER_AGENT;
+const REQUEST_TIMEOUT_MS = 30_000;
+const RESPONSE_MAX_BYTES = 8 * 1024 * 1024;
 
 export type Budget = "low" | "mid" | "high" | string;
 export type TagsMatch = "any" | "all" | "any_strict" | "all_strict";
@@ -210,6 +212,49 @@ interface RequestOptions {
 	allow404?: boolean;
 }
 
+class ResponseTooLargeError extends Error {}
+
+async function readResponseText(response: Response): Promise<string> {
+	const contentLength = response.headers.get("content-length");
+	if (contentLength !== null) {
+		const declaredBytes = Number(contentLength);
+		if (Number.isFinite(declaredBytes) && declaredBytes > RESPONSE_MAX_BYTES) {
+			void response.body?.cancel().catch(() => undefined);
+			throw new ResponseTooLargeError();
+		}
+	}
+
+	const reader = response.body?.getReader();
+	if (!reader) return "";
+
+	const chunks: Uint8Array[] = [];
+	let totalBytes = 0;
+	try {
+		while (true) {
+			const { done, value } = await reader.read();
+			if (done) break;
+			if (!value || value.byteLength === 0) continue;
+
+			totalBytes += value.byteLength;
+			if (totalBytes > RESPONSE_MAX_BYTES) {
+				void reader.cancel().catch(() => undefined);
+				throw new ResponseTooLargeError();
+			}
+			chunks.push(value);
+		}
+	} finally {
+		reader.releaseLock();
+	}
+
+	const bytes = new Uint8Array(totalBytes);
+	let offset = 0;
+	for (const chunk of chunks) {
+		bytes.set(chunk, offset);
+		offset += chunk.byteLength;
+	}
+	return new TextDecoder().decode(bytes);
+}
+
 export class HindsightApi {
 	#baseUrl: string;
 	#headers: Record<string, string>;
@@ -489,7 +534,8 @@ export class HindsightApi {
 			if (qs) url += `?${qs}`;
 		}
 
-		const init: RequestInit = { method, headers: this.#headers };
+		const requestSignal = AbortSignal.timeout(REQUEST_TIMEOUT_MS);
+		const init: RequestInit = { method, headers: this.#headers, signal: requestSignal };
 		if (opts?.body !== undefined) {
 			init.body = JSON.stringify(pruneUndefined(opts.body));
 		}
@@ -498,6 +544,9 @@ export class HindsightApi {
 		try {
 			response = await fetch(url, init);
 		} catch (err) {
+			if (requestSignal.aborted) {
+				throw new HindsightError(`${operation} request failed: timed out`);
+			}
 			throw new HindsightError(
 				`${operation} request failed: ${err instanceof Error ? err.message : String(err)}`,
 				undefined,
@@ -506,10 +555,24 @@ export class HindsightApi {
 		}
 
 		if (opts?.allow404 && response.status === 404) {
+			await response.body?.cancel().catch(() => undefined);
 			return null as T;
 		}
 
-		const text = await response.text();
+		let text: string;
+		try {
+			text = await readResponseText(response);
+		} catch (err) {
+			const reason = requestSignal.aborted
+				? "timed out"
+				: err instanceof ResponseTooLargeError
+					? "response exceeded size limit"
+					: "response could not be read";
+			throw new HindsightError(`${operation} request failed: ${reason}`, response.status);
+		}
+		if (requestSignal.aborted) {
+			throw new HindsightError(`${operation} request failed: timed out`, response.status);
+		}
 		const parsed = text ? safeJsonParse(text) : null;
 
 		if (!response.ok) {