@gajae-code/coding-agent 0.12.0 → 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();
 	}