@gajae-code/coding-agent 0.18.5 → 0.18.7

package/src/session/internal/task-artifact-owner-access.ts

@@ -0,0 +1,229 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { NativeDirectoryTreeSnapshot } from "@gajae-code/natives";
+import {
+	assertSafeRelativePath,
+	assertSessionRoot,
+	freezeTreeSnapshot,
+	immutableDeletionEvidence,
+	isOwnerRetainedRoot,
+	manifestRelativePath,
+	OWNER_DIRECTORY,
+	OWNER_MANIFEST,
+	OWNER_SCHEMA_VERSION,
+	ownerIdForSession,
+	ownerRelativePath,
+	parseTaskArtifactOwnerLocator,
+	sameOwnerParentIdentity,
+	type TaskArtifactOwnerDeletionEvidence,
+	type TaskArtifactOwnerLocator,
+	type TaskArtifactOwnerParentIdentity,
+	type TaskArtifactOwnerStorageContext,
+} from "../task-artifact-owner-codec";
+import { ManagedSessionDescendantStore } from "./managed-session-storage";
+
+export interface OwnerManifest extends TaskArtifactOwnerLocator {
+	readonly sessionId: string;
+}
+
+export function newSessionRootStore(context: TaskArtifactOwnerStorageContext): ManagedSessionDescendantStore {
+	assertSessionRoot(context);
+	if (path.resolve(context.profileAgentDir) !== context.profileAgentDir)
+		throw new Error("task_artifact_owner_profile_invalid");
+	const profile = fs.lstatSync(context.profileAgentDir, { bigint: true });
+	if (!profile.isDirectory() || profile.isSymbolicLink()) throw new Error("task_artifact_owner_profile_invalid");
+	const stat = fs.lstatSync(context.sessionsRoot, { bigint: true });
+	if (!stat.isDirectory() || stat.isSymbolicLink()) throw new Error("task_artifact_owner_root_invalid");
+	return new ManagedSessionDescendantStore(
+		context.rootAuthority,
+		context.sessionsRoot,
+		undefined,
+		context.securityPolicy,
+		context.profileAgentDir,
+		{
+			canonicalPath: context.sessionsRoot,
+			dev: BigInt.asUintN(64, stat.dev),
+			ino: BigInt.asUintN(64, stat.ino),
+		},
+	);
+}
+
+function parseOwnerManifest(bytes: Uint8Array): OwnerManifest {
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(Buffer.from(bytes).toString("utf8"));
+	} catch {
+		throw new Error("task_artifact_owner_manifest_invalid");
+	}
+	if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed) || Object.keys(parsed).length !== 5)
+		throw new Error("task_artifact_owner_manifest_invalid");
+	const record = parsed as Record<string, unknown>;
+	if (typeof record.sessionId !== "string" || record.sessionId.length === 0)
+		throw new Error("task_artifact_owner_manifest_invalid");
+	let locator: TaskArtifactOwnerLocator | undefined;
+	try {
+		locator = parseTaskArtifactOwnerLocator({
+			schemaVersion: record.schemaVersion,
+			ownerId: record.ownerId,
+			directoryDev: record.directoryDev,
+			directoryIno: record.directoryIno,
+		});
+	} catch {
+		throw new Error("task_artifact_owner_manifest_invalid");
+	}
+	if (!locator) throw new Error("task_artifact_owner_manifest_invalid");
+	return { ...locator, sessionId: record.sessionId };
+}
+
+export function readOwnerManifest(
+	store: ManagedSessionDescendantStore,
+	locator: TaskArtifactOwnerLocator,
+	relativePath = manifestRelativePath(locator.ownerId),
+): OwnerManifest {
+	const manifest = store.readExpected(relativePath);
+	if (!manifest) throw new Error("task_artifact_owner_manifest_missing");
+	const parsed = parseOwnerManifest(manifest.bytes);
+	if (
+		parsed.ownerId !== locator.ownerId ||
+		parsed.directoryDev !== locator.directoryDev ||
+		parsed.directoryIno !== locator.directoryIno
+	)
+		throw new Error("task_artifact_owner_manifest_mismatch");
+	return parsed;
+}
+
+export function assertOwnerDirectoryExists(context: TaskArtifactOwnerStorageContext, ownerId: string): void {
+	const parent = path.join(context.sessionsRoot, OWNER_DIRECTORY);
+	const owner = path.join(parent, ownerId);
+	for (const candidate of [parent, owner]) {
+		let stat: fs.BigIntStats;
+		try {
+			stat = fs.lstatSync(candidate, { bigint: true });
+		} catch (error) {
+			if ((error as NodeJS.ErrnoException).code === "ENOENT") throw new Error("task_artifact_owner_missing");
+			throw error;
+		}
+		if (!stat.isDirectory() || stat.isSymbolicLink()) throw new Error("task_artifact_owner_replaced");
+	}
+}
+
+export function assertOwnerIdentity(store: ManagedSessionDescendantStore, locator: TaskArtifactOwnerLocator): void {
+	const identity = store.subtreeRootAuthority;
+	if (identity.dev.toString() !== locator.directoryDev || identity.ino.toString() !== locator.directoryIno)
+		throw new Error("task_artifact_owner_identity_mismatch");
+}
+
+export function openOwnerStore(
+	context: TaskArtifactOwnerStorageContext,
+	rootStore: ManagedSessionDescendantStore,
+	locator: TaskArtifactOwnerLocator,
+	sessionId: string,
+): ManagedSessionDescendantStore {
+	if (locator.ownerId !== ownerIdForSession(sessionId)) throw new Error("task_artifact_owner_session_mismatch");
+	assertOwnerDirectoryExists(context, locator.ownerId);
+	const manifest = readOwnerManifest(rootStore, locator);
+	if (manifest.sessionId !== sessionId) throw new Error("task_artifact_owner_session_mismatch");
+	const identity = rootStore.captureDirectoryIdentity(ownerRelativePath(locator.ownerId));
+	if (identity.dev !== locator.directoryDev || identity.ino !== locator.directoryIno)
+		throw new Error("task_artifact_owner_identity_mismatch");
+	const ownerPath = path.join(context.sessionsRoot, ownerRelativePath(locator.ownerId));
+	const ownerStore = new ManagedSessionDescendantStore(
+		context.rootAuthority,
+		ownerPath,
+		undefined,
+		context.securityPolicy,
+		context.profileAgentDir,
+		{
+			canonicalPath: ownerPath,
+			dev: BigInt(locator.directoryDev),
+			ino: BigInt(locator.directoryIno),
+		},
+	);
+	try {
+		assertOwnerIdentity(ownerStore, locator);
+		readOwnerManifest(ownerStore, locator, OWNER_MANIFEST);
+		return ownerStore;
+	} catch (error) {
+		ownerStore.close();
+		throw error;
+	}
+}
+
+export function locatorFromManifest(manifest: OwnerManifest): TaskArtifactOwnerLocator {
+	return {
+		schemaVersion: OWNER_SCHEMA_VERSION,
+		ownerId: manifest.ownerId,
+		directoryDev: manifest.directoryDev,
+		directoryIno: manifest.directoryIno,
+	};
+}
+
+export function captureValidatedOwnerTree(
+	context: TaskArtifactOwnerStorageContext,
+	rootStore: ManagedSessionDescendantStore,
+	sessionId: string,
+	locator: TaskArtifactOwnerLocator,
+): NativeDirectoryTreeSnapshot {
+	if (locator.ownerId !== ownerIdForSession(sessionId)) throw new Error("task_artifact_owner_session_mismatch");
+	assertOwnerDirectoryExists(context, locator.ownerId);
+	const manifest = readOwnerManifest(rootStore, locator);
+	if (manifest.sessionId !== sessionId) throw new Error("task_artifact_owner_session_mismatch");
+	const tree = rootStore.captureTree(ownerRelativePath(locator.ownerId));
+	if (tree.rootDev !== locator.directoryDev || tree.rootIno !== locator.directoryIno)
+		throw new Error("task_artifact_owner_identity_mismatch");
+	return tree;
+}
+
+export function captureOwnerTreeIfPresent(
+	context: TaskArtifactOwnerStorageContext,
+	rootStore: ManagedSessionDescendantStore,
+	ownerId: string,
+	pathname: string,
+): NativeDirectoryTreeSnapshot | undefined {
+	if (!isOwnerRetainedRoot(context, ownerId, pathname))
+		throw new Error("task_artifact_owner_retained_root_unrecognized");
+	let named: fs.BigIntStats;
+	try {
+		named = fs.lstatSync(pathname, { bigint: true });
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "ENOENT") return undefined;
+		throw error;
+	}
+	if (!named.isDirectory() || named.isSymbolicLink()) throw new Error("task_artifact_owner_retained_root_replaced");
+	const relative = path.relative(context.sessionsRoot, pathname).split(path.sep).join("/");
+	assertSafeRelativePath(relative);
+	return freezeTreeSnapshot(rootStore.captureTree(relative));
+}
+
+export function ownerTreeHasPendingManagedPublication(snapshot: NativeDirectoryTreeSnapshot): boolean {
+	return snapshot.entries.some(entry =>
+		/^\..+\.[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\.(?:staging|replacement)$/u.test(
+			path.posix.basename(entry.relativePath),
+		),
+	);
+}
+
+/** Capture exact owner evidence without repairing its security, timestamps, or namespace. */
+export function captureTaskArtifactOwnerDeletionEvidence(
+	context: TaskArtifactOwnerStorageContext,
+	sessionId: string,
+	locatorValue: unknown,
+): TaskArtifactOwnerDeletionEvidence | undefined {
+	const locator = parseTaskArtifactOwnerLocator(locatorValue);
+	if (!locator) return undefined;
+	const rootStore = newSessionRootStore(context);
+	try {
+		rootStore.verifyRootSecurity();
+		const parentIdentity: TaskArtifactOwnerParentIdentity = rootStore.captureDirectoryIdentity(OWNER_DIRECTORY);
+		const treeSnapshot = captureValidatedOwnerTree(context, rootStore, sessionId, locator);
+		// This refuses to capture during publication; it does not revoke independent open descriptors.
+		if (ownerTreeHasPendingManagedPublication(treeSnapshot))
+			throw new Error("task_artifact_owner_writer_not_quiescent");
+		const parentAfter = rootStore.captureDirectoryIdentity(OWNER_DIRECTORY);
+		if (!sameOwnerParentIdentity(parentIdentity, parentAfter))
+			throw new Error("task_artifact_owner_parent_changed_during_capture");
+		return immutableDeletionEvidence(sessionId, locator, parentIdentity, treeSnapshot);
+	} finally {
+		rootStore.close();
+	}
+}

package/src/session/internal/task-artifact-owner-transcript.ts

@@ -0,0 +1,68 @@
+import { parseFirstJsonlLine } from "../session-transcript-header";
+import { parseTaskArtifactOwnerLocator, type TaskArtifactOwnerLocator } from "../task-artifact-owner-codec";
+
+const transcriptDecoder = new TextDecoder("utf-8", { fatal: true });
+
+/** Resolve the path-free owner locator using transcript replay's header-patch semantics. */
+export function taskArtifactOwnerLocatorFromTranscriptBytes(
+	bytes: Uint8Array,
+	expectedSessionId: string,
+): TaskArtifactOwnerLocator | undefined {
+	const header = parseFirstJsonlLine(bytes);
+	if (header?.type !== "session" || header.id !== expectedSessionId)
+		throw new Error("task_artifact_owner_transcript_header_invalid");
+	let locator = parseTaskArtifactOwnerLocator(header.taskArtifactOwner);
+	if (typeof header.version !== "number" || header.version < 4) return locator;
+	const firstEnd = bytes.indexOf(0x0a);
+	let start = firstEnd < 0 ? bytes.byteLength : firstEnd + 1;
+	while (start < bytes.byteLength) {
+		const newline = bytes.indexOf(0x0a, start);
+		const end = newline < 0 ? bytes.byteLength : newline;
+		const line = bytes.subarray(start, end);
+		let record: Record<string, unknown> | undefined;
+		try {
+			if (line.byteLength > 0) {
+				const parsed: unknown = JSON.parse(transcriptDecoder.decode(line));
+				if (typeof parsed === "object" && parsed !== null && !Array.isArray(parsed))
+					record = parsed as Record<string, unknown>;
+			}
+		} catch {
+			const text = Buffer.from(line).toString("utf8");
+			if (text.includes("header_patch") && text.includes("taskArtifactOwner"))
+				throw new Error("task_artifact_owner_patch_invalid");
+		}
+		if (
+			record?.type === "header_patch" &&
+			typeof record.patch === "object" &&
+			record.patch !== null &&
+			!Array.isArray(record.patch) &&
+			Object.hasOwn(record.patch, "taskArtifactOwner")
+		) {
+			const patch = record.patch as Record<string, unknown>;
+			if (
+				!Object.keys(record).every(key => key === "type" || key === "patch") ||
+				!Object.keys(patch).every(
+					key =>
+						key === "cwd" ||
+						key === "title" ||
+						key === "titleSource" ||
+						key === "starred" ||
+						key === "taskArtifactOwner",
+				) ||
+				(patch.cwd !== undefined && typeof patch.cwd !== "string") ||
+				(patch.title !== undefined && typeof patch.title !== "string") ||
+				(patch.titleSource !== undefined && patch.titleSource !== "auto" && patch.titleSource !== "user") ||
+				(patch.starred !== undefined && typeof patch.starred !== "boolean")
+			)
+				throw new Error("task_artifact_owner_patch_invalid");
+			try {
+				locator = parseTaskArtifactOwnerLocator(patch.taskArtifactOwner);
+			} catch {
+				throw new Error("task_artifact_owner_patch_invalid");
+			}
+		}
+		if (newline < 0) break;
+		start = newline + 1;
+	}
+	return locator;
+}

package/src/session/session-retirement.ts

@@ -0,0 +1,155 @@
+import * as crypto from "node:crypto";
+import * as path from "node:path";
+
+import { toError } from "@gajae-code/utils";
+import {
+	type FileSessionStorage,
+	SessionDeleteVerificationError,
+	type SessionStorageSnapshot,
+	type VerifiedSessionDeleteTarget,
+} from "./session-storage";
+import { parseFirstJsonlLine } from "./session-transcript-header";
+
+/**
+ * Outcome of a disk-retention retirement attempt.
+ *
+ * `kept` means the transcript survived and nothing of the session was
+ * destroyed, with the exact reason so `gjc gc --disk` can report it.
+ * `cleanup_pending` means the delete authority already detached or removed the
+ * session's artifact tree (or quarantined the transcript) before it stopped:
+ * the record survives, the session does not, and a caller must NOT report that
+ * as an ordinary keep.
+ */
+export type SessionRetirementOutcome =
+	| { kind: "retired" }
+	| { kind: "kept"; reason: string }
+	| { kind: "cleanup_pending"; reason: string };
+
+/** A retirement that cleared every precondition the retention pass itself owns. */
+type SessionRetirementPlan =
+	| { kind: "retirable"; target: VerifiedSessionDeleteTarget; artifactsPresent: boolean }
+	| { kind: "kept"; reason: string };
+
+/**
+ * Evaluate the preconditions retirement owns — the transcript must be readable
+ * and carry a usable session header — and bind the delete target to the exact
+ * bytes just read. Nothing here mutates the store.
+ */
+function planSessionRetirement(
+	storage: FileSessionStorage,
+	sessionsRoot: string,
+	transcriptPath: string,
+): SessionRetirementPlan {
+	let snapshot: SessionStorageSnapshot;
+	try {
+		snapshot = storage.readSnapshotSync(transcriptPath);
+	} catch (err) {
+		return { kind: "kept", reason: `transcript_unreadable: ${toError(err).message}` };
+	}
+
+	const header = parseFirstJsonlLine(snapshot.bytes);
+	if (header?.type !== "session" || typeof header.id !== "string" || typeof header.cwd !== "string") {
+		return { kind: "kept", reason: "transcript_header_unusable" };
+	}
+
+	// The verified delete authority only unlinks a single-link transcript, so a
+	// hard-linked one can never be retired. Refusing here keeps the dry run from
+	// promising bytes prune cannot release, and — because this runs before the
+	// artifact phase — keeps a doomed retirement from destroying the artifact
+	// tree of a session whose transcript will survive anyway.
+	if (snapshot.stat.nlink === undefined || snapshot.stat.nlink !== 1n) {
+		return { kind: "kept", reason: "transcript_not_single_link" };
+	}
+
+	const directory = path.dirname(transcriptPath);
+	return {
+		kind: "retirable",
+		artifactsPresent: storage.existsSync(transcriptPath.slice(0, -".jsonl".length)),
+		target: {
+			sessionsRoot,
+			transcriptPath,
+			sessionId: header.id,
+			cwd: header.cwd,
+			transcriptIdentity: {
+				dev: snapshot.stat.dev,
+				ino: snapshot.stat.ino,
+				nlink: snapshot.stat.nlink,
+				size: snapshot.stat.size,
+				mtimeNs: snapshot.stat.mtimeNs,
+				sha256: crypto.createHash("sha256").update(snapshot.bytes).digest("hex"),
+			},
+			plannedArtifactsPath: path.join(directory, `.gjc-delete-gc-${crypto.randomUUID()}-artifacts`),
+			plannedTranscriptPath: path.join(directory, `.gjc-delete-gc-${crypto.randomUUID()}-transcript`),
+		},
+	};
+}
+
+/**
+ * Non-mutating projection of {@link retireSessionTranscript}: would the
+ * retention pass's own preconditions let this transcript be retired at all?
+ *
+ * `gjc gc --disk` runs it so a dry run reports the verdict a prune would reach
+ * instead of promising bytes the delete authority will refuse to release. The
+ * authority's verdict (containment, identity, artifact tree) is deliberately
+ * not predicted here — it is re-derived against live state at delete time.
+ */
+export function probeSessionRetirement(
+	storage: FileSessionStorage,
+	sessionsRoot: string,
+	transcriptPath: string,
+): { kind: "retirable" } | { kind: "kept"; reason: string } {
+	const plan = planSessionRetirement(storage, sessionsRoot, transcriptPath);
+	return plan.kind === "retirable" ? { kind: "retirable" } : plan;
+}
+
+/**
+ * A transcript that survives after its artifacts are already gone is not a
+ * benign keep: the session is half-destroyed and the caller has to surface it.
+ */
+function retirementIncomplete(artifactsRemoved: boolean, reason: string): SessionRetirementOutcome {
+	return artifactsRemoved ? { kind: "cleanup_pending", reason } : { kind: "kept", reason };
+}
+
+/**
+ * Retire one managed session transcript through the verified hard-delete
+ * authority.
+ *
+ * This is the only supported way for a retention pass to remove a transcript:
+ * identity, containment, header id/cwd, artifact tree and parent directory are
+ * all re-verified inside {@link FileSessionStorage.deleteSessionVerified}, and
+ * anything ambiguous fails closed as `kept` rather than deleting bytes. The
+ * caller owns the retention policy; this function owns nothing but the delete
+ * authority.
+ */
+export async function retireSessionTranscript(
+	storage: FileSessionStorage,
+	sessionsRoot: string,
+	transcriptPath: string,
+): Promise<SessionRetirementOutcome> {
+	const plan = planSessionRetirement(storage, sessionsRoot, transcriptPath);
+	if (plan.kind === "kept") return plan;
+
+	let artifactsRemoved = false;
+	try {
+		// Phase 1 removes the sibling artifact directory (or proves it absent);
+		// phase 2 unlinks the transcript only against the same bound identity.
+		const artifacts = await storage.deleteSessionVerified(plan.target);
+		if (artifacts.kind === "deleted") return { kind: "retired" };
+		if (artifacts.kind === "cleanup_pending") {
+			return { kind: "cleanup_pending", reason: `cleanup_pending_${artifacts.phase}: ${artifacts.error.message}` };
+		}
+		// Phase 1 is durable: whatever artifact tree the session had is gone, so
+		// every later refusal leaves a record without its artifacts.
+		artifactsRemoved = plan.artifactsPresent;
+		const deletion = await storage.deleteSessionVerified({ ...plan.target, artifactsRemoved: true });
+		if (deletion.kind === "deleted") return { kind: "retired" };
+		if (deletion.kind === "cleanup_pending") {
+			return { kind: "cleanup_pending", reason: `cleanup_pending_${deletion.phase}: ${deletion.error.message}` };
+		}
+		return retirementIncomplete(artifactsRemoved, "transcript_not_deleted");
+	} catch (err) {
+		const error = toError(err);
+		const kind = err instanceof SessionDeleteVerificationError ? err.kind : "error";
+		return retirementIncomplete(artifactsRemoved, `verified_delete_rejected(${kind}): ${error.message}`);
+	}
+}

package/src/session/session-storage.ts

@@ -28,6 +28,7 @@ import {
 	type NativePublishOutcome,
 } from "./internal/native-publish-outcome";
 import { isDerivedSessionMemoryFile } from "./internal/session-memory-sidecar";
+import { parseFirstJsonlLine } from "./session-transcript-header";
 
 const utf8Decoder = new TextDecoder("utf-8");
 const newlineBuffer = Buffer.from("\n", "utf8");
@@ -2883,22 +2884,6 @@ export class FileSessionStorage implements SessionStorage {
 	}
 }
 
