@gajae-code/coding-agent 0.11.6 → 0.11.8

package/src/internal-urls/local-protocol.ts

@@ -145,6 +145,8 @@ async function assertDirectoryNotSymlink(directoryPath: string): Promise<void> {
 const LEGACY_MIGRATION_MARKER = ".gjc-local-legacy-migrated-v1";
 const MAX_LEGACY_LOCAL_BYTES = 64 * 1024 * 1024;
 
+type LegacyMigrationState = "complete" | "cleanup_pending";
+
 interface LegacyEntrySnapshot {
 	readonly relativePath: string;
 	readonly dev: bigint;
@@ -169,6 +171,26 @@ async function snapshotDirectory(directoryPath: string, relativePath: string): P
 	return { relativePath, dev: stat.dev, ino: stat.ino, size: stat.size };
 }
 
+interface CanonicalLegacyRoot {
+	readonly root: string;
+	readonly identity: LegacyEntrySnapshot;
+}
+
+async function canonicalLegacyRoot(artifactsDir: string): Promise<CanonicalLegacyRoot> {
+	const lexicalRoot = path.resolve(artifactsDir, "local");
+	const lexicalIdentity = await snapshotDirectory(lexicalRoot, "");
+	const [canonicalArtifactsDir, canonicalRoot] = await Promise.all([
+		fs.realpath(path.resolve(artifactsDir)),
+		fs.realpath(lexicalRoot),
+	]);
+	if (canonicalRoot === canonicalArtifactsDir) throw new Error("Unsafe legacy local:// migration source");
+	ensureWithinRoot(canonicalRoot, canonicalArtifactsDir);
+	const canonicalIdentity = await snapshotDirectory(canonicalRoot, "");
+	if (!matchesSnapshot(canonicalIdentity, lexicalIdentity))
+		throw new Error("Legacy local:// migration source changed during capture");
+	return { root: canonicalRoot, identity: lexicalIdentity };
+}
+
 async function snapshotRegularFile(filePath: string, relativePath: string): Promise<LegacyEntrySnapshot> {
 	const before = await fs.lstat(filePath, { bigint: true });
 	if (!before.isFile() || before.isSymbolicLink()) throw new Error("Unsafe legacy local:// migration source");
@@ -202,11 +224,16 @@ function manifestsMatch(left: readonly LegacyEntrySnapshot[], right: readonly Le
 	);
 }
 
-async function captureLegacyManifest(root: string): Promise<readonly LegacyEntrySnapshot[]> {
+async function captureLegacyManifest(
+	root: string,
+	expectedRootIdentity: LegacyEntrySnapshot,
+): Promise<readonly LegacyEntrySnapshot[]> {
 	const manifest: LegacyEntrySnapshot[] = [];
 	let copiedBytes = 0n;
 	const captureDirectory = async (directoryPath: string, relativePath: string): Promise<void> => {
 		const directory = await snapshotDirectory(directoryPath, relativePath);
+		if (relativePath === "" && !matchesSnapshot(directory, expectedRootIdentity))
+			throw new Error("Legacy local:// migration source changed during capture");
 		manifest.push(directory);
 		const entries = (await fs.readdir(directoryPath, { withFileTypes: true })).sort((a, b) =>
 			a.name.localeCompare(b.name),
@@ -309,7 +336,7 @@ async function migrateManagedLegacyLocal(
 	}
 	const staging = path.join(scratchParent, `.gjc-local-migration-${randomUUID()}`);
 	const installed: Array<{ readonly path: string; readonly dev: bigint; readonly ino: bigint }> = [];
-	let installedMarker: { readonly dev: bigint; readonly ino: bigint } | null = null;
+	let sourceRetired = false;
 	try {
 		await fs.mkdir(staging, { mode: 0o700 });
 		for (const entry of captured.entries) {
@@ -335,18 +362,22 @@ async function migrateManagedLegacyLocal(
 			const identity = await fs.lstat(destination, { bigint: true });
 			installed.push({ path: destination, dev: identity.dev, ino: identity.ino });
 		}
+		try {
+			source.retire(captured.snapshot);
+			sourceRetired = true;
+		} catch (error) {
+			if (!(error instanceof Error) || error.message !== "cleanup_pending") throw error;
+			await fs.writeFile(marker, "cleanup_pending\n", { mode: 0o600, flag: "wx" });
+			return;
+		}
 		await fs.writeFile(marker, "verified\n", { mode: 0o600, flag: "wx" });
-		const markerIdentity = await fs.lstat(marker, { bigint: true });
-		installedMarker = { dev: markerIdentity.dev, ino: markerIdentity.ino };
-		source.retire(captured.snapshot);
 	} catch (error) {
-		const currentMarker = await fs.lstat(marker, { bigint: true }).catch(() => null);
-		if (installedMarker && currentMarker?.dev === installedMarker.dev && currentMarker.ino === installedMarker.ino)
-			await fs.rm(marker, { force: true });
-		for (const destination of installed.reverse()) {
-			const current = await fs.lstat(destination.path, { bigint: true }).catch(() => null);
-			if (current?.dev === destination.dev && current.ino === destination.ino)
-				await fs.rm(destination.path, { recursive: true, force: true });
+		if (!sourceRetired) {
+			for (const destination of installed.reverse()) {
+				const current = await fs.lstat(destination.path, { bigint: true }).catch(() => null);
+				if (current?.dev === destination.dev && current.ino === destination.ino)
+					await fs.rm(destination.path, { recursive: true, force: true });
+			}
 		}
 		throw error;
 	} finally {
@@ -354,15 +385,16 @@ async function migrateManagedLegacyLocal(
 	}
 }
 
-async function readMigrationMarker(marker: string): Promise<boolean> {
+async function readMigrationMarker(marker: string): Promise<LegacyMigrationState | null> {
 	try {
 		const snapshot = await snapshotRegularFile(marker, LEGACY_MIGRATION_MARKER);
 		if (snapshot.size > 32n || snapshot.bytes === undefined) throw new Error("Unsafe local:// migration marker");
 		const value = snapshot.bytes.toString("utf8");
-		if (value !== "verified\n" && value !== "absent\n") throw new Error("Unsafe local:// migration marker");
-		return true;
+		if (value === "cleanup_pending\n") return "cleanup_pending";
+		if (value === "verified\n" || value === "absent\n") return "complete";
+		throw new Error("Unsafe local:// migration marker");
 	} catch (error) {
-		if (isEnoent(error)) return false;
+		if (isEnoent(error)) return null;
 		throw error;
 	}
 }
@@ -384,10 +416,11 @@ async function migrateLegacyLocal(
 		await fs.writeFile(marker, "absent\n", { mode: 0o600, flag: "wx" });
 		return;
 	}
-	const legacyRoot = path.resolve(artifactsDir, "local");
+	let legacySource: CanonicalLegacyRoot;
 	let manifest: readonly LegacyEntrySnapshot[];
 	try {
-		manifest = await captureLegacyManifest(legacyRoot);
+		legacySource = await canonicalLegacyRoot(artifactsDir);
+		manifest = await captureLegacyManifest(legacySource.root, legacySource.identity);
 	} catch (error) {
 		if (isEnoent(error)) {
 			await fs.writeFile(marker, "absent\n", { mode: 0o600, flag: "wx" });
@@ -397,8 +430,8 @@ async function migrateLegacyLocal(
 	}
 	const staging = path.join(scratchParent, `.gjc-local-migration-${randomUUID()}`);
 	try {
-		await copyLegacyManifest(legacyRoot, staging, manifest);
-		const verifiedManifest = await captureLegacyManifest(legacyRoot);
+		await copyLegacyManifest(legacySource.root, staging, manifest);
+		const verifiedManifest = await captureLegacyManifest(legacySource.root, legacySource.identity);
 		if (!manifestsMatch(verifiedManifest, manifest))
 			throw new Error("Legacy local:// migration source changed during capture");
 		for (const entry of await fs.readdir(staging)) {
@@ -410,7 +443,17 @@ async function migrateLegacyLocal(
 			}
 			await fs.rename(path.join(staging, entry), path.join(localRoot, entry));
 		}
-		await retireLegacyTree(legacyRoot, manifest);
+		try {
+			await retireLegacyTree(legacySource.root, manifest);
+		} catch (error) {
+			if (
+				!(error instanceof Error) ||
+				error.message !== "Legacy local:// migration retirement failed: cleanup_pending"
+			)
+				throw error;
+			await fs.writeFile(marker, "cleanup_pending\n", { mode: 0o600, flag: "wx" });
+			return;
+		}
 		await fs.writeFile(marker, "verified\n", { mode: 0o600, flag: "wx" });
 	} finally {
 		await fs.rm(staging, { recursive: true, force: true });

package/src/internal-urls/mcp-protocol.ts

@@ -2,29 +2,91 @@ import { MCPManager } from "../runtime-mcp/manager";
 import type { MCPResourceReadResult } from "../runtime-mcp/types";
 import type { InternalResource, InternalUrl, ProtocolHandler } from "./types";
 
-function escapeRegex(text: string): string {
-	return text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+const MAX_MCP_RESOURCE_URI_CHARS = 16_384;
+const MAX_MCP_URI_TEMPLATE_CHARS = 8_192;
+const MAX_MCP_URI_TEMPLATE_EXPRESSIONS = 32;
+
+interface CompiledUriTemplate {
+	literalSegments: string[];
+	literalChars: number;
+	expressionCount: number;
+}
+
+function containsExpressionLineTerminator(text: string, start: number, end: number): boolean {
+	for (let index = start; index < end; index++) {
+		const code = text.charCodeAt(index);
+		if (code === 0x0a || code === 0x0d || code === 0x2028 || code === 0x2029) return true;
+	}
+	return false;
+}
+
+function compileUriTemplate(uriTemplate: string): CompiledUriTemplate | undefined {
+	if (uriTemplate.length > MAX_MCP_URI_TEMPLATE_CHARS) return undefined;
+
+	const literalSegments: string[] = [];
+	let expressionCount = 0;
+	let literalChars = 0;
+	let segmentStart = 0;
+	let scanPosition = 0;
+	while (scanPosition < uriTemplate.length) {
+		const expressionStart = uriTemplate.indexOf("{", scanPosition);
+		if (expressionStart < 0) break;
+		const expressionEnd = uriTemplate.indexOf("}", expressionStart + 1);
+		if (expressionEnd < 0) break;
+		if (expressionEnd === expressionStart + 1) {
+			scanPosition = expressionStart + 1;
+			continue;
+		}
+		expressionCount++;
+		if (expressionCount > MAX_MCP_URI_TEMPLATE_EXPRESSIONS) return undefined;
+		const segment = uriTemplate.slice(segmentStart, expressionStart);
+		literalSegments.push(segment);
+		literalChars += segment.length;
+		segmentStart = expressionEnd + 1;
+		scanPosition = segmentStart;
+	}
+	const finalSegment = uriTemplate.slice(segmentStart);
+	literalSegments.push(finalSegment);
+	literalChars += finalSegment.length;
+	return { literalSegments, literalChars, expressionCount };
+}
+
+function matchesUriTemplate(uri: string, template: CompiledUriTemplate): boolean {
+	const { literalSegments, expressionCount } = template;
+	if (expressionCount === 0) return uri === literalSegments[0];
+	if (!uri.startsWith(literalSegments[0])) return false;
+
+	let cursor = literalSegments[0].length;
+	for (let index = 1; index < literalSegments.length - 1; index++) {
+		const segment = literalSegments[index];
+		const matchIndex = uri.indexOf(segment, cursor);
+		if (matchIndex < 0 || containsExpressionLineTerminator(uri, cursor, matchIndex)) return false;
+		cursor = matchIndex + segment.length;
+	}
+
+	const suffix = literalSegments.at(-1) ?? "";
+	const suffixStart = uri.length - suffix.length;
+	return suffixStart >= cursor && uri.endsWith(suffix) && !containsExpressionLineTerminator(uri, cursor, suffixStart);
 }
 
 function getUriTemplateMatchScore(
 	uri: string,
 	uriTemplate: string,
 ): { literalChars: number; expressionCount: number } | undefined {
-	const expressionPattern = /\{[^}]+\}/g;
-	const literalSegments = uriTemplate.split(expressionPattern);
-	const expressionCount = (uriTemplate.match(expressionPattern) ?? []).length;
-	const pattern = literalSegments.map(escapeRegex).join("(.*?)");
-	const regex = new RegExp(`^${pattern}$`);
-	if (!regex.test(uri)) return undefined;
-	const literalChars = literalSegments.reduce((total, segment) => total + segment.length, 0);
-	return { literalChars, expressionCount };
+	const template = compileUriTemplate(uriTemplate);
+	if (!template || !matchesUriTemplate(uri, template)) return undefined;
+	return { literalChars: template.literalChars, expressionCount: template.expressionCount };
 }
 
 function extractResourceUri(url: InternalUrl): string {
 	const host = url.rawHost || url.hostname;
 	const rawPathname = url.rawPathname ?? url.pathname;
 	const hasPath = rawPathname && rawPathname !== "/";
-	const uri = `${host}${hasPath ? rawPathname : ""}${url.search}${url.hash}`.trim();
+	const rawUri = `${host}${hasPath ? rawPathname : ""}${url.search}${url.hash}`;
+	if (rawUri.length > MAX_MCP_RESOURCE_URI_CHARS) {
+		throw new Error("MCP resource URI exceeds the 16384-character limit.");
+	}
+	const uri = rawUri.trim();
 	if (!uri) {
 		throw new Error("mcp:// URL requires a resource URI: mcp://<resource-uri>");
 	}

package/src/main.ts

@@ -11,7 +11,8 @@ import * as path from "node:path";
 import { createInterface } from "node:readline/promises";
 import type { ImageContent } from "@gajae-code/ai";
 import {
-	$env,
+	$pickenv,
+	getAgentDir,
 	getProjectDir,
 	logger,
 	normalizePathForComparison,
@@ -534,7 +535,16 @@ interface InteractiveModeFactoryOptions {
 type CreateInteractiveMode = (options: InteractiveModeFactoryOptions) => InteractiveMode;
 
 type ResumePickerTerminalCheck = () => boolean;
-type ListForResumePickerReadOnly = (cwd: string, sessionDir?: string) => Promise<SessionInfo[]>;
+type ListForResumePickerReadOnly = (cwd: string, sessionDir?: string, storage?: undefined) => Promise<SessionInfo[]>;
+
+type ListManagedForResumePickerReadOnly = (
+	cwd: string,
+	managedAgentDir?: string,
+	storage?: undefined,
+) => Promise<SessionInfo[]>;
+
+type ResolveManagedAgentDirForScope = (cwd: string) => string;
+
 type SelectResumeSession = (sessions: SessionInfo[]) => Promise<SessionSelectionResult>;
 type OpenExistingSessionStrict = (
 	identity: ResumeSessionIdentity,
@@ -546,6 +556,11 @@ type OpenExistingSessionStrict = (
 export const BARE_RESUME_CONFLICT_ERROR =
 	"--resume without a session cannot be combined with --continue, --fork, or --no-session.";
 export const BARE_RESUME_INTERACTIVE_ERROR = "--resume requires an interactive terminal; use --resume <id>.";
+
+/** Resolves only the managed agent root needed for pre-consent picker inventory. */
+export function resolveManagedAgentDirForScope(_cwd: string): string {
+	return getAgentDir();
+}
 export const BARE_RESUME_OPEN_ERROR = "Could not open the selected session. Use --resume <id>.";
 
 function isBareResume(parsed: Args): boolean {
@@ -741,7 +756,13 @@ export async function createSessionManager(
 		if (forkSource.includes("/") || forkSource.includes("\\") || forkSource.endsWith(".jsonl")) {
 			return await SessionManager.forkFrom(forkSource, cwd, sessionDestination(), undefined, migrationPolicy);
 		}
-		const match = await resolveResumableSession(forkSource, cwd, parsed.sessionDir);
+		const match = await resolveResumableSession(
+			forkSource,
+			cwd,
+			parsed.sessionDir,
+			undefined,
+			parsed.sessionDir ? undefined : activeSettings.getAgentDir(),
+		);
 		if (!match) {
 			throw new Error(`Session "${forkSource}" not found.`);
 		}
@@ -754,14 +775,18 @@ export async function createSessionManager(
 	if (typeof parsed.resume === "string") {
 		const sessionArg = parsed.resume;
 		if (sessionArg.includes("/") || sessionArg.includes("\\") || sessionArg.endsWith(".jsonl")) {
-			return await SessionManager.open(
-				sessionArg,
-				SessionManager.explicitDestination(path.dirname(sessionArg)),
-				undefined,
-				migrationPolicy,
-			);
+			const destination = parsed.sessionDir
+				? SessionManager.explicitDestination(parsed.sessionDir)
+				: SessionManager.explicitDestination(path.dirname(sessionArg));
+			return await SessionManager.open(sessionArg, destination, undefined, migrationPolicy);
 		}
-		const match = await resolveResumableSession(sessionArg, cwd, parsed.sessionDir);
+		const match = await resolveResumableSession(
+			sessionArg,
+			cwd,
+			parsed.sessionDir,
+			undefined,
+			parsed.sessionDir ? undefined : activeSettings.getAgentDir(),
+		);
 		if (!match) {
 			throw new Error(`Session "${sessionArg}" not found.`);
 		}
@@ -1058,12 +1083,62 @@ export interface RunRootCommandDependencies {
 	runPrintMode?: RunPrintMode;
 	isResumePickerTerminal?: ResumePickerTerminalCheck;
 	listForResumePickerReadOnly?: ListForResumePickerReadOnly;
+	listManagedForResumePickerReadOnly?: ListManagedForResumePickerReadOnly;
+	resolveManagedAgentDirForScope?: ResolveManagedAgentDirForScope;
 	selectResumeSession?: SelectResumeSession;
 	openExistingSessionStrict?: OpenExistingSessionStrict;
 	initializeSettings?: typeof Settings.init;
 	loadSettingsForScope?: typeof Settings.loadForScope;
 }
 
+export interface ModelRoleOverrides {
+	smol?: string;
+	slow?: string;
+	plan?: string;
+}
+
+/**
+ * Resolve the ephemeral `smol`/`slow`/`plan` model-role overrides.
+ *
+ * Precedence per role is CLI flag > documented `GJC_*_MODEL` > legacy
+ * `PI_*_MODEL`, matching the repo-wide GJC-first/PI-fallback convention.
+ * Resolution reads the process environment via `$pickenv`, which trims values
+ * and treats empty/whitespace as unset; it is deliberately kept separate from
+ * credential env resolution (`$credentialEnv`/`$pickCredentialEnv`). The
+ * function is pure and stateless, so it reads fresh each call and a later
+ * invocation never inherits an earlier one's values.
+ */
+export function resolveModelRoleOverrides(parsed: Pick<Args, "smol" | "slow" | "plan">): ModelRoleOverrides {
+	const overrides: ModelRoleOverrides = {};
+	const smol = parsed.smol ?? $pickenv("GJC_SMOL_MODEL", "PI_SMOL_MODEL");
+	const slow = parsed.slow ?? $pickenv("GJC_SLOW_MODEL", "PI_SLOW_MODEL");
+	const plan = parsed.plan ?? $pickenv("GJC_PLAN_MODEL", "PI_PLAN_MODEL");
+	if (smol) overrides.smol = smol;
+	if (slow) overrides.slow = slow;
+	if (plan) overrides.plan = plan;
+	return overrides;
+}
+
+/**
+ * Apply the `--no-pty` / `--no-title` terminal-control flags to the environment.
+ *
+ * Sets the canonical `GJC_*` name (so an explicit flag wins over a user-set
+ * `GJC_*` value under the GJC-first resolver — CLI authority) and the legacy
+ * `PI_*` name for backward compatibility. `--acp` mode implies `--no-title`.
+ */
+export function applyTerminalControlFlagsToEnv(
+	parsed: Pick<Args, "noPty" | "noTitle" | "mode">,
+	env: NodeJS.ProcessEnv = Bun.env,
+): void {
+	if (parsed.noPty) {
+		env.GJC_NO_PTY = "1";
+		env.PI_NO_PTY = "1";
+	}
+	if (parsed.noTitle || parsed.mode === "acp") {
+		env.GJC_NO_TITLE = "1";
+		env.PI_NO_TITLE = "1";
+	}
+}
 export async function runRootCommand(
 	parsed: Args,
 	rawArgs: string[],
@@ -1094,10 +1169,18 @@ export async function runRootCommand(
 		await logger.time("maybeAutoChdir", maybeAutoChdir, parsedArgs);
 		autoChdirApplied = true;
 		const resumeCwd = getProjectDir();
-		const sessions = await (deps.listForResumePickerReadOnly ?? SessionManager.listForResumePickerReadOnly)(
-			resumeCwd,
-			parsedArgs.sessionDir,
-		);
+		const managedAgentDir = parsedArgs.sessionDir
+			? undefined
+			: (deps.resolveManagedAgentDirForScope ?? resolveManagedAgentDirForScope)(resumeCwd);
+		const sessions = parsedArgs.sessionDir
+			? await (deps.listForResumePickerReadOnly ?? SessionManager.listForResumePickerReadOnly)(
+					resumeCwd,
+					parsedArgs.sessionDir,
+				)
+			: await (deps.listManagedForResumePickerReadOnly ?? SessionManager.listManagedForResumePickerReadOnly)(
+					resumeCwd,
+					managedAgentDir,
+				);
 		if (sessions.length === 0) {
 			process.stdout.write(`${chalk.dim("No sessions found")}\n`);
 			return;
@@ -1108,19 +1191,16 @@ export async function runRootCommand(
 		if (selection.kind === "cancelled") {
 			return;
 		}
+		const scopedSettings = await (deps.loadSettingsForScope ?? Settings.loadForScope)({ cwd: resumeCwd });
 		const resumeMigrationPolicy =
-			(await (deps.loadSettingsForScope ?? Settings.loadForScope)({ cwd: resumeCwd })).get(
-				"session.directoryMigration",
-			) === "disabled"
-				? "disabled"
-				: "copy-retain";
+			scopedSettings.get("session.directoryMigration") === "disabled" ? "disabled" : "copy-retain";
 		let opened: StrictSessionOpenResult;
 		try {
 			opened = await (deps.openExistingSessionStrict ?? SessionManager.openExistingStrict)(
 				selection.identity,
 				parsedArgs.sessionDir
 					? SessionManager.explicitDestination(parsedArgs.sessionDir)
-					: SessionManager.managedDestination(resumeCwd, settings.getAgentDir()),
+					: SessionManager.managedDestination(resumeCwd, scopedSettings.getAgentDir()),
 				undefined,
 				resumeMigrationPolicy,
 			);
@@ -1198,12 +1278,7 @@ export async function runRootCommand(
 		applyAcpDefaultSettingOverrides(settingsInstance);
 	}
 	modelRegistry.applyConfiguredModelBindings(settingsInstance);
-	if (parsedArgs.noPty) {
-		Bun.env.PI_NO_PTY = "1";
-	}
-	if (parsedArgs.noTitle || parsedArgs.mode === "acp") {
-		Bun.env.PI_NO_TITLE = "1";
-	}
+	applyTerminalControlFlagsToEnv(parsedArgs);
 	const hasPreparedInput = parsedArgs.messages.length > 0 || parsedArgs.fileArgs.length > 0;
 	const { pipedInput, fileText, fileImages } = await logger.time("prepareInitialMessage", async () => {
 		const pipedInput =
@@ -1252,15 +1327,14 @@ export async function runRootCommand(
 	// Initialize discovery system with settings for provider persistence
 	logger.time("initializeWithSettings", initializeWithSettings, settingsInstance);
 
-	// Apply model role overrides from CLI args or env vars (ephemeral, not persisted)
-	const smolModel = parsedArgs.smol ?? $env.PI_SMOL_MODEL;
-	const slowModel = parsedArgs.slow ?? $env.PI_SLOW_MODEL;
-	const planModel = parsedArgs.plan ?? $env.PI_PLAN_MODEL;
-	if (smolModel || slowModel || planModel) {
+	// Apply model role overrides from CLI args or env vars (ephemeral, not persisted).
+	// Precedence per role: CLI flag > documented GJC_*_MODEL > legacy PI_*_MODEL.
+	const roleOverrides = resolveModelRoleOverrides(parsedArgs);
+	if (roleOverrides.smol || roleOverrides.slow || roleOverrides.plan) {
 		settingsInstance.overrideModelRoles({
-			smol: smolModel,
-			slow: slowModel,
-			plan: planModel,
+			...(roleOverrides.smol ? { smol: roleOverrides.smol } : {}),
+			...(roleOverrides.slow ? { slow: roleOverrides.slow } : {}),
+			...(roleOverrides.plan ? { plan: roleOverrides.plan } : {}),
 		});
 	}
 
@@ -1554,9 +1628,9 @@ export async function runRootCommand(
 					process.stdout.write(`${chalk.dim(`Model scope: ${modelList} ${chalk.gray("(Alt+N to cycle)")}`)}\n`);
 				}
 
-				if ($env.PI_TIMING) {
+				if ($pickenv("GJC_TIMING", "PI_TIMING")) {
 					logger.printTimings();
-					exitForTiming = $env.PI_TIMING === "x";
+					exitForTiming = $pickenv("GJC_TIMING", "PI_TIMING") === "x";
 				}
 
 				if (!exitForTiming) {
@@ -1601,7 +1675,7 @@ export async function runRootCommand(
 					initialImages,
 					suppressProcessExit: deps.suppressProcessExit,
 				});
-				if ($env.PI_TIMING) {
+				if ($pickenv("GJC_TIMING", "PI_TIMING")) {
 					logger.printTimings();
 				}
 			} finally {

package/src/modes/DESIGN.md

@@ -94,6 +94,11 @@ empty space and list density for an operational setup flow.
   removing line breaks. Notification secrets will use the dedicated masked
   input from Work item 6; they must never appear in list values, descriptions,
   previews, artifacts, or logs.
+### Shortcut labels and binding authority
+
+Keybinding configuration is a portable canonical grammar: textual key IDs use `ctrl`, `alt`, `shift`, and `super` plus a key name (for example, `ctrl+p` or `alt+enter`). Do not serialize or require display-only labels. Runtime UI renders those IDs through the shared formatter for its explicit platform context; macOS uses MacBook-style glyphs (`⌃`, `⌥`, `⇧`, `⌘`, `↩`, `⎋`, `⇥`, `⌫`, `⌦`, and arrow glyphs) while other platforms use textual labels. A glyph is never configuration syntax.
+
+Static onboarding and generated documentation have authority only over shipped defaults. Keep generated tables host-independent by showing canonical textual IDs, not the capture host's labels. The runtime `KeybindingsManager` owns the effective binding set after user remaps and extensions load; `/hotkeys` and runtime hints must render that effective set with the platform context injected by their host. Do not let a static onboarding hint imply that it reflects remaps.
 
 ### Status, errors, confirmation, and disabled work
 

package/src/modes/acp/acp-agent.ts

@@ -42,7 +42,7 @@ import {
 	AcpSdkAdapterError,
 } from "../../sdk/acp";
 import { ensureBroker } from "../../sdk/broker/ensure";
-import { readSdkBrokerDiscovery, SdkClient } from "../../sdk/client";
+import { readSdkBrokerDiscovery, SdkClient, SdkClientError } from "../../sdk/client";
 import { mapAgentWireEventPayloadToAcpSessionUpdates } from "./acp-event-mapper";
 import { resolveAcpPermissionMode } from "./permission-mode";
 import type { AcpStartupOptions } from "./startup-options";
@@ -88,6 +88,7 @@ type PendingAttachment = { epoch: number; task: Promise<void> };
 type SessionRecord = {
 	cwd: string;
 	adapter: AcpSdkAdapter;
+	closeIdempotencyKey: string;
 	unsubscribe: () => void;
 	reconnectUnsubscribe: () => void;
 	/** Per-session frame work queue; callbacks never race prompt ownership. */
@@ -571,8 +572,10 @@ export class AcpAgent implements Agent {
 	readonly #attaching = new Map<string, PendingAttachment>();
 	readonly #resolvingExisting = new Map<string, PendingAttachment>();
 	readonly #knownSessionCwds = new Map<string, string>();
+	readonly #pendingCloseIdempotencyKeys = new Map<string, string>();
 	readonly #sessionEpochs = new Map<string, number>();
 	readonly #tearingDown = new Map<string, number>();
+	readonly #closing = new Map<string, Promise<CloseSessionResponse>>();
 	#clientCapabilities: ClientCapabilities | undefined;
 	#broker: Promise<BrokerConnection> | undefined;
 	readonly #startupOptions: AcpStartupOptions | undefined;
@@ -730,19 +733,21 @@ export class AcpAgent implements Agent {
 		return paginateAcpSessions(listed, params.cwd ?? undefined, this.#cursor(params.cursor));
 	}
 
-	async closeSession(params: CloseSessionRequest): Promise<CloseSessionResponse> {
+	closeSession(params: CloseSessionRequest): Promise<CloseSessionResponse> {
 		const record = this.#sessions.get(params.sessionId);
 		const cwd = record?.cwd ?? this.#knownSessionCwds.get(params.sessionId);
 		// ACP close has no cwd. Only connection-owned sessions may reach broker lifecycle control.
-		if (!cwd) return {};
-		this.#beginTeardown(params.sessionId);
-		try {
-			await this.#teardownSession(params.sessionId, "closed", true);
-			this.#knownSessionCwds.delete(params.sessionId);
-			return {};
-		} finally {
-			this.#finishTeardown(params.sessionId);
-		}
+		if (!cwd) return Promise.resolve({});
+		const existing = this.#closing.get(params.sessionId);
+		if (existing) return existing;
+		const deferred = Promise.withResolvers<CloseSessionResponse>();
+		this.#closing.set(params.sessionId, deferred.promise);
+		void this.#closeOwnedSession(params.sessionId).then(deferred.resolve, deferred.reject);
+		const cleanup = deferred.promise.finally(() => {
+			if (this.#closing.get(params.sessionId) === deferred.promise) this.#closing.delete(params.sessionId);
+		});
+		void cleanup.catch(() => undefined);
+		return deferred.promise;
 	}
 
 	async deleteSession(params: DeleteSessionRequest): Promise<DeleteSessionResponse> {
@@ -932,6 +937,15 @@ export class AcpAgent implements Agent {
 		);
 	}
 
+	#isDefinitiveBrokerResponse(error: unknown): boolean {
+		// Response-derived client errors retain the broker error as details. Responses
+		// that represent ongoing or ambiguous lifecycle work must keep their key.
+		if (!(error instanceof SdkClientError)) return false;
+		const details = object(error.details);
+		if (details?.code !== error.code || details.message !== error.message) return false;
+		return !["terminal_uncertain", "cleanup_pending", "broker_restarting", "unavailable"].includes(error.code);
+	}
+
 	async #attachExisting(id: string, cwd: string): Promise<void> {
 		const epoch = this.#sessionEpoch(id);
 		const attached = this.#sessions.get(id);
@@ -1045,6 +1059,7 @@ export class AcpAgent implements Agent {
 			const record: SessionRecord = {
 				cwd,
 				adapter,
+				closeIdempotencyKey: randomUUID(),
 				unsubscribe: () => {},
 				reconnectUnsubscribe: () => {},
 				frameTail: Promise.resolve(),
@@ -1059,6 +1074,7 @@ export class AcpAgent implements Agent {
 			this.#knownSessionCwds.set(id, cwd);
 			await applyAcpPermissionMode(adapter, this.#clientCapabilities);
 			this.#assertSessionEpoch(id, epoch);
+			this.#pendingCloseIdempotencyKeys.delete(id);
 		} catch (error) {
 			if (adapter && this.#sessions.get(id)?.adapter === adapter) {
 				try {
@@ -1103,6 +1119,21 @@ export class AcpAgent implements Agent {
 		this.#knownSessionCwds.delete(id);
 	}
 
+	async #closeOwnedSession(id: string): Promise<CloseSessionResponse> {
+		this.#beginTeardown(id);
+		try {
+			const attaching = this.#attaching.get(id);
+			// The record is published before permission initialization. Let a canceled
+			// provisional attachment retire it before selecting the generation key.
+			if (attaching) await Promise.allSettled([attaching.task]);
+			await this.#teardownSession(id, "closed", true);
+			this.#knownSessionCwds.delete(id);
+			return {};
+		} finally {
+			this.#finishTeardown(id);
+		}
+	}
+
 	/**
 	 * All local session disposal follows one path: remove ownership and reject a
 	 * waiting prompt before any awaited socket or broker work. A failed close is
@@ -1130,13 +1161,13 @@ export class AcpAgent implements Agent {
 				failures.push(error);
 			}
 			if (closeRemote) {
+				const closeIdempotencyKey =
+					record?.closeIdempotencyKey ?? this.#pendingCloseIdempotencyKeys.get(id) ?? randomUUID();
+				this.#pendingCloseIdempotencyKeys.set(id, closeIdempotencyKey);
 				try {
-					await (await this.#brokerAdapter()).global(
-						"session.close",
-						{ sessionId: id },
-						this.#lifecycleIdempotencyKey(id, "session.close"),
-					);
+					await (await this.#brokerAdapter()).global("session.close", { sessionId: id }, closeIdempotencyKey);
 				} catch (error) {
+					if (this.#isDefinitiveBrokerResponse(error)) this.#pendingCloseIdempotencyKeys.delete(id);
 					if (!(ownershipBound && this.#isAlreadyGone(error))) failures.push(error);
 				}
 			}
@@ -1146,6 +1177,7 @@ export class AcpAgent implements Agent {
 					.join("; ");
 				throw aggregateAcpFailure("terminal_uncertain", `ACP session cleanup is uncertain: ${detail}`, failures);
 			}
+			if (closeRemote) this.#pendingCloseIdempotencyKeys.delete(id);
 		} finally {
 			this.#finishTeardown(id);
 		}
@@ -1494,6 +1526,8 @@ export class AcpAgent implements Agent {
 		this.#attaching.clear();
 		this.#resolvingExisting.clear();
 		this.#knownSessionCwds.clear();
+		this.#pendingCloseIdempotencyKeys.clear();
+		if (this.#closing.size === 0) this.#closing.clear();
 		this.#tearingDown.clear();
 		if (this.#broker) {
 			const broker = this.#broker;