@gajae-code/coding-agent 0.18.6 → 0.18.8

package/src/sdk/broker/session-index.ts

@@ -3,7 +3,7 @@ import * as fs from "node:fs/promises";
 import path from "node:path";
 import { logger, resolveEquivalentPath } from "@gajae-code/utils";
 import { nativeProcessBindings } from "@gajae-code/utils/native-process";
-import { withFileLock } from "../../config/file-lock";
+import { type FileLockOptions, isFileLockAcquireTimeout, withFileLock } from "../../config/file-lock";
 import { repo } from "../../utils/git";
 import { endpointIncarnation } from "./endpoint-authority";
 import { processIncarnation } from "./process-incarnation";
@@ -653,6 +653,7 @@ function reduceEvents(
 	now: number,
 	agentDir: string,
 	probedIncarnations?: ReadonlyMap<string, string | undefined>,
+	sessionIds?: ReadonlySet<string>,
 ): SessionIndexProjection {
 	// Resolved once: the fence-row check runs per root, and only this side of the
 	// comparison is ours to normalize.
@@ -669,7 +670,12 @@ function reduceEvents(
 		}
 		return identity;
 	};
-	const { admitted } = admitEvents(events);
+	// Admission and projection are keyed by sessionId (tuple, tombstone, identity),
+	// so a scoped read reduces only the requested sessions' events and skips the
+	// other sessions' pid/incarnation probes without changing their rows.
+	const { admitted } = admitEvents(
+		sessionIds === undefined ? events : events.filter(event => sessionIds.has(event.sessionId)),
+	);
 	const latestByIdentity = new Map<string, SessionIndexEvent>();
 	const latestHeartbeatByIdentity = new Map<string, SessionIndexEvent>();
 	for (const event of admitted) {
@@ -797,6 +803,16 @@ const SESSION_INDEX_PROBE_FRESHNESS_MS = 50;
  * and the next pass re-probes from scratch.
  */
 const SESSION_INDEX_REPLAY_FRESHNESS_MS = 2_000;
+/**
+ * Fresh re-probe attempts one heartbeat checkpoint pass makes when its
+ * observation batch goes stale under lock contention. Each attempt is fully
+ * fail-closed; the bound only prevents a contended machine from writing no
+ * heartbeat for long enough that live hosts project as dead.
+ */
+const SESSION_HEARTBEAT_CHECKPOINT_ATTEMPTS = 4;
+/** One elapsed budget for queueing, probing and every reacquisition in a pass. */
+const SESSION_HEARTBEAT_CHECKPOINT_BUDGET_MS = 15_000;
+const STALE_OBSERVATION: unique symbol = Symbol("stale-heartbeat-observation");
 /** Maximum distinct live identity probes admitted by one public status query. */
 const SESSION_GENERATION_PROBE_LIMIT = 32;
 
@@ -807,10 +823,16 @@ const SESSION_GENERATION_PROBE_LIMIT = 32;
  * observation window and (b) the lock budget cannot silently drift per call
  * site.
  */
-function withSessionIndexLock<T>(operation: string, agentDir: string, callback: () => Promise<T>): Promise<T> {
+function withSessionIndexLock<T>(
+	operation: string,
+	agentDir: string,
+	callback: () => Promise<T>,
+	options: FileLockOptions = SESSION_INDEX_LOCK_OPTIONS,
+): Promise<T> {
 	return withFileLock(
 		logFor(agentDir),
 		async () => {
+			options.signal?.throwIfAborted();
 			// Armed only once the lock is actually held: queueing time behind another
 			// legitimate holder must not be attributed to this operation.
 			const note = setTimeout(
@@ -826,7 +848,7 @@ function withSessionIndexLock<T>(operation: string, agentDir: string, callback:
 				clearTimeout(note);
 			}
 		},
-		SESSION_INDEX_LOCK_OPTIONS,
+		options,
 	);
 }
 function isValidSnapshot(snapshot: unknown): snapshot is { indexSeq: number; events: SessionIndexEvent[] } {
@@ -1195,32 +1217,39 @@ export class SessionIndex {
 	 * stamp of the last completed locked pass, the in-memory projection is
 	 * already current and the locked rescan is skipped entirely — this is what
 	 * keeps an idle SessionRouter reconcile (2s cadence) from re-parsing and
-	 * re-checksumming the whole index forever. An append committed before the
-	 * stat always changes the stamp, so a miss is impossible; a change landing
-	 * after the stat is seen on the next poll, the same TOCTOU envelope a
-	 * locked read has. A corrupt suffix never takes the fast path: re-scanning
+	 * re-checksumming the whole index forever. The unchanged check runs before
+	 * the local queue so unrelated heartbeat work cannot delay ordinary creates.
+	 * Admission that requires serialized authority must use refresh() instead.
+	 * An append committed before the stat always changes
+	 * the stamp; a change landing after the stat is seen on the next poll, the
+	 * same TOCTOU envelope a locked read has. A corrupt suffix never takes the fast path: re-scanning
 	 * preserves the existing re-diagnosis behavior. Returns true when state was
 	 * reloaded. Authority revalidation that needs the strongest available
 	 * snapshot inside an already-locked write (append, unregister) keeps using
 	 * the exact locked paths.
 	 */
 	async refreshIfChanged(): Promise<boolean> {
-		if (this.#changeStamp !== undefined && !this.#corruptSuffix) {
+		if (this.#changeStamp === undefined || this.#corruptSuffix) {
+			await this.open();
+			await this.refresh();
+			return true;
+		}
+		const stamp = await readIndexChangeStamp(this.#agentDir);
+		if (sameIndexChangeStamp(this.#changeStamp, stamp)) return false;
+		const indexPath = path.resolve(logFor(this.#agentDir));
+		return await SessionIndex.#enqueue(indexPath, async () => {
+			if (this.#changeStamp === undefined || this.#corruptSuffix) {
+				await withSessionIndexLock("poll-refresh", this.#agentDir, () => this.#refreshUnderLock());
+				return true;
+			}
 			const stamp = await readIndexChangeStamp(this.#agentDir);
 			if (sameIndexChangeStamp(this.#changeStamp, stamp)) return false;
 			// A possible change is re-classified UNDER the lock (#4689 review):
 			// writers mutate these files only while holding it, so the locked
-			// observation is atomic with the tail/replay it selects. The
-			// unlocked stamp above is only the cheap "definitely unchanged" cut.
-			const indexPath = path.resolve(logFor(this.#agentDir));
-			await SessionIndex.#enqueue(indexPath, () =>
-				withSessionIndexLock("poll-refresh", this.#agentDir, () => this.#refreshOrReplayUnderLock()),
-			);
+			// observation is atomic with the tail/replay it selects.
+			await withSessionIndexLock("poll-refresh", this.#agentDir, () => this.#refreshOrReplayUnderLock());
 			return true;
-		}
-		await this.open();
-		await this.refresh();
-		return true;
+		});
 	}
 	/**
 	 * Locked change classification (#4689). Append-only log growth with an
@@ -1327,6 +1356,10 @@ export class SessionIndex {
 	}
 	/** Seed the audit dedupe set once, then append records for newly-rejected events. */
 	async #writeAuditUnderLock(): Promise<void> {
+		const candidates = auditRecords(this.#events, this.#policy.clock());
+		// The audit log only dedupes rejections, so a reader with none never pays
+		// for loading it.
+		if (candidates.length === 0) return;
 		if (this.#auditedSeq === null) {
 			this.#auditedSeq = new Set();
 			try {
@@ -1344,9 +1377,7 @@ export class SessionIndex {
 				if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
 			}
 		}
-		const pending = auditRecords(this.#events, this.#policy.clock()).filter(
-			record => !this.#auditedSeq!.has(record.indexSeq),
-		);
+		const pending = candidates.filter(record => !this.#auditedSeq!.has(record.indexSeq));
 		if (pending.length === 0) return;
 		await appendSync(auditFor(this.#agentDir), pending.map(record => JSON.stringify(record)).join("\n"));
 		for (const record of pending) this.#auditedSeq.add(record.indexSeq);
@@ -1956,10 +1987,18 @@ export class SessionIndex {
 		this.#changeStamp = await readIndexChangeStamp(this.#agentDir);
 	}
 
-	listSessions(probedIncarnations?: ReadonlyMap<string, string | undefined>): SessionList {
+	/**
+	 * Public session rows. `sessionIds` scopes the projection to those sessions:
+	 * rows for them are identical to the unscoped read, other sessions are absent.
+	 */
+	listSessions(
+		probedIncarnations?: ReadonlyMap<string, string | undefined>,
+		sessionIds?: ReadonlySet<string>,
+	): SessionList {
 		return {
 			indexSeq: this.indexSeq,
-			sessions: reduceEvents(this.#events, this.#policy.clock(), this.#agentDir, probedIncarnations).sessions,
+			sessions: reduceEvents(this.#events, this.#policy.clock(), this.#agentDir, probedIncarnations, sessionIds)
+				.sessions,
 			warnings: this.#warnings,
 		};
 	}
@@ -2334,9 +2373,64 @@ export class SessionIndex {
 	 * while the broker was down keep their stale or missing heartbeat and read as
 	 * unknown/not-live (never fresh forever). Returns the number of checkpoints written.
 	 */
-	async checkpointLiveHeartbeats(now = Date.now()): Promise<number> {
+	async checkpointLiveHeartbeats(
+		now = Date.now(),
+		abortSignal?: AbortSignal,
+		deadlineAt = performance.now() + SESSION_HEARTBEAT_CHECKPOINT_BUDGET_MS,
+	): Promise<number> {
+		// A stale observation batch fails closed (no heartbeat), but on a busy
+		// machine a single contended lock acquisition is enough to discard the
+		// whole cycle. With the broker's 5s cadence repeatedly losing that race,
+		// every live host's heartbeat aged past the 2-interval freshness window
+		// and the router retired attached sessions as "removed" mid-prompt.
+		// Re-probe from scratch a bounded number of times inside this pass: each
+		// attempt keeps the exact fail-closed contract (fresh probes, freshness
+		// bounds re-checked under the lock); only the starvation is removed.
+		const deadline = Math.min(deadlineAt, performance.now() + SESSION_HEARTBEAT_CHECKPOINT_BUDGET_MS);
+		if (abortSignal?.aborted || performance.now() >= deadline) return 0;
+		const budget = new AbortController();
+		const signal = abortSignal ? AbortSignal.any([abortSignal, budget.signal]) : budget.signal;
+		const timer = setTimeout(() => budget.abort(), deadline - performance.now());
+		timer.unref?.();
+		const checkpoint = async (): Promise<number> => {
+			for (let attempt = 0; ; attempt++) {
+				if (signal.aborted || performance.now() >= deadline) return 0;
+				const result = await this.#checkpointLiveHeartbeatsOnce(now, signal, deadline);
+				if (result !== STALE_OBSERVATION || attempt + 1 >= SESSION_HEARTBEAT_CHECKPOINT_ATTEMPTS)
+					return result === STALE_OBSERVATION ? 0 : result;
+				now = Date.now();
+			}
+		};
+		try {
+			// The deadline aborts queued work and prevents a late callback from
+			// entering its write section, but it cannot cancel an append/fsync that
+			// has already started. Keep the caller tied to the lock-owning operation
+			// so startup readiness never overtakes lock release.
+			return await checkpoint();
+		} catch (error) {
+			if (signal.aborted && error === signal.reason) return 0;
+			if (
+				performance.now() >= deadline &&
+				isFileLockAcquireTimeout(error) &&
+				!error.orphanPath &&
+				!error.removalFailure
+			)
+				return 0;
+			throw error;
+		} finally {
+			clearTimeout(timer);
+			budget.abort();
+		}
+	}
+
+	async #checkpointLiveHeartbeatsOnce(
+		now: number,
+		signal: AbortSignal,
+		deadline: number,
+	): Promise<number | typeof STALE_OBSERVATION> {
 		const indexPath = path.resolve(logFor(this.#agentDir));
 		return await SessionIndex.#enqueue(indexPath, async () => {
+			if (signal.aborted || performance.now() >= deadline) return 0;
 			// An absent index holds no registration to checkpoint, so this pass must read
 			// it as "nothing to do" instead of creating one. Recreating the directory
 			// resurrects a state root its owner already retired: the broker's 5s
@@ -2371,62 +2465,78 @@ export class SessionIndex {
 				probed.set(`${row.sessionId}\u0000${row.endpointGeneration}\u0000${row.pid}`, processIncarnation(row.pid));
 			}
 			const probedAt = performance.now();
-			return await withSessionIndexLock("heartbeat checkpoint", this.#agentDir, async () => {
-				// Contended or delayed acquisition invalidates the observation set:
-				// never trust identity evidence gathered meaningfully before the
-				// lock was held. The checkpoint is skipped this cycle (fail-closed);
-				// the OS is never probed while the machine-global lock is held. The
-				// bound tolerates scheduler jitter on an uncontended acquisition —
-				// which is the only path where the evidence is trustworthy.
-				if (performance.now() - probedAt > SESSION_INDEX_PROBE_FRESHNESS_MS) return 0;
-				await this.#replayUnderLock();
-				// Recheck AFTER the awaited replay too (#4544 review round 4): the
-				// replay re-reads the whole log (up to the 4 MiB rotation bound) and
-				// fsyncs pending audit rows, so the probe→write interval can stretch
-				// well past the acquisition bound above while the lock is held. The
-				// same pid-reuse window exists across that awaited replay; consuming
-				// the cached observation then would checkpoint the replacement
-				// process as the dead row. The replay bound covers the full locked
-				// replay cost envelope of a healthy machine; anything slower fails
-				// closed (no heartbeat this cycle) and the next pass re-probes.
-				if (performance.now() - probedAt > SESSION_INDEX_REPLAY_FRESHNESS_MS) return 0;
-				if (this.#corruptSuffix) return 0;
-				const events: SessionIndexEvent[] = [];
-				const rows = reduceEvents(this.#events, now, this.#agentDir, probed).sessions;
-				for (const row of rows) {
-					if (!isSessionAuthorityEligible(row) || row.terminal || row.terminalUncertain) continue;
-					if (row.lastHeartbeatAt !== undefined && now - row.lastHeartbeatAt < SESSION_HEARTBEAT_INTERVAL_MS)
-						continue;
-					if (!alive(row.pid)) continue;
-					const recordedIncarnation = row.hostIncarnation ?? row.processIncarnation;
-					if (recordedIncarnation === undefined) continue;
-					const current = probed.get(`${row.sessionId}\u0000${row.endpointGeneration}\u0000${row.pid}`);
-					if (current === undefined || current !== recordedIncarnation) continue;
-					const unsigned: Omit<SessionIndexEvent, "checksum"> = {
-						version: SESSION_INDEX_EVENT_VERSION,
-						indexSeq: this.indexSeq + events.length + 1,
-						type: "host_heartbeat",
-						sessionId: row.sessionId,
-						locator: row.locator,
-						endpointGeneration: row.endpointGeneration,
-						pid: row.pid,
-						...(row.processIncarnation === undefined ? {} : { processIncarnation: row.processIncarnation }),
-						...(row.hostIncarnation === undefined ? {} : { hostIncarnation: row.hostIncarnation }),
-						...(row.masterRole === undefined ? {} : { masterRole: row.masterRole }),
-						// Preserve the host's last observed activity state while this
-						// broker-owned heartbeat only renews liveness. A live idle host
-						// must not be rewritten as active merely because its pid is alive.
-						activity: row.activity ?? { state: "active", at: now },
-						ts: now,
-					};
-					events.push({ ...unsigned, checksum: sessionIndexChecksum(unsigned) });
-				}
-				if (events.length === 0) return 0;
-				for (const event of events) await appendSync(logFor(this.#agentDir), JSON.stringify(event));
-				await this.#refreshUnderLock();
-				if ((await fs.stat(logFor(this.#agentDir))).size >= ROTATE_BYTES) await this.#rotate();
-				return events.length;
-			});
+			if (signal.aborted || probedAt >= deadline) return 0;
+			return await withSessionIndexLock(
+				"heartbeat checkpoint",
+				this.#agentDir,
+				async () => {
+					if (signal.aborted || performance.now() >= deadline) return 0;
+					// Contended or delayed acquisition invalidates the observation set:
+					// never trust identity evidence gathered meaningfully before the
+					// lock was held. The checkpoint is skipped this cycle (fail-closed);
+					// the OS is never probed while the machine-global lock is held. The
+					// bound tolerates scheduler jitter on an uncontended acquisition —
+					// which is the only path where the evidence is trustworthy.
+					if (performance.now() - probedAt > SESSION_INDEX_PROBE_FRESHNESS_MS) return STALE_OBSERVATION;
+					await this.#replayUnderLock();
+					if (signal.aborted || performance.now() >= deadline) return 0;
+					// Recheck AFTER the awaited replay too (#4544 review round 4): the
+					// replay re-reads the whole log (up to the 4 MiB rotation bound) and
+					// fsyncs pending audit rows, so the probe→write interval can stretch
+					// well past the acquisition bound above while the lock is held. The
+					// same pid-reuse window exists across that awaited replay; consuming
+					// the cached observation then would checkpoint the replacement
+					// process as the dead row. The replay bound covers the full locked
+					// replay cost envelope of a healthy machine; anything slower fails
+					// closed (no heartbeat this cycle) and the next pass re-probes.
+					if (performance.now() - probedAt > SESSION_INDEX_REPLAY_FRESHNESS_MS) return STALE_OBSERVATION;
+					if (this.#corruptSuffix) return 0;
+					const events: SessionIndexEvent[] = [];
+					const rows = reduceEvents(this.#events, now, this.#agentDir, probed).sessions;
+					for (const row of rows) {
+						if (!isSessionAuthorityEligible(row) || row.terminal || row.terminalUncertain) continue;
+						if (row.lastHeartbeatAt !== undefined && now - row.lastHeartbeatAt < SESSION_HEARTBEAT_INTERVAL_MS)
+							continue;
+						if (!alive(row.pid)) continue;
+						const recordedIncarnation = row.hostIncarnation ?? row.processIncarnation;
+						if (recordedIncarnation === undefined) continue;
+						const current = probed.get(`${row.sessionId}\u0000${row.endpointGeneration}\u0000${row.pid}`);
+						if (current === undefined || current !== recordedIncarnation) continue;
+						const unsigned: Omit<SessionIndexEvent, "checksum"> = {
+							version: SESSION_INDEX_EVENT_VERSION,
+							indexSeq: this.indexSeq + events.length + 1,
+							type: "host_heartbeat",
+							sessionId: row.sessionId,
+							locator: row.locator,
+							endpointGeneration: row.endpointGeneration,
+							pid: row.pid,
+							...(row.processIncarnation === undefined ? {} : { processIncarnation: row.processIncarnation }),
+							...(row.hostIncarnation === undefined ? {} : { hostIncarnation: row.hostIncarnation }),
+							...(row.masterRole === undefined ? {} : { masterRole: row.masterRole }),
+							// Preserve the host's last observed activity state while this
+							// broker-owned heartbeat only renews liveness. A live idle host
+							// must not be rewritten as active merely because its pid is alive.
+							activity: row.activity ?? { state: "active", at: now },
+							ts: now,
+						};
+						events.push({ ...unsigned, checksum: sessionIndexChecksum(unsigned) });
+					}
+					if (events.length === 0) return 0;
+					if (signal.aborted || performance.now() >= deadline) return 0;
+					for (const event of events) await appendSync(logFor(this.#agentDir), JSON.stringify(event));
+					await this.#refreshUnderLock();
+					if ((await fs.stat(logFor(this.#agentDir))).size >= ROTATE_BYTES) await this.#rotate();
+					return events.length;
+				},
+				{
+					...SESSION_INDEX_LOCK_OPTIONS,
+					retries: Math.min(
+						SESSION_INDEX_LOCK_OPTIONS.retries,
+						Math.max(1, Math.ceil((deadline - performance.now()) / SESSION_INDEX_LOCK_OPTIONS.retryDelayMs)),
+					),
+					signal,
+				},
+			);
 		});
 	}
 

package/src/sdk/broker/task-artifact-owner-validation.ts

@@ -0,0 +1,259 @@
+import type { NativeExactUnlinkResult } from "@gajae-code/natives";
+import {
+	assertSessionRoot,
+	parseTaskArtifactOwnerDeletionEvidence,
+	parseTaskArtifactOwnerRetirementContinuation,
+	parseTaskArtifactOwnerRetirementOutcome,
+	type TaskArtifactOwnerDeletionEvidence,
+	type TaskArtifactOwnerRetirementContinuation,
+	type TaskArtifactOwnerRetirementOutcome,
+	type TaskArtifactOwnerStorageContext,
+} from "../../session/task-artifact-owner-codec";
+
+export type BrokerCleanupPhase = "artifacts" | "transcript" | "metadata" | "lifecycle";
+
+/** Exact owner-disposition wire shape. Evidence and continuation are supplied separately by cleanup replay. */
+export type BrokerTaskArtifactOwnerRetirementDisposition =
+	| { readonly kind: "completed"; readonly nativeOutcome?: NativeExactUnlinkResult }
+	| {
+			readonly kind: "payload_retired";
+			readonly namespace: "retained";
+			readonly nativeOutcome: NativeExactUnlinkResult;
+	  }
+	| { readonly kind: "cleanup_pending"; readonly nativeOutcome?: NativeExactUnlinkResult }
+	| { readonly kind: "uncertain"; readonly reason: string; readonly nativeOutcome?: NativeExactUnlinkResult };
+
+/** Owner-only projection of durable cleanup state accepted by the pure validator. */
+export interface BrokerTaskArtifactOwnerCleanupFields {
+	readonly taskArtifactOwnerDeletionEvidence?: unknown;
+	readonly taskArtifactOwnerRetirementContinuation?: unknown;
+	readonly taskArtifactOwnerRetirementOutcome?: unknown;
+	readonly taskArtifactOwnerPayloadRetired?: unknown;
+	readonly taskArtifactOwnerNamespaceRetained?: unknown;
+	readonly taskArtifactOwnerRetired?: unknown;
+	readonly taskArtifactOwnerTranscriptDeleted?: unknown;
+	readonly taskArtifactOwnerCleanupError?: unknown;
+}
+
+/** Fully decoded owner-only cleanup state for an authorized session and phase. */
+export interface BrokerTaskArtifactOwnerCleanupValidation {
+	readonly deletionEvidence?: TaskArtifactOwnerDeletionEvidence;
+	readonly retirementContinuation?: TaskArtifactOwnerRetirementContinuation;
+	readonly retirementOutcome?: TaskArtifactOwnerRetirementOutcome;
+	readonly payloadRetired?: true;
+	readonly namespaceRetained?: true;
+	readonly retired?: true;
+	readonly transcriptDeleted?: true;
+	readonly cleanupDiagnostic?: string;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function hasExactKeys(value: Record<string, unknown>, keys: readonly string[]): boolean {
+	return Object.keys(value).length === keys.length && keys.every(key => Object.hasOwn(value, key));
+}
+
+function invalidDisposition(): never {
+	throw new Error("task_artifact_owner_retirement_disposition_invalid");
+}
+
+/**
+ * Decode the owner-only wire disposition using its exact trusted evidence and continuation.
+ * A decoded `completed` value is historical DTO data, not proof of physical retirement or writer closure.
+ */
+export function parseBrokerTaskArtifactOwnerRetirementDisposition(
+	value: unknown,
+	context: TaskArtifactOwnerStorageContext,
+	evidence: TaskArtifactOwnerDeletionEvidence,
+	continuation: TaskArtifactOwnerRetirementContinuation | undefined,
+): TaskArtifactOwnerRetirementOutcome {
+	assertSessionRoot(context);
+	if (!isRecord(value)) return invalidDisposition();
+	const kind = value.kind;
+	let expectedKeys: readonly string[];
+	switch (kind) {
+		case "completed":
+		case "cleanup_pending":
+			expectedKeys = Object.hasOwn(value, "nativeOutcome") ? ["kind", "nativeOutcome"] : ["kind"];
+			break;
+		case "payload_retired":
+			expectedKeys = ["kind", "namespace", "nativeOutcome"];
+			break;
+		case "uncertain":
+			expectedKeys = Object.hasOwn(value, "nativeOutcome")
+				? ["kind", "reason", "nativeOutcome"]
+				: ["kind", "reason"];
+			break;
+		default:
+			return invalidDisposition();
+	}
+	if (!hasExactKeys(value, expectedKeys)) return invalidDisposition();
+	const reconstructed = {
+		...value,
+		evidence,
+		...(continuation !== undefined ? { continuation } : {}),
+	};
+	return parseTaskArtifactOwnerRetirementOutcome(context, evidence, reconstructed);
+}
+
+function serializeNativeOutcome(outcome: NativeExactUnlinkResult): NativeExactUnlinkResult {
+	return Object.freeze({
+		ok: outcome.ok,
+		...(outcome.code !== undefined ? { code: outcome.code } : {}),
+		...(outcome.detachedPath !== undefined ? { detachedPath: outcome.detachedPath } : {}),
+		...(outcome.retainedSuccessorPath !== undefined ? { retainedSuccessorPath: outcome.retainedSuccessorPath } : {}),
+		...(outcome.retainedPlaceholderPath !== undefined
+			? { retainedPlaceholderPath: outcome.retainedPlaceholderPath }
+			: {}),
+		...(outcome.retainedUnknownPath !== undefined ? { retainedUnknownPath: outcome.retainedUnknownPath } : {}),
+		...(outcome.payloadDurable !== undefined ? { payloadDurable: outcome.payloadDurable } : {}),
+		...(outcome.windowsErrorCode !== undefined ? { windowsErrorCode: outcome.windowsErrorCode } : {}),
+	}) as NativeExactUnlinkResult;
+}
+
+/** Project an already validated internal outcome to the exact broker wire disposition. */
+export function serializeBrokerTaskArtifactOwnerRetirementDisposition(
+	outcome: TaskArtifactOwnerRetirementOutcome,
+): BrokerTaskArtifactOwnerRetirementDisposition {
+	switch (outcome.kind) {
+		case "completed":
+			return Object.freeze({
+				kind: outcome.kind,
+				...(outcome.nativeOutcome ? { nativeOutcome: serializeNativeOutcome(outcome.nativeOutcome) } : {}),
+			});
+		case "payload_retired":
+			return Object.freeze({
+				kind: outcome.kind,
+				namespace: outcome.namespace,
+				nativeOutcome: serializeNativeOutcome(outcome.nativeOutcome),
+			});
+		case "cleanup_pending":
+			return Object.freeze({
+				kind: outcome.kind,
+				...(outcome.nativeOutcome ? { nativeOutcome: serializeNativeOutcome(outcome.nativeOutcome) } : {}),
+			});
+		case "uncertain":
+			return Object.freeze({
+				kind: outcome.kind,
+				reason: outcome.reason,
+				...(outcome.nativeOutcome ? { nativeOutcome: serializeNativeOutcome(outcome.nativeOutcome) } : {}),
+			});
+		default: {
+			const exhaustive: never = outcome;
+			throw new Error(`task_artifact_owner_retirement_outcome_unknown:${String(exhaustive)}`);
+		}
+	}
+}
+
+const OWNER_CLEANUP_KEYS = new Set([
+	"taskArtifactOwnerDeletionEvidence",
+	"taskArtifactOwnerRetirementContinuation",
+	"taskArtifactOwnerRetirementOutcome",
+	"taskArtifactOwnerPayloadRetired",
+	"taskArtifactOwnerNamespaceRetained",
+	"taskArtifactOwnerRetired",
+	"taskArtifactOwnerTranscriptDeleted",
+	"taskArtifactOwnerCleanupError",
+]);
+
+/**
+ * Strictly decode the owner-field projection of cleanup state against trusted session, scope context, phase,
+ * and artifact-removal state. Empty/legacy owner fields decode to an empty result. A decoded completion
+ * remains historical data: any later effect must separately verify current physical absence, fresh scrub
+ * proof, native success and current owner-parent/side-path authority before it mutates storage or transcripts.
+ */
+export function decodeBrokerTaskArtifactOwnerCleanupFields(
+	value: unknown,
+	context: TaskArtifactOwnerStorageContext,
+	expectedSessionId: string,
+	phase: BrokerCleanupPhase,
+	artifactsRemoved: boolean | undefined,
+): BrokerTaskArtifactOwnerCleanupValidation {
+	assertSessionRoot(context);
+	if (!isRecord(value) || Object.keys(value).some(key => !OWNER_CLEANUP_KEYS.has(key)))
+		throw new Error("task_artifact_owner_cleanup_fields_invalid");
+	if (expectedSessionId.length === 0 || (artifactsRemoved !== undefined && typeof artifactsRemoved !== "boolean"))
+		throw new Error("task_artifact_owner_cleanup_fields_invalid");
+
+	const has = (key: string) => Object.hasOwn(value, key);
+	const trueFlag = (key: string): true | undefined => {
+		if (!has(key)) return undefined;
+		if (value[key] !== true) throw new Error("task_artifact_owner_cleanup_flags_invalid");
+		return true;
+	};
+	let deletionEvidence: TaskArtifactOwnerDeletionEvidence | undefined;
+	if (has("taskArtifactOwnerDeletionEvidence")) {
+		deletionEvidence = parseTaskArtifactOwnerDeletionEvidence(value.taskArtifactOwnerDeletionEvidence);
+		if (deletionEvidence.sessionId !== expectedSessionId)
+			throw new Error("task_artifact_owner_cleanup_session_mismatch");
+	}
+	let retirementContinuation: TaskArtifactOwnerRetirementContinuation | undefined;
+	if (has("taskArtifactOwnerRetirementContinuation")) {
+		if (!deletionEvidence) throw new Error("task_artifact_owner_cleanup_evidence_missing");
+		retirementContinuation = parseTaskArtifactOwnerRetirementContinuation(
+			context,
+			deletionEvidence,
+			value.taskArtifactOwnerRetirementContinuation,
+		);
+	}
+	let retirementOutcome: TaskArtifactOwnerRetirementOutcome | undefined;
+	if (has("taskArtifactOwnerRetirementOutcome")) {
+		if (!deletionEvidence) throw new Error("task_artifact_owner_cleanup_evidence_missing");
+		retirementOutcome = parseBrokerTaskArtifactOwnerRetirementDisposition(
+			value.taskArtifactOwnerRetirementOutcome,
+			context,
+			deletionEvidence,
+			retirementContinuation,
+		);
+	}
+
+	const payloadRetired = trueFlag("taskArtifactOwnerPayloadRetired");
+	const namespaceRetained = trueFlag("taskArtifactOwnerNamespaceRetained");
+	const retired = trueFlag("taskArtifactOwnerRetired");
+	const transcriptDeleted = trueFlag("taskArtifactOwnerTranscriptDeleted");
+	let cleanupDiagnostic: string | undefined;
+	if (has("taskArtifactOwnerCleanupError")) {
+		const diagnostic = value.taskArtifactOwnerCleanupError;
+		if (typeof diagnostic !== "string" || diagnostic.length === 0 || diagnostic.length > 4096)
+			throw new Error("task_artifact_owner_cleanup_diagnostic_invalid");
+		cleanupDiagnostic = diagnostic;
+	}
+
+	if (
+		(retired !== undefined && (payloadRetired !== undefined || namespaceRetained !== undefined)) ||
+		(retired !== undefined && retirementOutcome?.kind !== "completed") ||
+		(payloadRetired !== undefined) !== (namespaceRetained !== undefined) ||
+		((retired !== undefined ||
+			payloadRetired !== undefined ||
+			namespaceRetained !== undefined ||
+			transcriptDeleted !== undefined) &&
+			(!deletionEvidence || !retirementOutcome)) ||
+		(transcriptDeleted !== undefined &&
+			(phase !== "artifacts" || artifactsRemoved !== true || retirementOutcome === undefined))
+	)
+		throw new Error("task_artifact_owner_cleanup_state_invalid");
+
+	if (retirementOutcome) {
+		if (
+			(retired !== undefined && retirementOutcome.kind !== "completed") ||
+			(retirementOutcome.kind === "completed" && retired === undefined) ||
+			(payloadRetired !== undefined &&
+				(retirementOutcome.kind !== "payload_retired" || retirementContinuation === undefined)) ||
+			(retirementOutcome.kind === "payload_retired" && payloadRetired === undefined)
+		)
+			throw new Error("task_artifact_owner_cleanup_disposition_mismatch");
+	}
+
+	return Object.freeze({
+		deletionEvidence,
+		retirementContinuation,
+		retirementOutcome,
+		payloadRetired,
+		namespaceRetained,
+		retired,
+		transcriptDeleted,
+		cleanupDiagnostic,
+	});
+}