-/** Parse the first JSONL line as a generic record; returns undefined on parse failure. */
-function parseFirstJsonlLine(bytes: Uint8Array): Record<string, unknown> | undefined {
-	const NL = 0x0a;
-	const end = bytes.indexOf(NL);
-	const firstLine = end === -1 ? bytes : bytes.subarray(0, end);
-	if (firstLine.length === 0) return undefined;
-	try {
-		const text = utf8Decoder.decode(firstLine).trim();
-		if (!text) return undefined;
-		const value: unknown = JSON.parse(text);
-		return typeof value === "object" && value !== null ? (value as Record<string, unknown>) : undefined;
-	} catch {
-		return undefined;
-	}
-}
-
 function matchesPattern(name: string, pattern: string): boolean {
 	if (pattern === "*") return true;
 	if (pattern === ".*") return name.startsWith(".");
@@ -3531,147 +3516,3 @@ export class MemorySessionStorage implements SessionStorage {
 		return new MemoryStagedStreamingWriter(this, path);
 	}
 }
-
-/**
- * Outcome of a disk-retention retirement attempt.
- *
- * `kept` means the transcript survived and nothing of the session was
- * destroyed, with the exact reason so `gjc gc --disk` can report it.
- * `cleanup_pending` means the delete authority already detached or removed the
- * session's artifact tree (or quarantined the transcript) before it stopped:
- * the record survives, the session does not, and a caller must NOT report that
- * as an ordinary keep.
- */
-export type SessionRetirementOutcome =
-	| { kind: "retired" }
-	| { kind: "kept"; reason: string }
-	| { kind: "cleanup_pending"; reason: string };
-
-/** A retirement that cleared every precondition the retention pass itself owns. */
-type SessionRetirementPlan =
-	| { kind: "retirable"; target: VerifiedSessionDeleteTarget; artifactsPresent: boolean }
-	| { kind: "kept"; reason: string };
-
-/**
- * Evaluate the preconditions retirement owns — the transcript must be readable
- * and carry a usable session header — and bind the delete target to the exact
- * bytes just read. Nothing here mutates the store.
- */
-function planSessionRetirement(
-	storage: FileSessionStorage,
-	sessionsRoot: string,
-	transcriptPath: string,
-): SessionRetirementPlan {
-	let snapshot: SessionStorageSnapshot;
-	try {
-		snapshot = storage.readSnapshotSync(transcriptPath);
-	} catch (err) {
-		return { kind: "kept", reason: `transcript_unreadable: ${toError(err).message}` };
-	}
-
-	const header = parseFirstJsonlLine(snapshot.bytes);
-	if (header?.type !== "session" || typeof header.id !== "string" || typeof header.cwd !== "string") {
-		return { kind: "kept", reason: "transcript_header_unusable" };
-	}
-
-	// The verified delete authority only unlinks a single-link transcript, so a
-	// hard-linked one can never be retired. Refusing here keeps the dry run from
-	// promising bytes prune cannot release, and — because this runs before the
-	// artifact phase — keeps a doomed retirement from destroying the artifact
-	// tree of a session whose transcript will survive anyway.
-	if (snapshot.stat.nlink === undefined || snapshot.stat.nlink !== 1n) {
-		return { kind: "kept", reason: "transcript_not_single_link" };
-	}
-
-	const directory = path.dirname(transcriptPath);
-	return {
-		kind: "retirable",
-		artifactsPresent: storage.existsSync(transcriptPath.slice(0, -".jsonl".length)),
-		target: {
-			sessionsRoot,
-			transcriptPath,
-			sessionId: header.id,
-			cwd: header.cwd,
-			transcriptIdentity: {
-				dev: snapshot.stat.dev,
-				ino: snapshot.stat.ino,
-				nlink: snapshot.stat.nlink,
-				size: snapshot.stat.size,
-				mtimeNs: snapshot.stat.mtimeNs,
-				sha256: createHash("sha256").update(snapshot.bytes).digest("hex"),
-			},
-			plannedArtifactsPath: path.join(directory, `.gjc-delete-gc-${randomUUID()}-artifacts`),
-			plannedTranscriptPath: path.join(directory, `.gjc-delete-gc-${randomUUID()}-transcript`),
-		},
-	};
-}
-
-/**
- * Non-mutating projection of {@link retireSessionTranscript}: would the
- * retention pass's own preconditions let this transcript be retired at all?
- *
- * `gjc gc --disk` runs it so a dry run reports the verdict a prune would reach
- * instead of promising bytes the delete authority will refuse to release. The
- * authority's verdict (containment, identity, artifact tree) is deliberately
- * not predicted here — it is re-derived against live state at delete time.
- */
-export function probeSessionRetirement(
-	storage: FileSessionStorage,
-	sessionsRoot: string,
-	transcriptPath: string,
-): { kind: "retirable" } | { kind: "kept"; reason: string } {
-	const plan = planSessionRetirement(storage, sessionsRoot, transcriptPath);
-	return plan.kind === "retirable" ? { kind: "retirable" } : plan;
-}
-
-/**
- * A transcript that survives after its artifacts are already gone is not a
- * benign keep: the session is half-destroyed and the caller has to surface it.
- */
-function retirementIncomplete(artifactsRemoved: boolean, reason: string): SessionRetirementOutcome {
-	return artifactsRemoved ? { kind: "cleanup_pending", reason } : { kind: "kept", reason };
-}
-
-/**
- * Retire one managed session transcript through the verified hard-delete
- * authority.
- *
- * This is the only supported way for a retention pass to remove a transcript:
- * identity, containment, header id/cwd, artifact tree and parent directory are
- * all re-verified inside {@link FileSessionStorage.deleteSessionVerified}, and
- * anything ambiguous fails closed as `kept` rather than deleting bytes. The
- * caller owns the retention policy; this function owns nothing but the delete
- * authority.
- */
-export async function retireSessionTranscript(
-	storage: FileSessionStorage,
-	sessionsRoot: string,
-	transcriptPath: string,
-): Promise<SessionRetirementOutcome> {
-	const plan = planSessionRetirement(storage, sessionsRoot, transcriptPath);
-	if (plan.kind === "kept") return plan;
-
-	let artifactsRemoved = false;
-	try {
-		// Phase 1 removes the sibling artifact directory (or proves it absent);
-		// phase 2 unlinks the transcript only against the same bound identity.
-		const artifacts = await storage.deleteSessionVerified(plan.target);
-		if (artifacts.kind === "deleted") return { kind: "retired" };
-		if (artifacts.kind === "cleanup_pending") {
-			return { kind: "cleanup_pending", reason: `cleanup_pending_${artifacts.phase}: ${artifacts.error.message}` };
-		}
-		// Phase 1 is durable: whatever artifact tree the session had is gone, so
-		// every later refusal leaves a record without its artifacts.
-		artifactsRemoved = plan.artifactsPresent;
-		const deletion = await storage.deleteSessionVerified({ ...plan.target, artifactsRemoved: true });
-		if (deletion.kind === "deleted") return { kind: "retired" };
-		if (deletion.kind === "cleanup_pending") {
-			return { kind: "cleanup_pending", reason: `cleanup_pending_${deletion.phase}: ${deletion.error.message}` };
-		}
-		return retirementIncomplete(artifactsRemoved, "transcript_not_deleted");
-	} catch (err) {
-		const error = toError(err);
-		const kind = err instanceof SessionDeleteVerificationError ? err.kind : "error";
-		return retirementIncomplete(artifactsRemoved, `verified_delete_rejected(${kind}): ${error.message}`);
-	}
-}

package/src/session/session-transcript-header.ts

@@ -0,0 +1,17 @@
+const utf8Decoder = new TextDecoder("utf-8");
+
+/** Parse the first JSONL line as a generic record; returns undefined on parse failure. */
+export function parseFirstJsonlLine(bytes: Uint8Array): Record<string, unknown> | undefined {
+	const NL = 0x0a;
+	const end = bytes.indexOf(NL);
+	const firstLine = end === -1 ? bytes : bytes.subarray(0, end);
+	if (firstLine.length === 0) return undefined;
+	try {
+		const text = utf8Decoder.decode(firstLine).trim();
+		if (!text) return undefined;
+		const value: unknown = JSON.parse(text);
+		return typeof value === "object" && value !== null ? (value as Record<string, unknown>) : undefined;
+	} catch {
+		return undefined;
+	}
+}