codebay 0.9.1 → 0.10.0

package/src/lib/devcontainer.server.ts

@@ -6,6 +6,9 @@ import { INSTALL_SCRIPT as TMUX_INSTALL_SCRIPT } from '../container-injections/t
 import { INSTALL_SCRIPT as TTYD_INSTALL_SCRIPT } from '../container-injections/ttyd.ts';
 import { INSTALL_SCRIPT as CLAUDE_INSTALL_SCRIPT } from '../container-injections/claude-code-install.ts';
 import { EXTENSION_ID as CLAUDE_CODE_EXTENSION_ID } from '../container-injections/claude-code-ide-extension.ts';
+import { ENV_FILE_NAME as CUSTOM_ENV_FILE } from '../container-injections/claude-code-custom.ts';
+import { ENV_FILE_NAME as MODELS_ENV_FILE } from '../container-injections/claude-code-models.ts';
+import { ENV_FILE_NAME as HOST_ENV_FILE } from '../container-injections/host-env-vars.ts';
 import {
 	CODE_SERVER_PORT,
 	DEFAULT_IMAGE,
@@ -15,8 +18,8 @@ import {
 	dockerEnv
 } from './config.server.ts';
 import { spawnCapture } from './spawn.server.ts';
-import type { InstanceMode } from './db.server.ts';
-import type { PortForward } from '../types.ts';
+import { getOption, type InstanceMode } from './db.server.ts';
+import { claudePermissionFlags, type ClaudePermissionMode, type PortForward } from '../types.ts';
 
 const CODE_SERVER_FEATURE = 'ghcr.io/coder/devcontainer-features/code-server:1';
 
@@ -141,6 +144,12 @@ const TMUX_SHELL_SESSION = 'codebay-shell';
 /** Written to `$HOME` when the post-up injection sequence finishes; the terminal launcher waits on it. */
 export const INJECTIONS_DONE_FILE = '.codebay-injections-done';
 
+/**
+ * IDE mode's folderOpen task touches this to stay run-once across workspace reloads, but it
+ * outlives a container restart — so a relaunch must clear it or the terminal never reopens.
+ */
+export const TERMINAL_LAUNCHED_MARKER = '.codebay-terminal-launched';
+
 /**
  * An auto-launched `claude` that starts mid-injection reads `~/.claude.json` before the trust
  * keys land and clobbers them on its next rewrite, so hold it until the sentinel appears.
@@ -160,45 +169,81 @@ const WAIT_FOR_INJECTIONS =
  */
 const WAIT_FOR_IDE_BRIDGE = `i=0; until ls "$HOME/.claude/ide/" 2>/dev/null | grep -q "\\.lock$" || [ "$i" -ge 30 ]; do sleep 1; i=$((i + 1)); done; `;
 
+/**
+ * The injections deliver `ANTHROPIC_*` (and host) env vars through `~/.bashrc`/`~/.zshrc`, which no
+ * auto-launch path reads — ttyd runs `bash <script>` and tmux runs its command via `$SHELL -c`, both
+ * non-interactive. LiteLLM first, so it wins over the manual override if both files somehow exist.
+ * An explicit list, never a glob: tmux runs this under the user's shell, and zsh would print
+ * "no matches found" when a file is absent.
+ */
+const SOURCE_INJECTED_ENV = `for f in ${[CUSTOM_ENV_FILE, MODELS_ENV_FILE, HOST_ENV_FILE]
+	.map((name) => `"$HOME/${name}"`)
+	.join(' ')}; do [ -r "$f" ] && . "$f"; done; `;
+
+/** The label/`runOn` pair that identifies our task in a project's own tasks.json. */
+const TERMINAL_TASK_LABEL = 'Terminal';
+
 /**
  * Runs under tmux so Claude survives the browser closing — code-server reaps the
  * detached PTY, which only kills the tmux client. `-A` doubles as the run-once gate.
  */
-const TERMINAL_TASK = {
-	label: 'Terminal',
+const terminalTask = (permissionMode: ClaudePermissionMode) => ({
+	label: TERMINAL_TASK_LABEL,
 	type: 'shell',
 	command:
 		// `"$SHELL"` must reach tmux unexpanded; VS Code would substitute a `${…}` form first.
-		`if command -v tmux >/dev/null 2>&1; then exec tmux new-session -A -s ${TMUX_SESSION} '${WAIT_FOR_INJECTIONS}${WAIT_FOR_IDE_BRIDGE}claude --dangerously-skip-permissions; exec "$SHELL" -l'; fi; ` +
+		`if command -v tmux >/dev/null 2>&1; then exec tmux new-session -A -s ${TMUX_SESSION} '${WAIT_FOR_INJECTIONS}${WAIT_FOR_IDE_BRIDGE}${SOURCE_INJECTED_ENV}claude ${claudePermissionFlags(permissionMode)}; exec "$SHELL" -l'; fi; ` +
 		// Without tmux there's no run-once gate, and folderOpen re-fires on every workspace load.
-		'MARK="$HOME/.codebay-terminal-launched"; [ -e "$MARK" ] && exit 0; touch "$MARK"; ' +
+		'MARK="$HOME/' +
+		TERMINAL_LAUNCHED_MARKER +
+		'"; [ -e "$MARK" ] && exit 0; touch "$MARK"; ' +
 		WAIT_FOR_INJECTIONS +
 		WAIT_FOR_IDE_BRIDGE +
-		'claude --dangerously-skip-permissions; exec ${env:SHELL} -l',
+		SOURCE_INJECTED_ENV +
+		`claude ${claudePermissionFlags(permissionMode)}; exec \${env:SHELL} -l`,
 	presentation: { reveal: 'always', panel: 'shared', focus: true },
 	runOptions: { runOn: 'folderOpen' },
 	problemMatcher: []
-};
+});
 
 const CODE_SERVER_APPLY_SETTINGS =
 	`mkdir -p ~/.local/share/code-server/User && ` +
 	`cp -f \\"$PWD/.devcontainer/${CODE_SERVER_SETTINGS_FILE}\\" ` +
 	`~/.local/share/code-server/User/settings.json 2>/dev/null;`;
 
-// Runs before code-server first launches so the extension host activates it on the first window
-// (the /ide bridge, in-container over localhost); best-effort, offline-tolerant, skipped if present.
+// Fully detached (redirects + </dev/null + &) because `devcontainer up` waits for postStart's
+// pipes to close — an attached download would keep the whole boot on the Open VSX critical path.
 const CODE_SERVER_INSTALL_EXT =
-	`ls -d ~/.local/share/code-server/extensions/${CLAUDE_CODE_EXTENSION_ID}-* >/dev/null 2>&1 || ` +
-	`code-server --install-extension ${CLAUDE_CODE_EXTENSION_ID} >/tmp/code-server-ext.log 2>&1 || true; `;
-
-const CODE_SERVER_LAUNCH =
-	`bash -c "${CODE_SERVER_APPLY_SETTINGS} ` +
-	`${CODE_SERVER_INSTALL_EXT} ` +
-	// The bare default image may not export SHELL, which the Terminal task needs.
-	`export SHELL=\\"\${SHELL:-/bin/bash}\\"; ` +
-	`pgrep -f 'code-server.*${CODE_SERVER_PORT}' >/dev/null 2>&1 || ` +
-	`nohup code-server --bind-addr 0.0.0.0:${CODE_SERVER_PORT} --auth none ` +
-	`--disable-workspace-trust \\"$PWD\\" >/tmp/code-server.log 2>&1 &"`;
+	`( ls -d ~/.local/share/code-server/extensions/${CLAUDE_CODE_EXTENSION_ID}-* >/dev/null 2>&1 || ` +
+	`code-server --install-extension ${CLAUDE_CODE_EXTENSION_ID} ) ` +
+	`>/tmp/code-server-ext.log 2>&1 </dev/null &`;
+
+// Foreground variant for the advanced escape hatch: slower boot, but the extension is guaranteed
+// active on the very first window.
+const CODE_SERVER_INSTALL_EXT_BLOCKING =
+	`( ls -d ~/.local/share/code-server/extensions/${CLAUDE_CODE_EXTENSION_ID}-* >/dev/null 2>&1 || ` +
+	`code-server --install-extension ${CLAUDE_CODE_EXTENSION_ID} ) ` +
+	`>/tmp/code-server-ext.log 2>&1; `;
+
+// By default the extension installs in the background after launch (the first window may need a
+// reload to activate it; the claude-code-ide-extension injection waits out this install as the fallback).
+function codeServerLaunch(blockingExtInstall: boolean): string {
+	return (
+		`bash -c "${CODE_SERVER_APPLY_SETTINGS} ` +
+		(blockingExtInstall ? CODE_SERVER_INSTALL_EXT_BLOCKING : '') +
+		// The bare default image may not export SHELL, which the Terminal task needs.
+		`export SHELL=\\"\${SHELL:-/bin/bash}\\"; ` +
+		// Probes the port rather than the process list: every `pgrep -f` pattern that matches a
+		// code-server daemon also matches this very shell (its own argv carries the nohup line
+		// below), so a cmdline guard would skip the launch every time. Bracketing can't escape it
+		// either — the payload text itself matches.
+		`(exec 3<>/dev/tcp/127.0.0.1/${CODE_SERVER_PORT}) 2>/dev/null || ` +
+		`nohup code-server --bind-addr 0.0.0.0:${CODE_SERVER_PORT} --auth none ` +
+		`--disable-workspace-trust \\"$PWD\\" >/tmp/code-server.log 2>&1 &` +
+		(blockingExtInstall ? '' : ` ${CODE_SERVER_INSTALL_EXT}`) +
+		`"`
+	);
+}
 
 /** Staged next to the config; ttyd runs it as its command so the nested quoting stays in a real file. */
 const TTYD_LAUNCH_SCRIPT_FILE = 'codebay-terminal.sh';
@@ -216,7 +261,7 @@ export const TTYD_SHELL_ARG = 'shell';
  * compare and never an eval. The shell branch sits above the injections wait so the split view's
  * scratch shell opens immediately instead of blocking on Claude's boot sentinel.
  */
-const TTYD_LAUNCH_SCRIPT =
+const ttydLaunchScript = (permissionMode: ClaudePermissionMode): string =>
 	'#!/usr/bin/env bash\n' +
 	'export SHELL="${SHELL:-/bin/bash}"\n' +
 	`if [ "$1" = "${TTYD_SHELL_ARG}" ]; then\n` +
@@ -228,9 +273,11 @@ const TTYD_LAUNCH_SCRIPT =
 	WAIT_FOR_INJECTIONS +
 	'\n' +
 	`if command -v tmux >/dev/null 2>&1; then\n` +
-	`  exec tmux new-session -A -s ${TMUX_SESSION} 'claude --dangerously-skip-permissions; exec "$SHELL" -l'\n` +
+	`  exec tmux new-session -A -s ${TMUX_SESSION} '${SOURCE_INJECTED_ENV}claude ${claudePermissionFlags(permissionMode)}; exec "$SHELL" -l'\n` +
 	'fi\n' +
-	'claude --dangerously-skip-permissions\n' +
+	SOURCE_INJECTED_ENV +
+	'\n' +
+	`claude ${claudePermissionFlags(permissionMode)}\n` +
 	'exec "$SHELL" -l\n';
 
 // ttyd defaults to read-only, so --writable is required for keyboard input. Guarded by `pgrep -x`
@@ -246,6 +293,16 @@ const TTYD_LAUNCH =
 	`nohup ttyd --port ${TTYD_PORT} --writable --url-arg ` +
 	`bash \\"$PWD/.devcontainer/${TTYD_LAUNCH_SCRIPT_FILE}\\" >/tmp/ttyd.log 2>&1 &"`;
 
+/**
+ * The launcher `postStartCommand` runs, exposed so a host-side relaunch can reuse the exact
+ * string rather than growing a second, driftable copy of "how the served surface is started".
+ */
+export function launchCommandFor(mode: InstanceMode): string {
+	return mode === 'terminal'
+		? TTYD_LAUNCH
+		: codeServerLaunch(getOption('advanced_blocking_ext_install') === '1');
+}
+
 export async function devcontainerCliAvailable(): Promise<boolean> {
 	return (await spawnCapture([devcontainerBin(), '--version'])) !== null;
 }
@@ -357,6 +414,7 @@ type DevcontainerConfig = {
 	forwardPorts?: (number | string)[];
 	postStartCommand?: unknown;
 	runArgs?: string[];
+	containerEnv?: Record<string, string>;
 	[key: string]: unknown;
 };
 
@@ -410,7 +468,9 @@ export async function writeOverrideConfig(
 	hostPort: number,
 	forwards: PortForward[] = [],
 	defaultImage: string = DEFAULT_IMAGE,
-	mode: InstanceMode = 'ide'
+	mode: InstanceMode = 'ide',
+	permissionMode: ClaudePermissionMode = 'default',
+	envVars: { name: string; value: string }[] = []
 ): Promise<{ imageSource: string }> {
 	const isTerminal = mode === 'terminal';
 	const target = configPath(workspaceDir);
@@ -474,26 +534,35 @@ export async function writeOverrideConfig(
 	runArgs.add(HOST_GATEWAY_ARG);
 	config.runArgs = [...runArgs];
 
-	const launch = isTerminal ? TTYD_LAUNCH : CODE_SERVER_LAUNCH;
+	const launch = launchCommandFor(mode);
 	const existing = config.postStartCommand;
 	config.postStartCommand =
 		typeof existing === 'string' && existing.trim() ? `${existing} && ${launch}` : launch;
 
+	// Baked onto the container at creation, so every process inherits it (broader than remoteEnv).
+	// The user's configured names win; a project's own containerEnv keys are otherwise preserved.
+	if (envVars.length) {
+		config.containerEnv = {
+			...(config.containerEnv ?? {}),
+			...Object.fromEntries(envVars.map((v) => [v.name, v.value]))
+		};
+	}
+
 	await mkdir(join(workspaceDir, '.devcontainer'), { recursive: true }).catch(() => {});
 	await writeFile(target, JSON.stringify(config, null, 2) + '\n', 'utf8');
 
 	if (isTerminal) {
 		await writeTtydFeature(workspaceDir);
-		await writeTerminalLaunchScript(workspaceDir);
+		await writeTerminalLaunchScript(workspaceDir, permissionMode);
 	} else {
-		// Staged next to the config; CODE_SERVER_LAUNCH copies it into the user-data dir on first start.
+		// Staged next to the config; codeServerLaunch copies it into the user-data dir on first start.
 		await writeFile(
 			join(workspaceDir, '.devcontainer', CODE_SERVER_SETTINGS_FILE),
 			JSON.stringify(CODE_SERVER_SETTINGS, null, 2) + '\n',
 			'utf8'
 		);
 		// The VS Code Terminal task is code-server-only; ttyd runs its own launcher script instead.
-		await writeTerminalTask(workspaceDir);
+		await writeTerminalTask(workspaceDir, permissionMode);
 	}
 
 	await writeTmuxFeature(workspaceDir);
@@ -616,14 +685,20 @@ async function writeTtydFeature(workspaceDir: string): Promise<void> {
 }
 
 /** Staged next to the config; TTYD_LAUNCH runs it as ttyd's command. */
-async function writeTerminalLaunchScript(workspaceDir: string): Promise<void> {
+async function writeTerminalLaunchScript(
+	workspaceDir: string,
+	permissionMode: ClaudePermissionMode
+): Promise<void> {
 	const path = join(workspaceDir, '.devcontainer', TTYD_LAUNCH_SCRIPT_FILE);
-	await writeFile(path, TTYD_LAUNCH_SCRIPT, 'utf8');
+	await writeFile(path, ttydLaunchScript(permissionMode), 'utf8');
 	await chmod(path, 0o755);
 }
 
 /** Replaces the managed task rather than skipping it, so a rebuild picks up command changes. */
-async function writeTerminalTask(workspaceDir: string): Promise<void> {
+async function writeTerminalTask(
+	workspaceDir: string,
+	permissionMode: ClaudePermissionMode
+): Promise<void> {
 	const tasksPath = join(workspaceDir, '.vscode', 'tasks.json');
 	let config: { version?: string; tasks?: unknown[] } = {};
 
@@ -641,9 +716,9 @@ async function writeTerminalTask(workspaceDir: string): Promise<void> {
 	const isManagedTask = (t: unknown) =>
 		typeof t === 'object' &&
 		t !== null &&
-		(t as Record<string, unknown>).label === TERMINAL_TASK.label &&
+		(t as Record<string, unknown>).label === TERMINAL_TASK_LABEL &&
 		((t as Record<string, { runOn?: string }>).runOptions?.runOn ?? '') === 'folderOpen';
-	config.tasks = [...tasks.filter((t) => !isManagedTask(t)), TERMINAL_TASK];
+	config.tasks = [...tasks.filter((t) => !isManagedTask(t)), terminalTask(permissionMode)];
 
 	await mkdir(join(workspaceDir, '.vscode'), { recursive: true }).catch(() => {});
 	await writeFile(tasksPath, JSON.stringify(config, null, 2) + '\n', 'utf8');
@@ -658,12 +733,7 @@ export interface UpResult {
 	description?: string;
 }
 
-/** Streams all output to `onLog` and returns the parsed final result line. */
-export async function devcontainerUp(
-	workspaceDir: string,
-	onLog: (chunk: string) => void,
-	opts: { noCache?: boolean } = {}
-): Promise<UpResult> {
+export function devcontainerUpArgs(workspaceDir: string, opts: { noCache?: boolean } = {}) {
 	const args = [
 		devcontainerBin(),
 		'up',
@@ -673,11 +743,28 @@ export async function devcontainerUp(
 	];
 	// Only takes effect because --remove-existing-container drops the container before the build.
 	if (opts.noCache) args.push('--build-no-cache');
-	const proc = Bun.spawn(args, {
+	return args;
+}
+
+/** Defaults only — the spread lets an explicit user env win. BuildKit is standard on modern
+ * daemons; forcing it here just keeps feature-layer caching on older ones. */
+export function devcontainerUpEnv(): Record<string, string | undefined> {
+	// Escape hatch for daemons where forcing BuildKit breaks builds (old builders, classic compose).
+	if (getOption('advanced_no_buildkit') === '1') return dockerEnv();
+	return { DOCKER_BUILDKIT: '1', COMPOSE_DOCKER_CLI_BUILD: '1', ...dockerEnv() };
+}
+
+/** Streams all output to `onLog` and returns the parsed final result line. */
+export async function devcontainerUp(
+	workspaceDir: string,
+	onLog: (chunk: string) => void,
+	opts: { noCache?: boolean } = {}
+): Promise<UpResult> {
+	const proc = Bun.spawn(devcontainerUpArgs(workspaceDir, opts), {
 		cwd: workspaceDir,
 		stdout: 'pipe',
 		stderr: 'pipe',
-		env: dockerEnv()
+		env: devcontainerUpEnv()
 	});
 
 	let stdoutText = '';

package/src/lib/health.server.ts

@@ -1,21 +1,26 @@
 import { type InstanceRow } from './db.server.ts';
 import { isRunning, publishedContainerPorts } from './docker.server.ts';
-import { broadcastHealth } from './instances.server.ts';
+import { broadcastHealth, relaunchSurface } from './instances.server.ts';
 import { resolveInjections } from './injections.server.ts';
 import type { InstanceHealth } from '../types.ts';
 
 const REFRESH_MS = 5000;
+const FAST_REFRESH_MS = 1000;
+const FAST_WINDOW_MS = 120_000;
 
 interface Monitor {
 	snapshot: InstanceHealth | null;
-	timer: ReturnType<typeof setInterval>;
+	timer: ReturnType<typeof setTimeout>;
+	startedAt: number;
+	everAccessible: boolean;
 }
 
 // Pin to globalThis so dev-mode hot reload doesn't orphan the interval timers.
 const globalForHealth = globalThis as unknown as { __codebayHealth?: Map<string, Monitor> };
 const monitors: Map<string, Monitor> = (globalForHealth.__codebayHealth ??= new Map());
 
-async function codeServerAccessible(port: number): Promise<boolean> {
+/** Named for what it measures — the served surface is ttyd in terminal mode, code-server in IDE. */
+export async function surfaceAccessible(port: number): Promise<boolean> {
 	try {
 		// Any HTTP response at all (200/302/401/…) means the server is listening.
 		await fetch(`http://127.0.0.1:${port}/`, { signal: AbortSignal.timeout(2000) });
@@ -38,7 +43,7 @@ async function check(row: InstanceRow): Promise<InstanceHealth> {
 	// Probes as the recorded remote user, so `$HOME` resolves to the one the injection wrote to.
 	const target = { containerId: row.container_id, remoteUser: row.remote_user, instance: row };
 	const [accessible, openPorts, injectionResults] = await Promise.all([
-		codeServerAccessible(row.host_port),
+		surfaceAccessible(row.host_port),
 		publishedContainerPorts(row.container_id),
 		Promise.all(
 			resolveInjections(row.mode)
@@ -59,27 +64,66 @@ async function check(row: InstanceRow): Promise<InstanceHealth> {
 	};
 }
 
-async function tick(row: InstanceRow): Promise<void> {
+/** Probes at 1s until code-server first answers, so the IDE iframe can mount without waiting out
+ * the 5s cadence; the window cap keeps a permanently-dead code-server off the fast path. */
+export function nextProbeDelay(
+	health: InstanceHealth,
+	everAccessible: boolean,
+	elapsedMs: number
+): number {
+	const waitingForFirstResponse =
+		health.containerRunning && !health.codeServerAccessible && !everAccessible;
+	return waitingForFirstResponse && elapsedMs < FAST_WINDOW_MS ? FAST_REFRESH_MS : REFRESH_MS;
+}
+
+async function tick(row: InstanceRow, mon: Monitor): Promise<void> {
 	const snapshot = await check(row);
-	const mon = monitors.get(row.id);
-	if (mon) mon.snapshot = snapshot;
 	broadcastHealth(row.id, snapshot);
-	if (!snapshot.containerRunning) stopHealthMonitor(row.id);
+	// Replaced or stopped while the probe was in flight — rescheduling would leak a second chain.
+	if (monitors.get(row.id) !== mon) return;
+	if (!snapshot.containerRunning) {
+		stopHealthMonitor(row.id);
+		return;
+	}
+	mon.snapshot = snapshot;
+	mon.everAccessible ||= snapshot.codeServerAccessible;
+	const delay = nextProbeDelay(snapshot, mon.everAccessible, Date.now() - mon.startedAt);
+	mon.timer = setTimeout(() => void tick(row, mon), delay);
 }
 
 function startHealthMonitor(row: InstanceRow): Monitor {
 	const existing = monitors.get(row.id);
 	if (existing) return existing;
-	const mon: Monitor = { snapshot: null, timer: setInterval(() => void tick(row), REFRESH_MS) };
+	const mon: Monitor = {
+		snapshot: null,
+		// Placeholder until the seed tick completes; it self-reschedules from then on.
+		timer: setTimeout(() => undefined, 0),
+		startedAt: Date.now(),
+		everAccessible: false
+	};
 	monitors.set(row.id, mon);
-	void tick(row); // seed the first snapshot rather than making the UI wait a full interval
+	// Seed a snapshot rather than making the UI wait a full interval (the tick self-reschedules
+	// the fast/slow probe chain from here), then use the seed to decide whether to relaunch.
+	void tick(row, mon).then(async () => {
+		if (monitors.get(row.id) !== mon) return;
+		const seeded = mon.snapshot;
+		if (!seeded?.containerRunning || seeded.codeServerAccessible) return;
+		// A live container with a dead port means postStartCommand never re-ran — it only fires
+		// under `devcontainer up`. Covers starts codebay didn't perform (a daemon restart, a bare
+		// `docker start`); once per monitor, so a genuinely wedged container isn't exec'd in a loop.
+		await relaunchSurface(row).catch(() => undefined);
+		if (monitors.get(row.id) !== mon) return;
+		// Drop the seed tick's already-scheduled probe and re-probe now, so a single chain survives.
+		clearTimeout(mon.timer);
+		void tick(row, mon);
+	});
 	return mon;
 }
 
 export function stopHealthMonitor(id: string): void {
 	const mon = monitors.get(id);
 	if (!mon) return;
-	clearInterval(mon.timer);
+	clearTimeout(mon.timer);
 	monitors.delete(id);
 }
 

package/src/lib/injections.server.ts

@@ -15,11 +15,13 @@ import { githubCredentials } from '../container-injections/github-credentials.ts
 import { attentionHooks } from '../container-injections/attention-hooks.ts';
 import { claudeStatusline } from '../container-injections/claude-statusline.ts';
 import { claudeModel } from '../container-injections/claude-model.ts';
-import { claudeSkipPermissions } from '../container-injections/claude-skip-permissions.ts';
+import { claudeEffortLevel } from '../container-injections/claude-effort-level.ts';
+import { claudePermissionMode } from '../container-injections/claude-permission-mode.ts';
 import { claudeTrust } from '../container-injections/claude-trust.ts';
 import { claudeAliases } from '../container-injections/claude-aliases.ts';
 import { claudeNoCoauthor } from '../container-injections/claude-no-coauthor.ts';
 import { hostEnvVars } from '../container-injections/host-env-vars.ts';
+import { customEnvVars } from '../container-injections/custom-env-vars.ts';
 
 /** Extends `ExecTarget` so exec-user semantics have a single source of truth. */
 export interface ContainerTarget extends ExecTarget {
@@ -47,51 +49,56 @@ export interface Injection {
 	check?(target: ContainerTarget): Promise<boolean>;
 }
 
-/** Split around the Claude slot, which `resolveInjections()` fills at call time. */
-const BASE_INJECTIONS_HEAD: Injection[] = [
-	// Must stay first — every later git-touching injection depends on safe.directory.
-	gitSafeDirectory,
-	// The package install is the slowest injection, so start it before a folderOpen can find tmux missing.
-	tmux,
-	// Terminal-mode only (filtered by resolveInjections); a download, so run it early like tmux.
-	ttyd,
-	// Terminal-mode only, and ahead of every claude-* step in the tail, which all assume a binary.
-	claudeCodeInstall,
-	gitIdentity
-];
-
-const BASE_INJECTIONS_TAIL: Injection[] = [
-	// Refresh the binary to latest before the other claude-config steps run against it.
-	claudeCodeUpdate,
-	// Self-skips unless manual override is on and LiteLLM off, so it's safe in the always-run tail.
-	claudeCodeModels,
-	claudeCodeIdeExtension,
-	githubCredentials,
-	attentionHooks,
-	claudeStatusline,
-	claudeModel,
-	claudeSkipPermissions,
-	claudeTrust,
-	claudeAliases,
-	claudeNoCoauthor,
-	hostEnvVars
-];
+/**
+ * Injections within a stage apply in parallel, so no two of them may write the same container
+ * resource; the stage boundaries serialize each shared resource in the same relative order the
+ * old flat list ran it (gitconfig, ~/.claude/settings.json, rc files, ~/.claude.json, apt/dpkg).
+ */
+function buildStages(claudeInjection: Injection): Injection[][] {
+	return [
+		// Disjoint resources — and the slow network installs (apt tmux, npm/standalone claude,
+		// Open VSX extension) start immediately instead of queueing behind one another.
+		// claude-code-install (terminal-only) must precede claude-code-update: both are the sole
+		// npm-global writer of their stage, and the update no-ops until a binary exists.
+		[
+			gitSafeDirectory,
+			tmux,
+			claudeCodeInstall,
+			claudeInjection,
+			claudeCodeIdeExtension,
+			claudeEffortLevel
+		],
+		// git-identity needs stage 1's safe.directory; ttyd shares the apt/dpkg lock with tmux and
+		// the /usr/local/bin symlink with claude-code-install, so it trails both.
+		[gitIdentity, attentionHooks, claudeCodeModels, ttyd, claudeCodeUpdate],
+		[githubCredentials, claudeStatusline, claudePermissionMode],
+		[claudeModel, claudeAliases],
+		// claude-trust edits ~/.claude.json, which the stage-1 Claude slot also writes.
+		// custom-env-vars writes nothing (values ride containerEnv) — it only verifies + health-checks.
+		[claudeTrust, hostEnvVars, customEnvVars],
+		[claudeNoCoauthor]
+	];
+}
 
 /**
  * Resolved per call so toggling the custom-endpoint setting takes effect without a restart.
  * `mode` drops injections that don't apply to it (e.g. ttyd off IDE instances, the IDE
  * extension off terminal ones); omit it in mode-agnostic contexts to keep every injection.
  */
-export function resolveInjections(mode?: InstanceMode): Injection[] {
+export function resolveInjectionStages(mode?: InstanceMode): Injection[][] {
 	const claudeInjection =
 		getOption('custom_endpoint_enabled') === '1' ? claudeCodeCustom : claudeCodeCredentials;
-	const all = [...BASE_INJECTIONS_HEAD, claudeInjection, ...BASE_INJECTIONS_TAIL];
-	return mode ? all.filter((i) => !i.modes || i.modes.includes(mode)) : all;
+	const stages = buildStages(claudeInjection)
+		.map((stage) => (mode ? stage.filter((i) => !i.modes || i.modes.includes(mode)) : stage))
+		.filter((stage) => stage.length > 0);
+	// One injection per stage restores the fully serial boot for diagnosing injection interference.
+	return getOption('advanced_serial_injections') === '1' ? stages.flat().map((i) => [i]) : stages;
+}
+
+/** Flat view of `resolveInjectionStages()` for order-insensitive consumers (health, auth chips). */
+export function resolveInjections(mode?: InstanceMode): Injection[] {
+	return resolveInjectionStages(mode).flat();
 }
 
 /** @deprecated Use `resolveInjections()`; this ignores settings/mode and is kept for the tests. */
-export const injections: Injection[] = [
-	...BASE_INJECTIONS_HEAD,
-	claudeCodeCredentials,
-	...BASE_INJECTIONS_TAIL
-];
+export const injections: Injection[] = buildStages(claudeCodeCredentials).flat();