@gajae-code/coding-agent 0.18.7 → 0.18.9

package/src/session/artifacts.ts

@@ -15,6 +15,7 @@ import {
 	publishManagedFileNoReplace,
 	publishManagedFileNoReplaceSync,
 } from "./internal/managed-session-storage";
+import { type SessionStorageStat, writeExplicitOwnerOnlyTextSync } from "./session-storage";
 import { DEFAULT_ARTIFACT_MAX_BYTES, truncateHeadBytes } from "./streaming-output";
 
 export interface ManagedOutputGeneration {
@@ -67,6 +68,28 @@ function parseManagedOutputGeneration(value: Uint8Array, outputFilenamePrefix: s
 function sameGeneration(left: ManagedOutputGeneration, right: ManagedOutputGeneration): boolean {
 	return left.outputFilename === right.outputFilename && left.metadataFilename === right.metadataFilename;
 }
+
+function normalizeByteRange(size: number, range: ArtifactByteRange): { start: number; endExclusive: number } {
+	const start = Math.max(0, Math.min(size, range.start ?? 0));
+	const endExclusive = Math.max(start, Math.min(size, range.endExclusive ?? size));
+	const normalizedStart = Number.isNaN(start) ? 0 : Math.trunc(start);
+	const normalizedEnd = Number.isNaN(endExclusive) ? 0 : Math.trunc(endExclusive);
+	return {
+		start: normalizedStart,
+		endExclusive: Math.max(normalizedStart, normalizedEnd),
+	};
+}
+
+const ARTIFACT_STREAM_CHUNK_BYTES = 64 * 1024;
+const ARTIFACT_RANGE_READ_CHUNK_BYTES = 64 * 1024 * 1024;
+
+type AttemptStagingCleanupClassification = { kind: "authorized_quarantine" } | { kind: "failure"; error: unknown };
+
+function classifyAttemptStagingCleanupFailure(error: unknown): AttemptStagingCleanupClassification {
+	return error instanceof Error && error.message === "cleanup_pending"
+		? { kind: "authorized_quarantine" }
+		: { kind: "failure", error };
+}
 export interface ArtifactSaveOptions {
 	maxBytes?: number;
 }
@@ -223,7 +246,8 @@ export class ArtifactManager {
 		if (!/^[a-zA-Z0-9_.-]+$/.test(filename)) throw new Error("Unsafe named artifact");
 		await this.#ensureDir();
 		if (this.#store) await this.#store.replace(filename, Buffer.from(content, "utf8"));
-		else await Bun.write(path.join(this.#dir, filename), content);
+		// Named files, including draft.txt, are created here.
+		else writeExplicitOwnerOnlyTextSync(path.join(this.#dir, filename), content);
 	}
 
 	async replaceNamedBytes(filename: string, bytes: Uint8Array): Promise<void> {
@@ -309,26 +333,16 @@ export class ArtifactManager {
 	 * Best-effort removal of a previously published named artifact. Used to roll
 	 * back staged publications when a transactional operation (e.g. gated
 	 * maintenance pruning) is rejected after publication succeeded. Returns false
-	 * when the artifact could not be removed so callers can log the failure
-	 * instead of silently treating the rollback as complete.
+	 * when the exact named artifact is absent or could not be removed; success does
+	 * not claim that unrelated native cleanup residue was reclaimed.
 	 */
 	async removeNamedBestEffort(filename: string): Promise<boolean> {
 		if (!/^[a-zA-Z0-9_.-]+$/.test(filename)) return false;
 		try {
 			if (this.#store) {
-				const beforePaths = new Set(await fs.readdir(this.#store.dir));
 				const staged = this.#store.readExpected(filename);
-				if (staged) this.#store.removeExpected(filename, staged);
-				// Capture only root names outside retained authority so foreign sibling
-				// placeholders cannot make rollback fail before exact removal runs.
-				for (const basename of await fs.readdir(this.#store.dir)) {
-					const nativeResidue = /^\.gjc-/u.test(basename);
-					const ownQuarantine = basename === `${filename}.removing` || basename.startsWith(`${filename}.`);
-					if (beforePaths.has(basename) || (!nativeResidue && !ownQuarantine)) continue;
-					const residuePath = path.join(this.#store.dir, basename);
-					const stat = await fs.lstat(residuePath);
-					await fs.rm(residuePath, { recursive: stat.isDirectory(), force: true });
-				}
+				if (!staged) return false;
+				this.#store.removeExpected(filename, staged);
 			} else {
 				await fs.unlink(path.join(this.#dir, filename));
 			}
@@ -502,7 +516,13 @@ export class ArtifactManager {
 				publishedNames.push(mappedFilename);
 			}
 			this.#reservations.set(attemptId, { start, count: ids.length, names: [...publishedNames] });
-			await staging.discardAttemptStaging();
+			try {
+				await staging.discardAttemptStaging();
+			} catch (error) {
+				const cleanup = classifyAttemptStagingCleanupFailure(error);
+				if (cleanup.kind === "authorized_quarantine") return frozenMap;
+				throw cleanup.error;
+			}
 			return frozenMap;
 		} catch (error) {
 			// Cleanup is best-effort, but a durable removal failure must never be silent: it leaves a
@@ -550,64 +570,34 @@ export class ArtifactManager {
 
 	async discardAttemptStaging(): Promise<void> {
 		if (this.#store) {
-			const cleanupStore = this.#stagingParentStore ?? this.#store;
-			const cleanupPath = this.#stagingParentStore ? this.#stagingRelativePath! : "";
-			const parentCleanupPath = cleanupPath ? path.posix.dirname(cleanupPath) : "";
-			let parentBefore: ReturnType<ManagedSessionDescendantStore["captureTree"]> | undefined;
-			if (this.#stagingParentStore) {
-				try {
-					parentBefore = cleanupStore.captureTree(parentCleanupPath);
-				} catch {
-					parentBefore = undefined;
-				}
-			}
+			// Only an attempt manager owns a managed subtree that it may retire. A
+			// normal manager's store is borrowed by this cleanup method and its root
+			// must never become a deletion target.
+			if (!this.#stagingParentStore || !this.#stagingRelativePath) return;
+			const cleanupStore = this.#stagingParentStore;
 			try {
-				const snapshot = cleanupStore.captureTree(cleanupPath);
-				cleanupStore.removeTreeExpected(cleanupPath, snapshot);
+				const snapshot = cleanupStore.captureTree(this.#stagingRelativePath);
+				const issuedRoot = this.#store.subtreeRootAuthority;
+				if (
+					issuedRoot.canonicalPath !== path.resolve(this.#dir) ||
+					snapshot.rootDev !== issuedRoot.dev.toString() ||
+					snapshot.rootIno !== issuedRoot.ino.toString()
+				)
+					throw new Error("artifact_staging_root_changed");
+				// Stop using and release this attempt's retained writable root before
+				// asking the parent authority to retire the tree. The exact tree snapshot
+				// above is still checked by native removal; a concurrent change therefore
+				// remains a refusal rather than being adopted. Never close the borrowed
+				// parent store.
+				this.#store.close();
+				cleanupStore.removeTreeExpected(this.#stagingRelativePath, snapshot);
 			} catch (error) {
-				if (!(error instanceof Error && (error.message === "not_found" || error.message === "cleanup_pending")))
-					throw error;
+				if (!(error instanceof Error && error.message === "not_found")) throw error;
+			} finally {
+				// Replacement, snapshot, and native cleanup failures also release only
+				// the capability owned by this attempt manager.
+				this.#store.close();
 			}
-			if (this.#stagingParentStore && parentBefore) {
-				try {
-					const after = cleanupStore.captureTree(parentCleanupPath);
-					const beforePaths = new Set(parentBefore.entries.map(entry => entry.relativePath));
-					for (const entry of after.entries) {
-						if (
-							entry.kind === "directory" &&
-							entry.relativePath.length > 0 &&
-							!beforePaths.has(entry.relativePath) &&
-							/\.removing$/u.test(path.posix.basename(entry.relativePath))
-						) {
-							await fs.rm(path.join(cleanupStore.dir, parentCleanupPath, entry.relativePath), {
-								recursive: true,
-								force: true,
-							});
-							continue;
-						}
-						if (
-							entry.kind !== "file" ||
-							beforePaths.has(entry.relativePath) ||
-							!/^\\.gjc-(?:exact-unlink-placeholder|remove)-/u.test(path.posix.basename(entry.relativePath))
-						)
-							continue;
-						const relative = path.posix.join(parentCleanupPath, entry.relativePath);
-						const expected = cleanupStore.readExpected(relative);
-						if (expected) {
-							try {
-								cleanupStore.removeExpected(relative, expected);
-							} catch (cleanupError) {
-								if (!(cleanupError instanceof Error && cleanupError.message === "cleanup_pending"))
-									throw cleanupError;
-							}
-						}
-						await fs.rm(path.join(cleanupStore.dir, relative), { force: true }).catch(() => undefined);
-					}
-				} catch {
-					// Retained cleanup evidence is safe to leave for a later maintenance pass.
-				}
-			}
-			this.#store.close();
 		} else {
 			await fs.rm(this.#dir, { recursive: true, force: true });
 		}
@@ -650,7 +640,69 @@ export class ArtifactManager {
 		}
 	}
 
+	#captureManagedArtifact(id: string): {
+		filename: string;
+		size: number;
+		expectedDescriptor: Pick<SessionStorageStat, "dev" | "ino" | "nlink" | "size" | "mtimeNs" | "ctimeNs">;
+	} | null {
+		if (!this.#store) return null;
+		try {
+			const entry = this.#store
+				.captureTree("")
+				.entries.find(candidate => candidate.kind === "file" && candidate.relativePath.startsWith(`${id}.`));
+			if (!entry) return null;
+			const size = Number(BigInt(entry.size));
+			if (!Number.isSafeInteger(size) || size < 0) return null;
+			return {
+				filename: entry.relativePath,
+				size,
+				expectedDescriptor: {
+					dev: BigInt(entry.dev),
+					ino: BigInt(entry.ino),
+					nlink: BigInt(entry.nlink),
+					size,
+					mtimeNs: BigInt(entry.mtimeNs),
+					ctimeNs: BigInt(entry.ctimeNs),
+				},
+			};
+		} catch {
+			// listFiles historically hides an unavailable managed tree as no artifacts.
+			return null;
+		}
+	}
+
 	async readRange(id: string, range: ArtifactByteRange = {}): Promise<string> {
+		if (this.#store) {
+			const artifact = this.#captureManagedArtifact(id);
+			if (!artifact) throw new Error(`artifact://${id} not found`);
+			const { start, endExclusive } = normalizeByteRange(artifact.size, range);
+			const length = Math.max(0, endExclusive - start);
+			let bytes: Uint8Array;
+			if (length <= ARTIFACT_RANGE_READ_CHUNK_BYTES) {
+				bytes = this.#store.readRangeExpectedSync(
+					artifact.filename,
+					start,
+					length,
+					artifact.expectedDescriptor,
+				).bytes;
+			} else {
+				const complete = Buffer.allocUnsafe(length);
+				let offset = 0;
+				while (offset < length) {
+					const chunkLength = Math.min(ARTIFACT_RANGE_READ_CHUNK_BYTES, length - offset);
+					const chunk = this.#store.readRangeExpectedSync(
+						artifact.filename,
+						start + offset,
+						chunkLength,
+						artifact.expectedDescriptor,
+					).bytes;
+					complete.set(chunk, offset);
+					offset += chunk.byteLength;
+				}
+				bytes = complete;
+			}
+			return new TextDecoder().decode(bytes);
+		}
 		const artifactPath = await this.getPath(id);
 		if (!artifactPath) throw new Error(`artifact://${id} not found`);
 		const file = Bun.file(artifactPath);
@@ -661,6 +713,59 @@ export class ArtifactManager {
 	}
 
 	async openReadStream(id: string, range: ArtifactByteRange = {}): Promise<ReadableStream<Uint8Array>> {
+		if (this.#store) {
+			const artifact = this.#captureManagedArtifact(id);
+			if (!artifact) throw new Error(`artifact://${id} not found`);
+			const { start, endExclusive } = normalizeByteRange(artifact.size, range);
+			const lease = this.#store.openReadLease(artifact.filename, artifact.expectedDescriptor);
+			let offset = start;
+			let closed = false;
+			const closeLease = (): void => {
+				if (closed) return;
+				closed = true;
+				lease.close();
+			};
+			const closeAfterFailure = (): void => {
+				try {
+					closeLease();
+				} catch {
+					// Keep the read failure as the stream's observable error.
+				}
+			};
+			return new ReadableStream<Uint8Array>(
+				{
+					start: controller => {
+						if (offset !== endExclusive) return;
+						try {
+							closeLease();
+							controller.close();
+						} catch (error) {
+							closeAfterFailure();
+							controller.error(error);
+						}
+					},
+					pull: controller => {
+						if (closed) return;
+						try {
+							const length = Math.min(ARTIFACT_STREAM_CHUNK_BYTES, endExclusive - offset);
+							const bytes = lease.readRange(offset, length);
+							if (bytes.byteLength !== length) throw new Error("range_not_present");
+							offset += bytes.byteLength;
+							if (offset === endExclusive) closeLease();
+							controller.enqueue(bytes);
+							if (offset === endExclusive) controller.close();
+						} catch (error) {
+							closeAfterFailure();
+							controller.error(error);
+						}
+					},
+					cancel: () => {
+						closeLease();
+					},
+				},
+				{ highWaterMark: 0 },
+			);
+		}
 		const artifactPath = await this.getPath(id);
 		if (!artifactPath) throw new Error(`artifact://${id} not found`);
 		const file = Bun.file(artifactPath);

package/src/session/internal/managed-gc-retirement-codec.ts

@@ -0,0 +1,319 @@
+import * as path from "node:path";
+import type { SessionStorageFileIdentity } from "../session-storage";
+import {
+	assertSessionRoot,
+	EMPTY_PAYLOAD_SHA256,
+	parseTaskArtifactOwnerDeletionEvidence,
+	parseTaskArtifactOwnerLocator,
+	parseTaskArtifactOwnerRetirementContinuation,
+	parseTaskArtifactOwnerRetirementOutcome,
+	type TaskArtifactOwnerDeletionEvidence,
+	type TaskArtifactOwnerLocator,
+	type TaskArtifactOwnerRetirementContinuation,
+	type TaskArtifactOwnerRetirementOutcome,
+	type TaskArtifactOwnerStorageContext,
+} from "../task-artifact-owner-codec";
+
+export type ManagedGcSessionRetirementState = "prepared" | "artifacts_removed" | "owner_pending" | "owner_retired";
+
+export interface ManagedGcSessionRetirementTarget {
+	readonly transcriptPath: string;
+	readonly sessionId: string;
+	readonly cwd: string;
+	readonly transcriptIdentity: SessionStorageFileIdentity;
+	readonly taskArtifactOwnerLocator: TaskArtifactOwnerLocator;
+}
+
+export interface ManagedGcSessionRetirementReceipt extends ManagedGcSessionRetirementTarget {
+	readonly state: ManagedGcSessionRetirementState;
+	readonly taskArtifactOwnerDeletionEvidence: TaskArtifactOwnerDeletionEvidence;
+	readonly artifactsRemoved?: true;
+	readonly ownerRetirementAttempt?: number;
+	readonly taskArtifactOwnerRetirementOutcome?: TaskArtifactOwnerRetirementOutcome;
+	readonly taskArtifactOwnerRetirementContinuation?: TaskArtifactOwnerRetirementContinuation;
+	readonly taskArtifactOwnerPayloadRetired?: true;
+	readonly taskArtifactOwnerNamespaceRetained?: true;
+	readonly taskArtifactOwnerRetired?: true;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+export function managedGcRetirementIdentityRecord(identity: SessionStorageFileIdentity): Record<string, unknown> {
+	return {
+		dev: identity.dev.toString(),
+		ino: identity.ino.toString(),
+		nlink: identity.nlink?.toString(),
+		size: identity.size,
+		mtimeNs: identity.mtimeNs.toString(),
+		sha256: identity.sha256,
+	};
+}
+
+export function sameIdentity(left: SessionStorageFileIdentity, right: SessionStorageFileIdentity): boolean {
+	return (
+		left.dev === right.dev &&
+		left.ino === right.ino &&
+		left.nlink === right.nlink &&
+		left.size === right.size &&
+		left.mtimeNs === right.mtimeNs &&
+		left.sha256 === right.sha256
+	);
+}
+
+export function managedGcRetirementIdentityValue(value: unknown): SessionStorageFileIdentity {
+	if (!isRecord(value)) throw new Error("task_artifact_owner_continuation_corrupt");
+	if (
+		Object.keys(value).length !== 6 ||
+		!["dev", "ino", "nlink", "size", "mtimeNs", "sha256"].every(key => key in value) ||
+		typeof value.dev !== "string" ||
+		!/^(0|[1-9][0-9]*)$/u.test(value.dev) ||
+		typeof value.ino !== "string" ||
+		!/^(0|[1-9][0-9]*)$/u.test(value.ino) ||
+		typeof value.nlink !== "string" ||
+		!/^(0|[1-9][0-9]*)$/u.test(value.nlink) ||
+		value.nlink !== "1" ||
+		typeof value.size !== "number" ||
+		!Number.isSafeInteger(value.size) ||
+		value.size < 0 ||
+		typeof value.mtimeNs !== "string" ||
+		!/^(0|-?[1-9][0-9]*)$/u.test(value.mtimeNs) ||
+		typeof value.sha256 !== "string" ||
+		!/^[0-9a-f]{64}$/u.test(value.sha256)
+	)
+		throw new Error("task_artifact_owner_continuation_corrupt");
+	return {
+		dev: BigInt(value.dev),
+		ino: BigInt(value.ino),
+		nlink: BigInt(value.nlink),
+		size: value.size,
+		mtimeNs: BigInt(value.mtimeNs),
+		sha256: value.sha256,
+	};
+}
+
+function validateTarget(
+	ownerContext: TaskArtifactOwnerStorageContext,
+	target: ManagedGcSessionRetirementTarget,
+): { locator: TaskArtifactOwnerLocator; identity: SessionStorageFileIdentity } {
+	if (
+		!target ||
+		typeof target.transcriptPath !== "string" ||
+		typeof target.sessionId !== "string" ||
+		typeof target.cwd !== "string"
+	)
+		throw new Error("task_artifact_owner_continuation_authority_mismatch");
+	assertSessionRoot(ownerContext);
+	const relativeTranscript = path.relative(ownerContext.sessionsRoot, target.transcriptPath);
+	if (
+		target.sessionId.length === 0 ||
+		!path.isAbsolute(target.transcriptPath) ||
+		path.resolve(target.transcriptPath) !== target.transcriptPath ||
+		relativeTranscript === "" ||
+		path.isAbsolute(relativeTranscript) ||
+		relativeTranscript === ".." ||
+		relativeTranscript.startsWith(`..${path.sep}`)
+	)
+		throw new Error("task_artifact_owner_continuation_authority_mismatch");
+	let locator: TaskArtifactOwnerLocator | undefined;
+	try {
+		locator = parseTaskArtifactOwnerLocator(target.taskArtifactOwnerLocator);
+	} catch {
+		throw new Error("task_artifact_owner_continuation_authority_mismatch");
+	}
+	if (!locator) throw new Error("task_artifact_owner_continuation_authority_mismatch");
+	let identity: SessionStorageFileIdentity;
+	try {
+		identity = managedGcRetirementIdentityValue(managedGcRetirementIdentityRecord(target.transcriptIdentity));
+	} catch {
+		throw new Error("task_artifact_owner_continuation_identity_invalid");
+	}
+	if (
+		identity.nlink !== 1n ||
+		identity.size < 0 ||
+		!Number.isSafeInteger(identity.size) ||
+		!/^[0-9a-f]{64}$/u.test(identity.sha256)
+	)
+		throw new Error("task_artifact_owner_continuation_identity_invalid");
+	return { locator, identity };
+}
+
+/**
+ * Strictly decode one persisted managed-GC receipt. A decoded `owner_retired` outcome is persisted DTO data only;
+ * this pure parser does not verify current filesystem state, payload destruction, or writer quiescence. A future
+ * journal reader must perform the live physical-retirement proof for the relevant state before treating it as done.
+ */
+export function parseManagedGcRetirementReceipt(
+	value: unknown,
+	scopeDigest: string,
+	ownerContext: TaskArtifactOwnerStorageContext,
+	target: ManagedGcSessionRetirementTarget,
+): ManagedGcSessionRetirementReceipt {
+	if (!isRecord(value)) throw new Error("task_artifact_owner_continuation_corrupt");
+	const { locator: targetLocator, identity: targetIdentity } = validateTarget(ownerContext, target);
+	const record = value;
+	const state = record.state;
+	const commonKeys = [
+		"schemaVersion",
+		"state",
+		"scope",
+		"transcriptPath",
+		"sessionId",
+		"cwd",
+		"transcriptIdentity",
+		"taskArtifactOwnerDeletionEvidence",
+	];
+	const outcomeValue = record.taskArtifactOwnerRetirementOutcome;
+	const outcomeKind = isRecord(outcomeValue) ? outcomeValue.kind : undefined;
+	const expectedKeys =
+		state === "prepared"
+			? commonKeys
+			: state === "artifacts_removed"
+				? [...commonKeys, "artifactsRemoved"]
+				: state === "owner_pending"
+					? [
+							...commonKeys,
+							"ownerRetirementAttempt",
+							"artifactsRemoved",
+							"taskArtifactOwnerRetirementOutcome",
+							"taskArtifactOwnerRetirementContinuation",
+							...(outcomeKind === "payload_retired"
+								? ["taskArtifactOwnerPayloadRetired", "taskArtifactOwnerNamespaceRetained"]
+								: []),
+						]
+					: state === "owner_retired"
+						? [
+								...commonKeys,
+								"artifactsRemoved",
+								"taskArtifactOwnerRetired",
+								"taskArtifactOwnerRetirementOutcome",
+							]
+						: undefined;
+	if (
+		!expectedKeys ||
+		Object.keys(record).length !== expectedKeys.length ||
+		!expectedKeys.every(key => key in record) ||
+		record.schemaVersion !== 1 ||
+		record.scope !== scopeDigest ||
+		record.transcriptPath !== target.transcriptPath ||
+		record.sessionId !== target.sessionId ||
+		record.cwd !== target.cwd ||
+		(state !== "prepared" && record.artifactsRemoved !== true) ||
+		(state === "owner_retired" && record.taskArtifactOwnerRetired !== true) ||
+		(state === "owner_pending" &&
+			(!Number.isSafeInteger(record.ownerRetirementAttempt) || (record.ownerRetirementAttempt as number) < 1))
+	)
+		throw new Error("task_artifact_owner_continuation_mismatch");
+	const identity = managedGcRetirementIdentityValue(record.transcriptIdentity);
+	if (!sameIdentity(identity, targetIdentity)) throw new Error("task_artifact_owner_continuation_transcript_replaced");
+	let evidence: TaskArtifactOwnerDeletionEvidence;
+	try {
+		evidence = parseTaskArtifactOwnerDeletionEvidence(record.taskArtifactOwnerDeletionEvidence);
+	} catch {
+		throw new Error("task_artifact_owner_continuation_evidence_corrupt");
+	}
+	if (evidence.sessionId !== target.sessionId || JSON.stringify(evidence.locator) !== JSON.stringify(targetLocator))
+		throw new Error("task_artifact_owner_continuation_locator_mismatch");
+	let outcome: TaskArtifactOwnerRetirementOutcome | undefined;
+	if (state === "owner_pending" || state === "owner_retired") {
+		outcome = parseTaskArtifactOwnerRetirementOutcome(ownerContext, evidence, outcomeValue);
+		if (
+			(state === "owner_pending" && outcome.kind === "completed") ||
+			(state === "owner_retired" && outcome.kind !== "completed")
+		)
+			throw new Error("task_artifact_owner_continuation_outcome_mismatch");
+		if (outcome.kind !== "completed") {
+			let receiptContinuation: TaskArtifactOwnerRetirementContinuation;
+			try {
+				receiptContinuation = parseTaskArtifactOwnerRetirementContinuation(
+					ownerContext,
+					evidence,
+					record.taskArtifactOwnerRetirementContinuation,
+				);
+			} catch {
+				throw new Error("task_artifact_owner_continuation_outcome_mismatch");
+			}
+			if (JSON.stringify(receiptContinuation) !== JSON.stringify(outcome.continuation))
+				throw new Error("task_artifact_owner_continuation_outcome_mismatch");
+			if (
+				(outcome.kind === "payload_retired" &&
+					(record.taskArtifactOwnerPayloadRetired !== true ||
+						record.taskArtifactOwnerNamespaceRetained !== true)) ||
+				(outcome.kind !== "payload_retired" &&
+					("taskArtifactOwnerPayloadRetired" in record || "taskArtifactOwnerNamespaceRetained" in record))
+			)
+				throw new Error("task_artifact_owner_continuation_outcome_mismatch");
+		}
+	}
+	return {
+		state: state as ManagedGcSessionRetirementState,
+		transcriptPath: target.transcriptPath,
+		sessionId: target.sessionId,
+		cwd: target.cwd,
+		transcriptIdentity: identity,
+		taskArtifactOwnerLocator: targetLocator,
+		taskArtifactOwnerDeletionEvidence: evidence,
+		...(state !== "prepared" ? { artifactsRemoved: true as const } : {}),
+		...(state === "owner_pending" ? { ownerRetirementAttempt: record.ownerRetirementAttempt as number } : {}),
+		...(outcome ? { taskArtifactOwnerRetirementOutcome: outcome } : {}),
+		...(outcome && outcome.kind !== "completed"
+			? { taskArtifactOwnerRetirementContinuation: outcome.continuation }
+			: {}),
+		...(outcome?.kind === "payload_retired"
+			? { taskArtifactOwnerPayloadRetired: true as const, taskArtifactOwnerNamespaceRetained: true as const }
+			: {}),
+		...(state === "owner_retired" ? { taskArtifactOwnerRetired: true as const } : {}),
+	};
+}
+
+/** Check only monotone DTO history; this does not establish physical cleanup or current authority. */
+export function continuationExtendsPrevious(
+	previous: TaskArtifactOwnerRetirementContinuation,
+	next: TaskArtifactOwnerRetirementContinuation,
+): boolean {
+	const previousTree = previous.retainedTreeSnapshot;
+	const nextTree = next.retainedTreeSnapshot;
+	if (
+		previous.parentIdentity.dev !== next.parentIdentity.dev ||
+		previous.parentIdentity.ino !== next.parentIdentity.ino ||
+		previousTree.rootDev !== nextTree.rootDev ||
+		previousTree.rootIno !== nextTree.rootIno ||
+		nextTree.entries.length > previousTree.entries.length
+	)
+		return false;
+	const previousEntries = new Map(previousTree.entries.map(entry => [entry.relativePath, entry]));
+	for (const entry of nextTree.entries) {
+		const old = previousEntries.get(entry.relativePath);
+		if (
+			!old ||
+			old.kind !== entry.kind ||
+			old.dev !== entry.dev ||
+			old.ino !== entry.ino ||
+			old.nlink !== entry.nlink
+		)
+			return false;
+		if (
+			entry.kind === "file" &&
+			!(
+				(entry.size === old.size && entry.sha256 === old.sha256) ||
+				(entry.size === "0" && entry.sha256 === EMPTY_PAYLOAD_SHA256)
+			)
+		)
+			return false;
+		if (entry.kind !== "file" && entry.size !== old.size) return false;
+	}
+	for (const key of [
+		"detachedPaths",
+		"nativeCodes",
+		"retainedSuccessorPaths",
+		"retainedPlaceholderPaths",
+		"retainedUnknownPaths",
+		"windowsErrorCodes",
+	] as const) {
+		const oldValues = previous[key] ?? [];
+		const nextValues = next[key] ?? [];
+		if (!oldValues.every(item => nextValues.includes(item))) return false;
+	}
+	return previous.payloadDurable !== true || next.payloadDurable === true;
+}