@gajae-code/coding-agent 0.14.2 → 0.15.0

package/src/prompts/tools/task-summary.md

@@ -5,6 +5,7 @@
 <agent id="{{id}}" agent="{{agent}}">
 <status>{{status}}</status>
 {{#if meta}}<meta lines="{{meta.lineCount}}" size="{{meta.charSize}}" />{{/if}}
+{{#if routing}}<routing tier="{{routing.tier}}" model="{{routing.effectiveModel}}" note="{{routing.note}}" />{{/if}}
 <synopsis{{#if outputUri}} ref="{{outputUri}}"{{/if}}>
 {{synopsis}}
 </synopsis>

package/src/prompts/tools/task.md

@@ -82,3 +82,9 @@ Agent spawning is disabled for this context.
 {{/list}}
 {{/if}}
 </agents>
+
+{{#if autoroutingActive}}
+<autorouting-guidance>
+Choose a tier by agent role/type, per-call complexity, and cost intent: fast for mechanical/lookup/high-volume work where cheap tokens are the point; balanced (default) for ordinary implementation/review lanes; strong for deep design, hard debugging, or high-stakes review where the cost is justified. Provider availability/auth is enforced by deterministic code and is never an input to tier choice. Omitting tier is fine and routes as balanced.
+</autorouting-guidance>
+{{/if}}

package/src/rlm/artifacts.ts

@@ -1,17 +1,19 @@
 /**
- * RLM session artifact layout under <cwd>/.gjc/_session-{gjcSessionId}/rlm/<rlmSessionId>/.
+ * RLM session artifact layout under
+ * <cwd>/.gjc/_session-{gjcSessionId}/autoresearch/runs/<rlmSessionId>/.
  *
  * The GJC session id (process boundary) scopes the directory; the RLM session id
  * names the individual research run within it. The two ids are kept distinct.
+ * The whole subtree lives under the session autoresearch root.
  */
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
 import { readNotebookDocument } from "../edit/notebook";
-import { rlmArtifactRoot } from "../gjc-runtime/session-layout";
+import { autoresearchRlmArtifactRoot } from "../gjc-runtime/session-layout";
 import { resolveGjcSessionForWrite } from "../gjc-runtime/session-resolution";
 import type { RlmArtifactPaths } from "./types";
 
-export const RLM_DIR_SEGMENT = "rlm";
+export const RLM_DIR_SEGMENT = "runs";
 
 const SESSION_ID_RE = /^[A-Za-z0-9_-]+$/;
 
@@ -26,13 +28,13 @@ export function generateRlmSessionId(now: Date = new Date()): string {
 	return `${stamp}-${suffix}`;
 }
 
-export function resolveRlmArtifactPaths(cwd: string, sessionId: string): RlmArtifactPaths {
+export function resolveRlmArtifactPaths(cwd: string, sessionId: string, gjcSessionId?: string): RlmArtifactPaths {
 	if (!isValidRlmSessionId(sessionId)) {
 		throw new Error(`Invalid RLM session id: ${JSON.stringify(sessionId)}`);
 	}
-	const dir = rlmArtifactRoot(
+	const dir = autoresearchRlmArtifactRoot(
 		cwd,
-		resolveGjcSessionForWrite(cwd, { envSessionId: process.env.GJC_SESSION_ID }).gjcSessionId,
+		gjcSessionId ?? resolveGjcSessionForWrite(cwd, { envSessionId: process.env.GJC_SESSION_ID }).gjcSessionId,
 		sessionId,
 	);
 	return {
@@ -48,8 +50,8 @@ export async function ensureRlmSessionDir(paths: RlmArtifactPaths): Promise<void
 	await fs.mkdir(paths.dir, { recursive: true });
 }
 
-export async function rlmSessionExists(cwd: string, sessionId: string): Promise<boolean> {
-	const paths = resolveRlmArtifactPaths(cwd, sessionId);
+export async function rlmSessionExists(cwd: string, sessionId: string, gjcSessionId?: string): Promise<boolean> {
+	const paths = resolveRlmArtifactPaths(cwd, sessionId, gjcSessionId);
 	try {
 		const stat = await fs.stat(paths.dir);
 		return stat.isDirectory();
@@ -58,8 +60,8 @@ export async function rlmSessionExists(cwd: string, sessionId: string): Promise<
 	}
 }
 
-export async function readRlmNotebookIfPresent(cwd: string, sessionId: string) {
-	const paths = resolveRlmArtifactPaths(cwd, sessionId);
+export async function readRlmNotebookIfPresent(cwd: string, sessionId: string, gjcSessionId?: string) {
+	const paths = resolveRlmArtifactPaths(cwd, sessionId, gjcSessionId);
 	try {
 		return await readNotebookDocument(paths.notebookPath, paths.notebookPath);
 	} catch (error) {

package/src/runtime/optional-runtime-services.ts

@@ -20,7 +20,8 @@ export type OptionalRuntimeServicesOverrides = Partial<OptionalRuntimeServices>;
 
 /** Context needed by services whose identity is scoped to the session cwd. */
 export interface OptionalRuntimeServicesContext {
-	cwd?: string;
+	/** Session cwd. Pass a getter when the session can rescope (`move_session`). */
+	cwd?: string | (() => string);
 }
 
 /**
@@ -32,7 +33,7 @@ export function createOptionalRuntimeServices(
 	overrides: OptionalRuntimeServicesOverrides = {},
 	context: OptionalRuntimeServicesContext = {},
 ): OptionalRuntimeServices {
-	const cwd = context.cwd ?? process.cwd();
+	const cwd = context.cwd ?? (() => process.cwd());
 	return {
 		memoryBackend: overrides.memoryBackend ?? createMemoryBackendService(settings),
 		workspaceTree: overrides.workspaceTree ?? createWorkspaceTreeService(settings, cwd),

package/src/runtime/workspace-tree-service.ts

@@ -15,8 +15,16 @@ export interface WorkspaceTreeRuntime {
  * Build the workspace-tree service without importing the native scanner until
  * the service is activated. The scan itself remains the single authority for
  * both eager startup and the lazy first-turn barrier.
+ *
+ * `cwd` is resolved per scan rather than captured once: a session that rescopes
+ * (`move_session`, `/move`) must have its refreshes re-root at the new cwd,
+ * otherwise every later tree describes the abandoned launcher root.
  */
-export function createWorkspaceTreeService(settings: Settings, cwd: string): LazyService<WorkspaceTreeRuntime> {
+export function createWorkspaceTreeService(
+	settings: Settings,
+	cwd: string | (() => string),
+): LazyService<WorkspaceTreeRuntime> {
+	const resolveCwd = typeof cwd === "function" ? cwd : () => cwd;
 	return createLazyService({
 		id: "workspaceTree",
 		enabled: () => settings.get("workspaceTree.mode") === "eager" || settings.get("workspaceTree.mode") === "lazy",
@@ -24,7 +32,7 @@ export function createWorkspaceTreeService(settings: Settings, cwd: string): Laz
 			const scan = async (): Promise<WorkspaceTree> => {
 				if (signal.aborted) throw new Error("Workspace-tree scan was aborted before it started.");
 				const { buildWorkspaceTree } = await import("../workspace-tree");
-				const tree = await buildWorkspaceTree(cwd, { timeoutMs: WORKSPACE_TREE_SCAN_TIMEOUT_MS });
+				const tree = await buildWorkspaceTree(resolveCwd(), { timeoutMs: WORKSPACE_TREE_SCAN_TIMEOUT_MS });
 				if (signal.aborted) throw new Error("Workspace-tree scan was aborted before it completed.");
 				return tree;
 			};
@@ -34,7 +42,7 @@ export function createWorkspaceTreeService(settings: Settings, cwd: string): Laz
 					snapshot,
 					refresh: async () => {
 						const { buildWorkspaceTree } = await import("../workspace-tree");
-						return buildWorkspaceTree(cwd, { timeoutMs: WORKSPACE_TREE_SCAN_TIMEOUT_MS });
+						return buildWorkspaceTree(resolveCwd(), { timeoutMs: WORKSPACE_TREE_SCAN_TIMEOUT_MS });
 					},
 				},
 			};

package/src/runtime-mcp/config.ts

@@ -34,6 +34,12 @@ export interface LoadMCPConfigsOptions {
 	nativeOnly?: boolean;
 	/** Load only this explicit MCP config file. */
 	configPath?: string;
+	/**
+	 * Agent directory that holds the user scope (`<agentDir>/mcp.json`).
+	 * Default: `getAgentDir()`. Sessions created with their own `agentDir` pass it
+	 * so discovery and `gjc mcp add --scope user` read and write the same file.
+	 */
+	agentDir?: string;
 }
 
 /** Result of loading MCP configs */
@@ -140,6 +146,7 @@ export async function loadAllMCPConfigs(cwd: string, options?: LoadMCPConfigsOpt
 		// implicit runtime authorities.
 		const result = await loadCapability<MCPServer>(mcpCapability.id, {
 			cwd,
+			agentDir: options?.agentDir,
 			providers: options?.nativeOnly === true ? ["native"] : undefined,
 		});
 		// Filter out project-level configs if disabled
@@ -150,7 +157,7 @@ export async function loadAllMCPConfigs(cwd: string, options?: LoadMCPConfigsOpt
 		// must not abort discovery of valid servers in the other scope (the
 		// capability loader itself is already per-file tolerant).
 		const [userDisabled, projectDisabled] = await Promise.all([
-			readDisabledServers(getMCPConfigPath("user", cwd)).catch(() => []),
+			readDisabledServers(getMCPConfigPath("user", cwd, options?.agentDir)).catch(() => []),
 			readDisabledServers(getMCPConfigPath("project", cwd)).catch(() => []),
 		]);
 		disabledServers = new Set([...userDisabled, ...projectDisabled]);

package/src/runtime-mcp/manager.ts

@@ -134,6 +134,21 @@ export function resolveExactConfigStartupTimeoutMs(configs: MCPServerConfig[]):
 	return Math.max(...effectiveTimeouts) + STARTUP_TIMEOUT_GRACE_MS;
 }
 
+/**
+ * Whether `config` declared a connection window that is still open `elapsedMs`
+ * into startup.
+ *
+ * The startup wait bounds how long session start blocks; a declared `timeout`
+ * bounds how long the server itself may take to come up (`connectToServer`
+ * enforces it). Those are different budgets: the wait elapsing says nothing
+ * about whether the operator's declared window has been spent.
+ */
+export function withinDeclaredConnectionWindow(config: MCPServerConfig, elapsedMs: number): boolean {
+	const timeout = config.timeout;
+	if (typeof timeout !== "number" || !Number.isFinite(timeout) || timeout <= 0) return false;
+	return elapsedMs < timeout;
+}
+
 function trackPromise<T>(promise: Promise<T>): TrackedPromise<T> {
 	const tracked: TrackedPromise<T> = { promise, status: "pending" };
 	promise.then(
@@ -1155,6 +1170,7 @@ export class MCPManager {
 					});
 				}
 			}
+			const startupStartedAt = Date.now();
 			const startupOutcome = await Promise.race([
 				Promise.allSettled(connectionTasks.map(task => task.tracked.promise)).then(() => undefined),
 				delay(startupTimeoutMs).then(() => undefined),
@@ -1190,7 +1206,24 @@ export class MCPManager {
 
 				const pendingWithoutCache = pendingTasks.filter(task => !cachedTools.has(task.name));
 				if (pendingWithoutCache.length > 0) {
+					// The startup wait elapsing means "stop blocking session start", not
+					// "this server failed". A server whose operator declared a `timeout`
+					// (`gjc mcp add --timeout`) asked to wait that long for it, so while it
+					// is still inside that window it keeps connecting in the background
+					// under `connectToServer`'s own timeout, and the background tool load
+					// adopts it. Only a server that declared no window, or already spent it,
+					// is torn down and reported. Exact-config (`toolsOnly`) startup still
+					// fails fast: it builds a catalog once, so a missing server is an error.
+					const startupElapsedMs = Date.now() - startupStartedAt;
 					for (const task of pendingWithoutCache) {
+						if (!this.#toolsOnly && withinDeclaredConnectionWindow(task.config, startupElapsedMs)) {
+							logger.warn("MCP server still connecting after the startup wait", {
+								path: `mcp:${task.name}`,
+								startupWaitMs: startupTimeoutMs,
+								declaredTimeoutMs: task.config.timeout,
+							});
+							continue;
+						}
 						const message = `MCP server connection timed out during startup: ${task.name}`;
 						errors.set(task.name, this.#serverError(message));
 						reportedErrors.add(task.name);

package/src/sdk/acp/adapter.ts

@@ -73,6 +73,8 @@ const ACP_MCP_PRESERVED_LAUNCH_CODES = new Set([
 	"model_profile_registry_error",
 	"startup_admission_refused",
 	"startup_admission_timeout",
+	"ready_then_exited",
+	"endpoint_unreadable",
 ]);
 
 /**
@@ -127,6 +129,21 @@ function isLifecycleOperation(operation: string): boolean {
  * Pure ACP-to-SDK adapter. It deliberately owns neither an AgentSession nor an
  * ACP bridge: all session work is performed through authenticated v3 frames.
  */
+/**
+ * Provider leases are renewed only through the maintenance capability (#4689).
+ * An attachment without it must be rejected at the admission boundary with an
+ * explicit migration error: falling back to `send()` would restore the 5s
+ * heartbeat-forced locked index rescan, and accepting it silently would leave
+ * live leases quietly un-renewed until they expire.
+ */
+function assertMaintenanceCapability(attachment: SessionAttachment): void {
+	if (typeof attachment.sendMaintenance === "function") return;
+	throw new AcpSdkAdapterError(
+		"operation_prohibited",
+		"SDK session attachment does not implement sendMaintenance(leaseId); provider leases cannot be renewed. Update the attachment implementation to the current SessionAttachment capability.",
+	);
+}
+
 export class AcpSdkAdapter {
 	readonly #client?: SdkClient;
 	readonly #router?: SessionRouter;
@@ -184,6 +201,11 @@ export class AcpSdkAdapter {
 	acceptAttachment(attachment: SessionAttachment): void {
 		if (!this.#router || attachment.sessionId !== this.#sessionId)
 			throw new AcpSdkAdapterError("invalid_input", "ACP attachment does not match this session adapter.");
+		// Reject an attachment that cannot renew provider leases at the handoff
+		// boundary (#4730 review), not just at start(): acceptAttachment is the
+		// single admission point for the replacement/ready paths too, so a
+		// capability-less replacement can never silently take over live leases.
+		assertMaintenanceCapability(attachment);
 		this.#abortActiveReverseRequests();
 		this.#attachment = attachment;
 		this.#connectionId = undefined;
@@ -202,6 +224,11 @@ export class AcpSdkAdapter {
 	}
 
 	async attachmentReady(attachment: SessionAttachment): Promise<void> {
+		// Guard BEFORE the branch (#4730 review): the same-object path below never
+		// reaches acceptAttachment, so guarding only inside that one arm let a
+		// current attachment without the maintenance capability activate providers
+		// and acquire leases it can never renew.
+		assertMaintenanceCapability(attachment);
 		if (this.#attachment !== attachment) this.acceptAttachment(attachment);
 		else {
 			this.#abortActiveReverseRequests();
@@ -251,6 +278,7 @@ export class AcpSdkAdapter {
 		}
 		if (this.#router) {
 			if (!this.#attachment?.isCurrent()) return;
+			if (this.#attachment) assertMaintenanceCapability(this.#attachment);
 			await this.#activateProviders();
 		} else {
 			await this.#activateProviders();
@@ -576,13 +604,32 @@ export class AcpSdkAdapter {
 		if (!attachment?.isCurrent()) throw new SessionRouterError("pre_send", "SDK session attachment is stale.");
 		await Promise.resolve(attachment.send(frame));
 	}
+	/** Lease heartbeats are idempotent maintenance: they skip the authority reconcile (#4689). */
+	async #sendLeaseHeartbeat(leaseId: string): Promise<void> {
+		if (!this.#router)
+			throw new AcpSdkAdapterError(
+				"operation_prohibited",
+				"Live session sends require the current Router attachment.",
+			);
+		const attachment = this.#attachment;
+		if (!attachment?.isCurrent()) throw new SessionRouterError("pre_send", "SDK session attachment is stale.");
+		// Fail closed when the capability is absent (#4730 review). Falling back to
+		// send() would put the 5s heartbeat back on the locked authority reconcile,
+		// which is the exact idle cost this fix removes.
+		if (typeof attachment.sendMaintenance !== "function")
+			throw new SessionRouterError(
+				"pre_send",
+				"SDK session attachment does not support provider-lease maintenance heartbeats.",
+			);
+		await Promise.resolve(attachment.sendMaintenance(leaseId));
+	}
 
 	async #heartbeatLeases(): Promise<void> {
 		if (this.#closed) return;
 		try {
 			if (!this.#router) return;
 			if (!this.#attachment?.isCurrent()) return;
-			for (const leaseId of this.#leases.values()) await this.#sendSession({ type: "provider_heartbeat", leaseId });
+			for (const leaseId of this.#leases.values()) await this.#sendLeaseHeartbeat(leaseId);
 		} catch (error) {
 			if (error instanceof SessionRouterError && error.phase === "pre_send") return;
 			this.#reportReconnectFailure(error);

package/src/sdk/broker/broker.ts

@@ -6,6 +6,8 @@ import path from "node:path";
 import type { NativeDirectoryTreeSnapshot } from "@gajae-code/natives";
 import { logger } from "@gajae-code/utils";
 import type { ModelProfileErrorDetails } from "../../config/model-profile-contract";
+import { planLaunchWorktree } from "../../gjc-runtime/launch-worktree";
+import { createDefaultSdkHostModelResolver, type SdkHostModelResolver } from "../host/model-pin";
 import {
 	type DirectoryMigrationPolicy,
 	listManagedSessionCandidates,
@@ -27,9 +29,7 @@ import {
 	redactBrokerDiscovery,
 } from "./discovery";
 import { deriveIdempotencyIdentity } from "./identity";
-
 import { canonicalDeleteLocatorPath, executeLifecycle, isCanonicalSessionId } from "./lifecycle";
-
 import {
 	type LifecycleDurableEffectsReceipt,
 	LifecycleLedger,
@@ -56,6 +56,22 @@ type ResolvedBrokerSettings = {
 	resolveDirectoryMigration: (_cwd: string) => Promise<DirectoryMigrationPolicy>;
 };
 
+function modelResolutionCwd(input: Record<string, unknown>): string | undefined {
+	const cwd = typeof input.cwd === "string" ? input.cwd : undefined;
+	if (!cwd) return undefined;
+	const target = input.target;
+	if (!target || typeof target !== "object" || Array.isArray(target)) return cwd;
+	const worktree = (target as Record<string, unknown>).worktree;
+	if (!worktree || typeof worktree !== "object" || Array.isArray(worktree)) return cwd;
+	if ((worktree as Record<string, unknown>).enabled !== true) return cwd;
+	const name = (worktree as Record<string, unknown>).name;
+	const planned =
+		typeof name === "string" && name.length > 0
+			? planLaunchWorktree(cwd, { enabled: true, detached: false, name })
+			: planLaunchWorktree(cwd, { enabled: true, detached: true, name: null });
+	return planned.enabled ? path.resolve(planned.worktreePath) : cwd;
+}
+
 export type BrokerErrorCode =
 	| "idempotency_conflict"
 	| "terminal_uncertain"
@@ -65,6 +81,8 @@ export type BrokerErrorCode =
 	| "resource_gone"
 	| "invalid_input"
 	| "spawn_failed"
+	| "ready_then_exited"
+	| "endpoint_unreadable"
 	| "startup_admission_timeout"
 	| "startup_admission_refused"
 	| "readiness_timeout"
@@ -796,6 +814,7 @@ export class Broker {
 	#completion!: Promise<void>;
 	#resolveCompletion!: () => void;
 	#rejectCompletion!: (error: unknown) => void;
+	readonly #resolveModelPin: SdkHostModelResolver;
 	constructor(settings: BrokerSettings) {
 		this.settings = {
 			agentDir: settings.agentDir,
@@ -806,6 +825,7 @@ export class Broker {
 		};
 		this.index = new SessionIndex(settings.agentDir);
 		this.ledger = new LifecycleLedger(settings.agentDir);
+		this.#resolveModelPin = createDefaultSdkHostModelResolver(this.settings.agentDir);
 		this.#lock = path.join(settings.agentDir, "sdk", "broker.lock");
 		const completion = Promise.withResolvers<void>();
 		this.#completion = completion.promise;
@@ -1496,6 +1516,14 @@ export class Broker {
 			return page;
 		}
 		if (operation === "session.get_endpoint") return this.#endpoint(input);
+		if (operation === "model.resolve") {
+			try {
+				const cwd = modelResolutionCwd(input);
+				return { ok: true, result: await this.#resolveModelPin(input.model, { cwd }) };
+			} catch {
+				return error("unavailable", "SDK host model resolution is unavailable.");
+			}
+		}
 		if (operation === "broker.lookup_lifecycle") {
 			const requestedOperation = typeof input.operation === "string" ? input.operation : undefined;
 			const requestedFingerprint = typeof input.fingerprint === "string" ? input.fingerprint : undefined;

package/src/sdk/broker/discovery.ts

@@ -1,4 +1,5 @@
 import { randomBytes } from "node:crypto";
+import * as fsSync from "node:fs";
 import * as fs from "node:fs/promises";
 import path from "node:path";
 
@@ -24,12 +25,221 @@ export interface RetainedBrokerDiscovery {
 	close(): void;
 }
 
+/**
+ * Objects retained broker publication authority opens, in the order and with
+ * the access mode the native layer opens them. Every one is opened no-follow,
+ * so a symlink or a missing entry withholds authority; the lock record is
+ * opened read-only and only the published record read/write, so a
+ * readable-but-unwritable lock record is not an obstruction.
+ *
+ * A wrong file kind is only ever reported through the open the native itself
+ * would have failed: `O_DIRECTORY` refuses a non-directory, and the read/write
+ * open of the published record refuses a directory with `EISDIR`. The kind is
+ * never re-judged after a successful open, because the native layer does not --
+ * it accepts, for example, a directory or a character device as the lock
+ * record, and refuses a character-device published record only later, for its
+ * missing heartbeat. Judging kind here would blame an object the native never
+ * rejected and hide the real obstruction.
+ */
+const BROKER_PUBLICATION_OBJECTS = [
+	{ name: "sdk", segments: ["sdk"], directory: true, write: false },
+	{ name: "sdk/broker.lock", segments: ["sdk", "broker.lock"], directory: true, write: false },
+	{
+		name: "sdk/broker.lock/owner.json",
+		segments: ["sdk", "broker.lock", "owner.json"],
+		directory: false,
+		write: false,
+	},
+	{ name: "sdk/broker.json", segments: ["sdk", "broker.json"], directory: false, write: true },
+] as const;
+
+/** Width the native layer requires of the published `heartbeatAt` field. */
+const FIXED_WIDTH_HEARTBEAT_DIGITS = 13;
+
+/** Bound on the published record the diagnostic will read through its descriptor. */
+const MAX_DIAGNOSTIC_PUBLISHED_BYTES = 1 << 20;
+
+/**
+ * Bound on the agent directory in the failure message. Broker startup persists
+ * a 512-character reason, and an unbounded directory would truncate away the
+ * obstruction this diagnostic exists to report.
+ */
+const MAX_AGENT_DIR_IN_MESSAGE = 120;
+
+function boundedAgentDir(agentDir: string): string {
+	return agentDir.length <= MAX_AGENT_DIR_IN_MESSAGE
+		? agentDir
+		: `...${agentDir.slice(agentDir.length - (MAX_AGENT_DIR_IN_MESSAGE - 3))}`;
+}
+
+function sanitizedAgentDir(agentDir: string): string {
+	const sanitized = agentDir.replace(/[\p{Cc}\p{Cf}\u2028\u2029]/gu, character => {
+		const codePoint = character.codePointAt(0) ?? 0;
+		return `\\u${codePoint.toString(16).padStart(4, "0")}`;
+	});
+	return boundedAgentDir(sanitized);
+}
+
+const NATIVE_RETAINED_FAILURE = /\[retained-publication object=([^;\]]+); reason=([^\]]+)\]$/;
+
+function nativeRetainedObstruction(error: unknown): string | undefined {
+	if (!(error instanceof Error)) return undefined;
+	const match = NATIVE_RETAINED_FAILURE.exec(error.message);
+	if (!match) return undefined;
+	const [, object, reason] = match;
+	if (reason === "heartbeat-missing") return `${object} has no heartbeatAt field`;
+	if (reason === "heartbeat-width")
+		return `${object} heartbeatAt is not a fixed-width ${FIXED_WIDTH_HEARTBEAT_DIGITS}-digit timestamp`;
+	if (reason === "non-regular") return `${object} is not a regular file`;
+	if (reason === "errno-ENOENT") return `${object} is missing`;
+	if (reason === "errno-EISDIR") return `${object} is not a regular file`;
+	if (reason === "unsupported-platform") return "retained publication authority is not implemented on this platform";
+	// The native reason names the stage that refused, so the prose must not
+	// claim an open failed when the descriptor was already open: `errno-`/`io-`
+	// come from the open itself, `read-` from reading the published record, and
+	// `clone-`/`metadata` from inspecting an object already opened.
+	if (reason.startsWith("errno-")) return `${object} could not be opened (${reason.slice("errno-".length)})`;
+	if (reason.startsWith("io-")) return `${object} could not be opened (${reason.slice("io-".length)})`;
+	if (reason.startsWith("read-")) return `${object} could not be read (${reason.slice("read-".length)})`;
+	if (reason.startsWith("clone-")) return `${object} could not be inspected (${reason.slice("clone-".length)})`;
+	if (reason === "metadata") return `${object} could not be inspected`;
+	if (reason.startsWith("metadata-")) return `${object} could not be inspected (${reason.slice("metadata-".length)})`;
+	return `${object} withheld publication authority (${reason})`;
+}
+
+/**
+ * Name the first condition the published record itself violates, reading only
+ * through the descriptor the no-follow open already verified. Reopening by
+ * pathname would let a replacement in that window redirect the diagnostic to a
+ * different object, or block on a name that is no longer a regular file.
+ */
+function describeWithheldPublishedRecord(descriptor: number, size: number): string | undefined {
+	if (size > MAX_DIAGNOSTIC_PUBLISHED_BYTES) return undefined;
+	const bytes = Buffer.alloc(Math.min(MAX_DIAGNOSTIC_PUBLISHED_BYTES, Math.max(size, 4096)));
+	let read = 0;
+	try {
+		while (read < bytes.length) {
+			const count = fsSync.readSync(descriptor, bytes, read, bytes.length - read, read);
+			if (count === 0) break;
+			read += count;
+		}
+	} catch (error) {
+		return `sdk/broker.json could not be read (${(error as NodeJS.ErrnoException).code ?? "unknown error"})`;
+	}
+	let hasMore = false;
+	if (read === bytes.length) {
+		try {
+			hasMore = fsSync.readSync(descriptor, Buffer.alloc(1), 0, 1, read) > 0;
+		} catch {
+			return undefined;
+		}
+	}
+	// latin1 keeps one character per byte, so offsets match the native's byte scan.
+	const published = bytes.subarray(0, read).toString("latin1");
+	const needle = '"heartbeatAt":';
+	const at = published.indexOf(needle);
+	// A record larger than this bounded read is inconclusive, never an absence.
+	if (at < 0) return hasMore ? undefined : "sdk/broker.json has no heartbeatAt field";
+	const digits = published.slice(at + needle.length, at + needle.length + FIXED_WIDTH_HEARTBEAT_DIGITS);
+	const next = published.charAt(at + needle.length + FIXED_WIDTH_HEARTBEAT_DIGITS);
+	if (!/^[0-9]{13}$/.test(digits) || /^[0-9]$/.test(next))
+		return `sdk/broker.json heartbeatAt is not a fixed-width ${FIXED_WIDTH_HEARTBEAT_DIGITS}-digit timestamp`;
+	return undefined;
+}
+
+function isSymbolicLink(pathname: string): boolean {
+	try {
+		return fsSync.lstatSync(pathname).isSymbolicLink();
+	} catch {
+		return false;
+	}
+}
+
+/**
+ * Name the first condition that withholds retained publication authority.
+ *
+ * The native layer reports withheld authority as one opaque failure, so a
+ * broker that cannot retain its own publication dies without naming the object
+ * responsible. Operators then cannot distinguish a missing lock record from a
+ * redirected `sdk` directory (a symlinked agent-directory entry is refused by
+ * the no-follow open, which is how shared multi-account layouts fail), and the
+ * only way to learn the precondition is to read the native source.
+ *
+ * This inspects the same objects in the same order and returns a description of
+ * the first obstruction, or `undefined` when every precondition holds and the
+ * refusal came from a race the caller must still fail closed on.
+ */
+function describeWithheldPublicationAuthority(agentDir: string): string | undefined {
+	for (const object of BROKER_PUBLICATION_OBJECTS) {
+		const pathname = path.join(agentDir, ...object.segments);
+		// O_NONBLOCK keeps the diagnostic itself from parking on an object that is
+		// no longer a regular file; the following fstat still names the wrong kind.
+		const flags = object.directory
+			? fsSync.constants.O_RDONLY | fsSync.constants.O_DIRECTORY | fsSync.constants.O_NOFOLLOW
+			: (object.write ? fsSync.constants.O_RDWR : fsSync.constants.O_RDONLY) |
+				fsSync.constants.O_NOFOLLOW |
+				fsSync.constants.O_NONBLOCK;
+		let descriptor: number;
+		try {
+			descriptor = fsSync.openSync(pathname, flags);
+		} catch (error) {
+			const code = (error as NodeJS.ErrnoException).code;
+			if (code === "ENOENT") return `${object.name} is missing`;
+			// A refused open is already authoritative; this only labels it. Linux
+			// answers a no-follow directory open on a symlink with ENOTDIR rather
+			// than ELOOP, so the entry kind decides between the two labels.
+			if (code === "ELOOP" || code === "ENOTDIR") {
+				if (isSymbolicLink(pathname))
+					return `${object.name} is a symlink; every publication object is opened no-follow`;
+				if (code === "ENOTDIR" && object.directory) return `${object.name} is not a directory`;
+			}
+			if (code === "EISDIR") return `${object.name} is not a regular file`;
+			return `${object.name} could not be opened (${code ?? "unknown error"})`;
+		}
+		try {
+			// The published record is the last precondition: the native layer edits
+			// the heartbeat in place and therefore requires a fixed-width field. It is
+			// read through this verified descriptor, never reopened by name.
+			if (object.write) return describeWithheldPublishedRecord(descriptor, fsSync.fstatSync(descriptor).size);
+		} catch (error) {
+			return `${object.name} could not be inspected (${(error as NodeJS.ErrnoException).code ?? "unknown error"})`;
+		} finally {
+			try {
+				fsSync.closeSync(descriptor);
+			} catch {
+				// Closing a diagnostic-only descriptor is best effort; the native refusal
+				// remains the authoritative error when this probe itself is inconclusive.
+			}
+		}
+	}
+	return undefined;
+}
+
 function requireRetainedBrokerPublication(agentDir: string): NativeRetainedBrokerPublication {
 	const retainBrokerPublication = nativeBrokerDiscovery().retainBrokerPublication;
 	if (typeof retainBrokerPublication !== "function") {
 		throw new Error("Loaded native bindings do not expose retained broker publication authority.");
 	}
-	return retainBrokerPublication(agentDir);
+	try {
+		return retainBrokerPublication(agentDir);
+	} catch (error) {
+		// Fail closed exactly as before; only name the condition on the way out.
+		const obstruction = nativeRetainedObstruction(error);
+		if (obstruction) {
+			throw new Error(
+				`${error instanceof Error ? error.message : String(error)} (${obstruction}; agent directory ${sanitizedAgentDir(agentDir)})`,
+				{ cause: error },
+			);
+		}
+		const observed = describeWithheldPublicationAuthority(agentDir);
+		if (!observed) throw error;
+		// The obstruction precedes the agent directory, and the directory is
+		// bounded, so a long valid path cannot truncate the named object away.
+		throw new Error(
+			`${error instanceof Error ? error.message : String(error)} (current observed state: ${observed}; agent directory ${sanitizedAgentDir(agentDir)})`,
+			{ cause: error },
+		);
+	}
 }
 
 async function rollbackPublishedBrokerDiscovery(agentDir: string, discovery: BrokerDiscovery): Promise<void> {
@@ -216,9 +426,14 @@ export async function publishBrokerDiscovery(
 		try {
 			await rollbackPublishedBrokerDiscovery(agentDir, published);
 		} catch (rollbackError) {
+			// The aggregate message is the only thing the durable startup-failure
+			// marker persists (`AggregateError.errors` is not serialized), so the named
+			// obstruction has to survive into it rather than only into `errors[0]`.
 			throw new AggregateError(
 				[error, rollbackError],
-				"Broker publication authority acquisition and exact rollback both failed.",
+				`Broker publication authority acquisition and exact rollback both failed. Acquisition: ${
+					error instanceof Error ? error.message : String(error)
+				}`,
 			);
 		}
 		throw error;