@gajae-code/coding-agent 0.11.11 → 0.12.1

package/src/session/internal/managed-session-scope.ts

@@ -33,6 +33,7 @@ import {
 	ManagedSessionDescendantStore,
 	type ManagedSessionSecurityPolicy,
 	type ManagedStorageLock,
+	managedSecurityFailureClassification,
 	prepareManagedDirectoryRoot,
 	publishManagedFileNoReplace,
 	publishManagedTombstone,
@@ -873,21 +874,44 @@ function isRecoverableOwnerOnlyModeDrift(error: unknown): boolean {
 	return message === "mode_mismatch" || message.endsWith(": mode_mismatch");
 }
 
+type ManagedScopePrepareStage =
+	| "retained_identity"
+	| "root_authority"
+	| "sessions_root"
+	| "scope_directory"
+	| "scope_identity"
+	| "retained_authority"
+	| "store"
+	| "binding_publish"
+	| "binding_read"
+	| "binding_validate"
+	| "scope_revalidate"
+	| "internal_directory"
+	| "locks_directory"
+	| "receipts_directory"
+	| "tombstones_directory";
+
 /** Synchronously create and validate the v2 binding before a default session writer exists. */
 export function prepareManagedSessionScopeForWriteSync(
 	scope: ManagedScope,
 	policy: ManagedSessionSecurityPolicy = "default",
 	authority?: ManagedCandidateWriteAuthority,
 ): ManagedScopeResolution {
+	let stage: ManagedScopePrepareStage = "retained_identity";
 	try {
 		assertRetainedManagedDirectoryIdentity(scope);
+		stage = "root_authority";
 		const root = authority?.rootAuthority ?? scopeRoot(scope, policy);
 		if (authority) bindManagedWriteAuthority(scope, authority);
+		stage = "sessions_root";
 		ensureManagedDirectory(scope.sessionsRoot, root, policy);
+		stage = "scope_directory";
 		ensureManagedDirectory(scope.directoryPath, root, policy);
+		stage = "scope_identity";
 		const preparedDirectory = fs.lstatSync(scope.directoryPath, { bigint: true });
 		if (!preparedDirectory.isDirectory() || preparedDirectory.isSymbolicLink())
 			throw new Error("Managed session directory changed");
+		stage = "retained_authority";
 		const retainedAuthority =
 			authority?.retainedAuthority &&
 			authority.retainedDirectory !== undefined &&
@@ -904,6 +928,7 @@ export function prepareManagedSessionScopeForWriteSync(
 				retainedAuthority ? { authority: retainedAuthority, authorityBaseDir: scope.directoryPath } : undefined,
 				policy,
 			);
+		stage = "store";
 		let store: ManagedSessionDescendantStore;
 		try {
 			store = buildStore();
@@ -917,15 +942,19 @@ export function prepareManagedSessionScopeForWriteSync(
 			store = buildStore();
 		}
 		const binding = new TextEncoder().encode(`${JSON.stringify(bindingFor(scope))}\n`);
+		stage = "binding_publish";
 		try {
 			store.publishNoReplaceSync(MANAGED_SESSION_BINDING_FILE, binding);
 		} catch (error) {
 			if ((error as Error).message !== "destination_conflict") throw error;
 		}
+		stage = "binding_read";
 		const capturedBinding = store.readExpected(MANAGED_SESSION_BINDING_FILE);
 		if (!capturedBinding) throw new Error("Managed scope binding is unavailable");
+		stage = "binding_validate";
 		const validated = validateBindingRaw(scope, capturedBinding.bytes.toString("utf8"));
 		managedDirectoryAuthorities.set(scope, retainedAuthority);
+		stage = "scope_revalidate";
 		const directoryStat = fs.lstatSync(scope.directoryPath, { bigint: true });
 		if (
 			!directoryStat.isDirectory() ||
@@ -935,11 +964,21 @@ export function prepareManagedSessionScopeForWriteSync(
 		)
 			throw new Error("Managed session directory changed");
 		managedDirectoryIdentities.set(scope, { dev: preparedDirectory.dev, ino: preparedDirectory.ino });
-		if (validated) return validated;
+		if (validated) {
+			if (validated.kind !== "error") throw new Error("Unexpected managed scope binding result");
+			return {
+				...validated,
+				cause: { classification: validated.code, diagnostic: "prepare:binding_validate" },
+			};
+		}
 		const internal = managedInternalDirectory(scope);
+		stage = "internal_directory";
 		ensureManagedDirectory(internal, root, policy);
+		stage = "locks_directory";
 		ensureManagedDirectory(path.join(internal, MANAGED_LOCKS_DIRECTORY), root, policy);
+		stage = "receipts_directory";
 		ensureManagedDirectory(path.join(internal, MANAGED_RECEIPTS_DIRECTORY), root, policy);
+		stage = "tombstones_directory";
 		ensureManagedDirectory(path.join(internal, MANAGED_TOMBSTONES_DIRECTORY), root, policy);
 		return { kind: "resolved", scope };
 	} catch (error) {
@@ -954,15 +993,14 @@ export function prepareManagedSessionScopeForWriteSync(
 			message === "durability_not_provable"
 				? message
 				: "binding_invalid";
+		const securityClassification = managedSecurityFailureClassification(error);
 		return {
 			kind: "error",
 			code,
 			message,
-			...(publication
-				? { cause: { classification: publication.classification, diagnostic: publication.diagnostic } }
-				: code === "binding_invalid"
-					? {}
-					: { cause: { classification: code } }),
+			cause: publication
+				? { classification: publication.classification, diagnostic: publication.diagnostic }
+				: { classification: securityClassification ?? code, diagnostic: `prepare:${stage}` },
 		};
 	}
 }

package/src/session/internal/managed-session-storage.ts

@@ -377,12 +377,31 @@ function managedRelativePath(root: ManagedDirectoryRoot, pathname: string): read
 
 const PROCESS_START_ID = randomUUID();
 
+class ManagedSecurityError extends Error {
+	readonly #classification: string;
+
+	constructor(pathname: string, result: NativeSecurity) {
+		const classification = result.ok ? "unexpected_security_state" : result.code;
+		super(
+			result.ok
+				? `Unexpected security state for ${pathname}`
+				: `Owner-only security rejected ${pathname}: ${classification}`,
+		);
+		this.name = "ManagedSecurityError";
+		this.#classification = classification;
+	}
+
+	getClassification(): string {
+		return this.#classification;
+	}
+}
+
+export function managedSecurityFailureClassification(error: unknown): string | undefined {
+	return error instanceof ManagedSecurityError ? error.getClassification() : undefined;
+}
+
 function securityError(pathname: string, result: NativeSecurity): Error {
-	return new Error(
-		result.ok
-			? `Unexpected security state for ${pathname}`
-			: `Owner-only security rejected ${pathname}: ${result.code}`,
-	);
+	return new ManagedSecurityError(pathname, result);
 }
 
 function secure(pathname: string, kind: "directory" | "file"): void {
@@ -453,7 +472,11 @@ export class ManagedSessionDescendantStore {
 	readonly #baseDir: string;
 	readonly #policy: ManagedSessionSecurityPolicy;
 	readonly #authority: RecoveryFsRoot | undefined;
+	#ownsAuthority = false;
+	#closed = false;
 	readonly #authorityBaseDir: string;
+	/** Logical profile root inherited by nested managed session destinations. */
+	readonly #profileAgentDir: string;
 	readonly #subtreeRoot: ManagedDirectoryRoot;
 
 	constructor(
@@ -461,12 +484,14 @@ export class ManagedSessionDescendantStore {
 		baseDir: string,
 		retained?: { authority: RecoveryFsRoot; authorityBaseDir: string },
 		policy?: ManagedSessionSecurityPolicy,
+		profileAgentDir?: string,
 	) {
 		managedRelativePath(root, baseDir);
 
 		this.#root = root;
 		this.#baseDir = path.resolve(baseDir);
 		this.#policy = policy ?? "default";
+		this.#profileAgentDir = profileAgentDir ?? root.canonicalPath;
 		this.#authorityBaseDir = retained?.authorityBaseDir ?? this.#baseDir;
 		if (retained) {
 			const relative = path.relative(retained.authorityBaseDir, this.#baseDir).split(path.sep).join("/");
@@ -501,6 +526,7 @@ export class ManagedSessionDescendantStore {
 				throw new Error("Managed descendant root identity changed");
 			}
 			this.#authority = authority;
+			this.#ownsAuthority = true;
 		}
 	}
 
@@ -520,10 +546,15 @@ export class ManagedSessionDescendantStore {
 		return this.#policy;
 	}
 
+	get profileAgentDir(): string {
+		return this.#profileAgentDir;
+	}
+
 	deriveSubtree(relativePath: string): ManagedSessionDescendantStore {
 		const child = this.ensureDirectory(relativePath);
 		const resolved = this.#resolve(relativePath);
-		if (!this.#authority) return new ManagedSessionDescendantStore(this.#root, resolved, undefined, this.#policy);
+		if (!this.#authority)
+			return new ManagedSessionDescendantStore(this.#root, resolved, undefined, this.#policy, this.#profileAgentDir);
 		const retainedChild = this.#authority.retainManagedDirectory(
 			this.#relative(resolved),
 			child.dev.toString(),
@@ -537,6 +568,7 @@ export class ManagedSessionDescendantStore {
 				authorityBaseDir: resolved,
 			},
 			this.#policy,
+			this.#profileAgentDir,
 		);
 	}
 
@@ -549,6 +581,16 @@ export class ManagedSessionDescendantStore {
 		);
 	}
 
+	/**
+	 * Release an authority this store opened itself. Retained authorities are owned by
+	 * the security context that supplied them and are never closed here. Idempotent.
+	 */
+	close(): void {
+		if (this.#closed || !this.#ownsAuthority || !this.#authority) return;
+		this.#closed = true;
+		this.#authority.close();
+	}
+
 	assertBound(): void {
 		this.#assertBound();
 	}

package/src/session/memory-guard-checkpoint-participant.ts

@@ -0,0 +1,131 @@
+import * as crypto from "node:crypto";
+import * as path from "node:path";
+import type { RecoveryFsRoot } from "@gajae-code/natives";
+import type {
+	RecoveryHydrationContext,
+	ResumeSessionIdentity,
+	SessionDestinationInput,
+	SessionManager,
+	SessionManagerCheckpointRevisionStrings,
+	StrictSessionOpenFailure,
+} from "./session-manager";
+
+export interface MemoryGuardTranscriptDescriptorV1 {
+	bytes: string;
+	relative_path: string;
+	sha256: string;
+}
+
+export interface MemoryGuardCheckpointBlobAuthorityV1 {
+	kind: "checkpoint_blob_tree_v1";
+	manifest_relative_path: string;
+	manifest_sha256: string;
+	root_relative_path: string;
+}
+
+export interface MemoryGuardCheckpointBlobManifestEntryV1 {
+	bytes: string;
+	relative_path: string;
+	sha256: string;
+}
+
+export interface MemoryGuardCheckpointBlobManifestV1 {
+	entries: MemoryGuardCheckpointBlobManifestEntryV1[];
+	schema_version: 1;
+}
+
+export interface MemoryGuardSessionManagerCheckpointV1 {
+	blob_authority: MemoryGuardCheckpointBlobAuthorityV1;
+	revisions: SessionManagerCheckpointRevisionStrings;
+	schema_version: 1;
+	session_id: string;
+	session_name: string | null;
+	transcript: MemoryGuardTranscriptDescriptorV1;
+}
+
+export interface MemoryGuardParticipantDescriptorV1 {
+	ordinal: number;
+	checkpoint: MemoryGuardCheckpointBlobAuthorityV1;
+	revisions: SessionManagerCheckpointRevisionStrings;
+	session_id: string;
+	session_name: string | null;
+	transcript: MemoryGuardTranscriptDescriptorV1;
+}
+
+export interface MemoryGuardParticipantIngressLease {
+	readonly token: symbol;
+	release(): void;
+}
+
+export interface MemoryGuardCreateCheckpointInput {
+	ingressLease: MemoryGuardParticipantIngressLease;
+	checkpointRoot: string;
+}
+
+export type MemoryGuardRestoreBlockedReason =
+	| StrictSessionOpenFailure["reason"]
+	| "checkpoint-mismatch"
+	| "participant-mismatch"
+	| "transcript-mismatch"
+	| "blob-manifest-mismatch"
+	| "blob-missing"
+	| "blob-hash-mismatch"
+	| "blob-authority-mismatch"
+	| "destination-unavailable";
+
+export interface MemoryGuardRestoreInput {
+	incidentAuthority: RecoveryFsRoot;
+	participant: MemoryGuardParticipantDescriptorV1;
+	checkpoint: MemoryGuardSessionManagerCheckpointV1;
+	destination: SessionDestinationInput;
+}
+
+export type MemoryGuardRestoreResult =
+	| {
+			kind: "staged";
+			manager: SessionManager;
+			hydrationContext: RecoveryHydrationContext;
+			transcriptIdentity: ResumeSessionIdentity;
+			cleanup: () => Promise<void>;
+	  }
+	| { kind: "blocked"; reason: MemoryGuardRestoreBlockedReason };
+
+function sortJson(value: unknown): unknown {
+	if (Array.isArray(value)) return value.map(sortJson);
+	if (value && typeof value === "object") {
+		return Object.fromEntries(
+			Object.entries(value as Record<string, unknown>)
+				.sort(([left], [right]) => left.localeCompare(right))
+				.map(([key, child]) => [key, sortJson(child)]),
+		);
+	}
+	return value;
+}
+
+export function memoryGuardCanonicalJson(value: unknown): string {
+	return `${JSON.stringify(sortJson(value))}\n`;
+}
+
+export function memoryGuardSha256Hex(value: Uint8Array | string): string {
+	return crypto.createHash("sha256").update(value).digest("hex");
+}
+
+export function isMemoryGuardDecimalString(value: unknown): value is string {
+	return typeof value === "string" && /^(?:0|[1-9]\d*)$/.test(value);
+}
+
+export function isMemoryGuardSha256Hex(value: unknown): value is string {
+	return typeof value === "string" && /^[0-9a-f]{64}$/.test(value);
+}
+
+export function isMemoryGuardRelativePath(value: unknown): value is string {
+	if (typeof value !== "string" || value.length === 0) return false;
+	if (path.isAbsolute(value) || value.includes("\\")) return false;
+	const parts = value.split("/");
+	return parts.every(part => part.length > 0 && part !== "." && part !== "..");
+}
+
+export function hasOnlyKeys(value: Record<string, unknown>, allowed: readonly string[]): boolean {
+	const keys = Object.keys(value);
+	return keys.length === allowed.length && keys.every(key => allowed.includes(key));
+}