@gajae-code/coding-agent 0.15.2 → 0.15.3

package/src/config/model-registry.ts

@@ -16,12 +16,14 @@ import {
 	enrichModelThinking,
 	getBundledModels,
 	getBundledProviders,
+	getEnvApiKey,
 	googleAntigravityModelManagerOptions,
 	googleGeminiCliModelManagerOptions,
 	isCodexGpt56Tier,
 	isKnownProvider,
 	type Model,
 	type ModelManagerOptions,
+	type ModelMaxTokensSource,
 	type ModelRefreshStrategy,
 	type ModelRequestTransform,
 	modelSupportsReasoningControl,
@@ -47,6 +49,10 @@ function isVllmNoAuthToken(provider: string, apiKey: string | undefined): boolea
 	return provider === "vllm" && apiKey === VLLM_DEFAULT_LOCAL_TOKEN;
 }
 
+function normalizeVllmApiKey(provider: string, apiKey: string | undefined): string | undefined {
+	return isVllmNoAuthToken(provider, apiKey) ? getEnvApiKey(provider) : apiKey;
+}
+
 import { registerOAuthProvider, unregisterOAuthProviders } from "@gajae-code/ai/utils/oauth";
 import type { OAuthCredentials, OAuthLoginCallbacks } from "@gajae-code/ai/utils/oauth/types";
 import { $pickCredentialEnv, $rotatingCredentialEnv, isRecord, logger } from "@gajae-code/utils";
@@ -996,7 +1002,10 @@ function applyModelOverride(model: Model<Api>, override: ModelOverride): Model<A
 			override: override.contextWindow,
 		});
 	}
-	if (override.maxTokens !== undefined) result.maxTokens = override.maxTokens;
+	if (override.maxTokens !== undefined && Number.isSafeInteger(override.maxTokens) && override.maxTokens > 0) {
+		result.maxTokens = override.maxTokens;
+		result.maxTokensSource = "configured";
+	}
 	if (override.contextPromotionTarget !== undefined) result.contextPromotionTarget = override.contextPromotionTarget;
 	if (override.wireModelId !== undefined) result.wireModelId = override.wireModelId;
 	result.requestTransform = mergeRequestTransform(model.requestTransform, override.requestTransform);
