codebay 0.13.0 → 0.15.0

package/src/lib/auth.server.ts

@@ -1,6 +1,7 @@
 import type { Handle } from 'mochi-framework';
 import { BASIC_AUTH_PASSWORD, BASIC_AUTH_USERNAME } from './config.server.ts';
 import { timingSafeEqualStr } from './crypto.server.ts';
+import { MCP_PATH } from './mcp-auth.server.ts';
 
 const REALM = 'Codebay';
 
@@ -37,6 +38,15 @@ function wsOriginOk(request: Request): boolean {
 	}
 }
 
+/**
+ * Paths that authenticate with their own token instead of the app password: exempt from Basic
+ * Auth and the CSRF check (their clients can't carry either), and from the request log, since
+ * every hit carries that token.
+ */
+export function tokenAuthenticated(pathname: string): boolean {
+	return pathname.startsWith('/api/bridge/') || pathname === MCP_PATH;
+}
+
 /** `Mochi.ws` routes are dispatched by Bun directly and never reach `basicAuth`. */
 export function wsUpgradeAllowed(request: Request): boolean {
 	if (!wsOriginOk(request)) return false;
@@ -69,8 +79,7 @@ function credentialsOk(header: string | null): boolean {
 export const basicAuth: Handle = async ({ event, resolve }) => {
 	const path = new URL(event.request.url).pathname;
 
-	// Containers can carry neither the app password nor the CSRF header; the route checks a token.
-	if (path.startsWith('/api/bridge/')) return resolve(event);
+	if (tokenAuthenticated(path)) return resolve(event);
 
 	// Covers the `/p/:id/*` proxy relay only; `Mochi.ws` routes call `wsUpgradeAllowed` themselves.
 	if (

package/src/lib/build-freshness.server.ts

@@ -0,0 +1,71 @@
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+
+interface BuildManifest {
+	components?: Record<string, { hydratables?: { resolvedPath?: string }[] }>;
+	stats?: { outputs?: { inputs?: { path?: string }[] }[] };
+}
+
+/** Every project file the build consumed: pages, islands, and each client bundle's inputs. */
+function buildInputs(manifest: BuildManifest): string[] {
+	const paths = new Set<string>();
+	for (const [source, component] of Object.entries(manifest.components ?? {})) {
+		paths.add(source);
+		for (const island of component.hydratables ?? []) {
+			if (island.resolvedPath) paths.add(island.resolvedPath);
+		}
+	}
+	for (const output of manifest.stats?.outputs ?? []) {
+		for (const input of output.inputs ?? []) {
+			if (input.path) paths.add(input.path);
+		}
+	}
+	// Dependencies, Mochi's own templates, and virtual modules are not things anyone edits in place.
+	return [...paths].filter(
+		(p) => !p.startsWith('node_modules/') && !p.startsWith('$mochi/') && !p.includes(':')
+	);
+}
+
+/**
+ * Build inputs edited since the manifest was written, relative to `root`. Only files the manifest
+ * itself names count, so editing a `.server.ts` (imported from source at boot) never trips it.
+ */
+export function staleBuildInputs(
+	root: string,
+	manifestPath = join(root, '.mochi', 'manifest.json')
+): string[] {
+	if (!existsSync(manifestPath)) return [];
+	const builtAt = statSync(manifestPath).mtimeMs;
+	let manifest: BuildManifest;
+	try {
+		manifest = JSON.parse(readFileSync(manifestPath, 'utf8')) as BuildManifest;
+	} catch (err) {
+		// A truncated manifest is Mochi's problem to report at serve time; an advisory check must not be what crashes boot.
+		console.warn(
+			`⚠ could not read ${manifestPath} for the build-freshness check: ${(err as Error).message}`
+		);
+		return [];
+	}
+	return buildInputs(manifest)
+		.filter((p) => {
+			const abs = join(root, p);
+			return existsSync(abs) && statSync(abs).mtimeMs > builtAt;
+		})
+		.sort();
+}
+
+/**
+ * Production serves pages and islands from the prebuilt manifest but imports routes from source,
+ * so restarting after a `.svelte` edit without `bun run build` splits the app: new API, old client.
+ * Gated on a checkout because a package install stamps every file with its extraction time.
+ */
+export function warnIfBuildStale(root = process.cwd()): void {
+	if (process.env.MODE === 'development' || !existsSync(join(root, '.git'))) return;
+	const stale = staleBuildInputs(root);
+	if (stale.length === 0) return;
+	const listed = stale.slice(0, 5).join(', ') + (stale.length > 5 ? ', …' : '');
+	console.warn(
+		`⚠ .mochi/ is older than ${stale.length} source file(s) it was built from (${listed}) — ` +
+			'production serves the prebuilt bundle, so run `bun run build` and restart, or pages and islands will be stale.'
+	);
+}

package/src/lib/config.server.ts

@@ -128,19 +128,42 @@ export function dockerEnv(): Record<string, string | undefined> {
 }
 
 /**
- * Resolved from our own dependency tree, not cwd, because under `bunx codebay`
+ * Windows picks an executable by PATHEXT, which `existsSync` doesn't apply — so each shim has
+ * to be probed by full name. The bare name is deliberately not a win32 candidate: npm writes a
+ * POSIX sh script there, which Bun can't exec. Bun's `.bunx` sibling is a data file and is never
+ * a candidate on any platform — spawning it throws EFTYPE.
+ */
+const BIN_SHIM_EXTS = process.platform === 'win32' ? ['.exe', '.cmd'] : [''];
+
+/** Null when no spawnable shim exists, so a caller can fall back instead of spawning a missing file. */
+export function binShim(binDir: string, name: string): string | null {
+	for (const ext of BIN_SHIM_EXTS) {
+		const candidate = join(binDir, name + ext);
+		if (existsSync(candidate)) return candidate;
+	}
+	return null;
+}
+
+/**
+ * An argv rather than a path, because the `devcontainer.js` fallback leads with a
+ * `#!/usr/bin/env node` shebang that Windows doesn't honour — there it only runs when handed to
+ * an interpreter. Resolved from our own dependency tree, not cwd, because under `bunx codebay`
  * cwd is the user's arbitrary folder.
  */
-export function devcontainerBin(): string {
+export function devcontainerBin(): string[] {
 	try {
 		const pkgJson = fileURLToPath(import.meta.resolve('@devcontainers/cli/package.json'));
-		const shim = join(dirname(pkgJson), '..', '..', '.bin', 'devcontainer');
-		if (existsSync(shim)) return shim;
+		const shim = binShim(join(dirname(pkgJson), '..', '..', '.bin'), 'devcontainer');
+		if (shim) return [shim];
 		const pkg = JSON.parse(readFileSync(pkgJson, 'utf8'));
 		const rel = typeof pkg.bin === 'string' ? pkg.bin : pkg.bin?.devcontainer;
-		if (rel) return join(dirname(pkgJson), rel);
+		if (rel) {
+			const js = join(dirname(pkgJson), rel);
+			return process.platform === 'win32' ? [process.execPath, js] : [js];
+		}
 	} catch {
 		// Fall through to the dev-checkout path below.
 	}
-	return join(process.cwd(), 'node_modules', '.bin', 'devcontainer');
+	const dir = join(process.cwd(), 'node_modules', '.bin');
+	return [binShim(dir, 'devcontainer') ?? join(dir, 'devcontainer')];
 }

package/src/lib/container-files.server.ts

@@ -13,7 +13,7 @@ export interface ContainerFile {
 }
 
 /** Resolves the exec user's home the same way every injection historically has. */
-const HOME_PRELUDE = 'h=$(eval echo ~$(id -un)); ';
+export const HOME_PRELUDE = 'h=$(eval echo ~$(id -un)); ';
 
 const filePath = (file: ContainerFile): string => `${file.dir ?? '$h'}/${file.name}`;
 
@@ -54,6 +54,15 @@ export function writeFileScript(file: ContainerFile): string {
 	);
 }
 
+/** Like `writeFileScript`, but the stdin payload is base64 so binary bytes survive the env-var carrier. */
+export function writeBase64FileScript(file: ContainerFile): string {
+	const mode = file.mode ?? '644';
+	return (
+		`set -e; ${HOME_PRELUDE}f="${filePath(file)}"; mkdir -p "$(dirname "$f")"; ` +
+		`printf '%s' "$CODEBAY_STDIN" | base64 -d > "$f"; chmod ${mode} "$f"`
+	);
+}
+
 /** Single-quotes a value for a sourced shell file so whatever it contains stays literal. */
 export const shellSingleQuote = (value: string): string => `'${value.replaceAll("'", "'\\''")}'`;
 
@@ -98,6 +107,19 @@ export async function writeContainerFile(
 	return res.ok ? { ok: true } : { ok: false, error: res.error };
 }
 
+/** Writes raw `bytes` to a container file, ferrying them as base64 so binary content stays intact. */
+export async function writeContainerFileBytes(
+	target: ExecTarget,
+	file: ContainerFile,
+	bytes: Buffer
+): Promise<{ ok: boolean; error?: string }> {
+	const res = await execInContainer(target, {
+		script: writeBase64FileScript(file),
+		stdin: bytes.toString('base64')
+	});
+	return res.ok ? { ok: true } : { ok: false, error: res.error };
+}
+
 /** Appends each line to every file it's missing from — the shared idempotent rc/conf write. */
 export async function appendLinesIfAbsent(
 	target: ExecTarget,

package/src/lib/data-dir-lock.server.ts

@@ -0,0 +1,78 @@
+import { mkdirSync, readFileSync, statSync, unlinkSync, utimesSync, writeFileSync } from 'node:fs';
+import { hostname } from 'node:os';
+import { join } from 'node:path';
+
+/** How often a live manager refreshes the lock, and how long a silent one keeps it. */
+export const LOCK_HEARTBEAT_MS = 5_000;
+export const LOCK_STALE_MS = 30_000;
+
+export const LOCK_FILE = 'manager.lock';
+
+export interface LockHolder {
+	pid: number;
+	host: string;
+	startedAt: number;
+}
+
+export type LockResult =
+	{ ok: true; release: () => void } | { ok: false; holder: LockHolder | null; path: string };
+
+// Pinned so a dev-mode re-evaluation of the entry module re-uses the heartbeat instead of stacking one.
+const globalForLock = globalThis as unknown as { __codebayDataDirLock?: LockResult };
+
+/**
+ * One manager per DATA_DIR. Two of them share the DB and both poll every run, so each folds only
+ * the stream chunks it fetched itself and whichever sees the exit file finishes the row from a
+ * partial state. Liveness is the file's mtime under a heartbeat rather than a pid check: pids
+ * don't cross a container boundary and get reused after a reboot, but a stale file just ages out.
+ */
+export function acquireDataDirLock(dir: string, now = Date.now()): LockResult {
+	if (globalForLock.__codebayDataDirLock?.ok) return globalForLock.__codebayDataDirLock;
+	const path = join(dir, LOCK_FILE);
+	const existing = readLock(path);
+	if (existing && now - existing.mtimeMs < LOCK_STALE_MS && existing.holder?.pid !== process.pid) {
+		return { ok: false, holder: existing.holder, path };
+	}
+	mkdirSync(dir, { recursive: true });
+	const holder: LockHolder = { pid: process.pid, host: hostname(), startedAt: now };
+	writeFileSync(path, JSON.stringify(holder) + '\n');
+	const timer = setInterval(() => {
+		try {
+			const at = new Date();
+			utimesSync(path, at, at);
+		} catch {
+			// The data dir went away underneath us; there is nothing left to keep alive.
+		}
+	}, LOCK_HEARTBEAT_MS);
+	// A heartbeat must never be the reason the process stays up.
+	timer.unref?.();
+	const result: LockResult = {
+		ok: true,
+		release: () => {
+			clearInterval(timer);
+			globalForLock.__codebayDataDirLock = undefined;
+			try {
+				if (readLock(path)?.holder?.pid === process.pid) unlinkSync(path);
+			} catch {
+				// Already gone, or not ours any more.
+			}
+		}
+	};
+	globalForLock.__codebayDataDirLock = result;
+	return result;
+}
+
+function readLock(path: string): { holder: LockHolder | null; mtimeMs: number } | null {
+	try {
+		const mtimeMs = statSync(path).mtimeMs;
+		let holder: LockHolder | null = null;
+		try {
+			holder = JSON.parse(readFileSync(path, 'utf8')) as LockHolder;
+		} catch {
+			// Garbage in the file still counts as a lock while it is fresh.
+		}
+		return { holder, mtimeMs };
+	} catch {
+		return null;
+	}
+}

package/src/lib/db.server.ts

@@ -3,7 +3,7 @@ import { migrate, getMigrations } from '@zihaolam/bun-sqlite-migrations';
 import { mkdirSync } from 'node:fs';
 import { join } from 'node:path';
 import { DATA_DIR, DB_PATH } from './config.server.ts';
-import type { FolderHistoryEntry } from '../types.ts';
+import type { AgentRunStatus, FolderHistoryEntry } from '../types.ts';
 
 // db.server.ts lives in src/lib, so ../../migrations resolves to the repo root.
 const MIGRATIONS_DIR = join(import.meta.dir, '../../migrations');
@@ -213,3 +213,122 @@ export function setOption(key: string, value: string): void {
      ON CONFLICT(key) DO UPDATE SET value = excluded.value`
 	).run({ $key: key, $value: value });
 }
+
+/** One `claude -p` invocation inside an instance, driven by the MCP server. */
+export interface AgentRunRow {
+	id: string;
+	instance_id: string;
+	prompt: string;
+	status: AgentRunStatus;
+	/** Claude's own session id, parsed out of the stream's `init` event; resumable. */
+	session_id: string | null;
+	/** The model Claude actually ran with, from the stream `init` event; the requested alias lives in `options`. */
+	model: string | null;
+	resume_session_id: string | null;
+	/** JSON blob of the launch options, so a run queued before its container existed can still start. */
+	options: string | null;
+	result: string | null;
+	/** JSON string, only when the caller passed a `--json-schema`. */
+	structured_output: string | null;
+	/** Latest tool call or assistant line, so a poller can see progress mid-run. */
+	last_activity: string | null;
+	is_error: number;
+	exit_code: number | null;
+	cost_usd: number | null;
+	duration_ms: number | null;
+	num_turns: number | null;
+	error: string | null;
+	created_at: number;
+	started_at: number | null;
+	finished_at: number | null;
+}
+
+/** Neither has finished, so both block a second run on the same instance. */
+const OPEN_RUN_STATUSES = "('queued', 'running')";
+
+export function insertRun(row: AgentRunRow): void {
+	db.query(
+		`INSERT INTO agent_runs
+       (id, instance_id, prompt, status, session_id, model, resume_session_id, options, result, structured_output, last_activity, is_error, exit_code, cost_usd, duration_ms, num_turns, error, created_at, started_at, finished_at)
+     VALUES ($id, $instance_id, $prompt, $status, $session_id, $model, $resume_session_id, $options, $result, $structured_output, $last_activity, $is_error, $exit_code, $cost_usd, $duration_ms, $num_turns, $error, $created_at, $started_at, $finished_at)`
+	).run({
+		$id: row.id,
+		$instance_id: row.instance_id,
+		$prompt: row.prompt,
+		$status: row.status,
+		$session_id: row.session_id,
+		$model: row.model,
+		$resume_session_id: row.resume_session_id,
+		$options: row.options,
+		$result: row.result,
+		$structured_output: row.structured_output,
+		$last_activity: row.last_activity,
+		$is_error: row.is_error,
+		$exit_code: row.exit_code,
+		$cost_usd: row.cost_usd,
+		$duration_ms: row.duration_ms,
+		$num_turns: row.num_turns,
+		$error: row.error,
+		$created_at: row.created_at,
+		$started_at: row.started_at,
+		$finished_at: row.finished_at
+	});
+}
+
+export function getRun(id: string): AgentRunRow | null {
+	return db.query('SELECT * FROM agent_runs WHERE id = $id').get({ $id: id }) as AgentRunRow | null;
+}
+
+export function listRuns(instanceId: string, limit = 50): AgentRunRow[] {
+	return db
+		.query('SELECT * FROM agent_runs WHERE instance_id = $id ORDER BY created_at DESC LIMIT $limit')
+		.all({ $id: instanceId, $limit: limit }) as AgentRunRow[];
+}
+
+/** Every unfinished run, across all instances — what the poller's timer works from. */
+export function openRuns(): AgentRunRow[] {
+	return db
+		.query(`SELECT * FROM agent_runs WHERE status IN ${OPEN_RUN_STATUSES} ORDER BY created_at`)
+		.all() as AgentRunRow[];
+}
+
+export function openRunFor(instanceId: string): AgentRunRow | null {
+	return db
+		.query(
+			`SELECT * FROM agent_runs WHERE instance_id = $id AND status IN ${OPEN_RUN_STATUSES} ORDER BY created_at LIMIT 1`
+		)
+		.get({ $id: instanceId }) as AgentRunRow | null;
+}
+
+/** The same allowlist discipline `updateInstance` uses — never interpolate a caller's column name. */
+const UPDATABLE_RUN_COLUMNS = [
+	'status',
+	'session_id',
+	'model',
+	'result',
+	'structured_output',
+	'last_activity',
+	'is_error',
+	'exit_code',
+	'cost_usd',
+	'duration_ms',
+	'num_turns',
+	'error',
+	'started_at',
+	'finished_at'
+] as const;
+
+type UpdatableRunColumn = (typeof UPDATABLE_RUN_COLUMNS)[number];
+
+export function updateRun(id: string, patch: Partial<Pick<AgentRunRow, UpdatableRunColumn>>): void {
+	const sets: string[] = [];
+	const params: Record<string, string | number | null> = { $id: id };
+	for (const col of UPDATABLE_RUN_COLUMNS) {
+		if (col in patch) {
+			sets.push(`${col} = $${col}`);
+			params[`$${col}`] = patch[col] ?? null;
+		}
+	}
+	if (sets.length === 0) return;
+	db.query(`UPDATE agent_runs SET ${sets.join(', ')} WHERE id = $id`).run(params);
+}

package/src/lib/devcontainer.server.ts

@@ -1,6 +1,6 @@
 import { chmod, cp, mkdir, readFile, unlink, writeFile } from 'node:fs/promises';
-import { existsSync, readdirSync, statSync } from 'node:fs';
-import { basename, dirname, join, relative } from 'node:path';
+import { existsSync, lstatSync, readdirSync, statSync } from 'node:fs';
+import { basename, dirname, join, relative, sep } from 'node:path';
 import { homedir } from 'node:os';
 import { INSTALL_SCRIPT as TMUX_INSTALL_SCRIPT } from '../container-injections/tmux.ts';
 import { INSTALL_SCRIPT as TTYD_INSTALL_SCRIPT } from '../container-injections/ttyd.ts';
@@ -160,6 +160,14 @@ 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';
 
+/**
+ * Present in `$HOME` for exactly as long as an MCP-driven `claude -p` run is executing. The
+ * surface launchers read it so opening the IDE mid-run doesn't start a second Claude beside the
+ * agent's — the two would share `~/.claude.json` and one project session dir, which is the same
+ * read-modify-write race documented on `terminalTask` below.
+ */
+export const AGENT_RUN_MARKER = '.codebay-agent-active';
+
 /**
  * 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.
@@ -174,14 +182,14 @@ export const TERMINAL_LAUNCHED_MARKER = '.codebay-terminal-launched';
 const INJECTIONS_WAIT_SECONDS = 600;
 
 /** Long enough to ride out an in-flight `npm install -g` of Claude Code. */
-const CLAUDE_BINARY_WAIT_SECONDS = 60;
+export const CLAUDE_BINARY_WAIT_SECONDS = 60;
 
 /**
  * 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.
  * Bounded so a failed boot (sentinel never written) still yields a usable terminal.
  */
-const WAIT_FOR_INJECTIONS =
+export const WAIT_FOR_INJECTIONS =
 	`[ -e "$HOME/${INJECTIONS_DONE_FILE}" ] || echo "Waiting for codebay setup to finish…"; ` +
 	`i=0; until [ -e "$HOME/${INJECTIONS_DONE_FILE}" ] || [ "$i" -ge ${INJECTIONS_WAIT_SECONDS} ]; do sleep 1; i=$((i + 1)); done; ` +
 	`[ -e "$HOME/${INJECTIONS_DONE_FILE}" ] || echo "codebay: setup did not finish in time — starting anyway"; `;
@@ -193,10 +201,17 @@ const WAIT_FOR_INJECTIONS =
  * skipped once the sentinel exists, since no injection can be mid-reinstall by then and a missing
  * binary is permanent. No single quotes: this is spliced into the single-quoted tmux commands below.
  */
-const launchClaude = (permissionMode: ClaudePermissionMode): string =>
+export const launchClaude = (permissionMode: ClaudePermissionMode): string =>
+	// An agent run already owns this container's Claude state, so drop to a plain shell instead of
+	// racing it. No single quotes: this whole string is spliced into the single-quoted tmux commands.
+	`if [ -e "$HOME/${AGENT_RUN_MARKER}" ]; then ` +
+	`echo "codebay: an agent run is driving Claude in this container — opening a shell instead."; ` +
+	`echo "codebay: run claude yourself once it finishes, or watch it in the Agent log."; ` +
+	`else ` +
 	`if [ ! -e "$HOME/${INJECTIONS_DONE_FILE}" ]; then i=0; until command -v claude >/dev/null 2>&1 || [ "$i" -ge ${CLAUDE_BINARY_WAIT_SECONDS} ]; do sleep 1; i=$((i + 1)); done; fi; ` +
 	`if command -v claude >/dev/null 2>&1; then claude ${claudePermissionFlags(permissionMode)}; ` +
-	`else echo "codebay: claude is not installed in this container — check the boot log, then Rebuild"; fi; `;
+	`else echo "codebay: claude is not installed in this container — check the boot log, then Rebuild"; fi; ` +
+	`fi; `;
 
 /**
  * claude scans `~/.claude/ide/*.lock` once at startup and never retries, so it must not race
@@ -215,7 +230,7 @@ const WAIT_FOR_IDE_BRIDGE = `i=0; until ls "$HOME/.claude/ide/" 2>/dev/null | gr
  * 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]
+export 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; `;
 
@@ -354,21 +369,49 @@ export function launchCommandFor(mode: InstanceMode): string {
 		: codeServerLaunch(getOption('advanced_blocking_ext_install') === '1');
 }
 
+/**
+ * Latched so the 5s preflight tick can't spam the console while the setup banner is up, but
+ * still re-arms on recovery. Without this, a spawn that fails for a *platform* reason (Windows
+ * can't exec an extensionless shim) is indistinguishable from the CLI simply not being installed.
+ */
+let cliProbeWarned = false;
+
 export async function devcontainerCliAvailable(): Promise<boolean> {
-	return (await spawnCapture([devcontainerBin(), '--version'])) !== null;
+	const argv = devcontainerBin();
+	const available = (await spawnCapture([...argv, '--version'])) !== null;
+	if (!available && !cliProbeWarned) {
+		console.warn(`⚠ devcontainer CLI probe failed — could not run: ${argv.join(' ')}`);
+	}
+	cliProbeWarned = !available;
+	return available;
 }
 
+/**
+ * Windows needs Developer Mode to *create* a symlink, and one EPERM rejects the whole `cp` — so
+ * there we follow them instead, which needs no privilege. Git for Windows does the same by default
+ * (`core.symlinks=false`). The count rides back out so the caller can say so in the boot log.
+ */
 export async function copyWorkspace(
 	source: string,
 	dest: string,
-	ignore: Set<string>
-): Promise<void> {
+	ignore: Set<string>,
+	dereference: boolean = process.platform === 'win32'
+): Promise<{ dereferencedSymlinks: number }> {
+	let dereferencedSymlinks = 0;
 	await mkdir(dest, { recursive: true });
 	await cp(source, dest, {
 		recursive: true,
-		dereference: false,
-		filter: (src) => !ignore.has(basename(src))
+		dereference,
+		filter: (src) => {
+			if (ignore.has(basename(src))) return false;
+			// Counted in the filter because cp offers no per-entry hook once the walk is underway.
+			if (dereference && lstatSync(src, { throwIfNoEntry: false })?.isSymbolicLink()) {
+				dereferencedSymlinks++;
+			}
+			return true;
+		}
 	});
+	return { dereferencedSymlinks };
 }
 
 /** Strip // and /* *\/ comments and trailing commas from JSONC, respecting string literals. */
@@ -582,7 +625,10 @@ export async function writeOverrideConfig(
 	// `./`-descendant feature paths), and under `.devcontainer/` for the two classic forms.
 	const featureRoot =
 		dirname(target) === workspaceDir ? join(workspaceDir, '.devcontainer') : dirname(target);
-	const featureKey = (dir: string) => `./${relative(dirname(target), join(featureRoot, dir))}`;
+	// A feature key is a config path the CLI resolves, not a host path: it must stay POSIX, or the
+	// flat-config form (whose relative path spans a directory) emits a backslash Windows-only key.
+	const featureKey = (dir: string) =>
+		`./${relative(dirname(target), join(featureRoot, dir)).replaceAll(sep, '/')}`;
 	const tmuxFeatureKey = featureKey(TMUX_FEATURE_DIR);
 	const ttydFeatureKey = featureKey(TTYD_FEATURE_DIR);
 	const claudeFeatureKey = featureKey(CLAUDE_FEATURE_DIR);
@@ -925,7 +971,7 @@ type UpOptions = { noCache?: boolean; configPath?: string; overrideConfigPath?:
 
 export function devcontainerUpArgs(workspaceDir: string, opts: UpOptions = {}) {
 	const args = [
-		devcontainerBin(),
+		...devcontainerBin(),
 		'up',
 		'--workspace-folder',
 		workspaceDir,

package/src/lib/docker-client.server.ts

@@ -1,5 +1,6 @@
 import Docker from 'dockerode';
 import { readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
 import { join } from 'node:path';
 import { DOCKER_HOST, dockerEnv } from './config.server.ts';
 import { spawnCapture } from './spawn.server.ts';
@@ -16,9 +17,13 @@ export function resetDocker(): void {
 	g.__codebayDocker = undefined;
 }
 
+/** Docker Desktop for Windows exposes no Unix socket; its daemon listens on a named pipe. */
+const DEFAULT_DOCKER_SOCKET =
+	process.platform === 'win32' ? '//./pipe/docker_engine' : '/var/run/docker.sock';
+
 async function resolveDocker(): Promise<Docker> {
 	const host = DOCKER_HOST || (await dockerContextHost()) || '';
-	return new Docker(host ? parseDockerHost(host) : { socketPath: '/var/run/docker.sock' });
+	return new Docker(host ? parseDockerHost(host) : { socketPath: DEFAULT_DOCKER_SOCKET });
 }
 
 /** dockerode ignores `docker context`, but the devcontainer CLI honors it — so read it here. */
@@ -33,7 +38,8 @@ async function dockerContextHost(): Promise<string> {
 
 /** Missing files yield undefined so the connection fails with a clear TLS error, not here. */
 function tlsMaterials(): { ca?: Buffer; cert?: Buffer; key?: Buffer } {
-	const dir = process.env.DOCKER_CERT_PATH?.trim() || join(process.env.HOME ?? '', '.docker');
+	// homedir(), not $HOME, which Windows leaves unset — that would make this cwd-relative.
+	const dir = process.env.DOCKER_CERT_PATH?.trim() || join(homedir(), '.docker');
 	const read = (name: string): Buffer | undefined => {
 		try {
 			return readFileSync(join(dir, name));
@@ -44,10 +50,10 @@ function tlsMaterials(): { ca?: Buffer; cert?: Buffer; key?: Buffer } {
 	return { ca: read('ca.pem'), cert: read('cert.pem'), key: read('key.pem') };
 }
 
-/** Windows `npipe://` is unsupported — this app runs on macOS/Linux. */
+/** dockerode takes a Windows named pipe as a `socketPath`, exactly like a Unix socket. */
 function parseDockerHost(host: string): Docker.DockerOptions {
-	if (host.startsWith('unix://')) {
-		return { socketPath: host.slice('unix://'.length) };
+	for (const scheme of ['unix://', 'npipe://']) {
+		if (host.startsWith(scheme)) return { socketPath: host.slice(scheme.length) };
 	}
 	const tls = (process.env.DOCKER_TLS_VERIFY ?? '') !== '';
 	const url = new URL(host.includes('://') ? host : `tcp://${host}`);

package/src/lib/drives.ts

@@ -0,0 +1,11 @@
+/**
+ * Windows has no single filesystem root: `dirname('C:\')` is `C:\`, so walking up from the home
+ * directory dead-ends on its own drive and a project on another one is unreachable. This stands in
+ * as the parent of every drive root, and browsing it lists the drives themselves.
+ *
+ * A colon is illegal in a Windows path segment, so this can never collide with a real folder.
+ */
+export const DRIVES_ROOT = '::drives';
+
+/** What the crumbs show for the virtual root, which has no path of its own. */
+export const DRIVES_ROOT_LABEL = 'This PC';