@@ -1074,6 +1083,7 @@ type CustomModelOverlay = {
 	cost?: { input: number; output: number; cacheRead: number; cacheWrite: number };
 	contextWindow?: number;
 	maxTokens?: number;
+	maxTokensSource?: ModelMaxTokensSource;
 	headers?: Record<string, string>;
 	compat?: Model<Api>["compat"];
 	contextPromotionTarget?: string;
@@ -1150,6 +1160,10 @@ function buildCustomModelOverlay(
 		cost: modelDef.cost,
 		contextWindow: modelDef.contextWindow,
 		maxTokens: modelDef.maxTokens,
+		maxTokensSource:
+			modelDef.maxTokens !== undefined && Number.isSafeInteger(modelDef.maxTokens) && modelDef.maxTokens > 0
+				? "configured"
+				: undefined,
 		headers: mergeCustomModelHeaders(providerHeaders, modelDef.headers, authHeader, providerApiKey),
 		compat: mergeCompat(providerCompat, modelDef.compat),
 		requestTransform: mergeRequestTransform(providerRequestTransform, modelDef.requestTransform),
@@ -1284,6 +1298,8 @@ function finalizeCustomModel(model: CustomModelOverlay, options: CustomModelBuil
 		contextWindow:
 			resolvedModel.contextWindow ?? reference?.contextWindow ?? (options.useDefaults ? 128000 : undefined),
 		maxTokens: resolvedModel.maxTokens ?? reference?.maxTokens ?? (options.useDefaults ? 16384 : undefined),
+		maxTokensSource:
+			resolvedModel.maxTokensSource ?? (reference?.maxTokensSource === "configured" ? "configured" : undefined),
 		headers: resolvedModel.headers,
 		compat: mergeCompat(reference?.compat, resolvedModel.compat),
 		contextPromotionTarget: resolvedModel.contextPromotionTarget,
@@ -1507,6 +1523,68 @@ export class ModelRegistry {
 		}
 	}
 
+	admitCachedProviderForStoredLiteralCredential(providerId: string, selector: AuthCredentialSelector): boolean {
+		const cachedModels = this.#loadCachedProviderModelsForStoredLiteralCredential(providerId, selector);
+		if (!cachedModels || cachedModels.length === 0) return false;
+
+		this.#suspendRebuild();
+		try {
+			this.#mergeDiscoveredModels(cachedModels);
+			this.#rebuildProviderActivity();
+			this.#modelBindingsApplier.apply();
+			return true;
+		} finally {
+			this.#resumeRebuild();
+		}
+	}
+
+	/** @internal Validate an existing startup model without mutating a caller-supplied registry. */
+	validateModelForStoredLiteralCredential(
+		providerId: string,
+		modelId: string,
+		selector: AuthCredentialSelector,
+	): boolean {
+		if (!this.find(providerId, modelId)) return false;
+		if (this.#resolveStaticModelReference(providerId, modelId)) return true;
+		const cachedModels = this.#loadCachedProviderModelsForStoredLiteralCredential(providerId, selector, false);
+		return cachedModels ? resolveProviderModelReference(providerId, modelId, cachedModels) !== undefined : false;
+	}
+
+	/** @internal Whether startup must establish credential-scoped cache provenance for this exact target. */
+	requiresStoredLiteralCredentialCacheAdmission(providerId: string, modelId: string): boolean {
+		return !this.find(providerId, modelId) || !this.#resolveStaticModelReference(providerId, modelId);
+	}
+
+	#loadCachedProviderModelsForStoredLiteralCredential(
+		providerId: string,
+		selector: AuthCredentialSelector,
+		publishDiscoveryState = true,
+	): Model<Api>[] | undefined {
+		const supportsDiscovery =
+			this.#discoveryManager.providerIds().has(providerId) ||
+			PROVIDER_DESCRIPTORS.some(descriptor => descriptor.providerId === providerId);
+		if (!supportsDiscovery) return undefined;
+		const authEvidence = this.authStorage.getStoredLiteralApiKeyEvidenceGeneration(providerId, selector);
+		if (!authEvidence) return undefined;
+		return [
+			...this.#loadCachedStandardProviderModels(providerId, authEvidence),
+			...this.#loadCachedDiscoverableModels(providerId, authEvidence, publishDiscoveryState),
+		];
+	}
+
+	#resolveStaticModelReference(providerId: string, modelId: string): Model<Api> | undefined {
+		const normalizedProvider = providerId.toLowerCase();
+		const matchingActivity = [...this.#providerActivity.entries()].filter(
+			([candidateProvider]) => candidateProvider.toLowerCase() === normalizedProvider,
+		);
+		if (matchingActivity.length !== 1) return undefined;
+		const [canonicalProvider, activity] = matchingActivity[0];
+		const staticModels = this.#models.filter(
+			model => model.provider === canonicalProvider && activity.staticModelIds.has(model.id),
+		);
+		return resolveProviderModelReference(providerId, modelId, staticModels);
+	}
+
 	#getStaticLoadEnvironmentFingerprint(): string {
 		const providerBaseUrlEnvKeys = new Set(
 			[
@@ -1744,6 +1822,7 @@ export class ModelRegistry {
 					cost: customModel.cost ?? existingModel.cost,
 					contextWindow: customModel.contextWindow ?? existingModel.contextWindow,
 					maxTokens: customModel.maxTokens ?? existingModel.maxTokens,
+					maxTokensSource: customModel.maxTokensSource ?? existingModel.maxTokensSource,
 					// Same-id custom definitions replace bundled transport behavior. Provider-level
 					// headers/compat were already folded into customModel during parsing; do not
 					// re-merge bundled transport metadata here.
@@ -1762,16 +1841,17 @@ export class ModelRegistry {
 		return merged;
 	}
 
-	#loadCachedStandardProviderModels(): Model<Api>[] {
+	#loadCachedStandardProviderModels(providerId?: string, authEvidence?: string): Model<Api>[] {
 		const configuredDiscoveryProviders = new Set(this.#discoveryManager.providers.map(provider => provider.provider));
 		const cachedModels: Model<Api>[] = [];
 		for (const descriptor of PROVIDER_DESCRIPTORS) {
+			if (providerId && descriptor.providerId !== providerId) continue;
 			if (configuredDiscoveryProviders.has(descriptor.providerId)) {
 				continue;
 			}
 			const cache = readModelCache<Api>(descriptor.providerId, 24 * 60 * 60 * 1000, Date.now, this.#cacheDbPath);
 			const expectedProvenance = fingerprintDescriptorDiscoveryProvenance(
-				this.#getProviderEvidenceGeneration(descriptor.providerId),
+				authEvidence ?? this.#getProviderEvidenceGeneration(descriptor.providerId),
 				this.#normalizeDiscoveryEvidenceEndpoint(this.#getProviderBaseUrlForDiscovery(descriptor.providerId) ?? ""),
 			);
 			if (
@@ -1796,22 +1876,29 @@ export class ModelRegistry {
 		return cachedModels;
 	}
 
-	#loadCachedDiscoverableModels(): Model<Api>[] {
+	#loadCachedDiscoverableModels(
+		providerId?: string,
+		authEvidence?: string,
+		publishDiscoveryState = true,
+	): Model<Api>[] {
 		const cachedModels: Model<Api>[] = [];
 		for (const providerConfig of this.#discoveryManager.providers) {
+			if (providerId && providerConfig.provider !== providerId) continue;
 			let expectedProvenance: string | undefined;
 			try {
 				const effectiveConfig = this.#effectiveDiscoveryProviderConfig(providerConfig);
 				expectedProvenance = fingerprintConfiguredDiscoveryRequestShape(
 					effectiveConfig,
-					this.#getProviderEvidenceGeneration(effectiveConfig.provider),
+					authEvidence ?? this.#getProviderEvidenceGeneration(effectiveConfig.provider),
 					this.#normalizeDiscoveryEvidenceEndpoint(effectiveConfig.baseUrl ?? ""),
 				);
 			} catch {
 				// A context that cannot be fully derived cannot vouch for a cache row.
 				expectedProvenance = undefined;
 			}
-			const models = this.#discoveryManager.loadCached(providerConfig, this.#cacheDbPath, expectedProvenance);
+			const models = publishDiscoveryState
+				? this.#discoveryManager.loadCached(providerConfig, this.#cacheDbPath, expectedProvenance)
+				: this.#readCachedDiscoverableModels(providerConfig, expectedProvenance);
 			// Cache rows persist sanitized transport metadata (no headers), so a
 			// rebooted registry re-derives the provider transport override from the
 			// same source the live publish path uses — mirroring the cached
@@ -1834,6 +1921,22 @@ export class ModelRegistry {
 		return cachedModels;
 	}
 
+	#readCachedDiscoverableModels(
+		providerConfig: DiscoveryProviderConfig,
+		expectedProvenance: string | undefined,
+	): Model<Api>[] {
+		const cache = readModelCache<Api>(providerConfig.provider, 24 * 60 * 60 * 1000, Date.now, this.#cacheDbPath);
+		if (
+			cache === null ||
+			cache.dynamicModelIds === undefined ||
+			expectedProvenance === undefined ||
+			cache.dynamicModelProvenance !== expectedProvenance
+		) {
+			return [];
+		}
+		return applyFinalCodexGpt56ContextCap(cache.models);
+	}
+
 	#applyProviderCompat(compat: Model<Api>["compat"] | undefined, models: Model<Api>[]): Model<Api>[] {
 		if (!compat) return models;
 		return models.map(model => ({ ...model, compat: mergeCompat(model.compat, compat) }));
@@ -2452,6 +2555,10 @@ export class ModelRegistry {
 			}
 			return;
 		}
+		this.#mergeDiscoveredModels(discovered);
+	}
+
+	#mergeDiscoveredModels(discovered: readonly Model<Api>[]): void {
 		const discoveredModels = this.#applyHardcodedModelPolicies(
 			discovered.map(model =>
 				mergeDiscoveredModel(
@@ -2495,11 +2602,14 @@ export class ModelRegistry {
 			if (optionalAuth && isCurrentPreflight()) this.#credentiallessAuthFallbackProviders.delete(provider);
 			let apiKey: string | undefined;
 			try {
-				apiKey = await this.#peekApiKeyForProvider(provider, {
-					ignoreCredentiallessFallback: optionalAuth,
-					refreshOAuth: true,
-					baseUrl: providerConfig.baseUrl,
-				});
+				apiKey = normalizeVllmApiKey(
+					provider,
+					await this.#peekApiKeyForProvider(provider, {
+						ignoreCredentiallessFallback: optionalAuth,
+						refreshOAuth: true,
+						baseUrl: providerConfig.baseUrl,
+					}),
+				);
 				const currentAuthConfigurationGeneration = this.authStorage.getProviderConfigurationGeneration(provider);
 				if (preflightAuthConfigurationGeneration !== currentAuthConfigurationGeneration) {
 					const currentOAuthRefreshGeneration = this.authStorage.getProviderOAuthRefreshGeneration(provider);
@@ -3287,6 +3397,11 @@ export class ModelRegistry {
 			if (!isRecord(item) || typeof item.id !== "string" || !item.id.trim()) continue;
 			const id = item.id;
 			const referenceModel = resolveCustomModelReference(id);
+			const discoveredMaxTokens = firstPositiveDiscoveryNumber(
+				item.max_completion_tokens,
+				item.max_tokens,
+				item.max_output_tokens,
+			);
 			const api = this.#resolveDiscoveredModelApi(providerConfig, id);
 			discovered.push(
 				enrichModelThinking({
@@ -3309,14 +3424,8 @@ export class ModelRegistry {
 							referenceModel?.contextWindow,
 							UNK_CONTEXT_WINDOW,
 						) ?? UNK_CONTEXT_WINDOW,
-					maxTokens:
-						firstPositiveDiscoveryNumber(
-							item.max_completion_tokens,
-							item.max_tokens,
-							item.max_output_tokens,
-							referenceModel?.maxTokens,
-							UNK_MAX_TOKENS,
-						) ?? UNK_MAX_TOKENS,
+					maxTokens: discoveredMaxTokens ?? referenceModel?.maxTokens ?? UNK_MAX_TOKENS,
+					maxTokensSource: discoveredMaxTokens === undefined ? referenceModel?.maxTokensSource : "discovered",
 					headers: providerConfig.headers,
 					compat: mergeCompat(
 						{
@@ -4367,9 +4476,11 @@ export class ModelRegistry {
 	}
 
 	async #getApiKeyOrNoAuth(provider: string, lookup: () => Promise<string | undefined>): Promise<string | undefined> {
-		if (!this.#isCredentiallessProvider(provider)) return lookup();
-		if (!this.#optionalAuthProviders.has(provider)) return kNoAuth;
+		const credentialless = this.#isCredentiallessProvider(provider);
+		if (credentialless && !this.#optionalAuthProviders.has(provider)) return kNoAuth;
 		const apiKey = await lookup();
+		if (isVllmNoAuthToken(provider, apiKey)) return normalizeVllmApiKey(provider, apiKey) ?? kNoAuth;
+		if (!credentialless) return apiKey;
 		if (apiKey !== undefined) {
 			this.#credentiallessAuthFallbackProviders.delete(provider);
 			return apiKey;

package/src/config/model-resolver.ts

@@ -1025,6 +1025,7 @@ export interface ModelChainResolutionOptions {
 	aliasIntent?: "preset-equivalent" | "reject";
 	canonicalSessionId?: string | null;
 	credentialSessionId?: string;
+	signal?: AbortSignal;
 }
 
 export async function resolveModelChainWithAuth(
@@ -1080,7 +1081,7 @@ export async function resolveModelChainWithAuth(
 					break;
 				}
 			}
-			const key = await modelRegistry.getApiKey(candidate.model, credentialSessionId);
+			const key = await modelRegistry.getApiKey(candidate.model, credentialSessionId, { signal: options?.signal });
 			if (isAuthenticatedOrKeyless(key)) {
 				return { ...candidate, activeIndex, skips };
 			}

package/src/config/models-config-schema.ts

@@ -158,7 +158,7 @@ const ModelDefinitionSchema = z
 			.optional(),
 		premiumMultiplier: z.number().optional(),
 		contextWindow: z.number().optional(),
-		maxTokens: z.number().optional(),
+		maxTokens: z.number().int().finite().positive().max(Number.MAX_SAFE_INTEGER).optional(),
 		headers: z.record(z.string(), z.string()).optional(),
 		compat: ModelCompatSchema.optional(),
 		contextPromotionTarget: z.string().min(1).optional(),
@@ -185,7 +185,7 @@ export const ModelOverrideSchema = z
 			.optional(),
 		premiumMultiplier: z.number().optional(),
 		contextWindow: z.number().optional(),
-		maxTokens: z.number().optional(),
+		maxTokens: z.number().int().finite().positive().max(Number.MAX_SAFE_INTEGER).optional(),
 		headers: z.record(z.string(), z.string()).optional(),
 		compat: ModelCompatSchema.optional(),
 		contextPromotionTarget: z.string().min(1).optional(),

package/src/config/settings-schema.ts

@@ -745,7 +745,7 @@ export const SETTINGS_SCHEMA = {
 	// ────────────────────────────────────────────────────────────────────────
 	"ui.language": {
 		type: "enum",
-		values: ["en", "ko"] as const,
+		values: ["en", "ko", "ja"] as const,
 		default: "en",
 		ui: {
 			tab: "appearance",
@@ -754,6 +754,7 @@ export const SETTINGS_SCHEMA = {
 			options: [
 				{ value: "en", label: "English" },
 				{ value: "ko", label: "Korean (한국어)" },
+				{ value: "ja", label: "Japanese (日本語)" },
 			],
 		},
 	},
@@ -1682,6 +1683,17 @@ export const SETTINGS_SCHEMA = {
 		},
 	},
 
+	"startup.skipLogoAnimation": {
+		type: "boolean",
+		default: false,
+		ui: {
+			tab: "interaction",
+			label: "Skip Startup Logo Animation",
+			description:
+				"Skip the animated startup logo sweep; the welcome surface, its resting logo, and all information rows still render. Applies at the next interactive start.",
+		},
+	},
+
 	"startup.checkUpdate": {
 		type: "boolean",
 		default: true,

package/src/coordinator/contract.ts

@@ -12,6 +12,7 @@ export const COORDINATOR_MCP_TOOL_NAMES = [
 	"gjc_coordinator_watch_events",
 	"gjc_coordinator_register_session",
 	"gjc_coordinator_start_session",
+	"gjc_coordinator_retire_start_session",
 	"gjc_coordinator_activate_session",
 	"gjc_coordinator_stop_session",
 	"gjc_coordinator_send_prompt",

package/src/coordinator-mcp/question-state.ts

@@ -287,18 +287,51 @@ export interface CreationRequestV1 {
 	key_digest: string;
 	request_digest: string;
 	tool: string;
-	phase: "claimed" | "remote_started" | "wal_committed" | "projected" | "completed" | "uncertain";
+	phase: "claimed" | "remote_started" | "wal_committed" | "projected" | "completed" | "uncertain" | "retired";
 	canonical_create_intent: CanonicalCreateIntentV1 | null;
 	remote_create_key: string;
 	session_id: string | null;
 	endpoint_incarnation: string | null;
 	sidecar_verifier: { key_id: string; public_key: string } | null;
+	/** Retirement is staged before the broker effect so a post-effect crash can replay safely. */
+	retirement_intent?: CreationRetirementIntentV1;
 	wal_revision?: number;
 	wal_digest?: string;
 	safe_response?: Record<string, unknown>;
 	created_at: string;
 	updated_at: string;
 }
+export interface CreationRetirementProofV1 {
+	session_id: string;
+	cwd: string;
+	state_root: string;
+	endpoint_generation: number;
+	endpoint_mtime_ms: number;
+	process_incarnation: string;
+	host_incarnation: string;
+	lifecycle_request_id: string;
+	remote_create_key: string;
+}
+export interface CreationRetirementBrokerProofV1 {
+	session_id: string;
+	retired: true;
+	ledger_state: "terminal_error";
+	index_type: "session_closed";
+	state_root: string;
+	endpoint_generation: number;
+	endpoint_mtime_ms: number;
+	process_incarnation: string;
+	host_incarnation: string;
+	lifecycle_request_id: string;
+	remote_create_key: string;
+}
+export interface CreationRetirementIntentV1 {
+	phase: "intent" | "pre_effect_rejected" | "broker_retired";
+	proof: CreationRetirementProofV1;
+	retirement_key_digest?: string;
+	broker_proof?: CreationRetirementBrokerProofV1;
+	updated_at: string;
+}
 export interface NamespaceDeletionEntryV1 {
 	deletion_id: string;
 	session_id: string;
@@ -2395,21 +2428,219 @@ export async function repairProjections(
 	});
 }
 
+function sameCreationRetirementProof(left: CreationRetirementProofV1, right: CreationRetirementProofV1): boolean {
+	return canonicalJson(left) === canonicalJson(right);
+}
+
+function assertCreationRetirementProofMatches(
+	request: CreationRequestV1,
+	proof: CreationRetirementProofV1,
+	includeStaged = true,
+): void {
+	if (
+		!proof.session_id ||
+		!proof.cwd ||
+		!proof.state_root ||
+		!Number.isSafeInteger(proof.endpoint_generation) ||
+		proof.endpoint_generation <= 0 ||
+		!Number.isFinite(proof.endpoint_mtime_ms) ||
+		proof.endpoint_mtime_ms <= 0 ||
+		!proof.process_incarnation ||
+		!proof.host_incarnation ||
+		!proof.lifecycle_request_id ||
+		!proof.remote_create_key
+	)
+		throw new Error("invalid_input");
+	if (request.remote_create_key !== proof.remote_create_key) throw new Error("idempotency_conflict");
+	if (request.session_id !== null && request.session_id !== proof.session_id) throw new Error("idempotency_conflict");
+	const intent = request.canonical_create_intent;
+	if (intent) {
+		const session = intent.session;
+		if (
+			session.session_id !== proof.session_id ||
+			path.resolve(session.cwd) !== path.resolve(proof.cwd) ||
+			path.resolve(session.cwd, ".gjc", "state") !== path.resolve(proof.state_root) ||
+			session.broker.endpoint_generation !== proof.endpoint_generation ||
+			intent.kind === "register" ||
+			intent.remote_create_key !== proof.remote_create_key
+		)
+			throw new Error("idempotency_conflict");
+	}
+	const staged = includeStaged ? request.retirement_intent : undefined;
+	if (staged && !sameCreationRetirementProof(staged.proof, proof)) throw new Error("idempotency_conflict");
+}
+
+/** Claims retirement under the creation receipt before any broker effect. */
+export async function recordCreationRetirementIntent(
+	paths: CoordinatorStatePaths,
+	keyDigest: string,
+	proof: CreationRetirementProofV1,
+	retirementKeyDigest?: string,
+): Promise<CreationRequestV1> {
+	return await withNamespaceRegistry(paths, async registry => {
+		const request = registry.creations[keyDigest];
+		if (!request) throw new Error("state_corrupt");
+		if (request.phase !== "remote_started" && request.phase !== "uncertain" && request.phase !== "retired")
+			throw new Error("retire_not_allowed");
+		assertCreationRetirementProofMatches(request, proof, request.retirement_intent?.phase !== "pre_effect_rejected");
+		if (
+			request.retirement_intent?.phase !== "pre_effect_rejected" &&
+			retirementKeyDigest &&
+			request.retirement_intent?.retirement_key_digest &&
+			request.retirement_intent.retirement_key_digest !== retirementKeyDigest
+		)
+			throw new Error("idempotency_conflict");
+		if (!request.retirement_intent) {
+			request.retirement_intent = {
+				phase: "intent",
+				proof,
+				...(retirementKeyDigest ? { retirement_key_digest: retirementKeyDigest } : {}),
+				updated_at: new Date().toISOString(),
+			};
+			request.updated_at = new Date().toISOString();
+		} else if (request.retirement_intent.phase === "pre_effect_rejected") {
+			request.retirement_intent.phase = "intent";
+			request.retirement_intent.proof = proof;
+			if (retirementKeyDigest) request.retirement_intent.retirement_key_digest = retirementKeyDigest;
+			request.retirement_intent.updated_at = new Date().toISOString();
+			request.updated_at = request.retirement_intent.updated_at;
+		} else if (retirementKeyDigest && !request.retirement_intent.retirement_key_digest) {
+			request.retirement_intent.retirement_key_digest = retirementKeyDigest;
+			request.retirement_intent.updated_at = new Date().toISOString();
+			request.updated_at = new Date().toISOString();
+		}
+		return request;
+	});
+}
+
+/** Replaces only a pre-effect retirement proof after an explicit broker rejection. */
+export async function replaceCreationRetirementIntent(
+	paths: CoordinatorStatePaths,
+	keyDigest: string,
+	proof: CreationRetirementProofV1,
+	retirementKeyDigest: string,
+): Promise<CreationRequestV1> {
+	return await withNamespaceRegistry(paths, async registry => {
+		const request = registry.creations[keyDigest];
+		if (!request) throw new Error("state_corrupt");
+		if (request.phase !== "remote_started" && request.phase !== "uncertain" && request.phase !== "retired")
+			throw new Error("retire_not_allowed");
+		const staged = request.retirement_intent;
+		if (!staged || staged.phase !== "intent" || staged.broker_proof) throw new Error("state_corrupt");
+		if (staged.retirement_key_digest !== retirementKeyDigest) throw new Error("idempotency_conflict");
+		assertCreationRetirementProofMatches(request, proof, false);
+		staged.phase = "pre_effect_rejected";
+		staged.updated_at = new Date().toISOString();
+		request.updated_at = staged.updated_at;
+		return request;
+	});
+}
+
+/** Records the bounded broker proof before receipt advancement or idempotency sealing. */
+export async function recordCreationRetirementBrokerProof(
+	paths: CoordinatorStatePaths,
+	keyDigest: string,
+	proof: CreationRetirementProofV1,
+	brokerProof: CreationRetirementBrokerProofV1,
+): Promise<CreationRequestV1> {
+	return await withNamespaceRegistry(paths, async registry => {
+		const request = registry.creations[keyDigest];
+		if (!request) throw new Error("state_corrupt");
+		if (request.phase !== "remote_started" && request.phase !== "uncertain" && request.phase !== "retired")
+			throw new Error("retire_not_allowed");
+		assertCreationRetirementProofMatches(request, proof);
+		if (
+			brokerProof.session_id !== proof.session_id ||
+			brokerProof.state_root !== proof.state_root ||
+			brokerProof.endpoint_generation !== proof.endpoint_generation ||
+			brokerProof.endpoint_mtime_ms !== proof.endpoint_mtime_ms ||
+			brokerProof.process_incarnation !== proof.process_incarnation ||
+			brokerProof.host_incarnation !== proof.host_incarnation ||
+			brokerProof.lifecycle_request_id !== proof.lifecycle_request_id ||
+			brokerProof.remote_create_key !== proof.remote_create_key ||
+			brokerProof.retired !== true ||
+			brokerProof.ledger_state !== "terminal_error" ||
+			brokerProof.index_type !== "session_closed"
+		)
+			throw new Error("protocol_error");
+		const staged = request.retirement_intent;
+		if (staged?.broker_proof) {
+			if (canonicalJson(staged.broker_proof) !== canonicalJson(brokerProof)) throw new Error("state_corrupt");
+			return request;
+		}
+		if (!staged) {
+			request.retirement_intent = {
+				phase: "broker_retired",
+				proof,
+				broker_proof: brokerProof,
+				updated_at: new Date().toISOString(),
+			};
+		} else {
+			staged.phase = "broker_retired";
+			staged.broker_proof = brokerProof;
+			staged.updated_at = new Date().toISOString();
+		}
+		request.updated_at = new Date().toISOString();
+		return request;
+	});
+}
+
 /** Advances a creation receipt only after its WAL or projection authority exists. */
+export async function assertCreationRetirementIdentity(
+	paths: CoordinatorStatePaths,
+	keyDigest: string,
+	proof: CreationRetirementProofV1,
+): Promise<CreationRequestV1> {
+	return await withNamespaceRegistry(paths, async registry => {
+		const request = registry.creations[keyDigest];
+		if (!request) throw new Error("state_corrupt");
+		if (request.phase !== "remote_started" && request.phase !== "uncertain" && request.phase !== "retired")
+			throw new Error("retire_not_allowed");
+		assertCreationRetirementProofMatches(request, proof, request.retirement_intent?.phase !== "pre_effect_rejected");
+		return request;
+	});
+}
+
 export async function advanceCreationReceipt(
 	paths: CoordinatorStatePaths,
 	keyDigest: string,
-	phase: "projected" | "completed" | "uncertain",
+	phase: "projected" | "completed" | "uncertain" | "retired",
 	safeResponse?: Record<string, unknown>,
+	proof?: CreationRetirementProofV1,
 ): Promise<void> {
 	await withNamespaceRegistry(paths, async registry => {
 		const request = registry.creations[keyDigest];
 		if (!request) throw new Error("state_corrupt");
-		if (request.phase === phase) return;
-		if (phase !== "uncertain" && request.phase !== "wal_committed" && request.phase !== "projected")
+		if (proof) assertCreationRetirementProofMatches(request, proof);
+		if (request.phase === phase) {
+			if (phase === "retired" && safeResponse) {
+				request.safe_response = safeResponse;
+				if (request.retirement_intent) request.retirement_intent.updated_at = new Date().toISOString();
+				request.updated_at = new Date().toISOString();
+			}
+			return;
+		}
+		if (
+			phase === "retired" &&
+			(request.phase === "completed" || request.phase === "retired" || request.phase === "claimed")
+		)
+			throw new Error("state_corrupt");
+		if (
+			phase !== "uncertain" &&
+			phase !== "retired" &&
+			request.phase !== "wal_committed" &&
+			request.phase !== "projected"
+		)
 			throw new Error("state_corrupt");
 		request.phase = phase;
 		request.safe_response = safeResponse;
+		if (phase === "retired" && proof && !request.retirement_intent) {
+			request.retirement_intent = {
+				phase: "intent",
+				proof,
+				updated_at: new Date().toISOString(),
+			};
+		}
 		request.updated_at = new Date().toISOString();
 	});
 }